@heyatom/bastion-client 0.2.0 → 0.3.1

package/dist/cjs/webhooks/index.js

@@ -0,0 +1,72 @@
+"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.verifyWebhookSignature = verifyWebhookSignature;
+const node_crypto_1 = require("node:crypto");
+/** Headers Bastion sends with every delivery. Lower-case, as Node exposes them. */
+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';
+/** 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;
+    return Array.isArray(v) ? v[0] : v;
+}
+function macEquals(hexA, hexB) {
+    const a = Buffer.from(hexA, 'hex');
+    const b = Buffer.from(hexB, 'hex');
+    return a.length === b.length && a.length > 0 && (0, node_crypto_1.timingSafeEqual)(a, b);
+}
+/**
+ * Verifies a Bastion delivery. Prefers `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; falls back to
+ * the legacy `X-Bastion-Signature: sha256=<hex>` over the body alone only when
+ * v2 is absent. Any of the caller's `secrets` matching any `v1=` 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);
+    if (secrets.length === 0)
+        return { ok: false, reason: 'missing' };
+    const v2 = header(options.headers, exports.BASTION_SIGNATURE_V2_HEADER);
+    if (v2) {
+        const parts = v2.split(',').map((p) => p.trim());
+        const t = parts.find((p) => p.startsWith('t='))?.slice(2);
+        const id = parts.find((p) => p.startsWith('id='))?.slice(3);
+        const macs = parts.filter((p) => p.startsWith('v1=')).map((p) => p.slice(3));
+        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))
+            return { ok: false, reason: 'stale' };
+        const signed = Buffer.concat([Buffer.from(`${timestamp}.${id}.`, 'utf8'), body]);
+        for (const secret of secrets) {
+            const expected = (0, node_crypto_1.createHmac)('sha256', secret).update(signed).digest('hex');
+            if (macs.some((mac) => macEquals(mac, expected)))
+                return { ok: true, version: 'v2', timestamp, deliveryId: id };
+        }
+        return { ok: false, reason: 'mismatch' };
+    }
+    const legacy = header(options.headers, exports.BASTION_SIGNATURE_HEADER);
+    if (!legacy)
+        return { ok: false, reason: 'missing' };
+    if (!legacy.startsWith('sha256='))
+        return { ok: false, reason: 'malformed' };
+    const provided = legacy.slice('sha256='.length).trim();
+    for (const secret of secrets) {
+        const expected = (0, node_crypto_1.createHmac)('sha256', secret).update(body).digest('hex');
+        if (macEquals(provided, expected))
+            return { ok: true, version: 'legacy' };
+    }
+    return { ok: false, reason: 'mismatch' };
+}

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

@@ -0,0 +1,222 @@
+import { createHash } from 'node:crypto';
+import { silentLogger } from './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.
+ */
+export 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 ?? 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 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);
+    }
+}

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

@@ -0,0 +1,7 @@
+/**
+ * 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 function isTwoFactorPending(result) {
+    return result.requiresTwoFactor === true;
+}

package/dist/esm/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/esm/core/bastion-http.js

@@ -1,37 +1,49 @@
-import { BastionHttpError } from './errors.js';
+import { BastionErrorCode, BastionHttpError } from './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.
  */
 export 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 BastionHttpError(503, `Bastion unreachable: ${err.message}`, BastionErrorCode.UNAVAILABLE);
+        }
         if (!res.ok) {
-            const err = (await res.json().catch(() => ({})));
-            throw new 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 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);