@heyatom/bastion-client 0.7.2 → 0.8.0

package/dist/esm/core/bastion-http.js

@@ -1,4 +1,5 @@
-import { BastionErrorCode, BastionHttpError } from './errors.js';
+import { BastionErrorCode, BastionHttpError, isBastionErrorCode } from './errors.js';
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
 /**
  * Outbound calls to Bastion. Nothing here verifies inbound tokens — that is
  * `JwksVerifier`. `call` is public so a service can reach any route with the
@@ -10,11 +11,13 @@ export class BastionHttp {
     baseUrl;
     timeoutMs;
     fetchImpl;
+    requestId;
     constructor(options) {
         this.baseUrl = options.baseUrl.replace(/\/$/, '');
         this.timeoutMs = options.timeoutMs ?? 8_000;
         // Late-bound on purpose: a consumer (or its tests) may replace global fetch after construction.
         this.fetchImpl = options.fetch ?? ((...args) => fetch(...args));
+        this.requestId = options.requestId;
     }
     async call(method, path, body, init = {}) {
         const headers = { ...init.headers };
@@ -22,6 +25,10 @@ export class BastionHttp {
             headers['Content-Type'] = 'application/json';
         if (init.token)
             headers['Authorization'] = `Bearer ${init.token}`;
+        const requestId = this.requestId?.();
+        const callerSetId = Object.keys(headers).some((k) => k.toLowerCase() === 'x-request-id');
+        if (requestId && REQUEST_ID_PATTERN.test(requestId) && !callerSetId)
+            headers['X-Request-Id'] = requestId;
         let res;
         try {
             res = await this.fetchImpl(`${this.baseUrl}${path}`, {
@@ -35,11 +42,28 @@ export class BastionHttp {
             throw new BastionHttpError(503, `Bastion unreachable: ${err.message}`, BastionErrorCode.UNAVAILABLE);
         }
         if (!res.ok) {
-            const parsed = (await res.json().catch(() => ({})));
+            // Bastion's error body (api.md §3): `{ code, message, errors? }`; older builds put the field errors in `message`.
+            const parsed = ((await res.json().catch(() => null)) ?? {});
+            const errors = Array.isArray(parsed.errors)
+                ? parsed.errors.map(String)
+                : Array.isArray(parsed.message)
+                    ? parsed.message.map(String)
+                    : undefined;
             const message = Array.isArray(parsed.message)
                 ? parsed.message.join(', ')
-                : (parsed.message ?? `Bastion error ${res.status}`);
-            throw new BastionHttpError(res.status, message);
+                : typeof parsed.message === 'string'
+                    ? parsed.message
+                    : `Bastion error ${res.status}`;
+            // A code Bastion still puts in `message` (UNDER_MINIMUM_AGE under `code: FORBIDDEN`) wins: classify reads it.
+            const code = isBastionErrorCode(message)
+                ? undefined
+                : isBastionErrorCode(parsed.code)
+                    ? parsed.code
+                    : res.status === 400 && errors?.length
+                        ? BastionErrorCode.VALIDATION_FAILED
+                        : undefined;
+            const upstreamCode = typeof parsed.code === 'string' && !isBastionErrorCode(parsed.code) ? parsed.code : undefined;
+            throw new BastionHttpError(res.status, message, code, errors, upstreamCode);
         }
         if (res.status === 204)
             return undefined;

package/dist/esm/core/errors.d.ts

@@ -21,7 +21,10 @@ export declare const BastionErrorCode: {
     readonly INVALID_REFRESH_TOKEN: "INVALID_REFRESH_TOKEN";
     /** `POST /auth/exchange` refused the one-time OAuth code: expired, already used, or minted for another app. */
     readonly INVALID_OAUTH_CODE: "INVALID_OAUTH_CODE";
+    /** A 400 carrying field errors (`BastionHttpError.errors`): Bastion's `ValidationPipe`. */
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
     readonly CONFLICT: "CONFLICT";
+    readonly RATE_LIMITED: "RATE_LIMITED";
     readonly BIRTH_DATE_REQUIRED: "BIRTH_DATE_REQUIRED";
     readonly BIRTH_DATE_INVALID: "BIRTH_DATE_INVALID";
     readonly UNDER_MINIMUM_AGE: "UNDER_MINIMUM_AGE";
@@ -36,9 +39,21 @@ export declare const BastionErrorCode: {
 };
 export type BastionErrorCode = (typeof BastionErrorCode)[keyof typeof BastionErrorCode];
 export declare function classifyBastionError(status: number, message: string): BastionErrorCode;
-/** A non-2xx answer from Bastion's HTTP API, or Bastion unreachable (`status` 503, code `UNAVAILABLE`). */
+export declare function isBastionErrorCode(value: unknown): value is BastionErrorCode;
+/**
+ * A non-2xx answer from Bastion's HTTP API, or Bastion unreachable (`status` 503, code `UNAVAILABLE`).
+ * `message` and `errors` are Bastion's own: fine to show for a 4xx, never for a 5xx (api.md §14).
+ */
 export declare class BastionHttpError extends Error {
     readonly status: number;
+    /** Field errors of a 400 (`VALIDATION_FAILED`), one line each. */
+    readonly errors?: string[] | undefined;
+    /** Bastion's own `code` when it is not a `BastionErrorCode` (`NOT_FOUND`, `PASSWORD_TOO_SHORT`, …). */
+    readonly upstreamCode?: string | undefined;
     readonly code: BastionErrorCode;
-    constructor(status: number, message: string, code?: BastionErrorCode);
+    constructor(status: number, message: string, code?: BastionErrorCode, 
+    /** Field errors of a 400 (`VALIDATION_FAILED`), one line each. */
+    errors?: string[] | undefined, 
+    /** Bastion's own `code` when it is not a `BastionErrorCode` (`NOT_FOUND`, `PASSWORD_TOO_SHORT`, …). */
+    upstreamCode?: string | undefined);
 }

package/dist/esm/core/errors.js

@@ -24,7 +24,10 @@ export const BastionErrorCode = {
     INVALID_REFRESH_TOKEN: 'INVALID_REFRESH_TOKEN',
     /** `POST /auth/exchange` refused the one-time OAuth code: expired, already used, or minted for another app. */
     INVALID_OAUTH_CODE: 'INVALID_OAUTH_CODE',
+    /** A 400 carrying field errors (`BastionHttpError.errors`): Bastion's `ValidationPipe`. */
+    VALIDATION_FAILED: 'VALIDATION_FAILED',
     CONFLICT: 'CONFLICT',
+    RATE_LIMITED: 'RATE_LIMITED',
     BIRTH_DATE_REQUIRED: 'BIRTH_DATE_REQUIRED',
     BIRTH_DATE_INVALID: 'BIRTH_DATE_INVALID',
     UNDER_MINIMUM_AGE: 'UNDER_MINIMUM_AGE',
@@ -72,17 +75,33 @@ export function classifyBastionError(status, message) {
         return BastionErrorCode.NO_APP_ACCESS;
     if (status === 409)
         return BastionErrorCode.CONFLICT;
+    if (status === 429)
+        return BastionErrorCode.RATE_LIMITED;
     if (status === 503)
         return BastionErrorCode.UNAVAILABLE;
     return BastionErrorCode.UPSTREAM;
 }
-/** A non-2xx answer from Bastion's HTTP API, or Bastion unreachable (`status` 503, code `UNAVAILABLE`). */
+export function isBastionErrorCode(value) {
+    return typeof value === 'string' && Object.hasOwn(BastionErrorCode, value);
+}
+/**
+ * A non-2xx answer from Bastion's HTTP API, or Bastion unreachable (`status` 503, code `UNAVAILABLE`).
+ * `message` and `errors` are Bastion's own: fine to show for a 4xx, never for a 5xx (api.md §14).
+ */
 export class BastionHttpError extends Error {
     status;
+    errors;
+    upstreamCode;
     code;
-    constructor(status, message, code) {
+    constructor(status, message, code, 
+    /** Field errors of a 400 (`VALIDATION_FAILED`), one line each. */
+    errors, 
+    /** Bastion's own `code` when it is not a `BastionErrorCode` (`NOT_FOUND`, `PASSWORD_TOO_SHORT`, …). */
+    upstreamCode) {
         super(message);
         this.status = status;
+        this.errors = errors;
+        this.upstreamCode = upstreamCode;
         this.name = 'BastionHttpError';
         this.code = code ?? classifyBastionError(status, message);
     }

package/dist/esm/core/jwks-verifier.d.ts

@@ -10,7 +10,7 @@ export interface JwksVerifierOptions {
     fetch?: typeof fetch;
 }
 /**
- * The canonical consumer of Bastion's JWKS (docs/BASTION_INTEGRATION.md):
+ * The canonical consumer of Bastion's JWKS (docs/integrations/bastion.md in the platform repo):
  * keys cached and indexed by `kid`, refetch on an unknown kid with a
  * cooldown, stale cache served when a refetch fails. Second safety net only:
  * Bastion publishes a key before signing with it (publish-before-use), so a

package/dist/esm/core/jwks-verifier.js

@@ -1,4 +1,4 @@
-import { decodeProtectedHeader, importJWK, jwtVerify, } from 'jose';
+import { decodeJwt, importRs256Jwk, verifyRs256 } from './jwt.js';
 import { BastionTokenError } from './errors.js';
 import { silentLogger } from './types.js';
 /**
@@ -9,7 +9,7 @@ import { silentLogger } from './types.js';
  */
 const UNKNOWN_KID_REFETCH_COOLDOWN_MS = 30_000;
 /**
- * The canonical consumer of Bastion's JWKS (docs/BASTION_INTEGRATION.md):
+ * The canonical consumer of Bastion's JWKS (docs/integrations/bastion.md in the platform repo):
  * keys cached and indexed by `kid`, refetch on an unknown kid with a
  * cooldown, stale cache served when a refetch fails. Second safety net only:
  * Bastion publishes a key before signing with it (publish-before-use), so a
@@ -36,12 +36,12 @@ export class JwksVerifier {
     async verify(token) {
         let kid;
         try {
-            ({ kid } = decodeProtectedHeader(token));
+            kid = decodeJwt(token).header.kid;
         }
         catch {
             throw new BastionTokenError('malformed', 'Malformed token');
         }
-        if (!kid)
+        if (typeof kid !== 'string' || !kid)
             throw new BastionTokenError('missing_kid', 'Missing kid in JWT header');
         await this.ensureFresh();
         let key = this.keys.get(kid);
@@ -54,11 +54,7 @@ export class JwksVerifier {
             throw new BastionTokenError('unknown_kid', 'Unknown or expired kid');
         }
         try {
-            const { payload } = await jwtVerify(token, key, {
-                algorithms: ['RS256'],
-                ...(this.issuer ? { issuer: this.issuer } : {}),
-            });
-            return payload;
+            return verifyRs256(token, key, this.issuer);
         }
         catch {
             throw new BastionTokenError('invalid', 'Invalid token');
@@ -76,7 +72,12 @@ export class JwksVerifier {
                 for (const jwk of keys) {
                     if (!jwk.kid)
                         continue;
-                    next.set(jwk.kid, await importJWK(jwk, 'RS256'));
+                    try {
+                        next.set(jwk.kid, importRs256Jwk(jwk));
+                    }
+                    catch (err) {
+                        this.logger.warn(`JWKS: skipping kid=${jwk.kid}: ${err.message}`);
+                    }
                 }
                 this.keys = next;
                 this.fetchedAt = Date.now();

package/dist/esm/core/jwt.d.ts

@@ -0,0 +1,13 @@
+import { type KeyObject } from 'node:crypto';
+/** Header and payload of a compact JWS, unverified. Throws on anything that isn't one. */
+export declare function decodeJwt(token: string): {
+    header: Record<string, unknown>;
+    payload: Record<string, unknown>;
+};
+/** An RS256 verification key from a JWKS entry; RSA ≥ 2048 bits only. */
+export declare function importRs256Jwk(jwk: JsonWebKey): KeyObject;
+/**
+ * RS256 signature, `exp`/`nbf`, optional `iss`. What `jose.jwtVerify` checked for us,
+ * in node:crypto so the CJS build has no ESM-only dependency. Throws on any failure.
+ */
+export declare function verifyRs256(token: string, key: KeyObject, issuer: string | null, now?: number): Record<string, unknown>;

package/dist/esm/core/jwt.js

@@ -0,0 +1,50 @@
+import { createPublicKey, verify } from 'node:crypto';
+/** Header and payload of a compact JWS, unverified. Throws on anything that isn't one. */
+export function decodeJwt(token) {
+    const parts = token.split('.');
+    // Strict alphabet: Buffer's base64url decoder skips padding and junk, which would let one token have many spellings.
+    if (parts.length !== 3 || !parts.every((part) => /^[A-Za-z0-9_-]*$/.test(part)))
+        throw new Error('not a compact JWS');
+    const header = JSON.parse(Buffer.from(parts[0], 'base64url').toString('utf8'));
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    if (!isObject(header) || !isObject(payload))
+        throw new Error('header or payload not an object');
+    return { header, payload };
+}
+/** An RS256 verification key from a JWKS entry; RSA ≥ 2048 bits only. */
+export function importRs256Jwk(jwk) {
+    if (jwk.kty !== 'RSA' || (jwk.alg !== undefined && jwk.alg !== 'RS256') || (jwk.use !== undefined && jwk.use !== 'sig')) {
+        throw new Error('not an RS256 signing key');
+    }
+    const key = createPublicKey({ key: jwk, format: 'jwk' });
+    if ((key.asymmetricKeyDetails?.modulusLength ?? 0) < 2048)
+        throw new Error('RSA key shorter than 2048 bits');
+    return key;
+}
+/**
+ * RS256 signature, `exp`/`nbf`, optional `iss`. What `jose.jwtVerify` checked for us,
+ * in node:crypto so the CJS build has no ESM-only dependency. Throws on any failure.
+ */
+export function verifyRs256(token, key, issuer, now = Date.now()) {
+    const { header, payload } = decodeJwt(token);
+    if (header.alg !== 'RS256')
+        throw new Error('alg not RS256');
+    if (header.crit !== undefined)
+        throw new Error('unsupported crit header');
+    const [h, p, s] = token.split('.');
+    if (!verify('RSA-SHA256', Buffer.from(`${h}.${p}`), key, Buffer.from(s, 'base64url')))
+        throw new Error('bad signature');
+    const seconds = Math.floor(now / 1000);
+    if (typeof payload.exp !== 'number' || payload.exp <= seconds)
+        throw new Error('expired');
+    if (payload.nbf !== undefined && (typeof payload.nbf !== 'number' || payload.nbf > seconds))
+        throw new Error('not yet valid');
+    if (payload.iat !== undefined && typeof payload.iat !== 'number')
+        throw new Error('bad iat');
+    if (issuer && payload.iss !== issuer)
+        throw new Error('wrong issuer');
+    return payload;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/esm/core/service-token-provider.js

@@ -1,4 +1,4 @@
-import { decodeJwt } from 'jose';
+import { decodeJwt } from './jwt.js';
 import { silentLogger } from './types.js';
 const REFRESH_MARGIN_MS = 5 * 60 * 1000;
 const FALLBACK_TTL_MS = 60 * 60 * 1000;
@@ -59,7 +59,7 @@ export class ServiceTokenProvider {
         if (!credential?.apiKey)
             throw new Error(`Bastion service client for "${serviceSlug}" not configured`);
         const { accessToken } = await this.http.clientAuth(credential);
-        const { exp, tenantId } = decodeJwt(accessToken);
+        const { exp, tenantId } = decodeJwt(accessToken).payload;
         this.cache.set(serviceSlug, {
             token: accessToken,
             expiresAt: exp ? exp * 1000 : Date.now() + FALLBACK_TTL_MS,

package/dist/esm/nest/bastion-api-client.provider.d.ts

@@ -4,8 +4,9 @@ import { type BastionModuleOptions } from './options.js';
 /**
  * `BastionApiClient` bound to this app (`serviceSlug` as `appSlug`,
  * `tenantSlug`), sharing `BastionService.http`. Inject it in an app backend
- * that proxies its users' login/refresh/account flows; a pure service
- * (Herald, Beacon) never needs it. Failures are `BastionHttpException`s:
+ * that proxies its users' login/refresh/account flows, or one that reads
+ * its users' Bastion data with their token (Beacon: `listSocialAccounts`);
+ * a pure machine service (Herald) never needs it. Failures are `BastionHttpException`s:
  * an `HttpException` with Bastion's status plus `code`/`upstreamMessage`.
  */
 export declare class BastionApiClientProvider extends BastionApiClient {

package/dist/esm/nest/bastion-api-client.provider.js

@@ -18,8 +18,9 @@ import { nestLogger } from './nest-logger.js';
 /**
  * `BastionApiClient` bound to this app (`serviceSlug` as `appSlug`,
  * `tenantSlug`), sharing `BastionService.http`. Inject it in an app backend
- * that proxies its users' login/refresh/account flows; a pure service
- * (Herald, Beacon) never needs it. Failures are `BastionHttpException`s:
+ * that proxies its users' login/refresh/account flows, or one that reads
+ * its users' Bastion data with their token (Beacon: `listSocialAccounts`);
+ * a pure machine service (Herald) never needs it. Failures are `BastionHttpException`s:
  * an `HttpException` with Bastion's status plus `code`/`upstreamMessage`.
  */
 let BastionApiClientProvider = class BastionApiClientProvider extends BastionApiClient {

package/dist/esm/nest/bastion-http-exception.d.ts

@@ -1,16 +1,26 @@
 import { HttpException } from '@nestjs/common';
 import { BastionHttp, type BastionRequestInit } from '../core/bastion-http.js';
-import { BastionHttpError, type BastionErrorCode } from '../core/errors.js';
+import { BastionErrorCode, BastionHttpError } from '../core/errors.js';
 /**
- * The Nest face of a Bastion error: an `HttpException` carrying Bastion's
- * status, so the global filter answers with it unchanged, plus the stable
- * `code` and the upstream message for the handlers that branch on them.
- * `getResponse()` is `{ code, message }`.
+ * The Nest face of a Bastion error, so the global filter answers the browser
+ * per api.md §3/§14:
+ * - 4xx: Bastion's status, `code`, message and `errors` (field errors of a 400). A 4xx the
+ *   package can't classify keeps Bastion's own code (`PASSWORD_TOO_SHORT`) or the status
+ *   default (`NOT_FOUND`), never `UPSTREAM`;
+ * - Bastion down, timed out or answering 503: 503 `UNAVAILABLE`, generic message;
+ * - any other 5xx: 502 `UPSTREAM`, generic message.
+ *
+ * `getResponse()` is `{ code, message, errors? }`. `upstreamStatus` and
+ * `upstreamMessage` keep Bastion's own for logs and branching; `message`
+ * carries them too, so the filter's 5xx log line says what Bastion answered.
  */
 export declare class BastionHttpException extends HttpException {
     readonly code: BastionErrorCode;
     readonly upstreamMessage: string;
-    constructor(code: BastionErrorCode, status: number, upstreamMessage: string);
+    readonly errors?: string[] | undefined;
+    readonly upstreamCode?: string | undefined;
+    readonly upstreamStatus: number;
+    constructor(code: BastionErrorCode, status: number, upstreamMessage: string, errors?: string[] | undefined, upstreamCode?: string | undefined);
     static from(err: BastionHttpError): BastionHttpException;
 }
 /** `BastionHttp` whose failures are `BastionHttpException`s — what `BastionService.http` is. */

package/dist/esm/nest/bastion-http-exception.js

@@ -1,24 +1,55 @@
-import { HttpException } from '@nestjs/common';
+import { HttpException, HttpStatus } from '@nestjs/common';
 import { BastionHttp } from '../core/bastion-http.js';
-import { BastionHttpError } from '../core/errors.js';
+import { BastionErrorCode, BastionHttpError } from '../core/errors.js';
 /**
- * The Nest face of a Bastion error: an `HttpException` carrying Bastion's
- * status, so the global filter answers with it unchanged, plus the stable
- * `code` and the upstream message for the handlers that branch on them.
- * `getResponse()` is `{ code, message }`.
+ * The Nest face of a Bastion error, so the global filter answers the browser
+ * per api.md §3/§14:
+ * - 4xx: Bastion's status, `code`, message and `errors` (field errors of a 400). A 4xx the
+ *   package can't classify keeps Bastion's own code (`PASSWORD_TOO_SHORT`) or the status
+ *   default (`NOT_FOUND`), never `UPSTREAM`;
+ * - Bastion down, timed out or answering 503: 503 `UNAVAILABLE`, generic message;
+ * - any other 5xx: 502 `UPSTREAM`, generic message.
+ *
+ * `getResponse()` is `{ code, message, errors? }`. `upstreamStatus` and
+ * `upstreamMessage` keep Bastion's own for logs and branching; `message`
+ * carries them too, so the filter's 5xx log line says what Bastion answered.
  */
 export class BastionHttpException extends HttpException {
     code;
     upstreamMessage;
-    constructor(code, status, upstreamMessage) {
-        super({ code, message: upstreamMessage }, status);
+    errors;
+    upstreamCode;
+    upstreamStatus;
+    constructor(code, status, upstreamMessage, errors, upstreamCode) {
+        const publicCode = code === BastionErrorCode.UPSTREAM ? (upstreamCode ?? statusCode(status)) : code;
+        const unavailable = code === BastionErrorCode.UNAVAILABLE || status === 503;
+        const publicStatus = status < 500 ? status : unavailable ? 503 : 502;
+        const body = status < 500
+            ? { code: publicCode, message: upstreamMessage, ...(errors?.length ? { errors } : {}) }
+            : unavailable
+                ? { code: BastionErrorCode.UNAVAILABLE, message: 'Upstream service unavailable' }
+                : { code: BastionErrorCode.UPSTREAM, message: 'Upstream service error' };
+        super(body, publicStatus);
         this.code = code;
         this.upstreamMessage = upstreamMessage;
+        this.errors = errors;
+        this.upstreamCode = upstreamCode;
+        this.upstreamStatus = status;
+        if (status >= 500)
+            this.message = `Bastion ${status}: ${upstreamMessage}`;
     }
     static from(err) {
-        return new BastionHttpException(err.code, err.status, err.message);
+        return new BastionHttpException(err.code, err.status, err.message, err.errors, err.upstreamCode);
     }
 }
+/** api.md §3 default code of a 4xx: `NOT_FOUND`, `UNPROCESSABLE`, `RATE_LIMITED`, … */
+function statusCode(status) {
+    if (status === 422)
+        return 'UNPROCESSABLE';
+    if (status === 429)
+        return 'RATE_LIMITED';
+    return HttpStatus[status] ?? 'BAD_REQUEST';
+}
 /** `BastionHttp` whose failures are `BastionHttpException`s — what `BastionService.http` is. */
 export class NestBastionHttp extends BastionHttp {
     async call(method, path, body, init) {

package/dist/esm/nest/bastion.module.d.ts

@@ -1,4 +1,4 @@
-import { DynamicModule } from '@nestjs/common';
+import { DynamicModule, type MiddlewareConsumer, type NestModule } from '@nestjs/common';
 import { type BastionModuleAsyncOptions, type BastionModuleOptions } from './options.js';
 /**
  * ```ts
@@ -11,9 +11,11 @@ import { type BastionModuleAsyncOptions, type BastionModuleOptions } from './opt
  *   }),
  * })
  * ```
- * Global: import once in `AppModule`, inject anywhere.
+ * Global: import once in `AppModule`, inject anywhere. Every route gets a
+ * middleware that tracks the request, so outbound calls carry its `X-Request-Id`.
  */
-export declare class BastionModule {
+export declare class BastionModule implements NestModule {
+    configure(consumer: MiddlewareConsumer): void;
     static forRoot(options: BastionModuleOptions): DynamicModule;
     static forRootAsync(options: BastionModuleAsyncOptions): DynamicModule;
     private static build;

package/dist/esm/nest/bastion.module.js

@@ -5,7 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var BastionModule_1;
-import { Global, Module } from '@nestjs/common';
+import { Global, Module, RequestMethod, } from '@nestjs/common';
 import { BASTION_OPTIONS } from './options.js';
 import { BastionJwksService } from './bastion-jwks.service.js';
 import { BastionService } from './bastion.service.js';
@@ -14,12 +14,15 @@ import { ServiceClientJwtGuard } from './guards/service-client-jwt.guard.js';
 import { BastionUserGuard } from './guards/bastion-user.guard.js';
 import { AuditInterceptor } from './interceptors/audit.interceptor.js';
 import { BastionApiClientProvider } from './bastion-api-client.provider.js';
+import { AppUserGuard } from './guards/app-user.guard.js';
+import { requestContextMiddleware } from './request-context.js';
 const PROVIDERS = [
     BastionJwksService,
     BastionService,
     BastionAuditService,
     ServiceClientJwtGuard,
     BastionUserGuard,
+    AppUserGuard,
     AuditInterceptor,
     BastionApiClientProvider,
 ];
@@ -34,9 +37,13 @@ const PROVIDERS = [
  *   }),
  * })
  * ```
- * Global: import once in `AppModule`, inject anywhere.
+ * Global: import once in `AppModule`, inject anywhere. Every route gets a
+ * middleware that tracks the request, so outbound calls carry its `X-Request-Id`.
  */
 let BastionModule = BastionModule_1 = class BastionModule {
+    configure(consumer) {
+        consumer.apply(requestContextMiddleware).forRoutes({ path: '{*splat}', method: RequestMethod.ALL });
+    }
     static forRoot(options) {
         return this.build({ provide: BASTION_OPTIONS, useValue: options });
     }

package/dist/esm/nest/bastion.service.d.ts

@@ -2,7 +2,7 @@ import { type BastionRequestInit } from '../core/bastion-http.js';
 import { NestBastionHttp } from './bastion-http-exception.js';
 import type { AuditEventInput, TokenResponse } from '../core/types.js';
 import { type BastionModuleOptions } from './options.js';
-/** Outbound HTTP to Bastion. A failure surfaces as `BastionHttpException` (an `HttpException` with Bastion's status, a stable `code` and the upstream message). */
+/** Outbound HTTP to Bastion, `X-Request-Id` included. A failure surfaces as `BastionHttpException` (4xx as Bastion's, 5xx as 502/503 with a generic message). */
 export declare class BastionService {
     private readonly options;
     readonly http: NestBastionHttp;

package/dist/esm/nest/bastion.service.js

@@ -13,13 +13,18 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { Inject, Injectable } from '@nestjs/common';
 import { NestBastionHttp } from './bastion-http-exception.js';
 import { BASTION_OPTIONS } from './options.js';
-/** Outbound HTTP to Bastion. A failure surfaces as `BastionHttpException` (an `HttpException` with Bastion's status, a stable `code` and the upstream message). */
+import { currentRequestId } from './request-context.js';
+/** Outbound HTTP to Bastion, `X-Request-Id` included. A failure surfaces as `BastionHttpException` (4xx as Bastion's, 5xx as 502/503 with a generic message). */
 let BastionService = class BastionService {
     options;
     http;
     constructor(options) {
         this.options = options;
-        this.http = new NestBastionHttp({ baseUrl: options.baseUrl, timeoutMs: options.timeoutMs });
+        this.http = new NestBastionHttp({
+            baseUrl: options.baseUrl,
+            timeoutMs: options.timeoutMs,
+            requestId: options.requestId ?? currentRequestId,
+        });
     }
     call(method, path, body, init) {
         return this.http.call(method, path, body, init);

package/dist/esm/nest/decorators/current-user.decorator.d.ts

@@ -2,3 +2,5 @@
 export declare const CurrentClient: (...dataOrPipes: unknown[]) => ParameterDecorator;
 /** The user payload set by `BastionUserGuard`. */
 export declare const CurrentAdminUser: (...dataOrPipes: unknown[]) => ParameterDecorator;
+/** The app user's payload set by `AppUserGuard`. */
+export declare const CurrentUser: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/esm/nest/decorators/current-user.decorator.js

@@ -3,3 +3,5 @@ import { createParamDecorator } from '@nestjs/common';
 export const CurrentClient = createParamDecorator((_, ctx) => ctx.switchToHttp().getRequest().user);
 /** The user payload set by `BastionUserGuard`. */
 export const CurrentAdminUser = createParamDecorator((_, ctx) => ctx.switchToHttp().getRequest().adminUser);
+/** The app user's payload set by `AppUserGuard`. */
+export const CurrentUser = createParamDecorator((_, ctx) => ctx.switchToHttp().getRequest().user);

package/dist/esm/nest/guards/app-user.guard.d.ts

@@ -0,0 +1,16 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { BastionJwksService } from '../bastion-jwks.service.js';
+/**
+ * Guard for an app backend's own users, meant as the global `APP_GUARD`: every
+ * route needs a Bastion *user* token minted for this app (`serviceSlug` is the
+ * app's slug) unless it carries `@Public()`. Machine tokens and other apps'
+ * tokens are refused. The payload lands on `req.user`, read with `@CurrentUser()`.
+ * Suspension, age gate and roles stay the app's business: stack its own guard after this one.
+ */
+export declare class AppUserGuard implements CanActivate {
+    private readonly jwks;
+    private readonly reflector;
+    constructor(jwks: BastionJwksService, reflector: Reflector);
+    canActivate(ctx: ExecutionContext): Promise<boolean>;
+}

package/dist/esm/nest/guards/app-user.guard.js

@@ -0,0 +1,44 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Injectable, UnauthorizedException } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { BastionJwksService } from '../bastion-jwks.service.js';
+import { IS_PUBLIC_KEY } from '../decorators/public.decorator.js';
+/**
+ * Guard for an app backend's own users, meant as the global `APP_GUARD`: every
+ * route needs a Bastion *user* token minted for this app (`serviceSlug` is the
+ * app's slug) unless it carries `@Public()`. Machine tokens and other apps'
+ * tokens are refused. The payload lands on `req.user`, read with `@CurrentUser()`.
+ * Suspension, age gate and roles stay the app's business: stack its own guard after this one.
+ */
+let AppUserGuard = class AppUserGuard {
+    jwks;
+    reflector;
+    constructor(jwks, reflector) {
+        this.jwks = jwks;
+        this.reflector = reflector;
+    }
+    async canActivate(ctx) {
+        if (this.reflector.getAllAndOverride(IS_PUBLIC_KEY, [ctx.getHandler(), ctx.getClass()]))
+            return true;
+        const req = ctx.switchToHttp().getRequest();
+        const auth = req.headers['authorization'];
+        if (!auth?.startsWith('Bearer '))
+            throw new UnauthorizedException('Missing token');
+        req.user = await this.jwks.verifyUserToken(auth.slice(7));
+        return true;
+    }
+};
+AppUserGuard = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [BastionJwksService,
+        Reflector])
+], AppUserGuard);
+export { AppUserGuard };

package/dist/esm/nest/index.d.ts

@@ -8,9 +8,11 @@ export { BastionHttpException, NestBastionHttp } from './bastion-http-exception.
 export { BastionAuditService, type AuditActor } from './bastion-audit.service.js';
 export { ServiceClientJwtGuard } from './guards/service-client-jwt.guard.js';
 export { BastionUserGuard } from './guards/bastion-user.guard.js';
+export { AppUserGuard } from './guards/app-user.guard.js';
 export { AuditInterceptor } from './interceptors/audit.interceptor.js';
 export { Public, IS_PUBLIC_KEY } from './decorators/public.decorator.js';
 export { RequireScope, REQUIRED_SCOPES_KEY } from './decorators/require-scope.decorator.js';
 export { Audit, AUDIT_EVENT_KEY, type AuditOptions, type AuditRequest, type AuditDescriptor } from './decorators/audit.decorator.js';
-export { CurrentClient, CurrentAdminUser } from './decorators/current-user.decorator.js';
+export { CurrentClient, CurrentAdminUser, CurrentUser } from './decorators/current-user.decorator.js';
+export { currentRequestId } from './request-context.js';
 export { resolveTenantScope, CROSS_TENANT_ROLE } from './tenant-scope.js';

package/dist/esm/nest/index.js

@@ -8,9 +8,11 @@ export { BastionHttpException, NestBastionHttp } from './bastion-http-exception.
 export { BastionAuditService } from './bastion-audit.service.js';
 export { ServiceClientJwtGuard } from './guards/service-client-jwt.guard.js';
 export { BastionUserGuard } from './guards/bastion-user.guard.js';
+export { AppUserGuard } from './guards/app-user.guard.js';
 export { AuditInterceptor } from './interceptors/audit.interceptor.js';
 export { Public, IS_PUBLIC_KEY } from './decorators/public.decorator.js';
 export { RequireScope, REQUIRED_SCOPES_KEY } from './decorators/require-scope.decorator.js';
 export { Audit, AUDIT_EVENT_KEY } from './decorators/audit.decorator.js';
-export { CurrentClient, CurrentAdminUser } from './decorators/current-user.decorator.js';
+export { CurrentClient, CurrentAdminUser, CurrentUser } from './decorators/current-user.decorator.js';
+export { currentRequestId } from './request-context.js';
 export { resolveTenantScope, CROSS_TENANT_ROLE } from './tenant-scope.js';

package/dist/esm/nest/options.d.ts

@@ -15,6 +15,13 @@ export interface BastionModuleOptions {
     jwksTtlMs?: number;
     /** Expected `iss`. Default `'bastion'`; `null` disables the check. */
     issuer?: string | null;
+    /**
+     * Id sent as `X-Request-Id` on calls to Bastion. Default: `req.id` of the request
+     * being served (pino-http / nest-common `genReqId`), tracked by the module's middleware.
+     * Express only: under Fastify the middleware sees the raw request, which has no `id`,
+     * so pass a getter here (e.g. from nestjs-cls).
+     */
+    requestId?: () => string | undefined;
     /** `BastionUserGuard`: which apps' user tokens are accepted. Default `['meridian']`. */
     acceptedAppSlugs?: string[];
     /** `BastionUserGuard`: which roles are accepted. Default `['ADMIN', 'OWNER', 'SUPER_ADMIN']`. */