Open banking consent management¶


ID	`MOD-049`
System	SD08
Repo	`bank-app`
Build status	Deployed
Deployed	Yes
Last commit	`bc8ae27c9ecc660c7eb59e321a9936d2a0c54463`

Purpose¶

The open banking consent management module is the single store of record for all open banking consents, regardless of jurisdiction. It implements the consent lifecycle — capture, validation, refresh, amendment, and revocation — in a jurisdiction-neutral way, with each active jurisdiction profile contributing its own consent schema. The consent store is the authoritative source for MOD-061 (gateway) and MOD-084 (data recipient) to validate whether a given data access is authorised.

What it does¶

A consent is a first-class entity: consent_id, jurisdiction_profile [au_cdr/nz_payments_nz/uk_open_banking/eu_psd2/generic_fapi2], customer_id, third_party_id, third_party_name, granted_scopes (list of internal scope identifiers), granted_at, expires_at (nullable — some profiles allow perpetual consents), status [active/revoked/expired/suspended], consent_payload (JSONB — the full jurisdiction-specific consent representation, e.g. CDR arrangement, OBIE permissions object, PSD2 authorization details).

Internal scopes are profile-agnostic identifiers (e.g. accounts:read, transactions:read:90d, payees:read) mapped from each profile's native permission model. The gateway uses internal scopes for enforcement; profile-specific serialisation happens at the API layer.

app.ob_consents stores the canonical consent record. app.ob_consent_events stores the full audit trail: created, amended, refreshed, revoked (by customer or TPP), expired, suspended.

AU CDR: consent captured via CDR authorisation flow — arrangement ID, data cluster selection, sharing period. Consumer must confirm at each renewal.

NZ (Payments NZ): consent via API Centre authorisation code flow — permission set, duration, purpose statement.

UK Open Banking: consent via OBIE authorisation flow — permission codes, transaction from/to dates, expiry date.

EU PSD2: SCA + dynamic linking for payment initiation; account information consent via ASPSP authorisation.

Generic FAPI 2.0: scope-based consent with RAR (Rich Authorization Requests) — consent detail in the authorization_details JWT claim.

Synchronous validation endpoint used by MOD-061 on every inbound TPP request: given (third_party_id, customer_id, requested_scopes, jurisdiction_profile), returns {valid: true/false, reason?, expires_at} within 50 ms.

Revocation propagates within 60 seconds — revoked consents return valid: false immediately after revocation is recorded.

Customers can view all active consents from the in-app settings screen: TPP name, profile, granted scopes (human-readable), expiry, and a single-tap revoke button.

Revocation is immediate — the TPP receives a 403 on their next request with no grace period.

Compliance reason¶

Every open banking regime requires that data sharing is customer-authorised and that the authorisation is specific, time-limited, and revocable. A single consent store that understands all profile schemas means a customer who revokes consent for an AU CDR arrangement and a UK Open Banking consent is handled by the same revocation logic, same audit trail, and same 60-second propagation guarantee — regardless of which regulator is looking.

Commercial reason¶

A unified consent store eliminates the need to build and maintain separate consent databases per jurisdiction. Customer-facing consent management (view, amend, revoke) is built once and works across all active profiles.

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-068	Authentication & session management	Required	—	Consent capture requires an authenticated customer session — no consent can be recorded without a verified identity from the app.user_identities table.
MOD-052	Role-scoped data access	Required	—	Back-office consent listing endpoints call MOD-052 enforce() before returning consent attribute data for CSR views of another customer's consents.
MOD-104	AWS shared infrastructure bootstrap	Required	—	AWS shared infrastructure provisioned by MOD-104 (EventBridge buses, KMS operational CMK, Cognito customer pool, ADOT layer, Lambda execution role) is required before this module can be deployed.
MOD-103	Neon database platform bootstrap	Required	—	Neon database and schema provisioned by MOD-103 must exist before this module can read or write Postgres.
MOD-044	JWT role-based access control	Required	—	Customer JWT validation is performed upstream by MOD-044's authoriser Lambda; MOD-049 reads custom:party_id from the JWT claims on every authenticated request.

Required by¶

Module	Title	As	Contract
MOD-061	Open banking API platform	Hard dependency	—
MOD-073	Document vault	Hard dependency	—
MOD-077	Account dashboard & insight feed	Optional enhancement	—
MOD-084	Open banking data access — data recipient	Hard dependency	—
MOD-108	Product offer engine	Hard dependency	—

Policies satisfied¶

Policy	Title	Mode	How
PRI-001	Privacy Policy	`GATE`	requireConsent() workspace library throws 403 CONSENT_NOT_GRANTED if no active row in app.consents (or app.ob_consents for OB purposes) exists for the customer + purpose tuple — personal data access is blocked without prior consent.
CON-007	Consumer Data Right (CDR) Policy	`GATE`	OB consent grant endpoint rejects any payload that does not carry the jurisdiction profile's required fields (CDR arrangement_id, OBIE permission codes, etc.) per per-profile Ajv JSON Schema validation — non-compliant CDR consent attempts are rejected before any row is inserted.
AML-010	AML Training & Awareness Policy	`LOG`	app.staff_training_acks stores immutable, timestamped AML/CFT training completion records per staff member — gated by MOD-052 so only authenticated staff may write their own acknowledgement; retained for seven years under ADR-048 Cat 1 immutability.

Capabilities satisfied¶

Capability	Title	Mode	How
CAP-060	CDR Data Holder compliance & consent management	`GATE`	Captures and stores customer consent before any CDR data sharing occurs — sharing is blocked without a valid active consent record in app.ob_consents; the synchronous validation endpoint enforces this on every TPP data request within 50 ms.

Part of SD08 — Customer App & Back Office Platform Compiled 2026-05-22 from source/entities/modules/MOD-049.yaml