@heyatom/bastion-client 0.7.2 → 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+## 0.9.0
+
+### Added
+
+- `verifyWebhookSignature` verifies [Standard Webhooks](https://www.standardwebhooks.com/) headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`: space-separated `v1,<base64 HMAC-SHA256("<id>.<timestamp>.<body>")>`, secret used as UTF-8). When any of them is present they are the ones checked: same tolerance, any secret against any `v1` entry, `deliveryId` = `webhook-id`, result `version: 'standard'`.
+- Header name constants `WEBHOOK_ID_HEADER`, `WEBHOOK_TIMESTAMP_HEADER`, `WEBHOOK_SIGNATURE_HEADER`.
+
+### Changed
+
+- Without Standard Webhooks headers, `X-Bastion-Signature-V2` is verified exactly as before, so receivers keep working against an older Bastion. Bastion sends both for one release and will then drop V2. `allowLegacySignature` is unchanged.
+- Whitespace-only entries in `secrets` (e.g. `' '` from an unset env var) are ignored instead of keying the HMAC; if none is left the result is `{ ok: false, reason: 'missing' }`. Other secrets are still used byte-exact (not trimmed).
+
+### Breaking (types)
+
+- `VerifyWebhookResult` gains the `version: 'standard'` variant: an exhaustive `switch` on `version` needs the new case.
+
+## 0.8.1
+
+### Added
+
+- Error code `STEP_UP_FAILED`: the 401 Bastion answers when the current password or 2FA code of a step-up protected route is wrong (or the step-up counter is locked). Tells a wrong factor apart from a dead session, also a 401 (`INVALID_CREDENTIALS`). Needs a Bastion that sends `code: 'STEP_UP_FAILED'`; an older one still classifies as `INVALID_CREDENTIALS`.
+
+## 0.8.0
+
+### Breaking
+
+- `BastionApiClient.exchange(code, ctx, state)` requires `state`; an empty one rejects before calling Bastion. Get it from the new `oauthStart`.
+- `jose` is no longer a peer dependency: token verification runs on `node:crypto`. The CJS build no longer loads an ESM-only module, so Jest needs no `transformIgnorePatterns`.
+- `BastionHttpException` no longer forwards Bastion's 5xx: it answers 502 `UPSTREAM` (503 `UNAVAILABLE` when Bastion is down) with a generic message. Bastion's status and message stay on `upstreamStatus`, `upstreamMessage` and `message`.
+- Tokens whose segments are not strict base64url (padding, stray characters) are rejected as `malformed`.
+
+### Added
+
+- `BastionApiClient.oauthStart(provider)` → `{ url, state } | null`.
+- `AppUserGuard` and `@CurrentUser()` for an app's own users.
+- `X-Request-Id` on every call to Bastion: `BastionHttpOptions.requestId`; in NestJS the served request's `req.id` by default (`BastionModuleOptions.requestId` to override).
+- `BastionHttpError.errors` (field errors of a 400) and `upstreamCode` (a code outside `BastionErrorCode`).
+- Error codes `VALIDATION_FAILED` and `RATE_LIMITED`.
+
+### Fixed
+
+- Validation errors from Bastion were reduced to "Validation failed": the field errors and Bastion's `code` are now kept.
+- A 4xx with a code the package does not know answered `UPSTREAM`: it now keeps Bastion's code or the status default (`NOT_FOUND`, `UNPROCESSABLE`, …).
+
+## 0.7.2
+
+- `completeAgeVerification(token, birthDate, { currentPassword?, twoFactorCode? })` sends the required step-up.
+- `UserJwtPayload.ageVerificationRequired` while the account owes the app's age screen.
+
+## 0.7.1
+
+- `exchange` sends the OAuth flow `state`.
+
+## 0.7.0
+
+- Step-up on `completeSocialAccountLink`.
+- **Breaking**: webhooks with only the legacy `X-Bastion-Signature` are rejected unless `allowLegacySignature` is set.
+
+## 0.6.0
+
+- `BastionSocialAccount.providerId`.

package/README.md

@@ -1,19 +1,25 @@
 # @heyatom/bastion-client
 
-Consumer SDK for [Bastion](https://github.com/heyatomdev/bastion), the HeyAtom identity provider.
-Replaces the `src/modules/bastion/` boilerplate every service used to copy by hand.
+Client SDK for [Bastion](https://github.com/heyatomdev/bastion), the HeyAtom identity provider.
+It verifies Bastion tokens locally against the JWKS, calls Bastion's API (machine-to-machine and
+on behalf of your users), verifies Bastion webhooks, and ships ready-made NestJS guards.
 
-- `@heyatom/bastion-client` — framework-free core: `JwksVerifier` (kid-indexed cache, unknown-kid refetch with cooldown, stale-on-error), `BastionHttp` (`POST /auth/client`, `POST /events`, any other route), `ServiceTokenProvider` (single-flight refresh ahead of `exp`), payload types.
-- `@heyatom/bastion-client` also carries Bastion's user-API contract: `BastionApiClient` (login, register, OAuth exchange, 2FA, single-flight refresh, logout, sessions, `/me`, profile, social accounts, email/password flows, export, delete), its types (`BastionMe`, `BastionTokenPair`, …) and `BastionErrorCode` (a stable code on every `BastionHttpError`: credentials, app context, refresh token, OAuth code, age gate, OAuth flow, unavailable, upstream). `refreshMemoryMs` tunes how long a refresh answer is remembered per token (default 60 s). Since 0.7.2 `completeAgeVerification(token, birthDate, { currentPassword?, twoFactorCode? })` sends the step-up Bastion requires (as `deleteSelf`), and `UserJwtPayload.ageVerificationRequired?: true` is set only while the account owes the app's age screen: a consumer API can refuse it from the token alone.
-- `@heyatom/bastion-client/webhooks` — `verifyWebhookSignature` (`X-Bastion-Signature-V2` with timestamp + delivery id, legacy fallback only with `allowLegacySignature: true` (off by default since 0.7.0), secret rotation on both sides), header constants, payload type.
-- `@heyatom/bastion-client/nest` — NestJS: `BastionModule`, `ServiceClientJwtGuard`, `BastionUserGuard`, `BastionAuditService`, `AuditInterceptor` (attributes to `req.adminUser`, any `AuditActor` shape: `sub` plus optional `tenantId`/`tenantSlug`/`role`/`appSlug`), `@Public()`, `@RequireScope()`, `@Audit()`, `@CurrentClient()`, `@CurrentAdminUser()`.
+```bash
+pnpm add @heyatom/bastion-client
+```
+
+- Node ≥ 20.19. CJS and ESM builds, no ESM-only runtime dependency (works in Jest as is).
+- NestJS adapter: peer dependencies `@nestjs/common` and `@nestjs/core` 11, `rxjs`, `reflect-metadata`.
 
-Ships CJS and ESM. `jose` v6 is ESM-only, so the CJS build relies on Node's `require(esm)` — Node ≥ 20.19 / 22.12. Peer deps: `jose` (always), `@nestjs/common`, `@nestjs/core`, `rxjs`, `reflect-metadata` (for `/nest`).
+| Import | What |
+|---|---|
+| `@heyatom/bastion-client` | Framework-free core: `JwksVerifier`, `BastionHttp`, `ServiceTokenProvider`, `BastionApiClient`, types, error codes |
+| `@heyatom/bastion-client/nest` | `BastionModule`, guards, decorators, audit (re-exports the core) |
+| `@heyatom/bastion-client/webhooks` | `verifyWebhookSignature` |
 
 ## NestJS
 
 ```ts
-// app.module.ts
 import { APP_GUARD } from '@nestjs/core';
 import { BastionModule, ServiceClientJwtGuard } from '@heyatom/bastion-client/nest';
 
@@ -23,9 +29,8 @@ import { BastionModule, ServiceClientJwtGuard } from '@heyatom/bastion-client/ne
       inject: [ConfigService],
       useFactory: (config: ConfigService) => ({
         baseUrl: config.getOrThrow('BASTION_URL'),
-        serviceSlug: config.getOrThrow('BASTION_APP_SLUG'),
-        apiKey: config.get('BASTION_CLIENT_API_KEY'),
-        // tenantSlug, jwksTtlMs, issuer, acceptedAppSlugs, acceptedRoles — optional
+        serviceSlug: config.getOrThrow('BASTION_APP_SLUG'), // this service's slug in Bastion
+        apiKey: config.get('BASTION_CLIENT_API_KEY'),       // needed for outbound calls and audit
       }),
     }),
   ],
@@ -34,6 +39,31 @@ import { BastionModule, ServiceClientJwtGuard } from '@heyatom/bastion-client/ne
 export class AppModule {}
 ```
 
+`BastionModule` is global. Options:
+
+| Option | Default | |
+|---|---|---|
+| `baseUrl` | — | Bastion base URL |
+| `serviceSlug` | — | Your app/service slug |
+| `apiKey` | — | Service client key, for outbound calls |
+| `tenantSlug` | — | Required when the app lives in more than one tenant |
+| `timeoutMs` | `8000` | Outbound call timeout |
+| `jwksTtlMs` | `300000` | JWKS cache lifetime |
+| `issuer` | `'bastion'` | Expected `iss`; `null` skips the check |
+| `acceptedAppSlugs` / `acceptedRoles` | `['meridian']` / `['ADMIN', 'OWNER', 'SUPER_ADMIN']` | Who `BastionUserGuard` lets in |
+| `requestId` | the served request's `req.id` | Sent as `X-Request-Id` to Bastion. Express only by default; on Fastify pass a getter |
+
+### Guards
+
+| Guard | Accepts | Payload on |
+|---|---|---|
+| `ServiceClientJwtGuard` | Machine tokens issued for this service; `@RequireScope('mail.send')` per route | `req.user`, `@CurrentClient()` |
+| `AppUserGuard` | Your app's own users (rejects machine tokens and other apps' tokens) | `req.user`, `@CurrentUser()` |
+| `BastionUserGuard` | Admin-console users with an accepted app and role | `req.adminUser`, `@CurrentAdminUser()` |
+
+All of them skip routes marked `@Public()`. Use one as the global `APP_GUARD` and the others with
+`@UseGuards()`. Suspension, age gate or custom roles are yours: add a guard after `AppUserGuard`.
+
 ```ts
 @Controller('mail')
 export class MailController {
@@ -42,79 +72,152 @@ export class MailController {
   @Post('send')
   @RequireScope('mail.send')
   send(@CurrentClient() client: ServiceClientJwtPayload, @Body() dto: SendDto) {
-    // ...
-    void this.audit.write('mail.sent', { metadata: { toDomain: 'example.com' } });
+    void this.audit.write('mail.sent', { metadata: { toDomain: 'example.com' } }); // never throws
   }
 
-  @Get('/health')
   @Public()
+  @Get('health')
   health() { return { status: 'ok' }; }
 }
 
-// Admin surface: user tokens from the console
 @Controller('admin/config')
 @UseGuards(BastionUserGuard)
 @UseInterceptors(AuditInterceptor)
 export class AdminController {
   @Patch()
-  @Audit('config.updated', { metadata: (_result, req) => ({ keys: Object.keys(req.body as object) }) })
+  @Audit('config.updated')
   update(@CurrentAdminUser() admin: UserJwtPayload, @Body() dto: UpdateDto) { /* ... */ }
 }
 ```
 
-Bastion stores app events as `<serviceSlug>.<event>` — send the bare `resource.action`.
+Audit events are stored by Bastion as `<serviceSlug>.<event>`: send `resource.action`.
 
-## App backends: verifying your users' tokens
+### Backend for your users (BFF)
 
-```ts
-// BastionJwksService.verifyUserToken(token): a user session token minted for this app
-// (rejects machine tokens, checks aud + appSlug === serviceSlug, requires sub). Build your
-// own guard on it — cookie extraction, suspension, age gate are the app's business.
-// Core equivalent: assertUserTokenFor(await verifier.verify(token), 'dbd-builds').
-```
-
-## App backends (a BFF for your users)
+`BastionApiClientProvider` is `BastionApiClient` bound to your `serviceSlug` and `tenantSlug`:
+login, register, OAuth, 2FA, refresh, logout, sessions, profile, social accounts, email and
+password flows, data export, account deletion.
 
 ```ts
-import { BastionApiClientProvider, BastionHttpException } from '@heyatom/bastion-client/nest';
-
 @Controller('auth')
 export class AuthController {
   constructor(private readonly bastion: BastionApiClientProvider) {}
 
+  @Public()
   @Post('login')
-  async login(@Body() dto: LoginDto, @Req() req: Request) {
-    try {
-      return await this.bastion.login(dto.email, dto.password, { ip: clientIp(req), userAgent: req.headers['user-agent'] });
-    } catch (err) {
-      if (err instanceof BastionHttpException && err.code === 'EMAIL_NOT_VERIFIED') throw new ForbiddenException(err.code);
-      throw err; // any other BastionHttpException already carries Bastion's status
-    }
+  login(@Body() dto: LoginDto, @Req() req: Request) {
+    // Pass the browser's IP and user agent: Bastion rate-limits per IP.
+    return this.bastion.login(dto.email, dto.password, { ip: req.ip, userAgent: req.headers['user-agent'] });
+  }
+
+  @Public()
+  @Get('oauth/:provider')
+  async oauthStart(@Param('provider') provider: string, @Res() res: Response) {
+    const start = await this.bastion.oauthStart(provider);
+    if (!start) throw new NotFoundException('Unknown OAuth provider');
+    res.cookie('oauthState', start.state, { httpOnly: true, secure: true, sameSite: 'lax', path: '/auth/callback', maxAge: 600_000 });
+    res.redirect(start.url);
+  }
+
+  @Public()
+  @Get('callback')
+  async callback(@Query('code') code: string, @Req() req: Request, @Res({ passthrough: true }) res: Response) {
+    const state = req.cookies.oauthState; // from your cookie, never from the query string
+    res.clearCookie('oauthState', { path: '/auth/callback' });
+    if (!code || !state) throw new UnauthorizedException();
+    return this.bastion.exchange(code, { ip: req.ip, userAgent: req.headers['user-agent'] }, state);
   }
 }
 ```
 
+- `exchange` requires the `state` returned by `oauthStart`: it is what stops login CSRF.
+- `refresh` is single-flight per token and remembers each answer for `refreshMemoryMs` (60 s):
+  Bastion rotates refresh tokens and revokes the whole family on reuse, so concurrent refreshes
+  from one browser must collapse into one call. Use one client instance per process.
+- `logout` revokes the latest token in the rotation chain and never throws.
+
+## Errors
+
+Every failed call throws `BastionHttpError` (core) or `BastionHttpException` (Nest) with a stable
+`code` (`BastionErrorCode`), so you never match Bastion's message text:
+
+`INVALID_CREDENTIALS`, `EMAIL_NOT_VERIFIED`, `NO_APP_ACCESS`, `ACCOUNT_INACTIVE`,
+`INVALID_APP_CONTEXT` (your configuration, not the user), `INVALID_REFRESH_TOKEN`,
+`INVALID_OAUTH_CODE`, `VALIDATION_FAILED`, `STEP_UP_FAILED` (wrong current password or 2FA
+code on a step-up route: the session is fine), `CONFLICT`, `RATE_LIMITED`, the age-gate codes
+(`BIRTH_DATE_REQUIRED`, `BIRTH_DATE_INVALID`, `UNDER_MINIMUM_AGE`), the OAuth flow codes
+(`OAUTH_*`), `UNAVAILABLE` (Bastion unreachable or timed out) and `UPSTREAM`.
+
+- A 400 carries the field errors in `errors: string[]`. Show them: `message` is only
+  "Validation failed".
+- A code outside `BastionErrorCode` (e.g. a password-policy code) is on `upstreamCode`.
+
+`BastionHttpException` is safe to let through to the client:
+
+- a 4xx keeps Bastion's status and answers `{ code, message, errors? }`;
+- a 5xx becomes 502 `UPSTREAM`, or 503 `UNAVAILABLE` when Bastion is down, with a generic message.
+  Bastion's own status and message stay on `upstreamStatus` / `upstreamMessage` and in
+  `message`, for your logs.
+
 ```ts
-// Webhook receiver — needs the raw body (NestFactory.create(AppModule, { rawBody: true }))
-import { verifyWebhookSignature } from '@heyatom/bastion-client/webhooks';
-const result = verifyWebhookSignature({ rawBody: req.rawBody, headers: req.headers, secrets: [secret, previousSecret] });
-if (!result.ok) throw new UnauthorizedException(result.reason);
+try {
+  return await this.bastion.login(email, password, ctx);
+} catch (err) {
+  if (err instanceof BastionHttpException && err.code === 'EMAIL_NOT_VERIFIED') { /* ... */ }
+  throw err;
+}
 ```
 
 ## Without NestJS
 
 ```ts
-import { JwksVerifier, BastionHttp, ServiceTokenProvider } from '@heyatom/bastion-client';
+import { JwksVerifier, BastionHttp, ServiceTokenProvider, BastionApiClient, assertUserTokenFor } from '@heyatom/bastion-client';
 
+// Verify incoming tokens (throws BastionTokenError)
 const verifier = new JwksVerifier({ baseUrl: process.env.BASTION_URL! });
-const payload = await verifier.verify(bearerToken); // throws BastionTokenError
-
-const http = new BastionHttp({ baseUrl: process.env.BASTION_URL! });
+const payload = await verifier.verify(bearerToken);
+const user = assertUserTokenFor(payload, 'my-app'); // only your app's user tokens
+
+// Call Bastion
+const http = new BastionHttp({
+  baseUrl: process.env.BASTION_URL!,
+  requestId: () => currentRequestIdFromYourFramework(), // optional, sent as X-Request-Id
+});
 const tokens = new ServiceTokenProvider(http, { apiKey, serviceSlug: 'my-service' });
-// several targets: a record keyed by serviceSlug, or { defaultSlug, resolve: (slug) => credential | null }
 await http.writeAuditEvent(await tokens.getToken(), { event: 'thing.done' });
+
+const api = new BastionApiClient({ http, appSlug: 'my-app' });
+```
+
+`ServiceTokenProvider` also takes several credentials, as a record keyed by `serviceSlug` or as
+`{ defaultSlug, resolve: (slug) => credential | null }`.
+
+## Webhooks
+
+```ts
+import { verifyWebhookSignature } from '@heyatom/bastion-client/webhooks';
+
+// Needs the raw body: NestFactory.create(AppModule, { rawBody: true })
+const result = verifyWebhookSignature({
+  rawBody: req.rawBody,
+  headers: req.headers,
+  secrets: [secret, previousSecret], // both accepted during a rotation
+});
+if (!result.ok) throw new UnauthorizedException(result.reason);
+// result.deliveryId: store it and ignore repeats
 ```
 
-## Release
+Checks [Standard Webhooks](https://www.standardwebhooks.com/) headers (`webhook-id`,
+`webhook-timestamp`, `webhook-signature`) when present: HMAC-SHA256 over id + timestamp + body,
+5 min tolerance, secret used as a UTF-8 string, `result.deliveryId` = `webhook-id`. Without them
+it falls back to `X-Bastion-Signature-V2` (same guarantees), so it works against an older Bastion
+too; Bastion will stop sending V2 in a later release. `result.version` says which one matched.
+Leave `allowLegacySignature` off.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## License
 
-Bump `version`, tag `vX.Y.Z`, push the tag. The workflow runs lint/test/build/DI smoke and publishes via npm trusted publishing (OIDC, no token; provenance implied).
+MIT

package/dist/cjs/core/api-client.d.ts

@@ -51,12 +51,23 @@ export declare class BastionApiClient {
         message: string;
     }>;
     /**
-     * Trades the one-time OAuth code for tokens. `state` is the value the app put
-     * on the initiate URL, read back from its own cookie/session (never from the
-     * callback query): Bastion refuses a code minted under a different one, which
-     * is what stops an attacker's code from being redeemed in a victim's browser.
+     * Starts an OAuth login: the provider's Bastion initiate URL with a fresh
+     * `state` on it, or `null` for a provider the app doesn't offer. Keep `state`
+     * in an httpOnly `SameSite=Lax` cookie scoped to the callback path, redirect
+     * the browser to `url`, then pass the cookie's value to `exchange`.
      */
-    exchange(code: string, ctx?: BastionClientContext, state?: string): Promise<BastionLoginResult>;
+    oauthStart(provider: string): Promise<{
+        url: string;
+        state: string;
+    } | null>;
+    /**
+     * Trades the one-time OAuth code for tokens. `state` is the value from
+     * `oauthStart`, read back from the app's own cookie (never from the callback
+     * query): Bastion refuses a code minted under a different one, which is what
+     * stops an attacker's code from being redeemed in a victim's browser (login CSRF).
+     * Required: an empty `state` throws before calling Bastion.
+     */
+    exchange(code: string, ctx: BastionClientContext | undefined, state: string): Promise<BastionLoginResult>;
     completeTwoFactor(twoFactorToken: string, code: string, ctx?: BastionClientContext): Promise<BastionTokenPair>;
     refresh(refreshToken: string, ctx?: BastionClientContext): Promise<BastionTokenPair>;
     /** Revokes the token and any successor issued through `refresh` within the memory window. Never throws. */

package/dist/cjs/core/api-client.js

@@ -62,13 +62,31 @@ class BastionApiClient {
         return this.call('POST', '/auth/register', { ...input, ...this.appContext }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
     /**
-     * Trades the one-time OAuth code for tokens. `state` is the value the app put
-     * on the initiate URL, read back from its own cookie/session (never from the
-     * callback query): Bastion refuses a code minted under a different one, which
-     * is what stops an attacker's code from being redeemed in a victim's browser.
+     * Starts an OAuth login: the provider's Bastion initiate URL with a fresh
+     * `state` on it, or `null` for a provider the app doesn't offer. Keep `state`
+     * in an httpOnly `SameSite=Lax` cookie scoped to the callback path, redirect
+     * the browser to `url`, then pass the cookie's value to `exchange`.
+     */
+    async oauthStart(provider) {
+        const method = (await this.getAuthMethods()).oauth.find((m) => m.provider === provider);
+        if (!method)
+            return null;
+        const state = (0, node_crypto_1.randomBytes)(32).toString('base64url');
+        const url = new URL(method.authorizeUrl);
+        url.searchParams.set('state', state);
+        return { url: url.toString(), state };
+    }
+    /**
+     * Trades the one-time OAuth code for tokens. `state` is the value from
+     * `oauthStart`, read back from the app's own cookie (never from the callback
+     * query): Bastion refuses a code minted under a different one, which is what
+     * stops an attacker's code from being redeemed in a victim's browser (login CSRF).
+     * Required: an empty `state` throws before calling Bastion.
      */
     exchange(code, ctx, state) {
-        return this.call('POST', '/auth/exchange', { code, appSlug: this.appSlug, ...(state !== undefined ? { state } : {}) }, { headers: BastionApiClient.clientHeaders(ctx) });
+        if (!state)
+            return Promise.reject(new Error('BastionApiClient.exchange: state is required (see oauthStart)'));
+        return this.call('POST', '/auth/exchange', { code, appSlug: this.appSlug, state }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
     completeTwoFactor(twoFactorToken, code, ctx) {
         return this.call('POST', '/auth/2fa/authenticate', { twoFactorToken, code }, { headers: BastionApiClient.clientHeaders(ctx) });

package/dist/cjs/core/bastion-http.d.ts

@@ -4,6 +4,12 @@ export interface BastionHttpOptions {
     /** Per-request timeout, default 8 000 ms. */
     timeoutMs?: number;
     fetch?: typeof fetch;
+    /**
+     * The id of the request being served, sent as `X-Request-Id` on every call
+     * (api.md §7) so Bastion logs it as `clientRequestId`. Read per call: back it
+     * with the framework's request context. A value outside `[A-Za-z0-9._-]{1,64}` is not sent.
+     */
+    requestId?: () => string | undefined;
 }
 export interface BastionRequestInit {
     token?: string;
@@ -26,6 +32,7 @@ export declare class BastionHttp {
     private readonly baseUrl;
     private readonly timeoutMs;
     private readonly fetchImpl;
+    private readonly requestId?;
     constructor(options: BastionHttpOptions);
     call<T>(method: string, path: string, body?: unknown, init?: BastionRequestInit): Promise<T>;
     clientAuth(input: ClientAuthInput): Promise<TokenResponse>;

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BastionHttp = void 0;
 const errors_js_1 = require("./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
@@ -13,11 +14,13 @@ 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 };
@@ -25,6 +28,10 @@ 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}`, {
@@ -38,11 +45,28 @@ class BastionHttp {
             throw new errors_js_1.BastionHttpError(503, `Bastion unreachable: ${err.message}`, errors_js_1.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 errors_js_1.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 = (0, errors_js_1.isBastionErrorCode)(message)
+                ? undefined
+                : (0, errors_js_1.isBastionErrorCode)(parsed.code)
+                    ? parsed.code
+                    : res.status === 400 && errors?.length
+                        ? errors_js_1.BastionErrorCode.VALIDATION_FAILED
+                        : undefined;
+            const upstreamCode = typeof parsed.code === 'string' && !(0, errors_js_1.isBastionErrorCode)(parsed.code) ? parsed.code : undefined;
+            throw new errors_js_1.BastionHttpError(res.status, message, code, errors, upstreamCode);
         }
         if (res.status === 204)
             return undefined;

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

@@ -21,7 +21,12 @@ 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";
+    /** A 401 from a step-up protected route (password change, email change, 2FA setup/confirm/disable, account delete): the current password or 2FA code is wrong, or the step-up counter is locked. The session is fine — do not log the user out. Bastion sends it as `code`; an older Bastion sends a plain 401, classified `INVALID_CREDENTIALS`. */
+    readonly STEP_UP_FAILED: "STEP_UP_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 +41,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/cjs/core/errors.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BastionHttpError = exports.BastionErrorCode = exports.BastionTokenError = void 0;
 exports.classifyBastionError = classifyBastionError;
+exports.isBastionErrorCode = isBastionErrorCode;
 /** Verification failure. `code` is safe to log; the message is safe to return to the caller. */
 class BastionTokenError extends Error {
     code;
@@ -29,7 +30,12 @@ exports.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',
+    /** A 401 from a step-up protected route (password change, email change, 2FA setup/confirm/disable, account delete): the current password or 2FA code is wrong, or the step-up counter is locked. The session is fine — do not log the user out. Bastion sends it as `code`; an older Bastion sends a plain 401, classified `INVALID_CREDENTIALS`. */
+    STEP_UP_FAILED: 'STEP_UP_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',
@@ -77,17 +83,33 @@ function classifyBastionError(status, message) {
         return exports.BastionErrorCode.NO_APP_ACCESS;
     if (status === 409)
         return exports.BastionErrorCode.CONFLICT;
+    if (status === 429)
+        return exports.BastionErrorCode.RATE_LIMITED;
     if (status === 503)
         return exports.BastionErrorCode.UNAVAILABLE;
     return exports.BastionErrorCode.UPSTREAM;
 }
-/** A non-2xx answer from Bastion's HTTP API, or Bastion unreachable (`status` 503, code `UNAVAILABLE`). */
+function isBastionErrorCode(value) {
+    return typeof value === 'string' && Object.hasOwn(exports.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).
+ */
 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/cjs/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