@heyatom/bastion-client 0.2.0 → 0.3.0

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);

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

@@ -4,8 +4,29 @@ export declare class BastionTokenError extends Error {
     readonly code: TokenErrorCode;
     constructor(code: TokenErrorCode, message: string);
 }
-/** A non-2xx answer from Bastion's HTTP API. */
+/**
+ * Stable classification of a Bastion error answer, so an app can branch on a
+ * code instead of on Bastion's message text. The age-gate codes are Bastion's
+ * own (it returns them verbatim); the rest are derived from status + message
+ * until Bastion carries a `code` field on every error.
+ */
+export declare const BastionErrorCode: {
+    readonly EMAIL_NOT_VERIFIED: "EMAIL_NOT_VERIFIED";
+    readonly INVALID_CREDENTIALS: "INVALID_CREDENTIALS";
+    readonly NO_APP_ACCESS: "NO_APP_ACCESS";
+    readonly ACCOUNT_INACTIVE: "ACCOUNT_INACTIVE";
+    readonly CONFLICT: "CONFLICT";
+    readonly BIRTH_DATE_REQUIRED: "BIRTH_DATE_REQUIRED";
+    readonly BIRTH_DATE_INVALID: "BIRTH_DATE_INVALID";
+    readonly UNDER_MINIMUM_AGE: "UNDER_MINIMUM_AGE";
+    readonly UNAVAILABLE: "UNAVAILABLE";
+    readonly UPSTREAM: "UPSTREAM";
+};
+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 class BastionHttpError extends Error {
     readonly status: number;
-    constructor(status: number, message: string);
+    readonly code: BastionErrorCode;
+    constructor(status: number, message: string, code?: BastionErrorCode);
 }

package/dist/esm/core/errors.js

@@ -7,12 +7,53 @@ export class BastionTokenError extends Error {
         this.name = 'BastionTokenError';
     }
 }
-/** A non-2xx answer from Bastion's HTTP API. */
+/**
+ * Stable classification of a Bastion error answer, so an app can branch on a
+ * code instead of on Bastion's message text. The age-gate codes are Bastion's
+ * own (it returns them verbatim); the rest are derived from status + message
+ * until Bastion carries a `code` field on every error.
+ */
+export const BastionErrorCode = {
+    EMAIL_NOT_VERIFIED: 'EMAIL_NOT_VERIFIED',
+    INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
+    NO_APP_ACCESS: 'NO_APP_ACCESS',
+    ACCOUNT_INACTIVE: 'ACCOUNT_INACTIVE',
+    CONFLICT: 'CONFLICT',
+    BIRTH_DATE_REQUIRED: 'BIRTH_DATE_REQUIRED',
+    BIRTH_DATE_INVALID: 'BIRTH_DATE_INVALID',
+    UNDER_MINIMUM_AGE: 'UNDER_MINIMUM_AGE',
+    UNAVAILABLE: 'UNAVAILABLE',
+    UPSTREAM: 'UPSTREAM',
+};
+export function classifyBastionError(status, message) {
+    if (message === BastionErrorCode.BIRTH_DATE_REQUIRED ||
+        message === BastionErrorCode.BIRTH_DATE_INVALID ||
+        message === BastionErrorCode.UNDER_MINIMUM_AGE) {
+        return message;
+    }
+    if (status === 403 && /email not verified/i.test(message))
+        return BastionErrorCode.EMAIL_NOT_VERIFIED;
+    if (status === 401) {
+        if (/no access to this app/i.test(message))
+            return BastionErrorCode.NO_APP_ACCESS;
+        if (/inactive|locked/i.test(message))
+            return BastionErrorCode.ACCOUNT_INACTIVE;
+        return BastionErrorCode.INVALID_CREDENTIALS;
+    }
+    if (status === 409)
+        return BastionErrorCode.CONFLICT;
+    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 class BastionHttpError extends Error {
     status;
-    constructor(status, message) {
+    code;
+    constructor(status, message, code) {
         super(message);
         this.status = status;
         this.name = 'BastionHttpError';
+        this.code = code ?? classifyBastionError(status, message);
     }
 }