User Consent Management DOMAIN - US API consent, token, and connection service layer

Overview

This domain layer owns the US consent lifecycle, scoped token issuance, connection readiness, feature snapshot generation, and scoring orchestration that sit behind the US API. It turns a partner’s consent request into a durable consent record, then uses that consent to mint access and refresh tokens, gate downstream data access, and preserve an audit trail for revocation, refresh, and decision replay.

The same primitives also support operational governance. Evidence snapshots are stored as schema-versioned feature records, drift checks compare live evidence against baselines, and retraining triggers are written when performance or drift thresholds are crossed. The result is a tightly separated service boundary: consent, token, connection, feature, scoring, governance, and gateway responsibilities are implemented in dedicated files instead of a single blended API surface.

Architecture Overview

flowchart TD
    PartnerClient[Partner Client] --> PartnerAuth[requirePartnerAuth]
    PartnerAuth --> ConsentService[consentService]
    ConsentService --> TokenService[tokenService]
    ConsentService --> ConnectionService[connectionService]
    ConsentService --> WebhookService[webhookService]
    TokenService --> AccessTokenMiddleware[requireAccessToken]
    AccessTokenMiddleware --> DataGateway[US Data Gateway]
    DataGateway --> TokenVerifier[auth TokenVerifier]
    TokenVerifier --> RedisSessionStore[Redis session store]
    DataGateway --> ConsentDB[Consent records]
    DataGateway --> Provider[provider interface]

    ConsentService --> PrismaConsent[prisma consent token connection logs]
    TokenService --> PrismaToken[prisma token refresh event]
    ConnectionService --> PrismaConnection[prisma connection]
    FeatureService[featureService] --> MockProvider[mockProvider]
    FeatureService --> EvidenceSnapshot[prisma evidenceSnapshot]
    FeatureService --> ModelGovernanceService[modelGovernanceService]
    ScoringService[scoringService] --> FeatureService
    ScoringService --> PrismaDecision[prisma decision]
    ScoringService --> ModelGovernanceService
    ModelGovernanceService --> PrismaModel[prisma modelArtifact deployment]
    ModelGovernanceService --> PrismaDrift[prisma featureDriftReport retrainTrigger]

    AuditLogger[registerAuditLogger] --> PrismaAccessLog[prisma accessLog]

Component Structure

Service boundaries and US-specific primitives

services/us-api/src/models/types.ts

This file defines the US consent vocabulary that is reused across middleware, services, and token claims. The values are intentionally small and closed so that scopes and connection states remain enumerable across the service boundary.

Enumerations and type aliases
Name Values
PurposeValues RENTAL_SCREENING, LENDING_UNDERWRITING, ACCOUNT_OPENING, INCOME_VERIFICATION, FRAUD_PREVENTION, GENERAL_PERSONAL_FINANCE
DataCategoryValues IDENTITY_BASIC, ACCOUNTS, BALANCES, TRANSACTIONS, INCOME, EMPLOYMENT, CASHFLOW_FEATURES, DEVICE_RISK, WATCHLIST_SCREENING
ConnectionStatusValues ACTIVE, REAUTH_REQUIRED, DEGRADED, DISCONNECTED
FeatureSet US_CASHFLOW_V1
Type property tables
Property Type Description
TokenClaims.consent_id string Consent identifier bound into scoped access tokens.
TokenClaims.purpose Purpose Consent purpose carried in the JWT claims.
TokenClaims.data_categories DataCategory[] Data categories authorized by the token.
TokenClaims.jti string Token identifier used for lookup and revocation.

services/us-api/src/models/creditFeatureSchema.ts

[!NOTE] TokenClaims is mirrored by AccessClaims in middleware/accessToken.ts, so the request context exposed to handlers carries the same consent scope that was signed into the JWT.

This file defines the canonical US cashflow feature schema and the migration bridge into the global credit schema. It is the contract used by feature extraction, evidence snapshots, and drift detection.

Constants and types
Name Values
GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION global-credit-v1
GlobalCreditFeatureSchemaV1
Property Type Description
schema_version typeof GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION Schema identifier written into evidence snapshots and model records.
income_monthly_avg_usd number Monthly income average derived from the provider income payload.
income_stability_index number Normalized income stability score.
nsf_overdraft_count_180d number Count of overdraft-like transactions in the US cashflow set.
balance_min_30d_usd number Minimum account balance across the computed balance set.
rent_payment_detected boolean Whether a rent-category transaction is present.
debt_payment_ratio_est number Estimated debt-payment-to-income ratio.
FeatureMigrationResult
Property Type Description
schema_version typeof GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION Schema version attached to the migrated feature set.
features GlobalCreditFeatureSchemaV1 Migrated and normalized feature object.
migration_notes string[] Notes about unsupported source sets and defaulted fields.
Public methods
Method Description Returns
migrateToGlobalCreditSchemaV1 Normalizes an input feature set into GlobalCreditFeatureSchemaV1, applying defaults for missing or non-numeric fields and recording migration notes. FeatureMigrationResult

services/us-api/src/services/consentService.ts

This service owns the consent record lifecycle. It creates US consent records, revokes them, returns receipts, and exposes the consent-active guard used by other services.

Public methods
Method Description Returns
createConsent Creates a US consent record, writes a consent log entry, and returns the stored consent object. Promise<consent record>
revokeConsent Marks the consent revoked, revokes active tokens, disconnects connections, writes a log entry, and attempts revocation webhook delivery. Promise<{ consentId: string }>
getConsentReceipt Loads the consent and returns the receipt payload used to prove consent state and disclosure version. Promise<receipt object>
ensureConsentActive Verifies that a consent exists, is active, and has not expired. Promise<consent record>
CreateConsentPayload
Property Type Description
user { country: 'US'; user_reference?: string } US user profile fragment attached to the consent.
purpose Purpose Consent purpose.
data_categories DataCategory[] Scoped data categories.
access_duration_days number Optional access duration used to compute expiresAt.
expires_at string Optional explicit expiration timestamp.
refresh_permissions { enabled: boolean; max_refresh_per_day: number } Optional refresh policy written to the consent record.
consent_disclosure_version string Version identifier for the disclosure text shown to the user.
Property Type Description
consent_id string Consent identifier.
status string Stored consent status.
purpose Purpose Stored purpose.
data_categories DataCategory[] Stored category scope.
consent_disclosure_version string Disclosure version used for the consent.
expires_at string ISO timestamp for expiration.
created_at string ISO timestamp for initial creation.
Property Type Description
id string Generated consent ID with cst_us_ prefix.
partnerId string Partner identifier passed into createConsent.
userReference `string \ null`
country 'US' Consent country fixed to US.
purpose Purpose Stored consent purpose.
dataCategories DataCategory[] Stored scope categories.
status string Starts as PENDING_USER_ACTION, then becomes ACTIVE or REVOKED.
consentDisclosureVersion string Disclosure version.
expiresAt Date Consent expiration.
refreshEnabled boolean Refresh permission flag.
maxRefreshPerDay number Refresh limit.
createdAt Date Creation timestamp returned by the receipt path.

services/us-api/src/services/tokenService.ts

[!NOTE] revokeConsent updates the consent state, revokes tokens, disconnects connections, and still returns success even if webhook delivery fails. The webhook failure is intentionally swallowed in this flow.

This service owns scoped token issuance, refresh, and introspection. It binds token claims to a consent, keeps a refresh-token hash in the database, and checks per-consent refresh limits.

Public methods
Method Description Returns
exchangeToken Validates an optional link token, activates pending consent, issues JWT access and refresh tokens, and emits an activation webhook when activation occurs. Promise<TokenPair>
refreshToken Resolves a refresh token hash, validates consent state, enforces the refresh limit, and issues a new token pair. Promise<TokenPair>
introspectToken Verifies a JWT access token and checks whether the corresponding token record is still active. `Promise<active object \
TokenPair
Property Type Description
access_token string RS256 JWT access token.
refresh_token string Opaque refresh token with rtk_us_ prefix.
expires_in number Access token TTL in seconds.
scope { purpose: Purpose; data_categories: DataCategory[] } The consent scope carried by the pair.
Scope object inside TokenPair
Property Type Description
purpose Purpose Purpose bound into the access token.
data_categories DataCategory[] Categories bound into the access token.
Token introspection result
Property Type Description
active boolean Indicates whether the token is valid and still active.
consent_id string Consent associated with the token.
purpose Purpose Token purpose.
data_categories DataCategory[] Token scope.
expires_at string Token expiration timestamp in ISO format.
Token record shape observed in this service
Property Type Description
id string Token record identifier with tok_ prefix.
consentId string Consent foreign key.
accessJti string JWT jti written into the token record.
refreshTokenHash string SHA-256 hash of the refresh token.
expiresAt Date Expiration timestamp.
revokedAt `Date \ null`
Operational rules captured in code
  • exchangeToken accepts an optional linkToken and requires it to match linktok_<consentId> when present.
  • exchangeToken promotes a consent from PENDING_USER_ACTION to ACTIVE.
  • refreshToken blocks inactive or expired consent.
  • refreshToken calls enforceRefreshLimit only when refresh permissions are enabled.
  • introspectToken requires a live token record whose accessJti matches the JWT claims.

services/us-api/src/services/connectionService.ts

This service evaluates connection readiness for a consent and refreshes connection state after downstream sync.

Public methods
Method Description Returns
ensureConnectionsReady Loads connection records for a consent and either returns readiness or throws a re-authentication error. `Promise<{ status: string; reauth_link: string \
recordConnectionRefresh Marks all consent connections active and stamps lastRefreshedAt. Promise<void>
Connection readiness result
Property Type Description
status string ACTIVE or DEGRADED when readiness succeeds.
reauth_link `string \ null`
Connection record shape observed in this service
Property Type Description
consentId string Consent foreign key.
status ConnectionStatus Connection state.
reauthLink `string \ null`
lastRefreshedAt `Date \ null`
Connection status handling
  • ensureConnectionsReady returns ACTIVE when no connection rows exist for the consent.
  • ensureConnectionsReady throws ApiError(409, 'REAUTH_REQUIRED', ...) when any connection is in REAUTH_REQUIRED.
  • ensureConnectionsReady returns DEGRADED when at least one connection is degraded and no reauth-required record is present.
  • recordConnectionRefresh normalizes all matched rows back to ACTIVE.

services/us-api/src/services/featureService.ts

This service computes US cashflow features from provider data, stores the evidence snapshot, and returns the migrated feature set used by scoring and governance.

Public methods
Method Description Returns
computeCashflow Pulls balances, transactions, and income from mockProvider, computes US cashflow features, migrates them to the global schema, persists an evidence snapshot, and returns the evidence reference plus migrated features. Promise<cashflow result>
fetchEvidence Loads a persisted evidence snapshot by ID. Promise<evidence snapshot record>
CashflowFeatures
Property Type Description
income_monthly_avg_usd number Rounded monthly income average.
income_stability_index number Two-decimal income stability score.
nsf_overdraft_count_180d number Count of overdraft-category transactions.
balance_min_30d_usd number Rounded minimum current balance from the retrieved balances.
rent_payment_detected boolean Indicates whether a rent transaction was seen.
debt_payment_ratio_est number Rounded debt-to-income ratio estimate.
computeCashflow result
Property Type Description
evidence_ref string Generated evidence snapshot identifier.
features GlobalCreditFeatureSchemaV1 Migrated global feature object.
income_method `'provider' \ 'inferred'`
schema_version string Schema version written into the snapshot.
migration_notes string[] Notes returned by the migration step.
Evidence snapshot record shape observed in this service
Property Type Description
id string Snapshot identifier with evd_us_ prefix.
consentId string Consent foreign key.
featureSet string Feature set identifier, US_CASHFLOW_V1.
features GlobalCreditFeatureSchemaV1 Migrated feature payload.
inputsDigest string SHA-256 digest of the raw provider inputs.
lookbackDays number Lookback window carried into the snapshot.
schemaVersion string Snapshot schema version.
metadata Record<string, unknown> Snapshot metadata with source and migration details.
Evidence metadata shape
Property Type Description
income_method string Provider income method.
source_feature_set string Original source set, US_CASHFLOW_V1.
source_features CashflowFeatures Pre-migration feature values.
migration_notes string[] Migration notes attached to the snapshot.

services/us-api/src/services/scoringService.ts

[!NOTE] computeCashflow persists the evidence snapshot after migration and schema registration, then returns the generated evidence reference for downstream scoring and replay.

This service validates decisions, persists them, and replays scoring either from a stored decision or via an external scoring callback.

Public methods
Method Description Returns
validateDecision Enforces deny-reason rules before a decision is stored. void
storeDecision Loads the evidence snapshot, records model lineage when model metadata is present, persists the decision, and returns the decision ID. Promise<string>
replayDecision Replays a decision from the scoring callback when configured, or returns the stored decision plus audit context. Promise<decision replay object>
DenyReasonsAllowlist

INSUFFICIENT_INCOME, INCOME_INSTABILITY, RECENT_OVERDRAFTS, LOW_MIN_BALANCE, HIGH_CASHFLOW_VOLATILITY, INSUFFICIENT_HISTORY, UNVERIFIED_ACCOUNT, INCONSISTENT_IDENTITY_SIGNALS, HIGH_RISK_DEVICE_SIGNAL

DecisionPayload
Property Type Description
applicant_reference `string \ undefined`
purpose string Decision purpose.
product_type `string \ undefined`
score `number \ undefined`
decision string Decision outcome.
approved_limit `number \ undefined`
model `{ name?: string; version?: string; schema_version?: string; training_snapshot_ref?: string; hyperparameters?: Record<string, unknown>; metrics?: Record<string, unknown> } \ undefined`
reasons `{ code: string; description?: string }[] \ undefined`
evidence_ref string Evidence snapshot reference.
consent_id string Consent identifier.
consent_text_version string Consent disclosure or text version.
connection_status string Connection status at decision time.
features Record<string, unknown> Feature payload used by the decision.
Decision record shape observed in this service
Property Type Description
id string Decision identifier with dec_ prefix.
consentId string Consent foreign key.
evidenceRef string Evidence snapshot foreign key.
payload DecisionPayload Full stored decision payload.
modelArtifactId `string \ null`
schemaVersion string Schema version stored with the decision.
Decision replay audit payload
Property Type Description
decision_id string Decision record identifier.
payload DecisionPayload Replayed or stored decision payload.
audit.evidence_ref string Evidence reference used for replay.
audit.feature_set string Snapshot feature set.
audit.schema_version string Snapshot schema version.
audit.features Record<string, unknown> Persisted feature payload.
audit.model_artifact `ModelArtifact \ null`
ModelArtifact shape returned from the audit path
Property Type Description
id string Model artifact identifier.
name string Model name.
version string Model version.
schema_version string Feature schema version linked to the model.
training_snapshot_ref string Training snapshot reference.
hyperparameters Record<string, unknown> Stored hyperparameters.
metrics Record<string, unknown> Stored model metrics.
Decision validation rule
  • A DENY decision must include at least one reason.
  • Every deny reason code must be in DenyReasonsAllowlist.
  • Violations raise ApiError(400, 'LEGAL_RESTRICTION', ...).
Replay callback behavior
  • When config.scoringCallbackUrl is present, replayDecision posts evidence_ref, features, consent_id, and feature_set to the callback.
  • Non-OK callback responses raise ApiError(502, 'PROVIDER_UNAVAILABLE', 'Scoring callback failed').
  • When no callback URL is configured, the service returns the stored decision and attached audit context.

services/us-api/src/services/modelGovernanceService.ts

This service owns feature-schema registration, drift detection, retraining trigger evaluation, and model lineage capture.

Public methods
Method Description Returns
ensureFeatureSchemaVersion Ensures the global credit feature schema record exists. Promise<feature schema record>
runFeatureDriftDetection Compares live evidence snapshot distribution against a baseline and writes a drift report. Promise<feature drift report>
evaluateRetrainingTriggers Checks the latest performance snapshot and latest drift report to decide whether a retrain trigger should be created. `Promise<retrain trigger \
recordModelLineage Upserts model artifact metadata and writes an active deployment record. Promise<model artifact record>
PerformanceThresholds
Property Type Description
aucMin number Minimum acceptable AUC.
driftScoreMax number Maximum acceptable drift score.
Default thresholds

aucMin: 0.72, driftScoreMax: 0.3

FeatureSchemaVersion record shape observed in this service
Property Type Description
id string Schema version ID.
description string Human-readable schema description.
definition Record<string, string> Feature definitions keyed by field name.
migrationRules Record<string, unknown> Source-set migration rules and defaults.
migrationRules shape
Property Type Description
from string[] Source feature sets that can migrate into the schema.
defaults Record<string, unknown> Default values for schema fields.
FeatureDriftReport record shape observed in this service
Property Type Description
id string Drift report identifier with drift_ prefix.
baselineId string Drift baseline foreign key.
featureSet string Feature set under analysis.
schemaVersion string Schema version used for drift analysis.
sampleSize number Number of evidence snapshots sampled.
driftScore number Fraction of drifted features.
driftedFeatures Record<string, { baseline_mean: number; live_mean: number; z_score: number }> Drift details keyed by feature name.
RetrainTrigger record shape observed in this service
Property Type Description
id string Trigger identifier with retrain_ prefix.
modelArtifactId string Target model artifact.
reason string Comma-separated reason codes.
details Record<string, unknown> Trigger metadata with reason details.
status string Set to PENDING.
ModelArtifact record shape observed in this service
Property Type Description
id string Model artifact identifier with mdl_ prefix.
name string Model name.
version string Model version.
schemaVersion string Schema version defaulting to GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION.
trainingSnapshotRef string Training snapshot reference.
hyperparameters Record<string, unknown> Model hyperparameters.
metrics Record<string, unknown> Model metrics.
Model deployment record shape observed in this service
Property Type Description
id string Deployment identifier with deploy_ prefix.
modelArtifactId string Model artifact foreign key.
status string Set to ACTIVE.
metadata Record<string, unknown> Deployment metadata with source: 'decision-ingest'.
Governance behavior
  • runFeatureDriftDetection uses a z-score threshold of 2 to mark a feature as drifted.
  • evaluateRetrainingTriggers compares the latest AUC and latest drift report against the default thresholds unless overrides are passed.
  • evaluateRetrainingTriggers returns null when no threshold is violated.
  • recordModelLineage defaults the schema version to GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION when one is not supplied.

services/us-api/src/webhooks/webhookService.ts

This service pushes consent lifecycle events to partner webhook endpoints and records the delivery attempt.

Public methods
Method Description Returns
dispatchWebhook Loads active webhook endpoints for a partner and delivers a signed event payload to each endpoint. Promise<void>
signPayload Creates the HMAC signature used in outbound webhook requests. string
WebhookEvent
Property Type Description
event string Event name delivered to the partner.
payload Record<string, unknown> Event payload delivered as webhook data.
Webhook endpoint record shape observed in this service
Property Type Description
id string Webhook endpoint identifier.
partnerId string Partner foreign key.
active boolean Active endpoint flag.
events string[] Subscribed event names.
secret string HMAC secret used for signature generation.
url string Destination URL.
Webhook delivery record shape observed in this service
Property Type Description
id string Delivery identifier with whd_ prefix.
webhookId string Endpoint foreign key.
eventType string Delivered event name.
payload Record<string, unknown> Delivered event payload.
status string Starts PENDING, then becomes DELIVERED or FAILED.
attemptCount number Delivery attempt count.
lastAttemptAt Date Timestamp of the last attempt.
Delivery behavior
  • Each delivery gets its own Idempotency-Key header equal to the delivery ID.
  • Each delivery is signed with X-Webhook-Signature.
  • Failures are recorded as FAILED and surfaced as ApiError(502, 'PROVIDER_UNAVAILABLE', 'Webhook dispatch failed').

services/us-api/src/middleware/accessToken.ts

This middleware turns a bearer token into request-scoped consent claims for downstream handlers.

Public methods
Method Description Returns
requireAccessToken Extracts a token from the Authorization header, x-access-token, or access_token query parameter, verifies the JWT, and attaches consent claims to the request. void
AccessClaims
Property Type Description
consent_id string Consent identifier carried into request context.
purpose Purpose Scoped purpose.
data_categories DataCategory[] Scoped category list.
jti string JWT identifier used for token lookup.
Request enrichment
  • Successful verification writes request.accessClaims.
  • Missing or invalid tokens raise ApiError(403, 'TOKEN_REQUIRED') or ApiError(403, 'INVALID_TOKEN').
  • Verification uses config.jwtPublicKey with RS256.

services/us-api/src/middleware/partnerAuth.ts

This middleware gates partner-facing consent APIs.

Public methods
Method Description Returns
requirePartnerAuth Extracts a partner token from headers or query parameters, validates it against config.partnerApiKeys, and sets request.partnerId. void
Request enrichment
Property Type Description
partnerId `string \ undefined`
Accepted token sources
  • Authorization: Bearer <token>
  • x-partner-token
  • x-api-key
  • partner_token query parameter

services/us-api/src/middleware/internalAuth.ts

This middleware protects internal analytics and control-plane routes.

Public methods
Method Description Returns
requireInternalAuth Validates the x-internal-token header or bearer token against config.internalApiToken. Promise<void>

services/us-api/src/middleware/requestId.ts

This middleware normalizes request identity for logging and response correlation.

Public methods
Method Description Returns
ensureRequestId Reuses an incoming x-request-id or creates a new UUID, then mirrors it to the response header. void

services/us-api/src/middleware/errorHandler.ts

This middleware shapes error responses for US API callers.

Public methods
Method Description Returns
errorHandler Converts ApiError instances into structured error responses and maps unexpected failures to PROVIDER_UNAVAILABLE. void
Error response shape
Property Type Description
error.code string Application error code.
error.message string Human-readable error message.
error.details unknown Optional error details payload.
request_id string Request correlation ID.

services/us-api/src/middleware/auditLogger.ts

This hook writes access logs after every response and disables itself if Prisma initialization fails.

Public methods
Method Description Returns
registerAuditLogger Registers an onResponse hook that writes an access log row for each request. Promise<void>
Access log record shape observed in this service
Property Type Description
id string Access log identifier with al_ prefix.
requestId string Request ID pulled from x-request-id.
partnerId `string \ null`
consentId `string \ null`
route string Route path or raw URL.
statusCode number Final response status code.

services/us-api/src/jobs/psuConsentTimeoutWatchdog.ts

[!NOTE] registerAuditLogger disables access-log writes after a PrismaClientInitializationError and keeps the hook in a no-op state for later responses.

This job closes stale PSU consent sessions by emitting a timeout consent event.

Public methods
Method Description Returns
runPsuConsentTimeoutWatchdog Scans consent sessions whose final status is still unset and emits a timeout event when the configured deadline is reached. Promise<void>
Timeout behavior
  • Provider-specific timeout minutes are read from PROVIDER_TIMEOUT_MINUTES.
  • DEFAULT_TIMEOUT_MINUTES defaults to 15.
  • Each stale session triggers applyConsentEvent with event_name: 'consent_timeout' and failure_reason: 'timeout'.

services/us-api/src/jobs/featureDriftJob.ts

Public methods
Method Description Returns
runDailyFeatureDriftCheck Runs drift detection for US_CASHFLOW_V1 against the global credit feature schema baseline. Promise<unknown>

services/us-api/src/jobs/retrainTriggerJob.ts

Public methods
Method Description Returns
evaluateRetrainingForModel Delegates retraining evaluation for a single model artifact. Promise<unknown>

services/us-api/src/jobs/dailyPsuConsentMetrics.ts

Public methods
Method Description Returns
runDailyPsuConsentMetricsJob Refreshes daily PSU consent metrics for the configured lookback window and run date. Promise<void>

US data gateway boundary

services/us-data-gateway/internal/auth/auth.go

The gateway verifies scoped US access tokens against the signing key and a Redis-backed session record. This is the last hop before a partner receives US banking data.

Public methods
Method Description Returns
Verify Verifies the JWT signature, checks the Redis session record for revocation, and returns the token claims. (*Claims, error)
Claims
Property Type Description
ConsentID string Consent identifier encoded as cid.
Purpose string Purpose encoded as pur.
Categories []string Allowed categories encoded as cat.
RegisteredClaims jwt.RegisteredClaims Standard JWT claims including ID for session lookup.
Token verification flow
  • Signature verification uses RS256.
  • Session state is read from Redis key session:<claims.ID>.
  • A session value with revoked: true blocks access.
Redis session key
Key pattern Purpose
session:<jti> Revocation and session status lookup for access tokens.

services/us-data-gateway/internal/provider/provider.go

This interface abstracts the gateway’s upstream data source.

Public methods
Method Description Returns
FetchAccounts Returns account records for a consent. ([]Account, error)
FetchBalances Returns balance records for a consent. ([]Balance, error)
FetchTransactions Returns transactions for a consent and date window. ([]Transaction, error)
FetchTransactionsSync Returns a sync delta and cursor. (TransactionSync, error)
FetchIncome Returns income records for a consent and lookback window. ([]Income, error)
Provider data models
Property Type Description
Account.AccountToken string Upstream account token.
Account.Name string Account label.
Account.Type string Account type string.
Account.Mask string Account mask.
Balance.AccountToken string Linked account token.
Balance.Available float64 Available balance.
Balance.Current float64 Current balance.
Balance.Currency string Currency code.
Transaction.TransactionID string Transaction identifier.
Transaction.AccountToken string Linked account token.
Transaction.Amount float64 Transaction amount.
Transaction.Currency string Currency code.
Transaction.PostedAt string Posting timestamp.
Transaction.MerchantName string Merchant name.
Transaction.MerchantCategory string Merchant category.
TransactionRemoval.TransactionID string Removed transaction identifier.
TransactionSync.Added []Transaction Newly added transactions.
TransactionSync.Modified []Transaction Modified transactions.
TransactionSync.Removed []TransactionRemoval Removed transaction IDs.
TransactionSync.NextCursor string Cursor for the next sync page.
Income.IncomeID string Income record identifier.
Income.Amount float64 Income amount.
Income.Currency string Currency code.
Income.PayDate string Pay date timestamp.

services/us-data-gateway/internal/provider/mock.go

This implementation provides the mocked upstream data used by the gateway.

Public methods
Method Description Returns
FetchAccounts Returns two mock depository accounts. ([]Account, error)
FetchBalances Returns balances for the mock accounts. ([]Balance, error)
FetchTransactions Returns a mock transaction list. ([]Transaction, error)
FetchTransactionsSync Returns a mock sync delta with added, modified, and removed records. (TransactionSync, error)
FetchIncome Returns a mock income list. ([]Income, error)

services/us-data-gateway/internal/handlers/handlers.go

This handler layer enforces consent scope before returning data to the caller.

Public methods
Method Description Returns
Accounts Returns the account list for the consent after token and category checks. void
Balances Returns balances for the consent after token and category checks. void
Transactions Returns transactions for the consent and optional date window after token and category checks. void
TransactionsSync Returns the sync delta for the consent and optional cursor after token and category checks. void
Income Returns income data for the consent after token and category checks. void
Handler dependencies
Type Description
*pgxpool.Pool PostgreSQL access for consent lookup.
provider.Provider Upstream banking data provider.
auth.TokenVerifier JWT and Redis-backed token verifier.
consentRecord
Property Type Description
ID string Consent ID loaded from the database.
Status string Consent status.
ExpiresAt time.Time Consent expiration.
Categories []string Allowed data categories.
Gateway behavior
  • Each handler calls authorize first.
  • Each handler checks the token’s category list before fetching data.
  • Each handler loads the consent record and rejects inactive or expired consent.
  • The Income handler defaults lookback_days to 180 when the query parameter is missing or invalid.
  • The transaction-related handlers accept optional query filters and return sorted data.

Feature Flows

sequenceDiagram
    participant Partner as Partner Client
    participant Consent as consentService createConsent
    participant Token as tokenService exchangeToken
    participant Webhook as webhookService dispatchWebhook
    participant Access as requireAccessToken
    participant Gateway as us-data-gateway Handler
    participant Auth as auth TokenVerifier
    participant Redis as Redis
    participant DB as Consent DB
    participant Provider as provider interface

    Partner->>Consent: createConsent
    Consent->>DB: insert consent and consent log
    Consent-->>Partner: consent record with PENDING_USER_ACTION

    Partner->>Token: exchangeToken
    Token->>DB: activate consent when pending
    Token->>DB: insert token and consent log
    Token->>Webhook: dispatchWebhook consent_activated
    Token-->>Partner: TokenPair

    Partner->>Access: send access token
    Access->>Access: verify jwt and attach accessClaims

    Partner->>Gateway: GET data endpoint
    Gateway->>Auth: Verify
    Auth->>Redis: HGetAll session jti
    Auth->>DB: load consent record
    Gateway->>Provider: FetchAccounts or FetchBalances
    Provider-->>Gateway: scoped data
    Gateway-->>Partner: JSON response

Evidence generation and scoring replay

sequenceDiagram
    participant App as Application Service
    participant Feature as featureService computeCashflow
    participant Mock as mockProvider
    participant Gov as modelGovernanceService
    participant Score as scoringService storeDecision
    participant DB as Prisma persistence

    App->>Feature: computeCashflow
    Feature->>Mock: balances transactions income
    Feature->>Gov: ensureFeatureSchemaVersion
    Feature->>DB: insert evidenceSnapshot
    Feature-->>App: evidence_ref and migrated features

    App->>Score: storeDecision
    Score->>DB: load evidence snapshot
    Score->>Gov: recordModelLineage when model is present
    Score->>DB: insert decision
    Score-->>App: decision_id
sequenceDiagram
    participant Partner as Partner Client
    participant Consent as consentService revokeConsent
    participant DB as Prisma persistence
    participant Token as token table
    participant Conn as connection table
    participant Webhook as webhookService

    Partner->>Consent: revokeConsent
    Consent->>DB: find consent by id
    Consent->>DB: update consent status to REVOKED
    Consent->>Token: revoke active tokens
    Consent->>Conn: set connections to DISCONNECTED
    Consent->>DB: insert consent log
    Consent->>Webhook: dispatchWebhook consent_revoked
    Consent-->>Partner: consentId

State Management

stateDiagram-v2
    [*] --> PENDING_USER_ACTION
    PENDING_USER_ACTION --> ACTIVE: exchangeToken
    ACTIVE --> REVOKED: revokeConsent
    PENDING_USER_ACTION --> REVOKED: revokeConsent
State Meaning
PENDING_USER_ACTION Consent exists but has not yet been activated by token exchange.
ACTIVE Consent is live and can support token issuance and data access.
REVOKED Consent is no longer valid and cannot support access or refresh.

Connection readiness states

State Meaning
ACTIVE Connection readiness succeeded.
REAUTH_REQUIRED The connection needs re-authentication and exposes a reauth_link.
DEGRADED The connection is usable but degraded.
DISCONNECTED Consent revocation forces downstream disconnection.

Token and refresh state

State Meaning
Active access token JWT verified by requireAccessToken and backed by a live token row.
Refresh token Opaque value hashed into token.refreshTokenHash.
Revoked token Token row marked with revokedAt, which blocks introspection and downstream use.
Refresh quota state refreshEvent rows count refreshes per consent per day.

Evidence and governance state

State Meaning
US_CASHFLOW_V1 Source feature set computed from the US provider data.
global-credit-v1 Canonical schema version written to snapshots and governance records.
PENDING retrain trigger Threshold breach captured for later retraining workflow.

Error Handling

The US API layer uses ApiError for controlled failures and translates them through errorHandler. Middleware fails early on missing tokens, invalid scopes, and invalid internal auth before handlers execute.

Location Error behavior
middleware/accessToken.ts TOKEN_REQUIRED and INVALID_TOKEN for missing or malformed access tokens.
middleware/partnerAuth.ts PARTNER_AUTH_REQUIRED for missing or invalid partner credentials.
middleware/internalAuth.ts FORBIDDEN when the internal token does not match.
services/consentService.ts NOT_FOUND for missing consent, CONSENT_REVOKED for inactive or expired consent.
services/tokenService.ts LEGAL_RESTRICTION, CONSENT_REVOKED, REFRESH_LIMIT_EXCEEDED.
services/connectionService.ts REAUTH_REQUIRED with reauth_link.
services/scoringService.ts LEGAL_RESTRICTION, NOT_FOUND, PROVIDER_UNAVAILABLE.
webhookService.ts PROVIDER_UNAVAILABLE when outbound webhook delivery fails.
modelGovernanceService.ts Plain Error for missing baseline or missing evidence snapshots.

Caching Strategy

Redis-backed token session checks

[!IMPORTANT] errorHandler maps unexpected exceptions to a 500 response with PROVIDER_UNAVAILABLE and preserves request_id so the caller can correlate the failure with audit logs.

The US data gateway reads session:<jti> from Redis inside auth.TokenVerifier.Verify.

Cache key Owner Purpose Invalidated by
session:<jti> auth.TokenVerifier Token session and revocation lookup Session state changes in Redis

Refresh limit tracking

The token service uses the database-backed refreshEvent table as a per-day refresh ledger.

Key or store Owner Purpose Invalidated by
refreshEvent rows tokenService Count refreshes per consent per day Day boundary rollover

Audit logging guard

registerAuditLogger does not use a cache, but it maintains an in-memory enable flag after a Prisma initialization failure.

Flag Owner Purpose
auditLoggingEnabled registerAuditLogger Prevent repeated failed writes after a database initialization error

API Integration

US Data Gateway endpoints

Get Accounts

{
    "title": "Get Accounts",
    "description": "Returns accounts for a consented US access token when the token includes the ACCOUNTS category and the consent is still active",
    "method": "GET",
    "baseUrl": "<USDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/accounts",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Accounts returned for the consent",
            "body": "{\n    \"accounts\": [\n        {\n            \"account_token\": \"acct_tok_1\",\n            \"name\": \"Checking\",\n            \"type\": \"depository\",\n            \"mask\": \"1234\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Token missing or category not allowed",
            "body": "{\n    \"error\": \"CATEGORY_NOT_ALLOWED\"\n}"
        },
        "409": {
            "description": "Consent has been revoked or expired",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

Get Balances

{
    "title": "Get Balances",
    "description": "Returns balance records for a consented US access token when the token includes the BALANCES category and the consent is still active",
    "method": "GET",
    "baseUrl": "<USDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/balances",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Balances returned for the consent",
            "body": "{\n    \"balances\": [\n        {\n            \"account_token\": \"acct_tok_1\",\n            \"available\": 1200,\n            \"current\": 1500,\n            \"currency\": \"USD\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Token missing or category not allowed",
            "body": "{\n    \"error\": \"CATEGORY_NOT_ALLOWED\"\n}"
        },
        "409": {
            "description": "Consent has been revoked or expired",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

Get Transactions

{
    "title": "Get Transactions",
    "description": "Returns transactions for a consented US access token when the token includes the TRANSACTIONS category and the consent is still active",
    "method": "GET",
    "baseUrl": "<USDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/transactions",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "from",
            "required": false,
            "description": "Optional lower bound for the transaction date window"
        },
        {
            "key": "to",
            "required": false,
            "description": "Optional upper bound for the transaction date window"
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transactions returned for the consent",
            "body": "{\n    \"transactions\": [\n        {\n            \"transaction_id\": \"txn_1\",\n            \"account_token\": \"acct_tok_1\",\n            \"amount\": 1200,\n            \"currency\": \"USD\",\n            \"posted_at\": \"2024-10-01T00:00:00Z\",\n            \"merchant_name\": \"Rent Co\",\n            \"merchant_category\": \"RENT\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Token missing or category not allowed",
            "body": "{\n    \"error\": \"CATEGORY_NOT_ALLOWED\"\n}"
        },
        "409": {
            "description": "Consent has been revoked or expired",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

Get Transactions Sync

{
    "title": "Get Transactions Sync",
    "description": "Returns a transaction sync delta for a consented US access token when the token includes the TRANSACTIONS category and the consent is still active",
    "method": "GET",
    "baseUrl": "<USDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/transactions/sync",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "cursor",
            "required": false,
            "description": "Optional sync cursor"
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transaction sync delta returned for the consent",
            "body": "{\n    \"added\": [\n        {\n            \"transaction_id\": \"txn_3\",\n            \"account_token\": \"acct_tok_2\",\n            \"amount\": 45,\n            \"currency\": \"USD\",\n            \"posted_at\": \"2024-10-03T00:00:00Z\",\n            \"merchant_name\": \"Coffee\",\n            \"merchant_category\": \"FOOD\"\n        }\n    ],\n    \"modified\": [\n        {\n            \"transaction_id\": \"txn_2\",\n            \"account_token\": \"acct_tok_1\",\n            \"amount\": 90,\n            \"currency\": \"USD\",\n            \"posted_at\": \"2024-10-02T00:00:00Z\",\n            \"merchant_name\": \"Card\",\n            \"merchant_category\": \"DEBT\"\n        }\n    ],\n    \"removed\": [\n        {\n            \"transaction_id\": \"txn_4\"\n        }\n    ],\n    \"next_cursor\": \"cursor_next_1\"\n}"
        },
        "403": {
            "description": "Token missing or category not allowed",
            "body": "{\n    \"error\": \"CATEGORY_NOT_ALLOWED\"\n}"
        },
        "409": {
            "description": "Consent has been revoked or expired",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

Get Income

{
    "title": "Get Income",
    "description": "Returns income records for a consented US access token when the token includes the INCOME category and the consent is still active",
    "method": "GET",
    "baseUrl": "<USDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/income",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "lookback_days",
            "required": false,
            "description": "Optional lookback window in days; defaults to 180 when absent or invalid"
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Income returned for the consent",
            "body": "{\n    \"income\": [\n        {\n            \"income_id\": \"inc_1\",\n            \"amount\": 5100,\n            \"currency\": \"USD\",\n            \"pay_date\": \"2024-09-30T00:00:00Z\"\n        },\n        {\n            \"income_id\": \"inc_2\",\n            \"amount\": 5300,\n            \"currency\": \"USD\",\n            \"pay_date\": \"2024-10-15T00:00:00Z\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Token missing or category not allowed",
            "body": "{\n    \"error\": \"CATEGORY_NOT_ALLOWED\"\n}"
        },
        "409": {
            "description": "Consent has been revoked or expired",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

Testing Considerations

The repository tests exercise the core consent and access paths, so these are the scenarios that should stay green:

  • consent creation returns a pending consent record
  • revocation updates consent state and succeeds with a request ID
  • refresh token enforcement returns 429 when the daily limit is reached
  • category enforcement returns 403 for account access without the right scope
  • PSU analytics event replay is idempotent
  • the first terminal consent event wins
  • timeout watchdog emits consent_timeout for stale sessions

Dependencies

Runtime libraries and services

  • prisma for consent, token, connection, evidence, decision, webhook, and governance persistence
  • jsonwebtoken for RS256 access-token issuance and verification
  • crypto for ID generation, hashing, HMAC signatures, and digests
  • fetch for outbound webhook delivery and scoring callback replay
  • PostgreSQL for analytics and consent state
  • Redis for gateway session revocation lookups
  • mockProvider for the feature computation path in this service layer

Service coupling

  • consentService depends on webhookService
  • tokenService depends on consent and token persistence plus webhookService
  • featureService depends on modelGovernanceService and mockProvider
  • scoringService depends on featureService evidence snapshots and modelGovernanceService
  • auth.TokenVerifier depends on Redis session data and the JWT public key

Key Classes Reference

Class Responsibility
types.ts Defines consent purpose, data category, connection status, and token claim primitives.
creditFeatureSchema.ts Defines the global credit feature schema and migration bridge.
consentService.ts Creates, revokes, receipts, and validates US consent records.
tokenService.ts Mints, refreshes, and introspects scoped access tokens.
connectionService.ts Evaluates connection readiness and refreshes connection state.
featureService.ts Computes US cashflow features and persists evidence snapshots.
scoringService.ts Validates, stores, and replays scoring decisions.
modelGovernanceService.ts Registers feature schemas, tracks drift, and evaluates retraining triggers.
webhookService.ts Delivers signed lifecycle webhooks to partner endpoints.
accessToken.ts Verifies access tokens and attaches scoped claims to the request.
partnerAuth.ts Authenticates partner-facing consent requests.
internalAuth.ts Protects internal control-plane routes.
requestId.ts Normalizes request correlation IDs.
auditLogger.ts Writes access logs after responses and self-disables on DB initialization failure.
auth.go Verifies gateway access tokens against JWT and Redis session state.
handlers.go Enforces consent scope and serves data-gateway responses.
provider.go Defines the data gateway provider contract and response models.