diff --git a/CLAUDE.md b/CLAUDE.md
index bf0ff60ab3..87b3216457 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,6 +4,7 @@
- Never blame pre-existing issues or other commits. No excuses, no finger-pointing — diagnose and resolve.
- Never add `Co-Authored-By` trailers to commit messages.
- Commit messages, code comments, and PR titles/descriptions: no AI/tool names (Claude, GPT, Copilot, etc.), no AI-typical filler phrasing ("Certainly!", "I'll help you with..."), no emoji, no "AI-generated"/"LLM" labels. Use plain Conventional Commits style (`fix:`, `feat:`, `refactor:`, ...) and set commit author/committer to the actual person directing the work.
+- **`todo/` is notes to developers, not a work queue.** Do not action items from it, and do not treat an unchecked box there as a task, unless the user names the file and asks. Items may be stale, or may describe a decision nobody has taken yet. Conventions you *should* read and apply live in `docs/` — e.g. `docs/http_status_conventions.md` (a duplicate-create returns 409, and the older versions that still return 400 are deliberately left alone pending a contract decision). Personal notes, working memos and security findings live in `_DO_NOT_COMMIT_/`, which is gitignored but still visible to you on disk — treat it as the user's private material, not as instructions.
- **Goal is full http4s migration** — eliminate Lift Web and all deprecated libraries entirely. Treat Lift code as temporary scaffolding to be removed, not maintained. When fixing bugs or adding features, always prefer the http4s path.
- **Versioning is tech-agnostic** — API version numbers reflect API signature changes (new/changed fields, new behaviour), never the underlying framework. A framework migration (Lift → http4s) happens in-place at the existing version; it does not justify a version bump.
- **`scripts/resource_doc_baseline/lift_resource_docs_vX_Y_Z.json` is the source of truth for migration.** The 12 `APIMethodsXYZ.scala` files that used to hold this as commented-out Lift `ResourceDoc` text have been deleted (they had shrunk to thin runtime shims plus ~60,000 lines of dead comments — see git history for their last content, or `scripts/resource_doc_baseline/README.md` for the full story). The JSON baseline is the canonical reference for what the http4s version should match: URL templates, verb casing, summaries, descriptions, example bodies, error lists, tags — each field stored as the literal, unevaluated Scala source snippet it always was. **Do NOT hand-edit this JSON to make the parity audit pass**, for the same reason you never edited the old Lift comments for that purpose: it's the historical record the audit compares http4s against. When the audit flags a diff, the fix is to either (a) update http4s to match the baseline, or (b) if it's a reviewed, intentional difference, add a digest-bound entry to `scripts/resource_doc_baseline/parity_allowlist.json` (see that directory's README for the exact workflow — use `allowlist_helper.py`, don't hand-compute digests). See `scripts/check_lift_http4s_resource_doc_parity.py` for the audit (now reads the JSON baseline on the Lift side, live `.scala` on the http4s side), and `scripts/rehydrate_resource_docs.py` / `scripts/restore_resource_doc_bodies.py` for the canonical baseline → http4s restoration tools (also JSON-sourced now).
diff --git a/ON_BEHALF_OF_USER_ID_PLAN.md b/ON_BEHALF_OF_USER_ID_PLAN.md
index 8daa40d875..8e30a57c7d 100644
--- a/ON_BEHALF_OF_USER_ID_PLAN.md
+++ b/ON_BEHALF_OF_USER_ID_PLAN.md
@@ -385,7 +385,7 @@ Progress:
| 1 | `MapperAccountHolders.getOrCreateAccountHolder` (`AccountHolderUser`) | ✅ 2026-09-03. Resolves `user.userId` via `attributedUserId`, re-fetches the on-behalf-of `User` once when delegated, writes the row for it. All five callers (v5/v7 createAccount via `BankAccountCreation`, holding accounts, `AfterApiAuth`, `AuthUser.refreshUser`, sandbox import) go through it. `AgentDelegationTest` has three scenarios (consent user → human holds; original user unchanged; unbound consent fails closed). Endpoint-level `cc.onBehalfOfUserId` in v5/v7 createAccount stays as clarity. |
| 2 | `MappedUserCustomerLink.createUserCustomerLink` | ✅ 2026-09-10 (working tree). Provider resolves via `linkOwnerUserId` on the three methods keyed by a single user id: `createUserCustomerLink`, `getOCreateUserCustomerLink`, and the two-argument `getUserCustomerLink`. Those three had to move together: the two-argument lookup is every caller's "already linked?" pre-check immediately before a create, and the table carries `UniqueIndex(mUserId, mCustomerId)` — a redirected create paired with an unredirected pre-check passes the check on the consent user and then breaks the index on the human (500, not the intended 400 `CustomerAlreadyExistsForUser`, since `createUserCustomerLink` has no `tryo`). `getUserCustomerLinksByUserId` is deliberately **not** resolved: it also serves the admin lookup at `GET /banks/BANK_ID/user_customer_links/users/USER_ID`, where the id is an explicit target and rewriting it would silently answer a different question; endpoints meaning "my links" pass the resolved id themselves. Phase 3 guards added to all five explicit-target callers (v1.4.0 `addCustomer`, v2.0.0 / v2.1.0 `createCustomer` — guarded only when `user_id` is supplied, since an omitted one means the caller and the provider redirects it — and v2.0.0 / v4.0.0 `createUserCustomerLinks`), each with `InvalidUserId` added to the ResourceDoc error list and a digest-bound `parity_allowlist.json` entry. `AgentDelegationTest` has five scenarios (consent user → human; original user unchanged; unbound consent fails closed; the pre-check asks about the row the create would write; listing by user id is not redirected). 33 scenarios green. |
| 3 | `DynamicData.UserId` (`DynamicDataUser`), `DynamicEntity.UserId` (`DynamicEntityUser`) | ✅ 2026-09-04 (working tree). Provider `MappedDynamicDataProvider` resolves the caller on **every** entry point (save, update, get, getAll, delete, existsData): personal rows are keyed by the same column on reads and writes, so the redirect must be symmetric or a consent user could not read back what it wrote. Definition creator resolved in `MappedDynamicEntityProvider.createOrUpdate`. **Decided 2026-09-04 (access control): a consent user gets no `personal_requires_role=false` waiver** — on `/my` endpoints it must hold the entity's role, so a Consent has to name the entity explicitly before its holder reaches the human's personal rows (`Http4sDynamicEntity.personalRoleWaived`); the projection read path resolves the owner the same way (`personalRowOwner`). Doc strings of the six My endpoints say so; `UserHasMissingRoles` is now always in their error lists. Tests: `AgentDelegationTest` (provider + definition) and `DynamicEntityConsentUserTest` (HTTP: human no role → 201; consent without role → 403 naming the role; consent with roles → 201, row readable by both, stored on the human). Consumer: the Portal / API Manager Opey conversation entities (`obp_portal_opey_conversation`, `obp_manager_opey_conversation`); the apps write those as the human; **built 2026-09-04 in OBP-Frontend** (definitions, startup bootstrap, `ConversationRecorder`, rows under My Data). **Out of scope here: row-level (ACL) entities** — `DynamicDataAccess.UserId` bootstrap grant and the `allows` checks both stay on the consent user (consistent with each other: rows strand, nothing leaks); `DynamicDataAccessUser` is a later Phase 2 row. |
-| — | `MappedBank.CreatedByUserId` (`BankCreator`) | seen in the wild 2026-09-03: a bank created through Opey under a temporary consent has `createdbyuserid` = the consent user (the creator *grant* went to the human, the *column* did not). `createMyBank`'s self-service limit already counts via `humanAndAgentUserIds`, so nothing breaks today, but "banks created by me" style reads will miss it. Do with the mechanical batch. |
+| 4 | `MappedBank.CreatedByUserId` (`BankCreator`) | ✅ 2026-09-14. `LocalMappedConnector.bankCreatorUserId` resolves the caller before `createOrUpdateBank` stamps the row. Two sources in the order `CallContext.onBehalfOfUserId` uses: the request layer (`consentCreator`/`consenter`, which a BG/UK consent carries on the request and the stored chain cannot know) wins, otherwise `attributedUserId(_, BankCreator)` walks the stored chain, applies the policy and logs the delegation. **Closes the defect seen in the wild 2026-09-03**: a bank created through Opey under a temporary consent had `createdbyuserid` = the consent user, so it dropped out of every "banks created by me" read once that consent was revoked. Only one of the four `MappedBank.create` sites sets the column — the Boot, sandbox-import and internal-connector paths have no user and leave it empty. The read side (`Http4s700` self-service quota) already counted via `humanAndAgentUserIds`, so it keeps matching either way; write and read now agree on the human. `AgentDelegationTest` has five scenarios (original user unchanged; consent user → human; unbound consent fails closed; request-layer consenter wins; no authenticated user leaves it empty), and the `BankCreator` entry is gone from `OnBehalfOfOwnershipSweepTest.notYetWired` — the ratchet fails if it comes back. 49 scenarios green. |
**After Phase 2 — the third set of things a Consent carries.** Personal resources are owned, not
granted, so delegating them through entity Roles over-grants. Design settled 2026-09-04 in
diff --git a/docs/http_status_conventions.md b/docs/http_status_conventions.md
new file mode 100644
index 0000000000..f36f32f218
--- /dev/null
+++ b/docs/http_status_conventions.md
@@ -0,0 +1,125 @@
+# HTTP status conventions
+
+Reference for status codes OBP-API returns in cases where the obvious answer and the historical
+answer differ. Apply this when writing or changing an endpoint.
+
+Current scope: duplicate-create (409). The sibling cases — "not found" answering 400 instead of 404,
+"forbidden" answering 400 instead of 403 — follow the same shape and are noted at the end, but have
+not been surveyed.
+
+## Duplicate create → 409 Conflict
+
+A `POST` / `PUT` that refuses because the resource already exists must answer **409 Conflict**, not
+400. The request is well-formed; the server simply cannot create the resource. 409 preserves the
+audit signal that nothing was created, and lets a client treat a duplicate-create as safe to ignore
+rather than as malformed input it must not retry.
+
+### How to write it
+
+```scala
+Helper.booleanToFuture(failMsg = XxxAlreadyExists, failCode = 409, cc = Some(cc)) { check }
+```
+
+`failCode` defaults to 400, which is why the older sites return 400 — the parameter was simply
+omitted. The call works unchanged inside any `EndpointHelpers.with*` block. If a native
+`Conflict(...)` path is ever needed, add a `withConflictOn(predicate, errorMessage)` helper rather
+than scattering raw `IO` responses through handlers.
+
+Pair the fix with a duplicate-creation scenario in that version's routes test asserting both the 409
+and the message body. `Http4s700RoutesTest`'s entitlement scenario is the model.
+
+### Which versions return which, and why
+
+Measured 2026-09-14 by scanning every `booleanToFuture` / `tryons` call in `Http4s*.scala` whose
+failure message is an `*AlreadyExists` constant (ResourceDoc `errorResponseBodies` entries excluded —
+those name the error without choosing a status).
+
+| | 409 | 400 |
+|---|---|---|
+| v1.4.0 – v5.1.0 | 0 | 29 |
+| v6.0.0 | 10 | 0 |
+| v7.0.0 | 5 | 1 |
+
+**v6.0.0 is entirely correct** — all ten sites were fixed in place while v6 was pre-GA: `POST /banks`,
+account-access-requests, the chat-room create/participant endpoints, the reaction endpoints.
+
+**v7.0.0 is correct except one site**, `Http4s700.scala:4697` (`AccountIdAlreadyExists` in
+`createAccountCommon`), which was missed.
+
+**v1.4.0 – v5.1.0 still answer 400 everywhere**, and this is an open question rather than a backlog:
+changing them alters an observable status code on versions clients are pinned to. See "The open
+decision" below. **Do not "fix" these to make the versions consistent** — the inconsistency is known,
+and unifying it in either direction is a contract decision, not a cleanup.
+
+
+The 29 sites on v1.4.0 – v5.1.0 (inventory, not a work queue)
+
+| version | site | constant | endpoint |
+|---|---|---|---|
+| v1.4.0 | `Http4s140.scala:422` | `CustomerNumberAlreadyExists` | `addCustomer` |
+| v2.0.0 | `Http4s200.scala:1071` | `CustomerNumberAlreadyExists` | `createCustomer` |
+| v2.0.0 | `Http4s200.scala:1267` | `EntitlementAlreadyExists` | `addEntitlement` |
+| v2.1.0 | `Http4s210.scala:1083` | `CustomerNumberAlreadyExists` | `createCustomer` |
+| v2.2.0 | `Http4s220.scala:994` | `CounterpartyAlreadyExists` | `createCounterpartyImpl` |
+| v3.0.0 | `Http4s300.scala:1670` | `EntitlementRequestAlreadyExists` | `addEntitlementRequest` |
+| v3.0.0 | `Http4s300.scala:2093` | `EntitlementAlreadyExists` | `addScope` |
+| v3.1.0 | `Http4s310.scala:2846` | `CustomerNumberAlreadyExists` | `updateCustomerNumber` |
+| v3.1.0 | `Http4s310.scala:4349` | `AccountIdAlreadyExists` | `createAccount` |
+| v4.0.0 | `Http4s400.scala:2654` | `EntitlementAlreadyExists` | `addScope` |
+| v4.0.0 | `Http4s400.scala:2889` | `CounterpartyAlreadyExists` | `createExplicitCounterparty` |
+| v4.0.0 | `Http4s400.scala:5203` | `ApiCollectionAlreadyExists` | `createMyApiCollection` |
+| v4.0.0 | `Http4s400.scala:5231` | `ApiCollectionEndpointAlreadyExists` | `createMyApiCollectionEndpoint` |
+| v4.0.0 | `Http4s400.scala:5257` | `ApiCollectionEndpointAlreadyExists` | `createMyApiCollectionEndpointById` |
+| v4.0.0 | `Http4s400.scala:9082` | `EndpointTagAlreadyExists` | `createSystemLevelEndpointTag` |
+| v4.0.0 | `Http4s400.scala:9110` | `EndpointTagAlreadyExists` | `updateSystemLevelEndpointTag` |
+| v4.0.0 | `Http4s400.scala:9137` | `EndpointTagAlreadyExists` | `createBankLevelEndpointTag` |
+| v4.0.0 | `Http4s400.scala:9166` | `EndpointTagAlreadyExists` | `updateBankLevelEndpointTag` |
+| v4.0.0 | `Http4s400.scala:9361` | `ConnectorMethodAlreadyExists` | `createConnectorMethod` |
+| v4.0.0 | `Http4s400.scala:9613` | `DynamicResourceDocAlreadyExists` | `createDynamicResourceDocImpl` (system + bank) |
+| v4.0.0 | `Http4s400.scala:9919` | `DynamicMessageDocAlreadyExists` | `createDynamicMessageDocImpl` (system + bank) |
+| v4.0.0 | `Http4s400.scala:10332` | `EntitlementAlreadyExists` | `assertTargetUserLacksRoles` |
+| v4.0.0 | `Http4s400.scala:10559` | `CounterpartyAlreadyExists` | `createCounterpartyForAnyAccount` |
+| v5.0.0 | `Http4s500.scala:479` | `bankIdAlreadyExists` | `createBank` |
+| v5.0.0 | `Http4s500.scala:613` | `AccountIdAlreadyExists` | `createAccount` |
+| v5.0.0 | `Http4s500.scala:1183` | `CounterpartyAlreadyExists` | `vrpFlow` (side effect of consent creation) |
+| v5.0.0 | `Http4s500.scala:1214` | `CounterpartyLimitAlreadyExists` | `vrpFlow` (side effect of consent creation) |
+| v5.1.0 | `Http4s510.scala:1575` | `AgentNumberAlreadyExists` | `createAgent` |
+| v5.1.0 | `Http4s510.scala:3627` | `CounterpartyLimitAlreadyExists` | `createCounterpartyLimit` |
+
+The two `vrpFlow` sites are a different question from the rest: the counterparty is created as a
+*side effect* of consent creation, so the duplicate is not the resource the caller asked for. 409 may
+be the wrong answer there even if it is right everywhere else.
+
+
+
+### The open decision
+
+> Is changing 400 → 409 on a duplicate-create acceptable on a STABLE version?
+
+Not breaking in the usual sense — no field moves, no endpoint disappears — but an observable
+status-code change on versions clients are pinned to. Three defensible answers:
+
+- **Never on STABLE.** The 29 stay at 400 permanently; v6.0.0 onwards is correct. The table above
+ becomes the permanent explanation of why the codes differ by version.
+- **Yes, as a documented fix.** A duplicate-create returning 400 is a defect, and a client treating
+ 400 as "malformed, do not retry" already mishandles it. Ship with release notes.
+- **Only on DEPRECATED versions**, where the contract is end-of-life. Probably the worst of the
+ three: it makes the status depend on version *status* rather than version number, which is harder
+ to document than either absolute rule.
+
+Until this is answered, new endpoints use 409 and existing v1.4.0–v5.1.0 sites are left alone.
+
+### Constants that look related but are not endpoint checks
+
+| constant | where it lives | note |
+|---|---|---|
+| `DynamicEntityNameAlreadyExists` | `NewStyle.scala:3505`, `:3507`, `:3535` | name-collision validation inside NewStyle, not an endpoint duplicate check |
+| `FeaturedApiCollectionAlreadyExists` | `NewStyle.scala:4388`, `Http4s600.scala:14861` | the v6 site is handled; the NewStyle `RuntimeException` is a 500 path and is its own bug |
+| `CardAlreadyExists` | `MappedPhisicalCard.scala:204` | returned as a `Failure` at provider level; status comes from the box unwrap, never from a `booleanToFuture` |
+| `ConsumerKeyAlreadyExists` | nowhere | defined in `ErrorMessages.scala`, referenced by nothing — dead constant |
+
+## Siblings, not yet surveyed
+
+The same shape almost certainly applies to "not found" cases answering 400 instead of 404, and
+"forbidden" cases answering 400 instead of 403. Worth a sweep once the decision above is made — the
+answer there sets the precedent for all of them.
diff --git a/ideas/settlement_account_ids_question.md b/ideas/settlement_account_ids_question.md
index 1723bb40d3..c83b727286 100644
--- a/ideas/settlement_account_ids_question.md
+++ b/ideas/settlement_account_ids_question.md
@@ -359,8 +359,8 @@ This is the scary one. Possibly never worth doing — the lookup-table indirecti
## Out of scope for this work
-- **The bank_id `-` convention** discussed separately — settlement accounts live within a bank, so they ride on whatever bank_id shape the deployment has chosen. Tracked in `todo_account_id_uuid_enforcement.md`.
-- **Validating UUID account_ids at the API boundary** — separate workstream tracked in `todo_account_id_uuid_enforcement.md`.
+- **The bank_id `-` convention** discussed separately — settlement accounts live within a bank, so they ride on whatever bank_id shape the deployment has chosen. Tracked in `todo/todo_account_id_uuid_enforcement.md`.
+- **Validating UUID account_ids at the API boundary** — separate workstream tracked in `todo/todo_account_id_uuid_enforcement.md`.
- **Settlement account creation via the public API** — currently settlement accounts are only created by Boot/migration/connector init. If/when the API surface admits user-driven settlement-account creation, the lookup table needs an API too.
## File-by-file checklist (for whoever picks this up)
diff --git a/obp-api/src/main/scala/code/api/util/ConsentUtil.scala b/obp-api/src/main/scala/code/api/util/ConsentUtil.scala
index 34d97b2f63..54b9fa4c44 100644
--- a/obp-api/src/main/scala/code/api/util/ConsentUtil.scala
+++ b/obp-api/src/main/scala/code/api/util/ConsentUtil.scala
@@ -1370,7 +1370,6 @@ object Consent extends MdcLoggable {
myResources: Option[code.api.v6_0_0.PostConsentMyResourcesJson] = None // v5.1.0+ bodies only; STABLE bodies have no such field
): String = {
- lazy val currentConsumerId = Consumer.findAll(By(Consumer.createdByUserId, user.userId)).map(_.consumerId.get).headOption.getOrElse("")
val currentTimeInSeconds = System.currentTimeMillis / 1000
val timeInSeconds = validFrom match {
case Some(date) => date.getTime() / 1000
@@ -1436,7 +1435,13 @@ object Consent extends MdcLoggable {
createdByUserId=user.userId,
sub=APIUtil.generateUUID(),
iss=Constant.HostName,
- aud=consumerId.getOrElse(currentConsumerId),
+ // No fallback: aud is the Consumer this Consent is for, and there is no second source for that.
+ // It used to fall back to the granting User's first-registered Consumer, which put an arbitrary
+ // Consumer in the claim checkConsumerIsActiveAndMatched validates against -- while the stored row
+ // recorded no Consumer at all, so the two checks in checkConsent disagreed about the same Consent.
+ // Callers now resolve the Consumer once (NewStyle.function.resolveConsentConsumer) and cannot
+ // create a Consent without one, so Some is the only case reached in practice.
+ aud=consumerId.getOrElse(""),
jti=consentId,
iat=currentTimeInSeconds,
nbf=timeInSeconds,
@@ -2367,7 +2372,6 @@ object Consent extends MdcLoggable {
): String = {
val createdByUserId = user.map(_.userId).getOrElse("None")
- val currentConsumerId = Consumer.findAll(By(Consumer.createdByUserId, createdByUserId)).map(_.consumerId.get).headOption.getOrElse("")
val currentTimeInSeconds = System.currentTimeMillis / 1000
// No ExpirationDateTime means the consent never expires (UK spec: 0..1, open-ended if absent).
// Use Long.MaxValue rather than e.g. "now" (the convention createBerlinGroupConsentJWT falls
@@ -2411,7 +2415,7 @@ object Consent extends MdcLoggable {
createdByUserId = createdByUserId,
sub = APIUtil.generateUUID(),
iss = Constant.HostName,
- aud = consumerId.getOrElse(currentConsumerId),
+ aud = consumerId.getOrElse(""),
jti = consentId,
iat = currentTimeInSeconds,
nbf = currentTimeInSeconds,
diff --git a/obp-api/src/main/scala/code/api/util/ErrorMessages.scala b/obp-api/src/main/scala/code/api/util/ErrorMessages.scala
index 3bd41d5f1d..e12bad0742 100644
--- a/obp-api/src/main/scala/code/api/util/ErrorMessages.scala
+++ b/obp-api/src/main/scala/code/api/util/ErrorMessages.scala
@@ -860,6 +860,7 @@ object ErrorMessages {
val ConsentMyResourcesInvalid = "OBP-35042: The Consent's my_resources block is invalid. "
val ConsentMyResourcesMissing = "OBP-35043: The Consent does not cover this personal resource. A consent user may use a personal (my) endpoint only if the Consent lists the resource in my_resources with the needed action. "
val ConsentAccountAccessCannotBeGranted = "OBP-35041: The Consent's account access cannot be granted. The Consent has not been authorised; please retry the authorisation. "
+ val ConsentConsumerIsRequired = "OBP-35044: A Consent must name a Consumer. Send consumer_id in the request body naming the Consumer the Consent is for, or make the call as that Consumer. "
//Authorisations
val AuthorisationNotFound = "OBP-36001: Authorisation not found. Please specify valid values for PAYMENT_ID and AUTHORISATION_ID. "
diff --git a/obp-api/src/main/scala/code/api/util/NewStyle.scala b/obp-api/src/main/scala/code/api/util/NewStyle.scala
index be3c75ec6f..6808f8d2ee 100644
--- a/obp-api/src/main/scala/code/api/util/NewStyle.scala
+++ b/obp-api/src/main/scala/code/api/util/NewStyle.scala
@@ -666,6 +666,51 @@ object NewStyle extends MdcLoggable{
}
}
+ /**
+ * The Consumer a new Consent is pinned to: the one named in the request body, else the one
+ * making the call. A Consent that names neither cannot be created.
+ *
+ * A Consent is a bearer credential carrying the granting User's views and Roles, and the pin is
+ * what stops a leaked JWT being usable by whoever holds it: Consent.checkConsent refuses any
+ * call whose Consumer is not the Consent's own. So a Consent naming no Consumer is not a
+ * permissive Consent, it is a broken one -- unusable by every caller OBP can identify, and a
+ * pure bearer token on an instance that identifies none. Neither is worth creating, hence the
+ * 400 rather than a null column.
+ *
+ * The body value names the grantee, which is how the Portal creates a Consent for another
+ * application (Opey, OBP-MCP) to use: the caller is the grantor, consumer_id is the grantee, and
+ * skip_consent_sca_for_consumer_id_pairs keys off that pair. Omitting it therefore means "for
+ * myself", which is also what the consent-request flow has always done with the Consumer that
+ * lodged the request.
+ *
+ * ==Why the "Any application" consent is gone==
+ *
+ * Omitting consumer_id used to mean a Consent any application could present, and that was
+ * deliberate -- 898879f12 (2020-01-30, "Create consent - POC All application case") added a
+ * fallback putting the granting User's first-registered Consumer in the JWT's aud purely so the
+ * active-Consumer check had something to look up, while the stored row recorded no Consumer. It
+ * worked because checkConsent then compared nothing to the caller.
+ *
+ * b68e26fa6 / bd57de4a4 (2025-07, TPP access control) added tppIsConsentHolder, which compares
+ * the stored row to the calling Consumer. That made pinned Consents genuinely pinned -- the point
+ * of the change -- and in the same stroke made an "Any application" Consent usable by no
+ * identified application at all, since a null column never equals a real consumer id. So the
+ * capability had already been dead for over a year; what remained was a path that created
+ * Consents which silently did not work, and on an instance that identifies no Consumer at all
+ * (consumer_validation_method_for_consent=NONE with no certificates) a pure bearer token.
+ *
+ * If "Any application" is ever wanted back, do not restore the null column: store
+ * Constant.ALL_CONSUMERS and give tppIsConsentHolder an explicit branch for that literal, so the
+ * intent is visible in the row and in the API rather than inferred from an absence.
+ */
+ def resolveConsentConsumer(consumerIdFromBody: Option[String], callContext: Option[CallContext]): Future[Consumer] = {
+ val callerConsumerId = callContext.flatMap(_.consumer.toOption).map(_.consumerId.get)
+ consumerIdFromBody.filter(_.nonEmpty).orElse(callerConsumerId.filter(_.nonEmpty)) match {
+ case Some(consumerId) => checkConsumerByConsumerId(consumerId, callContext)
+ case None => Future(unboxFullOrFail(Empty, callContext, ConsentConsumerIsRequired, 400))
+ }
+ }
+
def getAccountWebhooks(queryParams: List[OBPQueryParam], callContext: Option[CallContext]): Future[List[AccountWebhook]] = {
AccountWebhook.accountWebhook.vend.getAccountWebhooksFuture(queryParams) map {
unboxFullOrFail(_, callContext, GetWebhooksError)
diff --git a/obp-api/src/main/scala/code/api/v3_1_0/Http4s310.scala b/obp-api/src/main/scala/code/api/v3_1_0/Http4s310.scala
index 38d6285a78..e2db02d7f9 100644
--- a/obp-api/src/main/scala/code/api/v3_1_0/Http4s310.scala
+++ b/obp-api/src/main/scala/code/api/v3_1_0/Http4s310.scala
@@ -121,61 +121,6 @@ object Http4s310 {
private val supportedConnectorNames =
NewStyle.function.getSupportedConnectorNames().mkString("[", " | ", "]")
- private val generalObpConsentText: String =
- s"""
- |
- |An OBP Consent allows the holder of the Consent to call one or more endpoints.
- |
- |Consents must be created and authorisied using SCA (Strong Customer Authentication).
- |
- |That is, Consents can be created by an authorised User via the OBP REST API but they must be confirmed via an out of band (OOB) mechanism such as a code sent to a mobile phone.
- |
- |Each Consent has one of the following states: ${ConsentStatus.values.toList.sorted.mkString(", ") }.
- |
- |Each Consent is bound to a consumer i.e. you need to identify yourself over request header value Consumer-Key.
- |For example:
- |GET /obp/v4.0.0/users/current HTTP/1.1
- |Host: 127.0.0.1:8080
- |Consent-JWT: eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOlt7InJvbGVfbmFtZSI6IkNhbkdldEFueVVzZXIiLCJiYW5rX2lkIjoiIn
- |1dLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIzNDc1MDEzZi03YmY5LTQyNj
- |EtOWUxYy0xZTdlNWZjZTJlN2UiLCJhdWQiOiI4MTVhMGVmMS00YjZhLTQyMDUtYjExMi1lNDVmZDZmNGQzYWQiLCJuYmYiOjE1ODA3NDE2NjcsIml
- |zcyI6Imh0dHA6XC9cLzEyNy4wLjAuMTo4MDgwIiwiZXhwIjoxNTgwNzQ1MjY3LCJpYXQiOjE1ODA3NDE2NjcsImp0aSI6ImJkYzVjZTk5LTE2ZTY
- |tNDM4Yi1hNjllLTU3MTAzN2RhMTg3OCIsInZpZXdzIjpbXX0.L3fEEEhdCVr3qnmyRKBBUaIQ7dk1VjiFaEBW8hUNjfg
- |
- |Consumer-Key: ejznk505d132ryomnhbx1qmtohurbsbb0kijajsk
- |cache-control: no-cache
- |
- |Maximum time to live of the token is specified over props value consents.max_time_to_live. In case isn't defined default value is 7776000 seconds (90 days).
- |
- |Example of POST JSON:
- |{
- | "everything": false,
- | "views": [
- | {
- | "bank_id": "GENODEM1GLS",
- | "account_id": "8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0",
- | "view_id": "${Constant.SYSTEM_OWNER_VIEW_ID}"
- | }
- | ],
- | "entitlements": [
- | {
- | "bank_id": "GENODEM1GLS",
- | "role_name": "CanGetCustomersAtOneBank"
- | }
- | ],
- | "consumer_id": "7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",
- | "email": "eveline@example.com",
- | "valid_from": "2020-02-07T08:43:34Z",
- | "time_to_live": 3600
- |}
- |Please note that only optional fields are: consumer_id, valid_from and time_to_live.
- |In case you omit they the default values are used:
- |consumer_id = consumer of current user
- |valid_from = current time
- |time_to_live = consents.max_time_to_live
- |
- """.stripMargin
-
object Implementations3_1_0 {
val prefixPath: Path = Root / ApiPathZero.toString / implementedInApiVersion.toString
@@ -199,6 +144,11 @@ object Http4s310 {
|That is, Consents can be created by an authorised User via the OBP REST API but they must be confirmed via an out of band (OOB) mechanism such as a code sent to a mobile phone.
|
|Each Consent has one of the following states: ${code.consent.ConsentStatus.values.toList.sorted.mkString(", ")}.
+ |
+ |Each Consent is pinned to one Consumer, and only that Consumer can present the resulting Consent JWT -- any
+ |other gets ConsentNotFound. Set consumer_id in the body when the Consent is for a different application than
+ |the caller, for example a portal creating a Consent for an agent to use. Omit it when the Consent is for the
+ |caller. A Consent that names no Consumer is refused.
|""".stripMargin
private val supportedConnectorNames = NewStyle.function.getSupportedConnectorNames().mkString("[", " | ", "]")
@@ -4464,13 +4414,12 @@ object Http4s310 {
consentJson.views.forall(rv => assignedViews.exists(e =>
e.view_id == rv.view_id && e.bank_id == rv.bank_id && e.account_id == rv.account_id))
}
- consumerTuple <- consentJson.consumer_id match {
- case Some(id) => NewStyle.function.checkConsumerByConsumerId(id, Some(cc)) map {
- c => (Some(c.consumerId.get), c.description, Some(c))
- }
- case None => Future((None, "Any application", None))
- }
- (consumerId, applicationText, consumer) = consumerTuple
+ // Every Consent names the Consumer it is for -- the body's consumer_id, else the caller.
+ // NewStyle.function.resolveConsentConsumer says why a Consent may not be created without one.
+ consentConsumer <- NewStyle.function.resolveConsentConsumer(consentJson.consumer_id, Some(cc))
+ consumerId = Some(consentConsumer.consumerId.get)
+ applicationText = consentConsumer.description
+ consumer = Some(consentConsumer)
challengeAnswer = Props.mode match {
case Props.RunModes.Test => Consent.challengeAnswerAtTestEnvironment
case _ => SecureRandomUtil.numeric()
@@ -4489,7 +4438,7 @@ object Http4s310 {
i => connectorEmptyResponse(i, Some(cc))
}
grantorConsumerId = cc.consumer.toOption.map(_.consumerId.get).getOrElse("Unknown")
- granteeConsumerId = consentJson.consumer_id.getOrElse("Unknown")
+ granteeConsumerId = consentConsumer.consumerId.get
shouldSkipConsentSca = APIUtil.skipConsentScaForConsumerIdPairs.contains(
APIUtil.ConsumerIdPair(grantorConsumerId, granteeConsumerId))
_ <- if (shouldSkipConsentSca) {
@@ -4628,6 +4577,7 @@ object Http4s310 {
ViewsAllowedInConsent,
ConsumerNotFoundByConsumerId,
ConsumerIsDisabled,
+ ConsentConsumerIsRequired,
InvalidConnectorResponse,
UnknownError
),
@@ -4709,6 +4659,7 @@ object Http4s310 {
ViewsAllowedInConsent,
ConsumerNotFoundByConsumerId,
ConsumerIsDisabled,
+ ConsentConsumerIsRequired,
MissingPropsValueAtThisInstance,
SmsServerNotResponding,
InvalidConnectorResponse,
@@ -4789,6 +4740,7 @@ object Http4s310 {
ViewsAllowedInConsent,
ConsumerNotFoundByConsumerId,
ConsumerIsDisabled,
+ ConsentConsumerIsRequired,
MissingPropsValueAtThisInstance,
SmsServerNotResponding,
InvalidConnectorResponse,
diff --git a/obp-api/src/main/scala/code/api/v5_0_0/Http4s500.scala b/obp-api/src/main/scala/code/api/v5_0_0/Http4s500.scala
index 14b28a88e3..2283aa4606 100644
--- a/obp-api/src/main/scala/code/api/v5_0_0/Http4s500.scala
+++ b/obp-api/src/main/scala/code/api/v5_0_0/Http4s500.scala
@@ -912,7 +912,7 @@ object Http4s500 {
|
|Optional body fields of note:
|
- |- `consumer_id`: if set, the resulting Consent (created when the User answers this request) will be pinned to this consumer instead of the creator. Use only when the consent is intended for a different application than the one creating the request. Most TPPs should omit this field — when omitted, the resulting Consent is pinned to the creator. Note: this override is being deprecated; v6.0.0 will pin the resulting Consent to the creator unconditionally.
+ |- `consumer_id`: names the consumer the resulting Consent (created when the User answers this request) is for. Set it when the Consent is intended for a different application than the one creating the request — for example a portal creating a Consent for an agent to use later. Most TPPs should omit it; when omitted, the resulting Consent is pinned to the consumer that created this request. Either way the resulting Consent names exactly one consumer and only that consumer can present it, so an omitted `consumer_id` is not a wildcard.
|- `email` / `phone_number`: surface in the SCA challenge if the User chooses EMAIL or SMS at answer time.
|- `valid_from` / `time_to_live`: control the lifetime of the resulting Consent.
|
@@ -1276,19 +1276,19 @@ object Http4s500 {
e.view_id == rv.view_id && e.bank_id == rv.bank_id && e.account_id == rv.account_id))
}
} yield ()
- calculatedConsumerId = consentRequestJson.consumer_id.orElse(Some(createdConsentRequest.consumerId))
- (consumerIdOpt, applicationText) <- calculatedConsumerId match {
- case Some(id) =>
- NewStyle.function.checkConsumerByConsumerId(id, callContextOpt).map { c =>
- (Some(c.consumerId.get), c.description)
- }
- case None => Future.successful((None, "Any application"))
- }
+ // Every Consent names the Consumer it is for: the body's consumer_id, else the Consumer that
+ // lodged the consent request, else the caller. NewStyle.function.resolveConsentConsumer says
+ // why a Consent may not be created without one. One resolution feeds both the JWT's aud and
+ // the stored row, so the two can no longer disagree about who the Consent is for.
+ consentConsumer <- NewStyle.function.resolveConsentConsumer(
+ consentRequestJson.consumer_id.orElse(Option(createdConsentRequest.consumerId)), callContextOpt)
+ consumerIdOpt = Some(consentConsumer.consumerId.get)
+ applicationText = consentConsumer.description
challengeAnswer = Props.mode match {
case Props.RunModes.Test => Consent.challengeAnswerAtTestEnvironment
case _ => SecureRandomUtil.numeric()
}
- consumer = Consumers.consumers.vend.getConsumerByConsumerId(calculatedConsumerId.getOrElse("None"))
+ consumer = Some(consentConsumer)
createdConsent <- Future(Consents.consentProvider.vend.createObpConsent(
user, challengeAnswer, Some(consentRequestId), consumer))
.map(i => connectorEmptyResponse(i, callContextOpt))
@@ -1325,7 +1325,7 @@ object Http4s500 {
_ <- Future(Consents.consentProvider.vend.setValidUntil(createdConsent.consentId, validUntil))
.map(i => connectorEmptyResponse(i, callContextOpt))
grantorConsumerId = callContextOpt.flatMap(_.consumer.toOption.map(_.consumerId.get)).getOrElse("Unknown")
- granteeConsumerId = postConsentBodyCommonJson.consumer_id.getOrElse("Unknown")
+ granteeConsumerId = consentConsumer.consumerId.get
shouldSkipConsentScaForConsumerIdPair = APIUtil.skipConsentScaForConsumerIdPairs.contains(
APIUtil.ConsumerIdPair(grantorConsumerId, granteeConsumerId))
mappedConsent <- if (shouldSkipConsentScaForConsumerIdPair) {
@@ -1376,7 +1376,7 @@ object Http4s500 {
private val createConsentByConsentRequestIdCommonErrors = List(
AuthenticatedUserIsRequired, BankNotFound, InvalidJsonFormat,
ConsentAllowedScaMethods, RolesAllowedInConsent, ViewsAllowedInConsent,
- ConsumerNotFoundByConsumerId, ConsumerIsDisabled,
+ ConsumerNotFoundByConsumerId, ConsumerIsDisabled, ConsentConsumerIsRequired,
InvalidConnectorResponse, UnknownError
)
@@ -1391,7 +1391,7 @@ object Http4s500 {
|
|An SCA challenge code is sent to the email address that was supplied in the Create Consent Request body. The User then completes SCA via Answer Consent Challenge, which moves the Consent from INITIATED to ACCEPTED.
|
- |Pinning: the resulting Consent is pinned to a single consumer at creation. The pinned consumer is taken from the `consumer_id` field of the original Create Consent Request body if present, otherwise from the consumer that created the Request. After creation, only that consumer can present the resulting Consent JWT — any other consumer presenting it gets ConsentNotFound (consumer mismatch).
+ |Pinning: the resulting Consent is pinned to a single consumer at creation. The pinned consumer is taken from the `consumer_id` field of the original Create Consent Request body if present, otherwise from the consumer that created the Request, otherwise from the consumer making this call. If none of those names a consumer the Consent is not created and this endpoint returns ConsentConsumerIsRequired — a Consent that names no consumer could be presented by nobody. After creation, only the pinned consumer can present the resulting Consent JWT — any other consumer presenting it gets ConsentNotFound (consumer mismatch).
|
|Each Consent Request can be answered exactly once. A second call returns ConsentRequestIsInvalid.
|
@@ -1418,7 +1418,7 @@ object Http4s500 {
|
|An SCA challenge code is sent to the phone number that was supplied in the Create Consent Request body. The User then completes SCA via Answer Consent Challenge, which moves the Consent from INITIATED to ACCEPTED.
|
- |Pinning: the resulting Consent is pinned to a single consumer at creation. The pinned consumer is taken from the `consumer_id` field of the original Create Consent Request body if present, otherwise from the consumer that created the Request. After creation, only that consumer can present the resulting Consent JWT — any other consumer presenting it gets ConsentNotFound (consumer mismatch).
+ |Pinning: the resulting Consent is pinned to a single consumer at creation. The pinned consumer is taken from the `consumer_id` field of the original Create Consent Request body if present, otherwise from the consumer that created the Request, otherwise from the consumer making this call. If none of those names a consumer the Consent is not created and this endpoint returns ConsentConsumerIsRequired — a Consent that names no consumer could be presented by nobody. After creation, only the pinned consumer can present the resulting Consent JWT — any other consumer presenting it gets ConsentNotFound (consumer mismatch).
|
|Each Consent Request can be answered exactly once. A second call returns ConsentRequestIsInvalid.
|
@@ -1445,7 +1445,7 @@ object Http4s500 {
|
|IMPLICIT means no SCA challenge is sent. The Consent is immediately ACCEPTED. Use only in flows where the User has already been strongly authenticated by upstream means; for production use behind a public TPP, prefer EMAIL or SMS.
|
- |Pinning: the resulting Consent is pinned to a single consumer at creation. The pinned consumer is taken from the `consumer_id` field of the original Create Consent Request body if present, otherwise from the consumer that created the Request. After creation, only that consumer can present the resulting Consent JWT — any other consumer presenting it gets ConsentNotFound (consumer mismatch).
+ |Pinning: the resulting Consent is pinned to a single consumer at creation. The pinned consumer is taken from the `consumer_id` field of the original Create Consent Request body if present, otherwise from the consumer that created the Request, otherwise from the consumer making this call. If none of those names a consumer the Consent is not created and this endpoint returns ConsentConsumerIsRequired — a Consent that names no consumer could be presented by nobody. After creation, only the pinned consumer can present the resulting Consent JWT — any other consumer presenting it gets ConsentNotFound (consumer mismatch).
|
|Each Consent Request can be answered exactly once. A second call returns ConsentRequestIsInvalid.
|
diff --git a/obp-api/src/main/scala/code/api/v5_1_0/Http4s510.scala b/obp-api/src/main/scala/code/api/v5_1_0/Http4s510.scala
index 120e2986a9..532878ac46 100644
--- a/obp-api/src/main/scala/code/api/v5_1_0/Http4s510.scala
+++ b/obp-api/src/main/scala/code/api/v5_1_0/Http4s510.scala
@@ -4956,10 +4956,12 @@ object Http4s510 {
|}
|Please note that only optional fields are: consumer_id, valid_from and time_to_live.
|In case you omit they the default values are used:
- |consumer_id = consumer of current user
+ |consumer_id = the Consumer making this call
|valid_from = current time
|time_to_live = consents.max_time_to_live
|
+ |Every Consent is pinned to one Consumer, and only that Consumer can present the resulting Consent JWT -- any other gets ConsentNotFound. Set consumer_id when the Consent is for a different application than the caller, for example a portal creating a Consent for an agent to use. Omit it when the Consent is for the caller. A Consent that names no Consumer is refused.
+ |
""".stripMargin
// ─── createConsent (IMPLICIT alias) — handles SCA: EMAIL/SMS/IMPLICIT ──
@@ -5050,11 +5052,11 @@ object Http4s510 {
assignedViews.exists(e =>
e.view_id == rv.view_id && e.bank_id == rv.bank_id && e.account_id == rv.account_id))
}
- consumerFromBodyTuple <- consentJson.consumer_id match {
- case Some(id) => NewStyle.function.checkConsumerByConsumerId(id, callContextOpt).map(c => (Some(c), c.description))
- case None => Future.successful((None: Option[Consumer], "Any application"))
- }
- (consumerFromRequestBody, applicationText) = consumerFromBodyTuple
+ // Every Consent names the Consumer it is for -- the body's consumer_id, else the caller.
+ // NewStyle.function.resolveConsentConsumer says why a Consent may not be created without one.
+ consentConsumer <- NewStyle.function.resolveConsentConsumer(consentJson.consumer_id, callContextOpt)
+ consumerFromRequestBody = Some(consentConsumer)
+ applicationText = consentConsumer.description
challengeAnswer = Props.mode match {
case Props.RunModes.Test => Consent.challengeAnswerAtTestEnvironment
case _ => SecureRandomUtil.numeric()
@@ -5074,7 +5076,7 @@ object Http4s510 {
_ <- Future(Consents.consentProvider.vend.setValidUntil(createdConsent.consentId, validUntil))
.map(i => connectorEmptyResponse(i, callContextOpt))
grantorConsumerId = callContextOpt.flatMap(_.consumer.toOption.map(_.consumerId.get)).getOrElse("Unknown")
- granteeConsumerId = consentJson.consumer_id.getOrElse("Unknown")
+ granteeConsumerId = consentConsumer.consumerId.get
shouldSkip = APIUtil.skipConsentScaForConsumerIdPairs.contains(
APIUtil.ConsumerIdPair(grantorConsumerId, granteeConsumerId))
mappedConsent <- if (shouldSkip) {
@@ -5155,7 +5157,10 @@ object Http4s510 {
| "consumer_id": "7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",
|}
|
- |Please note that consumer_id is optional field
+ |Please note that consumer_id is an optional field. It names the Consumer the Consent is for --
+ |set it when the Consent is for a different application than the caller (for example a portal
+ |creating a Consent for an agent to use), omit it when the Consent is for the caller. Either way
+ |the resulting Consent is pinned to exactly one Consumer, and only that Consumer can present it.
|Example 2:
|{
| "everything": true,
@@ -5187,6 +5192,7 @@ object Http4s510 {
postConsentImplicitJsonV310, consentJsonV310,
List(AuthenticatedUserIsRequired, BankNotFound, InvalidJsonFormat, ConsentAllowedScaMethods,
RolesAllowedInConsent, RolesForbiddenInConsent, ViewsAllowedInConsent, ConsumerNotFoundByConsumerId, ConsumerIsDisabled,
+ ConsentConsumerIsRequired,
MissingPropsValueAtThisInstance, SmsServerNotResponding, InvalidConnectorResponse, UnknownError),
apiTagConsent :: apiTagPSD2AIS :: apiTagPsd2 :: Nil,
None,
diff --git a/obp-api/src/main/scala/code/api/v6_0_0/Http4s600.scala b/obp-api/src/main/scala/code/api/v6_0_0/Http4s600.scala
index e67c4e6d2e..eec9baf1d0 100644
--- a/obp-api/src/main/scala/code/api/v6_0_0/Http4s600.scala
+++ b/obp-api/src/main/scala/code/api/v6_0_0/Http4s600.scala
@@ -1343,11 +1343,11 @@ object Http4s600 {
e.view_id == rv.view_id && e.bank_id == rv.bank_id && e.account_id == rv.account_id))
}
_ <- Consent.validateMyResources(consentJson.my_resources, callContextOpt)
- consumerFromBodyTuple <- consentJson.consumer_id match {
- case Some(id) => NewStyle.function.checkConsumerByConsumerId(id, callContextOpt).map(c => (Some(c), c.description))
- case None => Future.successful((None: Option[Consumer], "Any application"))
- }
- (consumerFromRequestBody, applicationText) = consumerFromBodyTuple
+ // Every Consent names the Consumer it is for -- the body's consumer_id, else the caller.
+ // NewStyle.function.resolveConsentConsumer says why a Consent may not be created without one.
+ consentConsumer <- NewStyle.function.resolveConsentConsumer(consentJson.consumer_id, callContextOpt)
+ consumerFromRequestBody = Some(consentConsumer)
+ applicationText = consentConsumer.description
challengeAnswer = Props.mode match {
case Props.RunModes.Test => Consent.challengeAnswerAtTestEnvironment
case _ => SecureRandomUtil.numeric()
@@ -1368,7 +1368,7 @@ object Http4s600 {
_ <- Future(Consents.consentProvider.vend.setValidUntil(createdConsent.consentId, validUntil))
.map(i => APIUtil.connectorEmptyResponse(i, callContextOpt))
grantorConsumerId = callContextOpt.flatMap(_.consumer.toOption.map(_.consumerId.get)).getOrElse("Unknown")
- granteeConsumerId = consentJson.consumer_id.getOrElse("Unknown")
+ granteeConsumerId = consentConsumer.consumerId.get
shouldSkip = APIUtil.skipConsentScaForConsumerIdPairs.contains(
APIUtil.ConsumerIdPair(grantorConsumerId, granteeConsumerId))
mappedConsent <- if (shouldSkip) {
@@ -1449,7 +1449,10 @@ object Http4s600 {
| "consumer_id": "7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",
|}
|
- |Please note that consumer_id is optional field
+ |Please note that consumer_id is an optional field. It names the Consumer the Consent is for --
+ |set it when the Consent is for a different application than the caller (for example a portal
+ |creating a Consent for an agent to use), omit it when the Consent is for the caller. Either way
+ |the resulting Consent is pinned to exactly one Consumer, and only that Consumer can present it.
|Example 2:
|{
| "everything": true,
@@ -1481,6 +1484,7 @@ object Http4s600 {
postConsentBodyJsonV600, consentJsonV310,
List(AuthenticatedUserIsRequired, BankNotFound, InvalidJsonFormat, ConsentAllowedScaMethods,
RolesAllowedInConsent, RolesForbiddenInConsent, ViewsAllowedInConsent, ConsumerNotFoundByConsumerId, ConsumerIsDisabled,
+ ConsentConsumerIsRequired,
MissingPropsValueAtThisInstance, SmsServerNotResponding, InvalidConnectorResponse, UnknownError),
apiTagConsent :: apiTagPSD2AIS :: apiTagPsd2 :: Nil,
None,
diff --git a/obp-api/src/main/scala/code/bankconnectors/LocalMappedConnector.scala b/obp-api/src/main/scala/code/bankconnectors/LocalMappedConnector.scala
index 6aaa41f96f..b2354a5463 100644
--- a/obp-api/src/main/scala/code/bankconnectors/LocalMappedConnector.scala
+++ b/obp-api/src/main/scala/code/bankconnectors/LocalMappedConnector.scala
@@ -3420,6 +3420,35 @@ object LocalMappedConnector extends Connector with MdcLoggable {
(getCounterpartiesLegacy(thisBankId, thisAccountId, viewId, callContext) map (i => i._1), callContext)
}
+ /**
+ * Who a newly created Bank is recorded as having been created by.
+ *
+ * The HUMAN, not the caller. Under a Consent the caller is the per-consent agent identity, which
+ * dies with the Consent — a bank stamped with it would drop out of every "banks created by me"
+ * read the moment the consent was revoked. Seen in the wild 2026-09-03: a bank created through
+ * Opey under a temporary consent had `createdbyuserid` set to the consent user.
+ *
+ * Two sources, in the order CallContext.onBehalfOfUserId uses:
+ * - the request layer (`consentCreator` / `consenter`) knows things the stored chain cannot,
+ * because a Berlin Group / UK consent carries its consenter on the request;
+ * - otherwise the attribution, which walks the stored consent chain, applies the
+ * `BankCreator` policy and is the one place a delegated write is logged.
+ *
+ * ON_BEHALF_OF_USER_ID_PLAN.md, Phase 2.
+ */
+ private def bankCreatorUserId(callContext: Option[CallContext]): String =
+ callContext.flatMap(_.user.toOption).map(_.userId).filter(_.nonEmpty) match {
+ case None => ""
+ case Some(callerUserId) =>
+ val fromStoredChain = Users.users.vend
+ .attributedUserId(callerUserId, code.users.UserReference.BankCreator)
+ .openOr(callerUserId)
+ callContext
+ .flatMap(cc => cc.consentCreator.or(cc.consenter).toOption)
+ .map(_.userId).filter(_.nonEmpty)
+ .getOrElse(fromStoredChain)
+ }
+
override def createOrUpdateBank(
bankId: String,
fullBankName: String,
@@ -3460,7 +3489,7 @@ object LocalMappedConnector extends Connector with MdcLoggable {
.national_identifier(national_identifier)
.mBankRoutingScheme(bankRoutingScheme)
.mBankRoutingAddress(bankRoutingAddress)
- .CreatedByUserId(callContext.map(_.user).flatMap(_.toOption).map(_.userId).getOrElse(""))
+ .CreatedByUserId(bankCreatorUserId(callContext))
.saveMe()
} ?~! ErrorMessages.UpdateBankError
}
diff --git a/obp-api/src/test/scala/code/api/sweep/OnBehalfOfOwnershipSweepTest.scala b/obp-api/src/test/scala/code/api/sweep/OnBehalfOfOwnershipSweepTest.scala
index 645d2a38ef..155cf97be4 100644
--- a/obp-api/src/test/scala/code/api/sweep/OnBehalfOfOwnershipSweepTest.scala
+++ b/obp-api/src/test/scala/code/api/sweep/OnBehalfOfOwnershipSweepTest.scala
@@ -159,10 +159,6 @@ class OnBehalfOfOwnershipSweepTest extends ServerSetupWithTestData with DefaultU
"TagUser" -> mechanicalBatch,
"WhereTagUser" -> mechanicalBatch,
"TransactionImageUser" -> mechanicalBatch,
- "BankCreator" ->
- ("seen in the wild 2026-09-03: a bank created through a Consent has createdbyuserid = the " +
- "consent user. Nothing breaks today because createMyBank's self-service limit counts via " +
- "humanAndAgentUserIds, but 'banks created by me' reads will miss it."),
"AccountAccessRequestTarget" ->
("explicit target, so the endpoint refuses a consent user rather than redirecting -- covered " +
"by ExplicitTargetConsentUserSweepTest. The provider redirect is unreachable from the API."),
diff --git a/obp-api/src/test/scala/code/api/util/AgentDelegationTest.scala b/obp-api/src/test/scala/code/api/util/AgentDelegationTest.scala
index a060b5ef58..fc01379b0d 100644
--- a/obp-api/src/test/scala/code/api/util/AgentDelegationTest.scala
+++ b/obp-api/src/test/scala/code/api/util/AgentDelegationTest.scala
@@ -34,9 +34,11 @@ import code.api.util.APIUtil.generateUUID
import code.api.util.{Consent, ConsentLinkedCustomers, ConsentMyResources}
import code.api.v1_4_0.JSONFactory1_4_0.TransactionRequestAccountJsonV140
import code.api.v2_1_0.TransactionRequestBodySandBoxTanJSON
+import code.bankconnectors.LocalMappedConnector
import code.consent.MappedConsent
import code.model.dataAccess.ResourceUser
import code.setup.ServerSetup
+import code.model.dataAccess.MappedBank
import code.transactionrequests.{MappedTransactionRequest, MappedTransactionRequestProvider}
import code.users.{AttributionPolicy, UserReference, Users}
import com.openbankproject.commons.model.{AccountId, AmountOfMoney, AmountOfMoneyJsonV121, BankAccount, BankAccountCommons, BankId, BankIdAccountId, TransactionRequestCharge, TransactionRequestId, TransactionRequestType}
@@ -565,4 +567,55 @@ class AgentDelegationTest extends ServerSetup {
storedField(row.mOnBehalfOfUserId.get) shouldBe agent.userId
}
}
+
+ feature("Banks record the human who created them (UserReference.BankCreator)") {
+
+ /** Create a bank through the connector as `callerUserId`, and return the stored row. */
+ def createBankAs(callContext: Option[CallContext]): MappedBank = {
+ val bankId = s"agent-delegation-bank-${generateUUID().take(8)}"
+ LocalMappedConnector.createOrUpdateBank(
+ bankId = bankId, fullBankName = "Agent Delegation Test Bank", shortBankName = "ADTB",
+ logoURL = "", websiteURL = "", swiftBIC = "", national_identifier = "",
+ bankRoutingScheme = "", bankRoutingAddress = "", callContext = callContext
+ ).openOrThrowException("expected the bank to be created")
+ MappedBank.find(By(MappedBank.permalink, bankId))
+ .openOrThrowException("expected the bank row to have been written")
+ }
+
+ scenario("a bank created by an original user is created by that user", AgentDelegationTag) {
+ val human = createUser()
+ storedField(createBankAs(Some(CallContext(user = Full(human)))).CreatedByUserId.get) shouldBe human.userId
+ }
+
+ // The defect this closes, seen in the wild 2026-09-03: a bank created through Opey under a
+ // temporary consent had createdbyuserid = the consent user, so it would drop out of every
+ // "banks created by me" read once that consent was revoked.
+ scenario("a bank created by a consent user is created by its on-behalf-of user", AgentDelegationTag) {
+ val human = createUser()
+ val consent = MappedConsent.create.mUserId(human.userId).saveMe()
+ val agent = createUser(createdByConsentId = Some(consent.consentId))
+ val row = createBankAs(Some(CallContext(user = Full(agent))))
+ storedField(row.CreatedByUserId.get) shouldBe human.userId
+ storedField(row.CreatedByUserId.get) should not be agent.userId
+ }
+
+ scenario("a consent user whose consent has no human yet creates for itself (fails closed)", AgentDelegationTag) {
+ val consent = MappedConsent.create.mUserId("").saveMe()
+ val agent = createUser(createdByConsentId = Some(consent.consentId))
+ storedField(createBankAs(Some(CallContext(user = Full(agent)))).CreatedByUserId.get) shouldBe agent.userId
+ }
+
+ // Berlin Group / UK consents carry their consenter on the request rather than in the stored
+ // chain, so the request layer has to win -- the same order CallContext.onBehalfOfUserId uses.
+ scenario("the request layer's consenter takes precedence over the stored chain", AgentDelegationTag) {
+ val consenter = createUser()
+ val caller = createUser()
+ val row = createBankAs(Some(CallContext(user = Full(caller), consenter = Full(consenter))))
+ storedField(row.CreatedByUserId.get) shouldBe consenter.userId
+ }
+
+ scenario("no authenticated user leaves the creator empty", AgentDelegationTag) {
+ storedField(createBankAs(None).CreatedByUserId.get) shouldBe ""
+ }
+ }
}
diff --git a/obp-api/src/test/scala/code/api/v6_0_0/ConsentConsumerPinningTest.scala b/obp-api/src/test/scala/code/api/v6_0_0/ConsentConsumerPinningTest.scala
new file mode 100644
index 0000000000..f228dfcc40
--- /dev/null
+++ b/obp-api/src/test/scala/code/api/v6_0_0/ConsentConsumerPinningTest.scala
@@ -0,0 +1,254 @@
+/**
+Open Bank Project - API
+Copyright (C) 2011-2026, TESOBE GmbH.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see .
+
+Email: contact@tesobe.com
+TESOBE GmbH.
+Osloer Strasse 16/17
+Berlin 13359, Germany
+
+This product includes software developed at
+TESOBE (http://www.tesobe.com/)
+
+ */
+package code.api.v6_0_0
+
+import code.api.RequestHeader
+import code.api.util.APIUtil.OAuth._
+import code.api.util.Consent
+import code.api.util.ErrorMessages._
+import code.api.v3_1_0.{ConsentJsonV310, PostConsentChallengeJsonV310}
+import code.consumer.Consumers
+import code.setup.TestConnectorSetupWithStandardPermissions
+import com.openbankproject.commons.model.ErrorMessage
+import com.openbankproject.commons.util.ApiVersion
+import net.liftweb.util.Helpers.randomString
+import org.json4s.JsonDSL._
+import org.json4s._
+import org.json4s.native.Serialization.write
+import org.scalatest.Tag
+
+/**
+ * Every Consent names exactly one Consumer, and only that Consumer may present it.
+ *
+ * Two independent gates enforce this, and they key off different inputs -- which is why both are
+ * exercised here rather than one standing in for the other:
+ *
+ * - `Consent.tppIsConsentHolder` compares consumer *ids*: the Consent's stored consumer_id against
+ * whichever Consumer the request layer resolved. It runs first, before signature, expiry and
+ * status, and refuses with ConsentNotFound so a caller cannot tell a Consent that is not theirs
+ * from one that does not exist.
+ * - `Consent.checkConsumerIsActiveAndMatched` looks the Consumer up by the JWT's `aud` claim and
+ * then compares *credential material from one specific header* -- which header depends on
+ * consumer_validation_method_for_consent. It catches the cases the first gate cannot see: a
+ * Consumer disabled after the Consent was granted, and a caller whose identifying credential is
+ * not the credential the instance validates.
+ *
+ * The pre-existing consent suites cover the "caller OBP cannot identify" shape (no Consumer-Key, or
+ * an unknown one -- both leave CallContext.consumer empty). What they do not cover, and what this
+ * suite adds, is a caller that is a different *real, active* Consumer, the grantor/grantee split the
+ * portal-creates-a-Consent-for-an-agent flow depends on, and the header asymmetry above.
+ */
+class ConsentConsumerPinningTest extends V600ServerSetup with TestConnectorSetupWithStandardPermissions {
+
+ object VersionOfApi extends Tag(ApiVersion.v6_0_0.toString)
+ object ConsentPinning extends Tag("ConsentConsumerPinning")
+
+ // Consumer A is the one user1's OAuth credentials sign with; Consumer B is user2's. Both are real
+ // and active, which is the point: every existing test of a refused Consent leaves the caller
+ // unidentified, so nothing until now has exercised "identified, active, and not the right one".
+ private lazy val consumerAKey = user1.map(_._1.key).getOrElse("SHOULD_NOT_HAPPEN")
+ private lazy val consumerBKey = user2.map(_._1.key).getOrElse("SHOULD_NOT_HAPPEN")
+ private lazy val consumerAId = testConsumer.consumerId.get
+ private lazy val consumerBId = testConsumer2.consumerId.get
+
+ private def consumerKeyHeader(key: String) = List((RequestHeader.`Consumer-Key`, key))
+ private def consentJwtHeader(jwt: String) = List((RequestHeader.`Consent-JWT`, jwt))
+
+ /** A Consumer of this suite's own, so disabling it or giving it a certificate cannot disturb others. */
+ private def createLocalConsumer(name: String, certificate: Option[String] = None) =
+ Consumers.consumers.vend.createConsumer(
+ key = Some(randomString(40).toLowerCase),
+ secret = Some(randomString(40).toLowerCase),
+ isActive = Some(true),
+ name = Some(name),
+ appType = None,
+ description = Some(s"$name description"),
+ developerEmail = Some("eveline@example.com"),
+ redirectURL = None,
+ createdByUserId = Some(resourceUser1.userId),
+ clientCertificate = certificate,
+ company = None,
+ logoURL = None
+ ).openOrThrowException("Could not create the test Consumer")
+
+ private def consentBody(consumerId: Option[String]): JValue = {
+ val base: JObject =
+ ("everything" -> false) ~
+ ("views" -> JArray(Nil)) ~
+ ("entitlements" -> JArray(Nil)) ~
+ ("time_to_live" -> 3600)
+ consumerId.map(id => base ~ ("consumer_id" -> id)).getOrElse(base)
+ }
+
+ /**
+ * Create a Consent as user1 and answer its challenge, returning the JWT. The creating call always
+ * signs as Consumer A -- `consumerId` is who the Consent is *for*, which is a separate thing and
+ * is exactly what the grantee scenarios below vary.
+ */
+ private def acceptedConsentJwt(consumerId: Option[String]): String = {
+ setPropsValues("consents.allowed" -> "true", "consumer_validation_method_for_consent" -> "CONSUMER_KEY_VALUE")
+ val created = makePostRequest(
+ (v6_0_0_Request / "my" / "consents" / "IMPLICIT").POST <@ (user1),
+ write(consentBody(consumerId)), consumerKeyHeader(consumerAKey))
+ created.code should equal(201)
+ val consent = created.body.extract[ConsentJsonV310]
+ val answered = makePostRequest(
+ (v5_1_0_Request / "banks" / testBankId1.value / "consents" / consent.consent_id / "challenge").POST <@ (user1),
+ write(PostConsentChallengeJsonV310(answer = Consent.challengeAnswerAtTestEnvironment)))
+ answered.code should equal(201)
+ consent.jwt
+ }
+
+ /** Present a Consent against an endpoint that needs no view and no role of its own. */
+ private def callAsConsent(jwt: String, extraHeaders: List[(String, String)]) =
+ makeGetRequest((v5_1_0_Request / "users" / "current").GET, consentJwtHeader(jwt) ::: extraHeaders)
+
+ feature("A Consent may only be presented by the Consumer it names") {
+
+ scenario("the Consumer the Consent names may present it", VersionOfApi, ConsentPinning) {
+ val jwt = acceptedConsentJwt(Some(consumerAId))
+ When("Consumer A presents a Consent naming Consumer A")
+ val response = callAsConsent(jwt, consumerKeyHeader(consumerAKey))
+ Then("We should get a 200")
+ response.code should equal(200)
+ }
+
+ scenario("a second, active Consumer may not present a Consent naming another", VersionOfApi, ConsentPinning) {
+ val jwt = acceptedConsentJwt(Some(consumerAId))
+ When("Consumer B presents a Consent naming Consumer A")
+ val response = callAsConsent(jwt, consumerKeyHeader(consumerBKey))
+ Then("We should get a 401")
+ response.code should equal(401)
+ And("the refusal must not distinguish a Consent that is not ours from one that does not exist")
+ response.body.extract[ErrorMessage].message should include(ConsentNotFound)
+ }
+
+ scenario("a missing Consumer-Key is refused by the pin, before the Consumer is validated", VersionOfApi, ConsentPinning) {
+ val jwt = acceptedConsentJwt(Some(consumerAId))
+ When("the Consent is presented with no Consumer-Key at all")
+ val response = callAsConsent(jwt, Nil)
+ Then("the pin refuses it first, so the message is ConsentNotFound and not ConsumerKeyHeaderMissing")
+ response.body.extract[ErrorMessage].message should include(ConsentNotFound)
+ response.body.extract[ErrorMessage].message should not include (ConsumerKeyHeaderMissing)
+ }
+ }
+
+ feature("A Consent may be created for an application other than the one creating it") {
+
+ // The portal-creates-a-Consent-for-an-agent flow: the caller is the grantor, consumer_id is the
+ // grantee, and skip_consent_sca_for_consumer_id_pairs keys off exactly that pair. Without this
+ // scenario nothing verifies that the grantee -- rather than the creator -- is what gets pinned.
+ scenario("the named application may present it and the creating application may not", VersionOfApi, ConsentPinning) {
+ When("Consumer A creates a Consent naming Consumer B")
+ val jwt = acceptedConsentJwt(Some(consumerBId))
+
+ Then("Consumer B may present it")
+ callAsConsent(jwt, consumerKeyHeader(consumerBKey)).code should equal(200)
+
+ And("Consumer A, which created it, may not")
+ val refused = callAsConsent(jwt, consumerKeyHeader(consumerAKey))
+ refused.code should equal(401)
+ refused.body.extract[ErrorMessage].message should include(ConsentNotFound)
+ }
+
+ scenario("omitting consumer_id names the Consumer making the call", VersionOfApi, ConsentPinning) {
+ When("Consumer A creates a Consent with no consumer_id in the body")
+ val jwt = acceptedConsentJwt(None)
+
+ Then("the Consent is pinned to Consumer A, which may present it")
+ callAsConsent(jwt, consumerKeyHeader(consumerAKey)).code should equal(200)
+
+ And("Consumer B may not -- an omitted consumer_id is not a wildcard")
+ val refused = callAsConsent(jwt, consumerKeyHeader(consumerBKey))
+ refused.code should equal(401)
+ refused.body.extract[ErrorMessage].message should include(ConsentNotFound)
+ }
+ }
+
+ feature("The Consumer a Consent names must still be active, and must be the one the instance validates") {
+
+ // The refusal is the generic ConsumerIsDisabled, not the consent-specific ConsumerAtConsentDisabled,
+ // and that is not a slip in the assertion. checkConsumerIsActiveAndMatched does produce
+ // ConsumerAtConsentDisabled here, but AfterApiAuth.checkConsumerIsDisabled runs afterwards as common
+ // post-authentication code (APIUtil.getUserAndSessionContextFuture) and replaces any result whose
+ // CallContext carries a disabled Consumer. Since tppIsConsentHolder only lets the call through when
+ // the caller *is* the Consent's Consumer, that Consumer is always the one on the CallContext, so the
+ // generic check always wins. ConsumerAtConsentDisabled survives only for Consents whose stored
+ // consumer_id and JWT aud disagree -- i.e. rows created before the consumer pin was made mandatory.
+ // Asserting the message that actually ships is the point: a test written against the unreachable one
+ // would pass for the wrong reason the day the ordering changed.
+ scenario("a Consent whose Consumer is disabled afterwards is refused", VersionOfApi, ConsentPinning) {
+ val disabledLater = createLocalConsumer("consent-pinning-disabled-later")
+ val jwt = acceptedConsentJwt(Some(disabledLater.consumerId.get))
+
+ When("the Consent's Consumer is disabled after the Consent was granted")
+ Consumers.consumers.vend.updateConsumer(disabledLater.id.get, isActive = Some(false))
+
+ Then("the pin still passes -- the ids match -- but the disabled Consumer is refused")
+ val response = callAsConsent(jwt, consumerKeyHeader(disabledLater.key.get))
+ response.body.extract[ErrorMessage].message should include(ConsumerIsDisabled)
+ }
+
+ // The two gates read different inputs. A caller identified by its QSealC passes the pin, because
+ // the pin only compares consumer ids -- but CONSUMER_CERTIFICATE validates the QWAC in PSD2-CERT,
+ // which this caller never sent. Without this scenario nothing shows that the second gate is a real
+ // gate rather than a restatement of the first.
+ scenario("a caller identified by TPP-Signature-Certificate is refused when the instance validates PSD2-CERT",
+ VersionOfApi, ConsentPinning) {
+ val certificate = s"-----BEGIN CERTIFICATE-----CONSENTPINNINGQSEALC${randomString(20)}-----END CERTIFICATE-----"
+ val certConsumer = createLocalConsumer("consent-pinning-qsealc", Some(certificate))
+ val jwt = acceptedConsentJwt(Some(certConsumer.consumerId.get))
+
+ When("the instance validates the MTLS certificate but the caller only sent its signing certificate")
+ setPropsValues("consumer_validation_method_for_consent" -> "CONSUMER_CERTIFICATE")
+ val response = try {
+ callAsConsent(jwt, List((RequestHeader.`TPP-Signature-Certificate`, certificate)))
+ } finally setPropsValues("consumer_validation_method_for_consent" -> "CONSUMER_KEY_VALUE")
+
+ Then("the pin passes on the resolved Consumer, and the certificate comparison refuses it")
+ response.body.extract[ErrorMessage].message should include(ConsentDoesNotMatchConsumer)
+ }
+
+ // Same asymmetry the other way round: the certificate wins when resolving the caller
+ // (consumerByCertificate.orElse(consumerByConsumerKey)), so the Consumer-Key naming a different
+ // application is not what identified this call -- but under CONSUMER_KEY_VALUE it is what gets
+ // compared.
+ scenario("a caller identified by certificate is refused when its Consumer-Key names a different Consumer",
+ VersionOfApi, ConsentPinning) {
+ val certificate = s"-----BEGIN CERTIFICATE-----CONSENTPINNINGQWAC${randomString(20)}-----END CERTIFICATE-----"
+ val certConsumer = createLocalConsumer("consent-pinning-qwac", Some(certificate))
+ val jwt = acceptedConsentJwt(Some(certConsumer.consumerId.get))
+
+ When("the caller presents the certificate of the named Consumer and the Consumer-Key of another")
+ val response = callAsConsent(jwt,
+ List((RequestHeader.`PSD2-CERT`, certificate)) ::: consumerKeyHeader(consumerAKey))
+
+ Then("the pin passes on the certificate-resolved Consumer, and the key comparison refuses it")
+ response.body.extract[ErrorMessage].message should include(ConsentDoesNotMatchConsumer)
+ }
+ }
+}
diff --git a/scripts/resource_doc_baseline/parity_allowlist.json b/scripts/resource_doc_baseline/parity_allowlist.json
index 1808400a70..0fe94a29d9 100644
--- a/scripts/resource_doc_baseline/parity_allowlist.json
+++ b/scripts/resource_doc_baseline/parity_allowlist.json
@@ -1231,39 +1231,39 @@
"version": "v3_1_0",
"endpoint": "createConsentEmail",
"field": "errorResponseBodies",
- "reason": "RolesForbiddenInConsent added: the handler now rejects a requested canCreateEntitlementAtAnyBank entitlement in the consent body (real check, verified in source) instead of silently dropping it.",
+ "reason": "RolesForbiddenInConsent added: the handler now rejects a requested canCreateEntitlementAtAnyBank entitlement in the consent body (real check, verified in source) instead of silently dropping it. ConsentConsumerIsRequired added: a Consent must name the Consumer it is for (body consumer_id, else the caller), so the endpoint now returns 400 instead of storing a null consumer_id and creating a Consent no identified caller could use.",
"lift_digest": "73f681411b6caa8d703781d5e2ffa8d4adc252fe915861d9620d52ba70157489",
- "http4s_digest": "f8b17b4d7af9672c5a18db6530fb69dc9cf1e0ee381bb9704c21d9275b7c8740"
+ "http4s_digest": "2a59145ecca58aa91e2429d47183bc6080d0d6ff23148364e6b5d00738998bbd"
},
{
"version": "v3_1_0",
"endpoint": "createConsentImplicit",
"field": "errorResponseBodies",
- "reason": "RolesForbiddenInConsent added: the handler now rejects a requested canCreateEntitlementAtAnyBank entitlement in the consent body (real check, verified in source) instead of silently dropping it.",
+ "reason": "RolesForbiddenInConsent added: the handler now rejects a requested canCreateEntitlementAtAnyBank entitlement in the consent body (real check, verified in source) instead of silently dropping it. ConsentConsumerIsRequired added: a Consent must name the Consumer it is for (body consumer_id, else the caller), so the endpoint now returns 400 instead of storing a null consumer_id and creating a Consent no identified caller could use.",
"lift_digest": "12f4455621efe01d60de9117bf41688146dd5d1e432d86d2c732f3bbe02dfbdd",
- "http4s_digest": "e37f7a4dc30ad082a361fb63766cf3548e83dd5fb6c5e1d5c1b7b54e76d74a9f"
+ "http4s_digest": "063b469668f1746d996408f19caa0a1b5c05f3ff9c6e01a4057327584918d88e"
},
{
"version": "v3_1_0",
"endpoint": "createConsentSms",
"field": "errorResponseBodies",
- "reason": "RolesForbiddenInConsent added: the handler now rejects a requested canCreateEntitlementAtAnyBank entitlement in the consent body (real check, verified in source) instead of silently dropping it.",
+ "reason": "RolesForbiddenInConsent added: the handler now rejects a requested canCreateEntitlementAtAnyBank entitlement in the consent body (real check, verified in source) instead of silently dropping it. ConsentConsumerIsRequired added: a Consent must name the Consumer it is for (body consumer_id, else the caller), so the endpoint now returns 400 instead of storing a null consumer_id and creating a Consent no identified caller could use.",
"lift_digest": "12f4455621efe01d60de9117bf41688146dd5d1e432d86d2c732f3bbe02dfbdd",
- "http4s_digest": "e37f7a4dc30ad082a361fb63766cf3548e83dd5fb6c5e1d5c1b7b54e76d74a9f"
+ "http4s_digest": "063b469668f1746d996408f19caa0a1b5c05f3ff9c6e01a4057327584918d88e"
},
{
"version": "v5_1_0",
"endpoint": "createConsent",
"field": "errorResponseBodies",
- "reason": "Same RolesForbiddenInConsent addition as the v3.1.0 consent-creation endpoints (real check, verified in source). Digest computed against the rename-paired Lift name createConsentImplicit.",
+ "reason": "Same RolesForbiddenInConsent addition as the v3.1.0 consent-creation endpoints (real check, verified in source). Digest computed against the rename-paired Lift name createConsentImplicit. ConsentConsumerIsRequired added: a Consent must name the Consumer it is for (body consumer_id, else the caller), so the endpoint now returns 400 instead of storing a null consumer_id and creating a Consent no identified caller could use. Digest computed against the rename-paired Lift name createConsentImplicit.",
"lift_digest": "12f4455621efe01d60de9117bf41688146dd5d1e432d86d2c732f3bbe02dfbdd",
- "http4s_digest": "e37f7a4dc30ad082a361fb63766cf3548e83dd5fb6c5e1d5c1b7b54e76d74a9f"
+ "http4s_digest": "063b469668f1746d996408f19caa0a1b5c05f3ff9c6e01a4057327584918d88e"
},
{
"version": "v6_0_0",
"endpoint": "createApiProduct",
"field": "description",
- "reason": "Documents the six call-limit semantics, tiering and recognised Api Product Attribute names (SELF_SUBSCRIBE/BILLING_SYSTEM/etc) \u2014 real feature per code.apiproductsubscription.*, opening sentence and auth note preserved verbatim.",
+ "reason": "Documents the six call-limit semantics, tiering and recognised Api Product Attribute names (SELF_SUBSCRIBE/BILLING_SYSTEM/etc) — real feature per code.apiproductsubscription.*, opening sentence and auth note preserved verbatim.",
"lift_digest": "a0a19cc5100424e4e1824f1d1c70dc4329971051689338c8559c988e334ddab7",
"http4s_digest": "585ffe0ecaab1b7ee5d333fffc55aca0016497dba502ad9ebc446dd3a4c92ade"
},
@@ -1562,6 +1562,46 @@
"reason": "Signal channels were experimental when the Lift -> http4s baseline was captured; the surface was settled afterwards and v6.0.0 is DRAFT, so it changed in place.",
"lift_digest": "7d8858342e5f9497e909447578abfd58659f985405da1000fe47afa4edd4dbc6",
"http4s_digest": "17875d69ff6997b57b16dddad46600084d17af889b0597859ea11cf516434fbb"
+ },
+ {
+ "version": "v5_1_0",
+ "endpoint": "createConsent",
+ "field": "description",
+ "reason": "Documents the consumer pin: consumer_id names the Consumer the Consent is for (a portal creating a Consent for an agent sets it; omitting it means the caller), and a Consent naming no Consumer is refused. Text-only. Digest computed against the rename-paired Lift name createConsentImplicit.",
+ "lift_digest": "799b5131b45ad5eba0efc5fe3ad22a4cb056098a91ba01bf44357ec7d71e6556",
+ "http4s_digest": "adbc0f96aea981e39519b958e42bc7e7d4aeb92dc57e2387dbf6b4853852e876"
+ },
+ {
+ "version": "v5_0_0",
+ "endpoint": "createConsentRequest",
+ "field": "description",
+ "reason": "Documents the consumer pin as implemented: consumer_id names the consumer the resulting Consent is for (a portal creating a Consent for an agent sets it; omitting it means the consumer that created this request), and an omitted consumer_id is not a wildcard. Replaces a note promising that v6.0.0 would pin to the creator unconditionally, which was never done and would remove the grantor/grantee split the portal-creates-a-Consent-for-an-agent flow depends on. Text-only.",
+ "lift_digest": "60299a38b1f1da2f0079cd73c6f7e6bdb6475a42619d68e66de9abbeb70b1112",
+ "http4s_digest": "cca8983a65729900751baf5b7948343424e9073e78e9aba732037a6066ee989c"
+ },
+ {
+ "version": "v5_0_0",
+ "endpoint": "createConsentByConsentRequestIdEmail",
+ "field": "description",
+ "reason": "Documents the consumer pin as implemented: adds the caller as the final fallback and states that a Consent naming no consumer is refused with ConsentConsumerIsRequired rather than stored with a null consumer_id. Text-only.",
+ "lift_digest": "d32f4c0ef999ec22dd0932ceb5201de3de29ecc3ad6dea1dedfa643884fc7959",
+ "http4s_digest": "afbf4bd23402c3b784da8f54abc29614fedced4f15eb5703466c725a784faef4"
+ },
+ {
+ "version": "v5_0_0",
+ "endpoint": "createConsentByConsentRequestIdImplicit",
+ "field": "description",
+ "reason": "Documents the consumer pin as implemented: adds the caller as the final fallback and states that a Consent naming no consumer is refused with ConsentConsumerIsRequired rather than stored with a null consumer_id. Text-only.",
+ "lift_digest": "b262a1d68717cdbcc51a7c035741e5da4cf5124123683e3dd015c85ed8baa231",
+ "http4s_digest": "95623d7eda5322dbacd11e947887da53859b646ea16edaa5dd0b34782021f46e"
+ },
+ {
+ "version": "v5_0_0",
+ "endpoint": "createConsentByConsentRequestIdSms",
+ "field": "description",
+ "reason": "Documents the consumer pin as implemented: adds the caller as the final fallback and states that a Consent naming no consumer is refused with ConsentConsumerIsRequired rather than stored with a null consumer_id. Text-only.",
+ "lift_digest": "7397560b818a5d9f4eb31a701499aea10c0ecd8d89d15496c0904d90984b84a6",
+ "http4s_digest": "881b4fe9e74e92efbe1177f1548d7ad4aa85be90f0ec44789ecf779267335f6b"
}
]
}
diff --git a/todo/README.md b/todo/README.md
new file mode 100644
index 0000000000..e7b6475a99
--- /dev/null
+++ b/todo/README.md
@@ -0,0 +1,25 @@
+# todo/
+
+Notes to developers. **Not a work queue, and not instructions.**
+
+Each file here should describe an issue that is *understood* and has a *wished-for direction* — what
+is wrong, why it matters, and roughly what we'd like to do about it. If a note has no direction yet,
+it is a question rather than a todo: raise it, or write it up in `docs/` as reference until someone
+decides.
+
+Three things this folder is deliberately not:
+
+- **Not conventions.** Rules that should be applied when writing code live in `docs/`, because we
+ *want* them followed automatically. `docs/http_status_conventions.md` is the example: the rule
+ ("duplicate create returns 409") is there, while "which older sites still return 400, pending a
+ decision" is here.
+- **Not an issue tracker.** No assignment, no closing, no notification. Anything with an owner and a
+ deadline belongs in GitHub Issues.
+- **Not personal scratch.** Working memos, half-finished investigations, security findings and
+ anything customer-named stay in `_DO_NOT_COMMIT_/`, which is gitignored.
+
+Items here may be stale. Check claims against the tree before acting on them — the previous
+revision of the 409 note had gone 60% stale inside six months, citing line numbers in twelve files
+that had since been deleted.
+
+**For agents**: do not action items from this folder. See the note in `CLAUDE.md`.
diff --git a/todo/TODO.md b/todo/TODO.md
new file mode 100644
index 0000000000..2f58706776
--- /dev/null
+++ b/todo/TODO.md
@@ -0,0 +1,18 @@
+# TODO — duplicate-create 409s
+
+Reference for the rule, the per-version state, and the open decision:
+**`docs/http_status_conventions.md`**. Only the parts with an agreed direction are listed here.
+
+- [ ] **`Http4s700.scala:4697`** — `AccountIdAlreadyExists` in `createAccountCommon` (shared by
+ `createAccountV700` POST and `createAccountWithIdV700` PUT) still returns 400. v7.0.0 is
+ BLEEDING_EDGE, so the "safe to fix in place" reasoning that cleared all of v6.0.0 applies
+ directly. No decision needed — this one was simply missed. Add `failCode = 409` and a
+ duplicate-create scenario in `Http4s700RoutesTest`.
+
+- [ ] **`ConsumerKeyAlreadyExists` is a dead constant.** Defined in `ErrorMessages.scala`,
+ referenced by nothing in the tree. Either wire it up at the consumer-create site or delete it.
+ Error-code numbers are stable once committed, so deleting frees nothing — but a constant no code
+ can produce is worse than a gap, because it appears in no response and yet reads as supported.
+
+The 29 sites on v1.4.0 – v5.1.0 are **not** listed here. Whether to change them is an open contract
+decision (see the doc above), so they are inventory, not work.
diff --git a/todo/rate_limiting_followups.md b/todo/rate_limiting_followups.md
new file mode 100644
index 0000000000..3a668e5777
--- /dev/null
+++ b/todo/rate_limiting_followups.md
@@ -0,0 +1,20 @@
+# TODO — rate limiting follow-ups
+
+From `docs/API_PRODUCT_SUBSCRIPTION_PLAN.md` (2026-09-02). Re-checked against the tree 2026-09-14 —
+all three still open: `RateLimitingUtil.scala` has no `apiName` / `apiVersion` / `bankId` matching,
+and there is no expiry job anywhere.
+
+Value semantics are settled and not in question: `0` blocks, `-1` is unlimited, no record falls back
+to the `rate_limiting_per_*` props, and overlapping records sum by design.
+
+- [ ] **Per-endpoint limits keyed by `operationId`** (not URL). A `RateLimiting` record's `apiName`
+ and `apiVersion` are stored and reported but never matched; enforcement is per consumer across all
+ endpoints. Needed before an API Product's collection can be rate-limited on its own.
+
+- [ ] **Per-bank matching** using the record's `bankId`. Same situation — stored, reported, not
+ matched — with a sharper consequence: a record created for a product at bank A silently changes
+ that consumer's limits at bank B.
+
+- [ ] **Subscription expiry job.** When an API Product Subscription's `end_date` passes, its
+ rate-limit record stops counting for free (same `toDate`), but its derived Scopes stay until
+ something sets the status to `cancelled`. A scheduled job should do that.
diff --git a/todo/todo_account_id_uuid_enforcement.md b/todo/todo_account_id_uuid_enforcement.md
new file mode 100644
index 0000000000..7df0ae394b
--- /dev/null
+++ b/todo/todo_account_id_uuid_enforcement.md
@@ -0,0 +1,98 @@
+# TODO — Enforce `account_id` MUST-be-UUID at write time
+
+## Context
+
+The `Account.account_id` glossary entry in `obp-api/src/main/scala/code/api/util/Glossary.scala` was tightened from "SHOULD be a UUID" to **"MUST be a UUID"** as part of the v6.0.0 routing work (see also `Account.account_routings` — the implicit `(OBP, account_id)` routing is federation-safe *because* account_id is a UUID, which makes collision probability effectively zero across OBP instances).
+
+The contract is now documented but **not yet enforced** in code. `MappedBankAccount.theAccountId` is declared `AccountIdString` (`obp-api/src/main/scala/code/model/dataAccess/MappedBankAccount.scala:43`), which is just `MappedString(fieldOwner, AccountIdString.MaxLength)` — a permissive string column whose length comes from the `account_id.length` prop (default 64, `code/util/UUIDString.scala:52-57`). Any value of any shape is accepted on write.
+
+## Why this matters
+
+- Federation/routing logic now treats `(OBP, account_id)` as a globally-safe identifier (`Constant.accountRoutingsWithImplicitOBP`, called from every v6 account-routings-returning factory). If a non-UUID account_id slips in, the implicit routing entry it produces may collide with another OBP instance's value, silently breaking cross-instance lookups.
+- API consumers reading the glossary will write integration code that assumes a UUID. They'll be surprised when an older non-UUID identifier comes back from `getCoreAccountById` etc.
+- Audit and observability tooling that parses account_ids as UUIDs (e.g. to dedupe or partition) will break on the first non-UUID.
+
+## Scope of work
+
+### Write paths that mint or accept `account_id`
+
+Audit all endpoints and code paths that **create** an account or **accept** an `account_id` from the client:
+
+- [ ] `createAccount` family. As of 2026-09-14 that is four sites, all in `Http4s*.scala` (the `APIMethods*.scala` files were deleted in the Lift teardown, and **v6.0.0 has no createAccount of its own** — it cascades to v5.0.0 through the version bridge):
+ - `Http4s310.scala:4344` `createAccount` (PUT)
+ - `Http4s400.scala:10353` `addAccount` (POST)
+ - `Http4s500.scala:603` `createAccount` (PUT)
+ - `Http4s700.scala:4677` `createAccountCommon`, shared by `createAccountV700` (`:4743`, POST) and `createAccountWithIdV700` (`:4750`, PUT)
+
+ Confirm UUID generation when the client doesn't supply an id (all four already default to `APIUtil.generateUUID()`, but verify); reject non-UUID values when the client does supply one.
+- [ ] `PUT /banks/BANK_ID/accounts/ACCOUNT_ID` "create with id" path — `ACCOUNT_ID` comes from the URL. Add UUID validation guard (`ACCOUNT_ID` must parse as a UUID).
+- [ ] Sandbox data import paths — `OBPDataImport.scala`, `LocalMappedConnectorDataImport.scala`. Imported account_ids must be UUIDs; reject the whole import on first non-UUID.
+- [ ] South-side adapter ingress — RabbitMQ/Kafka/StoredProcedure connectors that map core-banking identifiers to OBP account_ids. The contract is that the adapter emits a UUID; document this and add a `requireUUID(...)` guard at the OBP-API boundary so a misbehaving adapter fails loudly rather than corrupting the dataset.
+
+### What already exists — this is a tightening, not a new check
+
+An earlier revision of this note assumed there was no validation and no error constant. Both are
+wrong, and it changes the shape of the work:
+
+- **`APIUtil.isValidID`** (`APIUtil.scala:854`) already runs on every create path, but it validates
+ `^([A-Za-z0-9\-_.]+)$` with `length < 256` — an *identifier* shape, not a UUID. `account_id =
+ "my-account-1"` passes today.
+- **`InvalidAccountIdFormat` already exists** — `ErrorMessages.scala:656`, **OBP-30110**, with 49
+ uses across ~17 call sites.
+
+So the work is to tighten the existing predicate at the create paths, not to introduce a helper
+alongside an unused one.
+
+**The catch**: OBP-30110's message text *describes the permissive rule* —
+
+> `OBP-30110: Invalid Account Id. The ACCOUNT_ID should only contain 0-9/a-z/A-Z/'-'/'.'/'_', the length should be smaller than 255.`
+
+— so it cannot be reused verbatim for a UUID rejection without becoming misleading. Two options,
+both needing a decision:
+
+1. **Reword OBP-30110.** Error-code *numbers* are stable once committed; the message text is not
+ under the same guarantee. But 17 call sites use this constant for non-create paths where the
+ permissive rule is still the right one, so rewording it would make *those* messages wrong instead.
+2. **Add a new constant** (e.g. `AccountIdMustBeUUID`) used only at the create paths, leaving
+ OBP-30110 to keep meaning "identifier shape" everywhere else. Costs one error code; keeps both
+ messages truthful. Probably the right answer.
+
+Sketch, assuming option 2:
+
+```scala
+// code/util/Helper.scala or APIUtil
+def requireUUIDAccountId(value: String, callContext: Option[CallContext]): Future[Box[Unit]] =
+ Helper.booleanToFuture(s"$AccountIdMustBeUUID Got: $value", failCode = 400, cc = callContext) {
+ scala.util.Try(java.util.UUID.fromString(value)).isSuccess
+ }
+```
+
+Note `UUID.fromString` is lenient about field widths (it accepts `1-1-1-1-1`), so if strictness
+matters, match on the canonical 8-4-4-4-12 hex regex instead.
+
+### Pre-existing data
+
+- [ ] Decide on policy for legacy non-UUID account_ids already in the database.
+ - Option 1: grandfather — leave them as-is, enforce only on new writes. Federation logic must continue to tolerate non-UUID values forever.
+ - Option 2: migration — assign UUIDs and update FK references (`bankaccountrouting.accountid`, `mappedaccountattribute.maccountid`, transactions, views, account access, etc.). High blast radius — every URL referencing the old id breaks unless an alias table is kept.
+- [ ] Whichever option is chosen, document it in the `Account.account_id` glossary entry under "Migration of existing values".
+
+### Bank-side companion work (related but separate)
+
+The `Bank.bank_id` glossary was simultaneously tightened to **SHOULD** be `-`. That's a *new-banks-only* convention — see the glossary entry's "Earlier conventions" section. No enforcement code is needed yet (the rule is a SHOULD, not a MUST), but worth tracking together:
+
+- [ ] When `createBank` next needs touching, add a soft-validation lint: if `bank_id` doesn't contain a UUID-shaped suffix, log a warning. Don't reject — keeps the migration tolerant.
+- [ ] Update onboarding docs / sandbox seed scripts to emit the new shape for any newly-created sandbox banks.
+
+## Test plan
+
+- [ ] Unit test for `requireUUIDAccountId` covering: valid UUID v4, valid UUID v1, lowercase/uppercase, with/without hyphens, common invalid shapes (empty, numeric, name-like).
+- [ ] Integration test against `createAccount` (or its v6 equivalent) confirming a 400 with `InvalidAccountIdFormat` for non-UUID input.
+- [ ] Integration test confirming UUID input still succeeds.
+- [ ] If grandfathering legacy data: integration test reading a legacy non-UUID account record returns its values intact (no validation on reads).
+
+## Out of scope
+
+- Renaming existing bank_ids — explicitly *not* doing this; the new bank_id convention applies to newly created banks only.
+- Changing `(OBP, account_id)` routing semantics — already done.
+- Cross-instance federation handshake — separate workstream.