@heyatom/bastion-client 0.7.2 → 0.9.0

package/dist/cjs/webhooks/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BASTION_LIFECYCLE_EVENTS = exports.BASTION_DELIVERY_ID_HEADER = exports.BASTION_EVENT_HEADER = exports.BASTION_SIGNATURE_V2_HEADER = exports.BASTION_SIGNATURE_HEADER = void 0;
+exports.BASTION_LIFECYCLE_EVENTS = exports.WEBHOOK_SIGNATURE_HEADER = exports.WEBHOOK_TIMESTAMP_HEADER = exports.WEBHOOK_ID_HEADER = exports.BASTION_DELIVERY_ID_HEADER = exports.BASTION_EVENT_HEADER = exports.BASTION_SIGNATURE_V2_HEADER = exports.BASTION_SIGNATURE_HEADER = void 0;
 exports.verifyWebhookSignature = verifyWebhookSignature;
 const node_crypto_1 = require("node:crypto");
 /** Headers Bastion sends with every delivery. Lower-case, as Node exposes them. */
@@ -8,14 +8,18 @@ exports.BASTION_SIGNATURE_HEADER = 'x-bastion-signature';
 exports.BASTION_SIGNATURE_V2_HEADER = 'x-bastion-signature-v2';
 exports.BASTION_EVENT_HEADER = 'x-bastion-event';
 exports.BASTION_DELIVERY_ID_HEADER = 'x-bastion-delivery-id';
+/** Standard Webhooks (standardwebhooks.com) headers, sent alongside v2 during the migration. */
+exports.WEBHOOK_ID_HEADER = 'webhook-id';
+exports.WEBHOOK_TIMESTAMP_HEADER = 'webhook-timestamp';
+exports.WEBHOOK_SIGNATURE_HEADER = 'webhook-signature';
 /** Sent to every app with a webhook URL, whether or not the user has a role in it. */
 exports.BASTION_LIFECYCLE_EVENTS = ['user.deleted', 'user.expired_unverified', 'user.deactivated'];
 function header(headers, name) {
-    const direct = headers[name] ?? headers[name.toLowerCase()];
-    if (direct !== undefined)
-        return Array.isArray(direct) ? direct[0] : direct;
-    const key = Object.keys(headers).find((k) => k.toLowerCase() === name);
-    const v = key ? headers[key] : undefined;
+    let v = headers[name];
+    if (v === undefined) {
+        const key = Object.keys(headers).find((k) => k.toLowerCase() === name);
+        v = key === undefined ? undefined : headers[key];
+    }
     return Array.isArray(v) ? v[0] : v;
 }
 function macEquals(hexA, hexB) {
@@ -23,20 +27,54 @@ function macEquals(hexA, hexB) {
     const b = Buffer.from(hexB, 'hex');
     return a.length === b.length && a.length > 0 && (0, node_crypto_1.timingSafeEqual)(a, b);
 }
+function isFresh(timestamp, options) {
+    const now = Math.floor((options.now ?? Date.now)() / 1000);
+    return Math.abs(now - timestamp) <= (options.toleranceSeconds ?? 300);
+}
 /**
- * Verifies a Bastion delivery. Prefers `X-Bastion-Signature-V2`
+ * Verifies a Bastion delivery. Prefers Standard Webhooks when any of `webhook-id`,
+ * `webhook-timestamp`, `webhook-signature` is present: `webhook-signature` is a
+ * space-separated list of `v1,<base64 HMAC-SHA256(secret, "<id>.<timestamp>.<body>")>`,
+ * keyed with the secret as UTF-8 (not a `whsec_` base64 key); `deliveryId` is `webhook-id`.
+ * Otherwise falls back to `X-Bastion-Signature-V2`
  * (`t=<unix>,id=<deliveryId>,v1=<hex>[,v1=<hex>]`, MAC over `"<t>.<id>.<body>"`),
  * which binds the timestamp and the delivery id so a stale or replayed
  * delivery is rejected without trusting any unsigned header. The legacy
  * `X-Bastion-Signature: sha256=<hex>` over the body alone is accepted only
- * when v2 is absent **and** `allowLegacySignature` is set. Any of the caller's `secrets` matching any `v1=` accepts:
+ * when both of the above are absent **and** `allowLegacySignature` is set. Any of the caller's
+ * `secrets` matching any `v1` entry accepts:
  * that is how a secret rotation stays zero-downtime on both sides.
  */
 function verifyWebhookSignature(options) {
     const body = typeof options.rawBody === 'string' ? Buffer.from(options.rawBody, 'utf8') : options.rawBody;
-    const secrets = (Array.isArray(options.secrets) ? options.secrets : [options.secrets]).filter(Boolean);
+    const secrets = (Array.isArray(options.secrets) ? options.secrets : [options.secrets]).filter(
+    // A whitespace-only secret is a misconfiguration, never a key; the rest are used byte-exact.
+    (s) => typeof s === 'string' && s.trim() !== '');
     if (secrets.length === 0)
         return { ok: false, reason: 'missing' };
+    const stdId = header(options.headers, exports.WEBHOOK_ID_HEADER);
+    const stdTs = header(options.headers, exports.WEBHOOK_TIMESTAMP_HEADER);
+    const stdSig = header(options.headers, exports.WEBHOOK_SIGNATURE_HEADER);
+    if (stdId || stdTs || stdSig) {
+        const macs = (stdSig ?? '')
+            .split(' ')
+            .map((entry) => entry.split(','))
+            .filter(([version, value]) => version === 'v1' && value)
+            .map(([, value]) => Buffer.from(value, 'base64'));
+        if (!stdId || !stdTs || !/^\d+$/.test(stdTs) || macs.length === 0)
+            return { ok: false, reason: 'malformed' };
+        const timestamp = Number(stdTs);
+        if (!isFresh(timestamp, options))
+            return { ok: false, reason: 'stale' };
+        const signed = Buffer.concat([Buffer.from(`${stdId}.${stdTs}.`, 'utf8'), body]);
+        for (const secret of secrets) {
+            const expected = (0, node_crypto_1.createHmac)('sha256', secret).update(signed).digest();
+            if (macs.some((mac) => mac.length === expected.length && (0, node_crypto_1.timingSafeEqual)(mac, expected))) {
+                return { ok: true, version: 'standard', timestamp, deliveryId: stdId };
+            }
+        }
+        return { ok: false, reason: 'mismatch' };
+    }
     const v2 = header(options.headers, exports.BASTION_SIGNATURE_V2_HEADER);
     if (v2) {
         const parts = v2.split(',').map((p) => p.trim());
@@ -46,8 +84,7 @@ function verifyWebhookSignature(options) {
         const timestamp = Number(t);
         if (!t || !id || macs.length === 0 || !Number.isFinite(timestamp))
             return { ok: false, reason: 'malformed' };
-        const now = Math.floor((options.now ?? Date.now)() / 1000);
-        if (Math.abs(now - timestamp) > (options.toleranceSeconds ?? 300))
+        if (!isFresh(timestamp, options))
             return { ok: false, reason: 'stale' };
         const signed = Buffer.concat([Buffer.from(`${timestamp}.${id}.`, 'utf8'), body]);
         for (const secret of secrets) {

package/dist/esm/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/esm/core/api-client.js

@@ -1,4 +1,4 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { silentLogger } from './types.js';
 const DEFAULT_REFRESH_MEMORY_MS = 60_000;
 const AUTH_METHODS_CACHE_MS = 5 * 60_000;
@@ -59,13 +59,31 @@ export 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 = 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/esm/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/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,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/esm/core/errors.js

@@ -24,7 +24,12 @@ 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',
+    /** 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',
@@ -72,17 +77,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) {