Open Corridor promise

Author: simonredfern

CLAUDE.md

@@ -241,7 +241,7 @@ Note: `executeFutureCreated` returns 201; pair it with `cc.user.openOrThrowExcep
 
 **Use `NEW_ACCOUNT_ID` for PUT-creates-account URLs**: When a `PUT /banks/BANK_ID/accounts/ACCOUNT_ID` *creates* the account (it doesn't exist yet), the middleware's `validateAccount` keys off the literal `ACCOUNT_ID` template var and tries to look it up → 404 before the handler runs. Change the ResourceDoc URL template to `/banks/BANK_ID/accounts/NEW_ACCOUNT_ID` (or any non-standard ALL_CAPS variant) — middleware treats it as a wildcard and skips the lookup, but the path still matches the route pattern. The handler can check "already exists" inline with `Connector.connector.vend.checkBankAccountExists(...)` and return 409/400 as needed.
 
-**Reserved ALL_CAPS literals — don't use them as placeholders**: `ResourceDocMatcher` in `Http4sSupport.scala` keeps an explicit `literalAllCapsSegments` set: `SANDBOX_TAN`, `COUNTERPARTY`, `SEPA`, `FREE_FORM`, `ACCOUNT`, `ACCOUNT_OTP`, `REFUND`, `SIMPLE`, `AGENT_CASH_WITHDRAWAL`, `CARD`, `EMAIL`, `SMS`, `IMPLICIT`, `NOT_EMAIL_NEITHER_SMS`. These are matched as **literals** (real Lift endpoints register them as concrete SCA-method / transaction-request-type segments — e.g. `/banks/BANK_ID/my/consents/EMAIL`). Any other ALL_CAPS segment is a wildcard. If you migrate an endpoint whose URL template uses one of these names as a *placeholder variable* (e.g. v3.0/v4.0 `getUsersByEmail` had `/users/email/EMAIL/terminator` with EMAIL meaning "any email value"), the matcher will only fire when the URL segment is literally `EMAIL` — real callers pass actual addresses and miss the doc entirely → middleware skips auth/role validation → handler 500s on the empty CallContext. Rename the placeholder to something outside the literal set (e.g. `EMAIL` → `USER_EMAIL`), and apply the rename in **both** the http4s `ResourceDoc` and the original Lift `ResourceDoc` (resource-docs aggregation reads both, and `collectResourceDocs` dedup keys off URL + verb).
+**Reserved ALL_CAPS literals — don't use them as placeholders**: `ResourceDocMatcher` in `Http4sSupport.scala` keeps an explicit `literalAllCapsSegments` set: `SANDBOX_TAN`, `COUNTERPARTY`, `SEPA`, `FREE_FORM`, `ACCOUNT`, `ACCOUNT_OTP`, `REFUND`, `SIMPLE`, `AGENT_CASH_WITHDRAWAL`, `CARD`, `OPEN_CORRIDOR_PROMISE`, `OPEN_CORRIDOR_SETTLEMENT`, `EMAIL`, `SMS`, `IMPLICIT`, `NOT_EMAIL_NEITHER_SMS`. These are matched as **literals** (real Lift endpoints register them as concrete SCA-method / transaction-request-type segments — e.g. `/banks/BANK_ID/my/consents/EMAIL`). Any other ALL_CAPS segment is a wildcard. If you migrate an endpoint whose URL template uses one of these names as a *placeholder variable* (e.g. v3.0/v4.0 `getUsersByEmail` had `/users/email/EMAIL/terminator` with EMAIL meaning "any email value"), the matcher will only fire when the URL segment is literally `EMAIL` — real callers pass actual addresses and miss the doc entirely → middleware skips auth/role validation → handler 500s on the empty CallContext. Rename the placeholder to something outside the literal set (e.g. `EMAIL` → `USER_EMAIL`), and apply the rename in **both** the http4s `ResourceDoc` and the original Lift `ResourceDoc` (resource-docs aggregation reads both, and `collectResourceDocs` dedup keys off URL + verb).
 
 **Bypass roles vs required roles**: Some Lift handlers check entitlements inline as **bypass** conditions inside authorisation helpers — e.g. `checkAuthorisationToCreateTransactionRequest` honours `canCreateAnyTransactionRequest` to let the caller skip the view-permission check, but the role is never a hard requirement. These roles are correctly absent from the Lift ResourceDoc role list — putting them in the doc would make Lift enforce them as required (since Lift DOES enforce doc roles by default), breaking the "view permission OR role" intent. The same holds for http4s middleware. So the trap on migration is the reflex copy: don't move a bypass role from inline-only into `Some(List(...))` just because it appears in the handler. Audit before copying: if the role appears in the Lift handler only inside an authorisation OR-chain ("has view permission OR has role X"), it belongs as `None` in the doc with the inline view/role logic preserved. Bypass roles must stay out of the doc.
 

obp-api/src/main/scala/code/api/util/http4s/Http4sSupport.scala

@@ -741,6 +741,7 @@ object ResourceDocMatcher extends code.util.Helper.MdcLoggable {
     "SANDBOX_TAN", "COUNTERPARTY", "SEPA", "FREE_FORM",
     "ACCOUNT", "ACCOUNT_OTP", "REFUND", "SIMPLE",
     "AGENT_CASH_WITHDRAWAL", "CARD",
+    "OPEN_CORRIDOR_PROMISE", "OPEN_CORRIDOR_SETTLEMENT",
     // SCA methods (POST /banks/BANK_ID/my/consents/{EMAIL|SMS|IMPLICIT})
     "EMAIL", "SMS", "IMPLICIT", "NOT_EMAIL_NEITHER_SMS"
   )

obp-api/src/main/scala/code/api/v7_0_0/Http4s700.scala

@@ -3175,14 +3175,14 @@ object Http4s700 {
 
     // ── End UTILITY ───────────────────────────────────────────────────────────
 
-    // ── OPEN_CORRIDOR transaction request ─────────────────────────────────────
+    // ── OPEN_CORRIDOR_PROMISE transaction request ─────────────────────────────
     // Travel-Rule-friendly TR with FATF Recommendation 16 originator block.
     // Money-movement is identical to SIMPLE; the originator is persisted as a
     // side-car on the TR row and surfaced on the v7 response. Lives natively at
     // v7 (rather than bridging to v4) because only v7's response shape carries
     // the originator block.
     val createTransactionRequestOpenCorridor: HttpRoutes[IO] = HttpRoutes.of[IO] {
-      case req @ POST -> `prefixPath` / "banks" / _ / "accounts" / _ / _ / "transaction-request-types" / "OPEN_CORRIDOR" / "transaction-requests" =>
+      case req @ POST -> `prefixPath` / "banks" / _ / "accounts" / _ / _ / "transaction-request-types" / "OPEN_CORRIDOR_PROMISE" / "transaction-requests" =>
         EndpointHelpers.withViewAndBodyCreated[JSONFactory700.TransactionRequestBodyOpenCorridorJsonV700, JSONFactory700.TransactionRequestWithChargeOpenCorridorJsonV700](req) { (user, fromAccount, view, body, cc) =>
           val callCtx = Some(cc)
           for {
@@ -3211,7 +3211,7 @@ object Http4s700 {
         other_branch_routing_address = ""
       ),
       value = com.openbankproject.commons.model.AmountOfMoneyJsonV121(currency = "EUR", amount = "100.00"),
-      description = "OPEN_CORRIDOR Travel-Rule payment",
+      description = "Open Corridor Travel-Rule payment",
       charge_policy = "SHARED",
       originator = com.openbankproject.commons.model.TransactionRequestOriginator(
         name = "Alice Sender",
@@ -3228,17 +3228,17 @@ object Http4s700 {
       implementedInApiVersion,
       nameOf(createTransactionRequestOpenCorridor),
       "POST",
-      "/banks/BANK_ID/accounts/ACCOUNT_ID/VIEW_ID/transaction-request-types/OPEN_CORRIDOR/transaction-requests",
-      "Create Transaction Request (OPEN_CORRIDOR)",
-      """Initiate an OPEN_CORRIDOR Transaction Request — a Travel-Rule-friendly payment that carries FATF Recommendation 16 originator information about the actual payer.
+      "/banks/BANK_ID/accounts/ACCOUNT_ID/VIEW_ID/transaction-request-types/OPEN_CORRIDOR_PROMISE/transaction-requests",
+      "Create Transaction Request (OPEN_CORRIDOR_PROMISE)",
+      """Initiate an OPEN_CORRIDOR_PROMISE Transaction Request — an Open Corridor Travel-Rule-friendly payment that carries FATF Recommendation 16 originator information about the actual payer.
         |
         |Money-movement is identical to the SIMPLE transaction request type (same beneficiary routing fields). What's distinct: the `originator` block is mandatory and is persisted alongside the transaction request. The v7 response includes a populated originator block.
         |
         |Authentication is Required.""".stripMargin,
       openCorridorBodyExample,
       JSONFactory700.TransactionRequestWithChargeOpenCorridorJsonV700(
         id = "4050046c-63b3-4868-8a22-14b4181d33a6",
-        `type` = "OPEN_CORRIDOR",
+        `type` = "OPEN_CORRIDOR_PROMISE",
         from = code.api.v1_4_0.JSONFactory1_4_0.TransactionRequestAccountJsonV140(
           bank_id = "gh.29.uk",
           account_id = "8ca8a7e4-6d02-40e3-a129-0b2bf89de9f1"
@@ -3271,7 +3271,7 @@ object Http4s700 {
       http4sPartialFunction = Some(createTransactionRequestOpenCorridor)
     )
 
-    // ── End OPEN_CORRIDOR ─────────────────────────────────────────────────────
+    // ── End OPEN_CORRIDOR_PROMISE ─────────────────────────────────────────────
 
     // ── BULK transaction request ──────────────────────────────────────────────
     // One TransactionRequest with type=BULK serves as the envelope; N actual

obp-api/src/main/scala/code/api/v7_0_0/JSONFactory7.0.0.scala

@@ -1011,7 +1011,7 @@ object JSONFactory700 extends MdcLoggable with code.api.util.CustomJsonFormats {
     )
   }
 
-  // ─── OPEN_CORRIDOR Transaction Request type ────────────────────────────────
+  // ─── OPEN_CORRIDOR_PROMISE Transaction Request type ────────────────────────
   //
   // SIMPLE-shaped beneficiary routing plus a REQUIRED `originator` block carrying
   // FATF Recommendation 16 (Travel Rule) information about the actual payer. The
@@ -1042,7 +1042,7 @@ object JSONFactory700 extends MdcLoggable with code.api.util.CustomJsonFormats {
     address: String
   )
 
-  // OPEN_CORRIDOR response wrapper — v4 TransactionRequestWithChargeJSON400 shape
+  // OPEN_CORRIDOR_PROMISE response wrapper — v4 TransactionRequestWithChargeJSON400 shape
   // plus the originator block. `originator` is None when there's no explicit value
   // stored AND no customer_account_link for the from-account; serializes as null.
   case class TransactionRequestWithChargeOpenCorridorJsonV700(

obp-api/src/main/scala/code/bankconnectors/LocalMappedConnector.scala

@@ -5259,12 +5259,12 @@ object LocalMappedConnector extends Connector with MdcLoggable {
           } yield {
             (transactionId, callContext)
           }
-        // OPEN_CORRIDOR: money-movement is identical to SIMPLE today (same beneficiary
+        // OPEN_CORRIDOR_PROMISE: money-movement is identical to SIMPLE today (same beneficiary
         // routing shape). The originator block is persisted on the TR row by
         // MappedTransactionRequestProvider and surfaced on v7 responses by
         // JSONFactory700.buildTransactionRequestOriginatorJson — neither is needed here.
         // Reuses the SIMPLE path via body.to_simple.
-        case OPEN_CORRIDOR =>
+        case OPEN_CORRIDOR_PROMISE =>
           for {
             bodyToSimple <- NewStyle.function.tryons(s"$TransactionRequestDetailsExtractException It can not extract to $TransactionRequestBodyCounterpartyJSON", 400, callContext) {
               body.to_simple.get

obp-api/src/main/scala/code/bankconnectors/opencorridor/OpenCorridorProcessor.scala

@@ -17,16 +17,16 @@ import net.liftweb.util.StringHelpers
 
 import scala.concurrent.Future
 
-// OPEN_CORRIDOR Transaction Request — Travel-Rule-friendly payment.
+// OPEN_CORRIDOR_PROMISE Transaction Request — Travel-Rule-friendly payment.
 //
 // Money-movement is identical to SIMPLE today (same beneficiary routing shape).
 // What's distinct is the mandatory `originator` block, persisted alongside the TR
-// and surfaced on v7 responses. Lives in its own package so future OPEN_CORRIDOR
+// and surfaced on v7 responses. Lives in its own package so future Open Corridor
 // extensions (Cardano Promise, netting, settlement) have a home that does not bloat
 // `LocalMappedConnector`.
 object OpenCorridorProcessor {
 
-  // Create an OPEN_CORRIDOR Transaction Request: validate the originator block,
+  // Create an OPEN_CORRIDOR_PROMISE Transaction Request: validate the originator block,
   // resolve the destination counterparty (via the same getOrCreateCounterparty
   // path SIMPLE uses), persist the TR with the originator side-car, and return it.
   def create(
@@ -39,7 +39,7 @@ object OpenCorridorProcessor {
     callContext: Option[CallContext]
   ): Future[(TransactionRequest, Option[CallContext])] = {
 
-    val transactionRequestType = TransactionRequestType("OPEN_CORRIDOR")
+    val transactionRequestType = TransactionRequestType("OPEN_CORRIDOR_PROMISE")
 
     for {
       _ <- Helper.booleanToFuture(s"$InvalidJsonValue originator.name must be non-empty", cc = callContext) {

obp-api/src/main/scala/code/transactionrequests/MappedTransactionRequestProvider.scala

@@ -104,7 +104,7 @@ object MappedTransactionRequestProvider extends TransactionRequestProvider with
     val consentOption = consentIdOption.map(consentId =>Consents.consentProvider.vend.getConsentByConsentId(consentId).toOption).flatten
     val consentReferenceIdOption = consentOption.map(_.consentReferenceId)
 
-    // Explicit originator (FATF Rec 16). Only the OPEN_CORRIDOR body carries this today;
+    // Explicit originator (FATF Rec 16). Only the OPEN_CORRIDOR_PROMISE body carries this today;
     // other TR types leave the columns null.
     val explicitOriginator: Option[TransactionRequestOriginator] = transactionRequestCommonBody match {
       case openCorridorBody: TransactionRequestBodyOpenCorridorJsonV700 => Some(openCorridorBody.originator)
@@ -168,7 +168,7 @@ object MappedTransactionRequestProvider extends TransactionRequestProvider with
       .mUserId(callContext.flatMap(_.user.map(_.userId)).getOrElse(null))
       .mOnBehalfOfUserId(callContext.flatMap(cc => cc.onBehalfOfUser.or(cc.consenter).map(_.userId)).getOrElse(null))
 
-      // Explicit originator fields (FATF Rec 16, OPEN_CORRIDOR type only — null otherwise).
+      // Explicit originator fields (FATF Rec 16, OPEN_CORRIDOR_PROMISE type only — null otherwise).
       .mOriginator_Name(explicitOriginator.map(_.name).getOrElse(null))
       .mOriginator_Address(explicitOriginator.map(_.address).getOrElse(null))
       .mOriginator_AccountRoutingScheme(explicitOriginator.map(_.account_routing.scheme).getOrElse(null))
@@ -272,7 +272,7 @@ class MappedTransactionRequest extends LongKeyedMapper[MappedTransactionRequest]
   object mIsBeneficiary extends MappedBoolean(this)
 
   // Originator fields (FATF Recommendation 16 "Travel Rule" — who the payment is from).
-  // Populated only for OPEN_CORRIDOR Transaction Requests. For other TR types these are null
+  // Populated only for OPEN_CORRIDOR_PROMISE Transaction Requests. For other TR types these are null
   // and the v7 JSON response layer can virtually fill from customer_account_link.
   object mOriginator_Name extends MappedString(this, 140)
   object mOriginator_Address extends MappedString(this, 2000)
@@ -344,10 +344,10 @@ class MappedTransactionRequest extends LongKeyedMapper[MappedTransactionRequest]
     else
       None
 
-    // OPEN_CORRIDOR's persisted body has the same `to: PostSimpleCounterpartyJson400` shape
+    // OPEN_CORRIDOR_PROMISE's persisted body has the same `to: PostSimpleCounterpartyJson400` shape
     // as SIMPLE, so we reuse this SIMPLE branch's JSON-field extraction.
     val t_to_simple = if ((TransactionRequestTypes.withName(transactionType) == TransactionRequestTypes.SIMPLE ||
-      TransactionRequestTypes.withName(transactionType) == TransactionRequestTypes.OPEN_CORRIDOR) && details.nonEmpty){
+      TransactionRequestTypes.withName(transactionType) == TransactionRequestTypes.OPEN_CORRIDOR_PROMISE) && details.nonEmpty){
       val transactionRequestSimples = for {
         JObject(child) <- parsedDetails
         JField("other_bank_routing_scheme", JString(otherBankRoutingScheme)) <- child