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-id header 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-Id on 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, or partner_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.partnerId and calls done().

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, or access_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, and jti.
  • Writes the extracted claims to request.accessClaims for 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-token or Authorization: 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] auditLoggingEnabled is flipped to false after 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.code
    • error.message
    • error.details
    • request_id
  • For any other error, returns HTTP 500 with:
    • PROVIDER_UNAVAILABLE
    • Unexpected error
    • request_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.

  1. ensureRequestId normalizes or creates the request ID.
  2. requirePartnerAuth, requireAccessToken, or requireInternalAuth gates the route.
  3. The route handler executes.
  4. registerAuditLogger writes the access log from onResponse.
  5. errorHandler emits the final error envelope when a handler or middleware throws.

Interaction between partner auth and access tokens

  • requirePartnerAuth identifies the calling partner and stores the token in request.partnerId.
  • requireAccessToken identifies the consent-bound subject and stores parsed JWT claims in request.accessClaims.
  • registerAuditLogger can 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

  • requireInternalAuth is 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}"
        }
    }
}

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
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

  1. Middleware throws ApiError.
  2. Fastify delegates to errorHandler.
  3. errorHandler echoes request_id.
  4. 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 ensureRequestId preserves an incoming x-request-id and generates one when absent.
  • Validate that requirePartnerAuth accepts Authorization, x-partner-token, x-api-key, and partner_token, and rejects tokens not in config.partnerApiKeys.
  • Validate that requireAccessToken rejects missing or malformed JWTs and stores request.accessClaims only after RS256 verification succeeds.
  • Validate that requireInternalAuth rejects any token that does not exactly match config.internalApiToken.
  • Validate that registerAuditLogger writes one accessLog row with requestId, partnerId, consentId, route, and statusCode.
  • Validate that auditLoggingEnabled flips to false on Prisma initialization failures and suppresses future writes.
  • Validate that errorHandler preserves ApiError status codes and includes request_id in 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.