@heyatom/bastion-client 0.2.0 → 0.3.1

package/README.md

@@ -4,7 +4,9 @@ Consumer SDK for [Bastion](https://github.com/heyatomdev/bastion), the HeyAtom i
 Replaces the `src/modules/bastion/` boilerplate every service used to copy by hand.
 
 - `@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/nest` — NestJS: `BastionModule`, `ServiceClientJwtGuard`, `BastionUserGuard`, `BastionAuditService`, `AuditInterceptor`, `@Public()`, `@RequireScope()`, `@Audit()`, `@CurrentClient()`, `@CurrentAdminUser()`.
+- `@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`).
+- `@heyatom/bastion-client/webhooks` — `verifyWebhookSignature` (`X-Bastion-Signature-V2` with timestamp + delivery id, legacy fallback, 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()`.
 
 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`).
 
@@ -71,6 +73,34 @@ Bastion stores app events as `<serviceSlug>.<event>` — send the bare `resource
 // Core equivalent: assertUserTokenFor(await verifier.verify(token), 'dbd-builds').
 ```
 
+## App backends (a BFF for your users)
+
+```ts
+import { BastionApiClientProvider, BastionHttpException } from '@heyatom/bastion-client/nest';
+
+@Controller('auth')
+export class AuthController {
+  constructor(private readonly bastion: BastionApiClientProvider) {}
+
+  @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
+    }
+  }
+}
+```
+
+```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);
+```
+
 ## Without NestJS
 
 ```ts
@@ -81,6 +111,7 @@ const payload = await verifier.verify(bearerToken); // throws BastionTokenError
 
 const http = new BastionHttp({ baseUrl: process.env.BASTION_URL! });
 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' });
 ```
 

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

@@ -0,0 +1,98 @@
+import type { BastionHttp } from './bastion-http.js';
+import { type BastionLogger } from './types.js';
+import type { BastionAgeVerificationResult, BastionAuthMethods, BastionClientContext, BastionEmailChangeRequest, BastionLinkTicket, BastionLoginResult, BastionMe, BastionProfile, BastionProfileUpdate, BastionRegisterInput, BastionSession, BastionSocialAccount, BastionTokenPair, BastionTwoFactorConfirmed, BastionTwoFactorSetup, BastionTwoFactorStatus, BastionUserAuditEventsPage } from './api-types.js';
+export interface BastionApiClientOptions {
+    http: BastionHttp;
+    /** This app's slug — sent as `appSlug` on every user-facing call. */
+    appSlug: string;
+    /** Required by Bastion when the app is registered in more than one tenant, or is `isGlobal`. */
+    tenantSlug?: string;
+    logger?: BastionLogger;
+}
+/**
+ * The user-facing half of Bastion's API, for an app backend that proxies its
+ * users' auth: login, register, OAuth exchange, 2FA, refresh, logout,
+ * sessions, `/me`, profile, social accounts, email/password flows, export,
+ * self-deletion. Every call takes the user's `accessToken` where Bastion
+ * needs one; nothing here holds state about who the user is.
+ *
+ * `refresh` is single-flight per refresh token and remembers each answer for
+ * 60 s: Bastion rotates the token on every use and treats a replay as
+ * theft (the whole family is revoked), so two concurrent refreshes with the
+ * same token from a racing browser must collapse into one call. `logout`
+ * follows the rotation chain so it revokes the token the browser is actually
+ * holding, not the one it started with.
+ */
+export declare class BastionApiClient {
+    private readonly http;
+    private readonly appSlug;
+    private readonly tenantSlug?;
+    private readonly logger;
+    private readonly inFlight;
+    private readonly recent;
+    private readonly successors;
+    private authMethods?;
+    constructor(options: BastionApiClientOptions);
+    private get appContext();
+    private static clientHeaders;
+    private call;
+    private static hash;
+    login(email: string, password: string, ctx?: BastionClientContext): Promise<BastionLoginResult>;
+    register(input: BastionRegisterInput, ctx?: BastionClientContext): Promise<{
+        message: string;
+    }>;
+    /** Trades the one-time OAuth code for tokens. */
+    exchange(code: string, ctx?: BastionClientContext): 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` in the last minute. Never throws. */
+    logout(refreshToken: string | null | undefined): Promise<void>;
+    listSessions(accessToken: string): Promise<BastionSession[]>;
+    revokeSession(accessToken: string, sessionId: string): Promise<void>;
+    revokeOtherSessions(accessToken: string): Promise<{
+        count: number;
+    }>;
+    me(accessToken: string): Promise<BastionMe>;
+    /** Answers the updated columns only (`BastionProfile`), not the full `BastionMe`. */
+    updateProfile(accessToken: string, update: BastionProfileUpdate): Promise<BastionProfile>;
+    completeAgeVerification(accessToken: string, birthDate: string): Promise<BastionAgeVerificationResult>;
+    /** Cached 5 min; a failed refetch serves the cached answer. */
+    getAuthMethods(): Promise<BastionAuthMethods>;
+    twoFactorStatus(accessToken: string): Promise<BastionTwoFactorStatus>;
+    twoFactorSetup(accessToken: string, currentPassword?: string): Promise<BastionTwoFactorSetup>;
+    twoFactorConfirm(accessToken: string, code: string, currentPassword?: string): Promise<BastionTwoFactorConfirmed>;
+    twoFactorDisable(accessToken: string, code: string, currentPassword?: string): Promise<{
+        message: string;
+    }>;
+    listSocialAccounts(accessToken: string): Promise<BastionSocialAccount[]>;
+    createSocialAccountLinkTicket(accessToken: string, provider: string): Promise<BastionLinkTicket>;
+    unlinkSocialAccount(accessToken: string, provider: string): Promise<void>;
+    updateSocialAccountSyncAvatar(accessToken: string, provider: string, syncAvatar: boolean): Promise<BastionSocialAccount>;
+    resendVerification(email: string): Promise<void>;
+    verifyEmail(token: string): Promise<void>;
+    forgotPassword(email: string): Promise<void>;
+    resetPassword(token: string, newPassword: string): Promise<void>;
+    changePassword(accessToken: string, currentPassword: string, newPassword: string): Promise<void>;
+    requestEmailChange(accessToken: string, input: BastionEmailChangeRequest): Promise<{
+        message: string;
+    }>;
+    confirmEmailChange(token: string): Promise<{
+        message: string;
+    }>;
+    revokeEmailChange(token: string): Promise<{
+        message: string;
+    }>;
+    /** The user's own audit trail (`GET /auth/me/events`), paginated. */
+    listMyEvents(accessToken: string, page?: {
+        page?: number;
+        limit?: number;
+    }): Promise<BastionUserAuditEventsPage>;
+    exportData(accessToken: string): Promise<Record<string, unknown>>;
+    /** Step-up: `currentPassword` when the account has one, `twoFactorCode` when 2FA is on. */
+    deleteSelf(accessToken: string, stepUp?: {
+        currentPassword?: string;
+        twoFactorCode?: string;
+    }): Promise<void>;
+    private latestRefreshToken;
+    private prune;
+}

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

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BastionApiClient = void 0;
+const node_crypto_1 = require("node:crypto");
+const types_js_1 = require("./types.js");
+const REFRESH_CACHE_MS = 60_000;
+const AUTH_METHODS_CACHE_MS = 5 * 60_000;
+const MAX_ROTATION_HOPS = 32;
+/**
+ * The user-facing half of Bastion's API, for an app backend that proxies its
+ * users' auth: login, register, OAuth exchange, 2FA, refresh, logout,
+ * sessions, `/me`, profile, social accounts, email/password flows, export,
+ * self-deletion. Every call takes the user's `accessToken` where Bastion
+ * needs one; nothing here holds state about who the user is.
+ *
+ * `refresh` is single-flight per refresh token and remembers each answer for
+ * 60 s: Bastion rotates the token on every use and treats a replay as
+ * theft (the whole family is revoked), so two concurrent refreshes with the
+ * same token from a racing browser must collapse into one call. `logout`
+ * follows the rotation chain so it revokes the token the browser is actually
+ * holding, not the one it started with.
+ */
+class BastionApiClient {
+    http;
+    appSlug;
+    tenantSlug;
+    logger;
+    inFlight = new Map();
+    recent = new Map();
+    successors = new Map();
+    authMethods;
+    constructor(options) {
+        this.http = options.http;
+        this.appSlug = options.appSlug;
+        this.tenantSlug = options.tenantSlug || undefined;
+        this.logger = options.logger ?? types_js_1.silentLogger;
+    }
+    get appContext() {
+        return { appSlug: this.appSlug, ...(this.tenantSlug ? { tenantSlug: this.tenantSlug } : {}) };
+    }
+    static clientHeaders(ctx) {
+        const headers = {};
+        if (ctx?.userAgent)
+            headers['User-Agent'] = ctx.userAgent;
+        if (ctx?.ip)
+            headers['X-Real-IP'] = ctx.ip;
+        return headers;
+    }
+    call(method, path, body, init) {
+        return this.http.call(method, path, body, init);
+    }
+    static hash(token) {
+        return (0, node_crypto_1.createHash)('sha256').update(token).digest('hex');
+    }
+    // ── session ──────────────────────────────────────────────────────────────
+    login(email, password, ctx) {
+        return this.call('POST', '/auth/login', { email, password, ...this.appContext }, { headers: BastionApiClient.clientHeaders(ctx) });
+    }
+    register(input, ctx) {
+        return this.call('POST', '/auth/register', { ...input, ...this.appContext }, { headers: BastionApiClient.clientHeaders(ctx) });
+    }
+    /** Trades the one-time OAuth code for tokens. */
+    exchange(code, ctx) {
+        return this.call('POST', '/auth/exchange', { code, appSlug: this.appSlug }, { headers: BastionApiClient.clientHeaders(ctx) });
+    }
+    completeTwoFactor(twoFactorToken, code, ctx) {
+        return this.call('POST', '/auth/2fa/authenticate', { twoFactorToken, code }, { headers: BastionApiClient.clientHeaders(ctx) });
+    }
+    async refresh(refreshToken, ctx) {
+        const key = BastionApiClient.hash(refreshToken);
+        this.prune(Date.now());
+        const cached = this.recent.get(key);
+        if (cached)
+            return cached.value;
+        const running = this.inFlight.get(key);
+        if (running)
+            return running;
+        const pending = this.call('POST', '/auth/refresh', { refreshToken, ...this.appContext }, { headers: BastionApiClient.clientHeaders(ctx) })
+            .then((value) => {
+            const at = Date.now();
+            this.recent.set(key, { value, at });
+            this.successors.set(key, { next: value.refreshToken, at });
+            return value;
+        })
+            .finally(() => this.inFlight.delete(key));
+        this.inFlight.set(key, pending);
+        return pending;
+    }
+    /** Revokes the token and any successor issued through `refresh` in the last minute. Never throws. */
+    async logout(refreshToken) {
+        if (!refreshToken)
+            return;
+        const tokens = new Set([refreshToken, this.latestRefreshToken(refreshToken)]);
+        this.recent.delete(BastionApiClient.hash(refreshToken));
+        await Promise.all([...tokens].map((token) => this.call('POST', '/auth/logout', { refreshToken: token }).catch((err) => this.logger.warn(`bastion: logout failed: ${err.message}`))));
+    }
+    listSessions(accessToken) {
+        return this.call('GET', '/auth/sessions', undefined, { token: accessToken });
+    }
+    revokeSession(accessToken, sessionId) {
+        return this.call('DELETE', `/auth/sessions/${encodeURIComponent(sessionId)}`, undefined, { token: accessToken });
+    }
+    revokeOtherSessions(accessToken) {
+        return this.call('DELETE', '/auth/sessions', undefined, { token: accessToken });
+    }
+    // ── account ──────────────────────────────────────────────────────────────
+    me(accessToken) {
+        return this.call('GET', '/auth/me', undefined, { token: accessToken });
+    }
+    /** Answers the updated columns only (`BastionProfile`), not the full `BastionMe`. */
+    updateProfile(accessToken, update) {
+        return this.call('PATCH', '/auth/me', update, { token: accessToken });
+    }
+    completeAgeVerification(accessToken, birthDate) {
+        return this.call('POST', '/auth/age-verification', { birthDate }, { token: accessToken });
+    }
+    /** Cached 5 min; a failed refetch serves the cached answer. */
+    async getAuthMethods() {
+        const cached = this.authMethods;
+        if (cached && Date.now() - cached.at < AUTH_METHODS_CACHE_MS)
+            return cached.value;
+        const params = new URLSearchParams({ appSlug: this.appSlug });
+        if (this.tenantSlug)
+            params.set('tenantSlug', this.tenantSlug);
+        try {
+            const value = await this.call('GET', `/auth/methods?${params}`);
+            this.authMethods = { value, at: Date.now() };
+            return value;
+        }
+        catch (err) {
+            if (!cached)
+                throw err;
+            this.logger.warn(`bastion: /auth/methods failed (${err.message}), serving the cached answer`);
+            return cached.value;
+        }
+    }
+    // ── 2FA ──────────────────────────────────────────────────────────────────
+    twoFactorStatus(accessToken) {
+        return this.call('GET', '/auth/2fa/status', undefined, { token: accessToken });
+    }
+    twoFactorSetup(accessToken, currentPassword) {
+        return this.call('POST', '/auth/2fa/setup', currentPassword ? { currentPassword } : {}, { token: accessToken });
+    }
+    twoFactorConfirm(accessToken, code, currentPassword) {
+        return this.call('POST', '/auth/2fa/confirm', { code, ...(currentPassword ? { currentPassword } : {}) }, { token: accessToken });
+    }
+    twoFactorDisable(accessToken, code, currentPassword) {
+        return this.call('POST', '/auth/2fa/disable', { code, ...(currentPassword ? { currentPassword } : {}) }, { token: accessToken });
+    }
+    // ── social accounts ──────────────────────────────────────────────────────
+    listSocialAccounts(accessToken) {
+        return this.call('GET', '/auth/me/social-accounts', undefined, { token: accessToken });
+    }
+    createSocialAccountLinkTicket(accessToken, provider) {
+        return this.call('POST', `/auth/me/social-accounts/${encodeURIComponent(provider)}/link-ticket`, undefined, { token: accessToken });
+    }
+    unlinkSocialAccount(accessToken, provider) {
+        return this.call('DELETE', `/auth/me/social-accounts/${encodeURIComponent(provider)}`, undefined, { token: accessToken });
+    }
+    updateSocialAccountSyncAvatar(accessToken, provider, syncAvatar) {
+        return this.call('PATCH', `/auth/me/social-accounts/${encodeURIComponent(provider)}`, { syncAvatar }, { token: accessToken });
+    }
+    // ── email & password ─────────────────────────────────────────────────────
+    resendVerification(email) {
+        return this.call('POST', '/auth/resend-verification', { email, ...this.appContext });
+    }
+    verifyEmail(token) {
+        return this.call('GET', `/auth/verify-email?token=${encodeURIComponent(token)}`);
+    }
+    forgotPassword(email) {
+        return this.call('POST', '/auth/forgot-password', { email, ...this.appContext });
+    }
+    resetPassword(token, newPassword) {
+        return this.call('POST', '/auth/reset-password', { token, newPassword });
+    }
+    changePassword(accessToken, currentPassword, newPassword) {
+        return this.call('PATCH', '/auth/me/password', { currentPassword, newPassword }, { token: accessToken });
+    }
+    requestEmailChange(accessToken, input) {
+        return this.call('PATCH', '/auth/me/email', input, { token: accessToken });
+    }
+    confirmEmailChange(token) {
+        return this.call('POST', '/auth/me/confirm-email', { token });
+    }
+    revokeEmailChange(token) {
+        return this.call('POST', '/auth/me/revoke-email-change', { token });
+    }
+    // ── GDPR ─────────────────────────────────────────────────────────────────
+    /** The user's own audit trail (`GET /auth/me/events`), paginated. */
+    listMyEvents(accessToken, page = {}) {
+        const params = new URLSearchParams();
+        if (page.page !== undefined)
+            params.set('page', String(page.page));
+        if (page.limit !== undefined)
+            params.set('limit', String(page.limit));
+        const qs = params.toString();
+        return this.call('GET', `/auth/me/events${qs ? `?${qs}` : ''}`, undefined, { token: accessToken });
+    }
+    exportData(accessToken) {
+        return this.call('GET', '/auth/me/export', undefined, { token: accessToken });
+    }
+    /** Step-up: `currentPassword` when the account has one, `twoFactorCode` when 2FA is on. */
+    deleteSelf(accessToken, stepUp = {}) {
+        return this.call('DELETE', '/auth/me', stepUp, { token: accessToken });
+    }
+    // ── internals ────────────────────────────────────────────────────────────
+    latestRefreshToken(refreshToken) {
+        let current = refreshToken;
+        for (let hop = 0; hop < MAX_ROTATION_HOPS; hop++) {
+            const next = this.successors.get(BastionApiClient.hash(current))?.next;
+            if (!next)
+                break;
+            current = next;
+        }
+        return current;
+    }
+    prune(now) {
+        for (const [key, entry] of this.recent)
+            if (now - entry.at >= REFRESH_CACHE_MS)
+                this.recent.delete(key);
+        for (const [key, entry] of this.successors)
+            if (now - entry.at >= REFRESH_CACHE_MS)
+                this.successors.delete(key);
+    }
+}
+exports.BastionApiClient = BastionApiClient;

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

@@ -0,0 +1,138 @@
+/**
+ * Bastion's public API contract as seen by an app backend. Field names and
+ * nullability mirror Bastion's DTOs; when Bastion changes one, it changes here.
+ */
+export interface BastionTokenPair {
+    accessToken: string;
+    refreshToken: string;
+    /** ISO timestamp — the refresh token is opaque, this is the only way to learn its lifetime. */
+    refreshTokenExpiresAt?: string;
+}
+export interface BastionTwoFactorPending {
+    requiresTwoFactor: true;
+    twoFactorToken: string;
+}
+export type BastionLoginResult = BastionTokenPair | BastionTwoFactorPending;
+export declare function isTwoFactorPending(result: BastionLoginResult): result is BastionTwoFactorPending;
+/** `GET /auth/me`. */
+export interface BastionMe {
+    id: string;
+    email: string;
+    username: string | null;
+    image: string | null;
+    preferredLocale: string | null;
+    emailVerified: boolean;
+    hasPassword: boolean;
+    role: string | null;
+    appSlug: string;
+    tenantId: string;
+    tenantSlug: string;
+    tenantName: string;
+    tenantActive: boolean;
+    apps: string[];
+    ageVerified: boolean;
+    ageVerificationRequired: boolean;
+    /** `null` = never screened, which is NOT "adult". */
+    isMinor: boolean | null;
+}
+export interface BastionSession {
+    id: string;
+    appSlug: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+    userAgent: string | null;
+    ip: string | null;
+    isCurrent: boolean;
+}
+export interface BastionRegisterInput {
+    email: string;
+    password: string;
+    username: string;
+    preferredLocale?: string;
+    /** ISO `YYYY-MM-DD`, required only when the app has `minimumAge`. */
+    birthDate?: string;
+}
+export interface BastionAgeVerificationResult {
+    ageVerified: true;
+    isMinor: boolean;
+}
+/** What `PATCH /auth/me` answers: the updated columns, not the full `BastionMe`. */
+export interface BastionProfile {
+    id: string;
+    email: string;
+    username: string | null;
+    image: string | null;
+    preferredLocale: string | null;
+    emailVerified: boolean;
+}
+export interface BastionProfileUpdate {
+    username?: string;
+    image?: string | null;
+    preferredLocale?: string;
+}
+export interface BastionEmailChangeRequest {
+    email: string;
+    currentPassword?: string;
+    twoFactorCode?: string;
+}
+export interface BastionTwoFactorStatus {
+    enabled: boolean;
+}
+export interface BastionTwoFactorSetup {
+    qrCodeDataUrl: string;
+    secret: string;
+}
+export interface BastionTwoFactorConfirmed {
+    recoveryCodes: string[];
+}
+export interface BastionTwoFactorRequest {
+    code?: string;
+    currentPassword?: string;
+}
+/** The end user behind a call: forwarded as `X-Real-IP` / `User-Agent` so Bastion's rate-limit and audit see the browser, not your container. */
+export interface BastionClientContext {
+    ip?: string;
+    userAgent?: string;
+}
+export interface BastionSocialAccount {
+    provider: string;
+    username: string | null;
+    email: string | null;
+    avatar: string | null;
+    syncAvatar: boolean;
+    createdAt: string;
+}
+/** `GET /auth/methods`. */
+export interface BastionAuthMethods {
+    tenantSlug: string;
+    appSlug: string;
+    password: {
+        login: boolean;
+        register: boolean;
+    };
+    oauth: {
+        provider: string;
+        authorizeUrl: string;
+    }[];
+    oauthSignup: boolean;
+}
+export interface BastionLinkTicket {
+    url: string;
+}
+/** One row of `GET /auth/me/events` — the user-facing projection, deliberately without `ip`/`userAgent`. */
+export interface BastionUserAuditEvent {
+    id: string;
+    tenantId: string;
+    userId: string | null;
+    appSlug: string;
+    event: string;
+    source: 'BASTION' | 'APP';
+    metadata: unknown;
+    createdAt: string;
+}
+export interface BastionUserAuditEventsPage {
+    data: BastionUserAuditEvent[];
+    total: number;
+    page: number;
+    limit: number;
+}

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

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Bastion's public API contract as seen by an app backend. Field names and
+ * nullability mirror Bastion's DTOs; when Bastion changes one, it changes here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTwoFactorPending = isTwoFactorPending;
+function isTwoFactorPending(result) {
+    return result.requiresTwoFactor === true;
+}

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

@@ -1,8 +1,15 @@
 import type { AuditEventInput, TokenResponse } from './types.js';
 export interface BastionHttpOptions {
     baseUrl: string;
+    /** Per-request timeout, default 8 000 ms. */
+    timeoutMs?: number;
     fetch?: typeof fetch;
 }
+export interface BastionRequestInit {
+    token?: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
 export interface ClientAuthInput {
     apiKey: string;
     serviceSlug: string;
@@ -10,19 +17,17 @@ export interface ClientAuthInput {
 }
 /**
  * Outbound calls to Bastion. Nothing here verifies inbound tokens — that is
- * `JwksVerifier`. `call` is public so a service can reach any other route
- * (e.g. `POST /auth/login` from a BFF) with the same error handling; pass the
- * browser's IP as `X-Real-IP` on user-facing calls so Bastion's rate-limit
- * and audit rows see the real client, not your container.
+ * `JwksVerifier`. `call` is public so a service can reach any route with the
+ * same error handling: a non-2xx answer becomes `BastionHttpError` with the
+ * status and a stable `code`; Bastion unreachable or timed out is a 503
+ * `UNAVAILABLE`. Pass the browser's IP as `X-Real-IP` on user-facing calls.
  */
 export declare class BastionHttp {
     private readonly baseUrl;
+    private readonly timeoutMs;
     private readonly fetchImpl;
     constructor(options: BastionHttpOptions);
-    call<T>(method: string, path: string, body?: unknown, init?: {
-        token?: string;
-        headers?: Record<string, string>;
-    }): Promise<T>;
+    call<T>(method: string, path: string, body?: unknown, init?: BastionRequestInit): Promise<T>;
     clientAuth(input: ClientAuthInput): Promise<TokenResponse>;
     /** `POST /events`. Bastion stores the event as `<serviceSlug>.<event>`; send the bare `resource.action`. */
     writeAuditEvent(token: string, data: AuditEventInput): Promise<{

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

@@ -4,37 +4,49 @@ exports.BastionHttp = void 0;
 const errors_js_1 = require("./errors.js");
 /**
  * Outbound calls to Bastion. Nothing here verifies inbound tokens — that is
- * `JwksVerifier`. `call` is public so a service can reach any other route
- * (e.g. `POST /auth/login` from a BFF) with the same error handling; pass the
- * browser's IP as `X-Real-IP` on user-facing calls so Bastion's rate-limit
- * and audit rows see the real client, not your container.
+ * `JwksVerifier`. `call` is public so a service can reach any route with the
+ * same error handling: a non-2xx answer becomes `BastionHttpError` with the
+ * status and a stable `code`; Bastion unreachable or timed out is a 503
+ * `UNAVAILABLE`. Pass the browser's IP as `X-Real-IP` on user-facing calls.
  */
 class BastionHttp {
     baseUrl;
+    timeoutMs;
     fetchImpl;
     constructor(options) {
         this.baseUrl = options.baseUrl.replace(/\/$/, '');
-        this.fetchImpl = options.fetch ?? fetch;
+        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));
     }
     async call(method, path, body, init = {}) {
-        const headers = {
-            'Content-Type': 'application/json',
-            ...init.headers,
-        };
+        const headers = { ...init.headers };
+        if (body !== undefined)
+            headers['Content-Type'] = 'application/json';
         if (init.token)
             headers['Authorization'] = `Bearer ${init.token}`;
-        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
-            method,
-            headers,
-            body: body === undefined ? undefined : JSON.stringify(body),
-        });
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(init.timeoutMs ?? this.timeoutMs),
+            });
+        }
+        catch (err) {
+            throw new errors_js_1.BastionHttpError(503, `Bastion unreachable: ${err.message}`, errors_js_1.BastionErrorCode.UNAVAILABLE);
+        }
         if (!res.ok) {
-            const err = (await res.json().catch(() => ({})));
-            throw new errors_js_1.BastionHttpError(res.status, err.message ?? 'Bastion error');
+            const parsed = (await res.json().catch(() => ({})));
+            const message = Array.isArray(parsed.message)
+                ? parsed.message.join(', ')
+                : (parsed.message ?? `Bastion error ${res.status}`);
+            throw new errors_js_1.BastionHttpError(res.status, message);
         }
         if (res.status === 204)
             return undefined;
-        return (await res.json());
+        return (await res.json().catch(() => undefined));
     }
     clientAuth(input) {
         return this.call('POST', '/auth/client', input);