Authentication and Authorization Domain Middleware
Overview
The US API uses a small set of cross-cutting middleware to enforce request identity, consent-scoped access, partner authentication, and internal admin access before any route handler runs. The same middleware layer also enriches audit logs with x-request-id, partner identity, consent identity, and response status so every request can be traced after it leaves the handler.
This is a service-layer security boundary, not a user-facing feature. In this repo, the US API middleware owns token validation and request instrumentation for standalone routes such as /internal/analytics/events and /internal/analytics/psu-consent/metrics, while the broader backend path shown in the repo is centered on application-level API calls and token forwarding rather than this consent-scoped validation stack.
Architecture Overview
flowchart TB
Client[Client or Internal Caller] --> RequestId[ensureRequestId]
RequestId --> PartnerAuth[requirePartnerAuth]
RequestId --> AccessToken[requireAccessToken]
RequestId --> InternalAuth[requireInternalAuth]
PartnerAuth --> PartnerRoutes[Partner Route Handlers]
AccessToken --> PartnerRoutes
InternalAuth --> InternalAnalytics[registerInternalAnalyticsRoutes]
PartnerRoutes --> AuditLogger[registerAuditLogger]
InternalAnalytics --> AuditLogger
PartnerRoutes --> ErrorHandler[errorHandler]
InternalAnalytics --> ErrorHandler
RequestId --> ErrorHandler
subgraph RuntimeDependencies[Runtime Dependencies]
Config[config]
Jwt[jwt]
Prisma[prisma]
ApiError[ApiError]
end
PartnerAuth --> Config
AccessToken --> Config
InternalAuth --> Config
AccessToken --> Jwt
AuditLogger --> Prisma
ErrorHandler --> ApiError
Middleware Components
Request Identity
services/us-api/src/middleware/requestId.ts
ensureRequestId is the request identity shim for the US API. It ensures every request has an x-request-id value in the incoming header map and mirrors it back to the client as X-Request-Id.
Public methods
| Method | Description |
|---|---|
ensureRequestId |
Reads x-request-id or generates a new UUID, stores it on the request, and writes the response header. |
Properties
| Property | Type | Description |
|---|---|---|
request.headers['x-request-id'] |
string |
Incoming request identifier used by later middleware and error responses. |
reply.header('X-Request-Id', ...) |
string |
Response header emitted by the middleware. |
Behavior
- Uses the incoming
x-request-idheader when it is a non-empty string. - Generates a new
crypto.randomUUID()value when the header is missing or empty. - Mutates
request.headers['x-request-id']so downstream code sees the normalized value. - Sets
X-Request-Idon the reply before the handler executes.
Partner Authentication
services/us-api/src/middleware/partnerAuth.ts
requirePartnerAuth validates partner-level access using a shared API key list from config.partnerApiKeys. When authentication succeeds, it stores the matched token in request.partnerId for later logging.
Public methods
| Method | Description |
|---|---|
requirePartnerAuth |
Accepts a partner token from headers or query string, validates it against config.partnerApiKeys, and populates request.partnerId. |
Properties
| Property | Type | Description |
|---|---|---|
request.partnerId |
`string \ | undefined` |
request.headers.authorization |
`string \ | undefined` |
request.headers['x-partner-token'] |
`string \ | undefined` |
request.headers['x-api-key'] |
`string \ | undefined` |
request.query.partner_token |
`string \ | undefined` |
Behavior
- Reads the token from
Authorization: Bearer ...,x-partner-token,x-api-key, orpartner_token. - Rejects the request with
ApiError(403, 'PARTNER_AUTH_REQUIRED')when no token is present. - Rejects the request with the same code when the token is not present in
config.partnerApiKeys. - Stores the validated token on
request.partnerIdand callsdone().
Access Token Authentication
services/us-api/src/middleware/accessToken.ts
requireAccessToken validates consent-scoped JWTs with the US API public key and attaches the decoded claims to request.accessClaims. The claims shape is intentionally narrow and only preserves consent, purpose, data categories, and JWT ID.
Public methods
| Method | Description |
|---|---|
requireAccessToken |
Validates a consent JWT from headers or query string and stores the parsed claims on the request. |
Properties
| Property | Type | Description |
|---|---|---|
request.accessClaims |
`AccessClaims \ | undefined` |
request.headers.authorization |
`string \ | undefined` |
request.headers['x-access-token'] |
`string \ | undefined` |
request.query.access_token |
`string \ | undefined` |
AccessClaims fields
| Property | Type |
|---|---|
consent_id |
string |
purpose |
Purpose |
data_categories |
DataCategory[] |
jti |
string |
Purpose values
RENTAL_SCREENING, LENDING_UNDERWRITING, ACCOUNT_OPENING, INCOME_VERIFICATION, FRAUD_PREVENTION, GENERAL_PERSONAL_FINANCE
DataCategory values
IDENTITY_BASIC, ACCOUNTS, BALANCES, TRANSACTIONS, INCOME, EMPLOYMENT, CASHFLOW_FEATURES, DEVICE_RISK, WATCHLIST_SCREENING
Behavior
- Accepts JWTs from
Authorization: Bearer ...,x-access-token, oraccess_token. - Rejects missing tokens with
ApiError(403, 'TOKEN_REQUIRED'). - Verifies the token with
jwt.verify(token, config.jwtPublicKey, { algorithms: ['RS256'] }). - Rejects any non-object or structurally incomplete payload with
ApiError(403, 'INVALID_TOKEN'). - Requires all four claims:
consent_id,purpose,data_categories, andjti. - Writes the extracted claims to
request.accessClaimsfor downstream business logic and audit logging.
Internal Authentication
services/us-api/src/middleware/internalAuth.ts
requireInternalAuth gates internal-only routes using a single shared token from config.internalApiToken. It does not attach request-scoped identity; its job is only to allow or deny the request.
Public methods
| Method | Description |
|---|---|
requireInternalAuth |
Validates the internal admin token from x-internal-token or Bearer auth and rejects mismatches. |
Properties
| Property | Type | Description |
|---|---|---|
request.headers['x-internal-token'] |
`string \ | undefined` |
request.headers.authorization |
`string \ | undefined` |
config.internalApiToken |
string |
Shared internal secret used for comparison. |
Behavior
- Accepts the token from
x-internal-tokenorAuthorization: Bearer .... - Rejects requests when the token is missing or does not exactly match
config.internalApiToken. - Throws
ApiError(403, 'FORBIDDEN', 'Internal API token required.')on failure.
Audit Instrumentation
services/us-api/src/middleware/auditLogger.ts
registerAuditLogger installs a Fastify onResponse hook that persists a per-request access log in Prisma after the route finishes. The log record combines request identity, partner identity, consent identity, route, and response status.
Public methods
| Method | Description |
|---|---|
registerAuditLogger |
Registers the response hook that writes access logs and disables itself after Prisma initialization failures. |
Properties
| Property | Type | Description |
|---|---|---|
auditLoggingEnabled |
boolean |
Module flag that disables further audit writes after a Prisma initialization error. |
auditLoggingDisabledLogged |
boolean |
Module flag that prevents repeated warnings after audit logging is disabled. |
request.headers['x-request-id'] |
string |
Request identifier copied into the access log row. |
request.partnerId |
`string \ | null` |
request.accessClaims.consent_id |
`string \ | null` |
request.routeOptions.url |
`string \ | undefined` |
reply.statusCode |
number |
Final response status stored in the access log. |
Access log record shape
| Field | Type | Description |
|---|---|---|
id |
string |
Random al_ prefixed identifier created with crypto.randomBytes(6). |
requestId |
string |
Copied from x-request-id. |
partnerId |
`string \ | null` |
consentId |
`string \ | null` |
route |
string |
Derived from request.routeOptions?.url, request.raw.url, or unknown. |
statusCode |
number |
Final HTTP status code. |
Behavior
- Runs after the response is produced, not before the handler.
- Writes one
prisma.accessLog.create(...)row per completed request when audit logging is enabled. - Disables future audit writes if Prisma raises
Prisma.PrismaClientInitializationError. - Emits a single warning when that disablement happens.
- Logs all other Prisma write failures as warnings without disabling the hook.
Error Translation
[!NOTE]
auditLoggingEnabledis flipped tofalseafter the first Prisma initialization error, and the hook stops writing any further access logs for the lifetime of the process. The disablement is permanent until the service restarts.
services/us-api/src/middleware/errorHandler.ts
errorHandler normalizes all Fastify errors into the response format used by the US API. It preserves explicit ApiError status codes and converts all other failures into a generic PROVIDER_UNAVAILABLE error envelope.
Public methods
| Method | Description |
|---|---|
errorHandler |
Converts thrown errors into the API error response format and echoes request_id. |
Properties
| Property | Type | Description |
|---|---|---|
request.headers['x-request-id'] |
`string \ | undefined` |
error.statusCode |
number |
Used for ApiError responses. |
error.code |
string |
API error code sent to the client. |
error.message |
string |
Human-readable error message sent to the client. |
error.details |
unknown |
Optional error details sent to the client. |
Behavior
- For
ApiError, returns:error.codeerror.messageerror.detailsrequest_id
- For any other error, returns HTTP 500 with:
PROVIDER_UNAVAILABLEUnexpected errorrequest_id
- Reads the request ID from the incoming headers rather than from response headers.
Request Identity and Authorization Flow
Cross-cutting request identity
| Input | Middleware | Stored On Request | Used By |
|---|---|---|---|
x-request-id |
ensureRequestId |
request.headers['x-request-id'] |
registerAuditLogger, errorHandler |
| Partner token headers or query parameter | requirePartnerAuth |
request.partnerId |
registerAuditLogger |
| Access JWT headers or query parameter | requireAccessToken |
request.accessClaims |
registerAuditLogger, route handlers |
| Internal token header or Bearer auth | requireInternalAuth |
none | internal-only routes |
Execution order
[!NOTE] The generic branch always maps unexpected failures to
PROVIDER_UNAVAILABLE, even when the underlying exception is unrelated to provider availability. That means the client sees a stable envelope, but not the original failure class.
ensureRequestIdnormalizes or creates the request ID.requirePartnerAuth,requireAccessToken, orrequireInternalAuthgates the route.- The route handler executes.
registerAuditLoggerwrites the access log fromonResponse.errorHandleremits the final error envelope when a handler or middleware throws.
Interaction between partner auth and access tokens
requirePartnerAuthidentifies the calling partner and stores the token inrequest.partnerId.requireAccessTokenidentifies the consent-bound subject and stores parsed JWT claims inrequest.accessClaims.registerAuditLoggercan combine both values in the same access log row when a route uses both middlewares.- The two middlewares are independent: one authenticates the partner, the other authenticates consent-scoped access.
Internal admin token flow
requireInternalAuthis separate from the partner and access-token paths.- It checks a single shared secret and does not attach identity claims.
- It is used by internal-only routes such as the analytics endpoints below.
API Endpoints
Create Internal Analytics Event
services/us-api/src/routes/internalAnalytics.ts
{
"title": "Create Internal Analytics Event",
"description": "Validates the analytics event body, requires requireInternalAuth, and applies the consent event through applyConsentEvent. The route returns 409 when the analytics layer reports dimension_mismatch.",
"method": "POST",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/internal/analytics/events",
"headers": [
{
"key": "x-internal-token",
"value": "<internal-api-token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"psu_id\": \"psu_123\",\n \"consent_session_id\": \"sess_123\",\n \"product\": \"product_a\",\n \"country\": \"US\",\n \"provider\": \"provider_a\",\n \"institution_id\": \"inst_123\",\n \"timestamp\": \"2024-01-01T00:00:00.000Z\",\n \"failure_reason\": \"timeout\",\n \"event_name\": \"consent_timeout\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Event applied successfully",
"body": "{\n \"status\": \"applied\"\n}"
},
"400": {
"description": "Invalid request body",
"body": "{\n \"error\": {\n \"code\": \"INVALID_BODY\",\n \"message\": \"string\",\n \"details\": \"string\"\n },\n \"request_id\": \"req_123\"\n}"
},
"403": {
"description": "Internal API token required",
"body": "{\n \"error\": {\n \"code\": \"FORBIDDEN\",\n \"message\": \"Internal API token required.\",\n \"details\": null\n },\n \"request_id\": \"req_123\"\n}"
},
"409": {
"description": "Dimension mismatch",
"body": "{\n \"status\": \"dimension_mismatch\"\n}"
}
}
}
Get PSU Consent Metrics
services/us-api/src/routes/internalAnalytics.ts
{
"title": "Get PSU Consent Metrics",
"description": "Validates date filters, requires requireInternalAuth, and returns the combined daily, funnel, failure, and latency metrics produced by the analytics helpers.",
"method": "GET",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/internal/analytics/psu-consent/metrics",
"headers": [
{
"key": "x-internal-token",
"value": "<internal-api-token>",
"required": true
}
],
"queryParams": [
{
"key": "start_date",
"value": "2024-01-01",
"required": true
},
{
"key": "end_date",
"value": "2024-01-31",
"required": true
},
{
"key": "product",
"value": "product_a",
"required": false
},
{
"key": "country",
"value": "US",
"required": false
},
{
"key": "provider",
"value": "provider_a",
"required": false
},
{
"key": "institution_id",
"value": "inst_123",
"required": false
}
],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Aggregated analytics payload",
"body": "{\n \"daily\": [],\n \"funnel\": [],\n \"failures\": [],\n \"latency\": []\n}"
},
"400": {
"description": "Invalid query parameters",
"body": "{\n \"error\": {\n \"code\": \"INVALID_QUERY\",\n \"message\": \"string\",\n \"details\": \"string\"\n },\n \"request_id\": \"req_123\"\n}"
},
"403": {
"description": "Internal API token required",
"body": "{\n \"error\": {\n \"code\": \"FORBIDDEN\",\n \"message\": \"Internal API token required.\",\n \"details\": null\n },\n \"request_id\": \"req_123\"\n}"
}
}
}
Feature Flows
Internal Analytics Request Flow
sequenceDiagram
participant Caller as Internal Caller
participant Fastify as Fastify App
participant RequestId as ensureRequestId
participant InternalAuth as requireInternalAuth
participant Route as registerInternalAnalyticsRoutes
participant DB as pool
participant Audit as registerAuditLogger
participant Err as errorHandler
Caller->>Fastify: POST internal analytics event
Fastify->>RequestId: normalize x-request-id
Fastify->>InternalAuth: validate x-internal-token
InternalAuth-->>Fastify: allow or throw ApiError
Fastify->>Route: parse body and call applyConsentEvent
Route->>DB: write analytics rows
Route-->>Fastify: status payload
Fastify->>Audit: onResponse write accessLog
Fastify-->>Caller: JSON response
Caller->>Fastify: invalid token or bad payload
Fastify->>Err: format ApiError response
Err-->>Caller: error JSON with request_id
Partner or Consent Scoped Request Flow
sequenceDiagram
participant Client as Client
participant Fastify as Fastify App
participant RequestId as ensureRequestId
participant PartnerAuth as requirePartnerAuth
participant AccessToken as requireAccessToken
participant Route as Partner Route Handler
participant Audit as registerAuditLogger
participant Err as errorHandler
Client->>Fastify: request with partner token or access JWT
Fastify->>RequestId: normalize x-request-id
Fastify->>PartnerAuth: validate partner token
PartnerAuth-->>Fastify: set request.partnerId
Fastify->>AccessToken: verify RS256 JWT
AccessToken-->>Fastify: set request.accessClaims
Fastify->>Route: execute business logic
Route-->>Fastify: response body
Fastify->>Audit: onResponse write accessLog with partnerId and consentId
Fastify-->>Client: response with X-Request-Id
Client->>Fastify: auth failure
Fastify->>Err: emit ApiError envelope
Err-->>Client: error JSON with request_id
State Management
Module-level state in audit logging
| State | Type | Meaning |
|---|---|---|
auditLoggingEnabled |
boolean |
Controls whether registerAuditLogger continues to write access logs. |
auditLoggingDisabledLogged |
boolean |
Ensures the disablement warning is emitted once. |
State transitions
stateDiagram-v2
[*] --> Enabled
Enabled --> Disabled: PrismaClientInitializationError
Disabled --> Disabled: subsequent responses
Request-scoped state
| Request field | Producer | Consumer |
|---|---|---|
request.headers['x-request-id'] |
ensureRequestId |
registerAuditLogger, errorHandler |
request.partnerId |
requirePartnerAuth |
registerAuditLogger |
request.accessClaims |
requireAccessToken |
registerAuditLogger, route handlers |
Error Handling
The US API uses ApiError as the explicit control path for security and validation failures. Middleware throws ApiError with a status code and code string, and errorHandler serializes that object into the standard response envelope.
Error envelope shape
| Field | Source |
|---|---|
error.code |
ApiError.code |
error.message |
ApiError.message |
error.details |
ApiError.details |
request_id |
x-request-id request header |
Observed error codes in this section
TOKEN_REQUIRED, INVALID_TOKEN, PARTNER_AUTH_REQUIRED, FORBIDDEN, INVALID_BODY, INVALID_QUERY, PROVIDER_UNAVAILABLE
Error propagation sequence
- Middleware throws
ApiError. - Fastify delegates to
errorHandler. errorHandlerechoesrequest_id.- The client receives the JSON envelope with the route-specific HTTP status.
Comparison with the Main Backend Auth Responsibilities
The standalone US API middleware is infrastructure-first: it validates partner tokens, consent JWTs, and internal admin tokens before any route executes, and it records request identity for auditability. The main backend path shown in this repo is more application-oriented; for example, backend/src/scripts/create_test_application.py only adds a Bearer Authorization header when an application API token is present, and the surrounding backend flow focuses on application submission and status management rather than this middleware stack.
The practical difference is scope. In the US API, auth is a reusable service-layer guardrail around request identity and consent-scoped access; in the main backend, auth is tied to application workflows and token forwarding at the edge of those flows.
Dependencies
| Dependency | Used By | Purpose |
|---|---|---|
fastify |
all middleware files | Request and reply types, hooks, and request augmentation. |
jsonwebtoken |
accessToken.ts |
RS256 verification of consent access JWTs. |
crypto |
requestId.ts, auditLogger.ts |
UUID generation, random IDs, and hash-safe log IDs. |
@prisma/client |
auditLogger.ts |
Prisma error detection. |
prisma |
auditLogger.ts, internalAnalytics.ts |
Access log persistence and analytics writes. |
config |
accessToken.ts, partnerAuth.ts, internalAuth.ts |
Public key, partner key list, and internal token source. |
ApiError |
all middleware and error handler | Consistent API error signaling. |
Testing Considerations
- Validate that
ensureRequestIdpreserves an incomingx-request-idand generates one when absent. - Validate that
requirePartnerAuthacceptsAuthorization,x-partner-token,x-api-key, andpartner_token, and rejects tokens not inconfig.partnerApiKeys. - Validate that
requireAccessTokenrejects missing or malformed JWTs and storesrequest.accessClaimsonly after RS256 verification succeeds. - Validate that
requireInternalAuthrejects any token that does not exactly matchconfig.internalApiToken. - Validate that
registerAuditLoggerwrites oneaccessLogrow withrequestId,partnerId,consentId,route, andstatusCode. - Validate that
auditLoggingEnabledflips tofalseon Prisma initialization failures and suppresses future writes. - Validate that
errorHandlerpreservesApiErrorstatus codes and includesrequest_idin every response envelope.
Key Classes Reference
| Class | Responsibility |
|---|---|
accessToken.ts |
Verifies consent JWTs and stores decoded claims on the Fastify request. |
partnerAuth.ts |
Validates partner tokens and stores the partner identity on the request. |
internalAuth.ts |
Enforces the internal admin token for internal-only routes. |
requestId.ts |
Ensures every request has a request ID and echoes it in the response header. |
auditLogger.ts |
Writes access log rows after responses complete and disables itself on Prisma initialization failure. |
errorHandler.ts |
Normalizes thrown errors into the US API error envelope. |
internalAnalytics.ts |
Exposes internal analytics endpoints protected by internal auth. |