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. |
Consent receipt output
| 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. |
Consent record shape observed in this service
| 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. |
| 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> |
| 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
Consent creation, activation, and scoped data access
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
Consent revocation and downstream teardown
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
Consent status lifecycle
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. |