@heyatom/bastion-client 0.1.2 → 0.3.0

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

@@ -1,11 +1,32 @@
-export type TokenErrorCode = 'malformed' | 'missing_kid' | 'unknown_kid' | 'invalid';
+export type TokenErrorCode = 'malformed' | 'missing_kid' | 'unknown_kid' | 'invalid' | 'not_user_token' | 'wrong_app';
 /** Verification failure. `code` is safe to log; the message is safe to return to the caller. */
 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);
     }
 }

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

@@ -1,5 +1,7 @@
 export * from './types.js';
+export * from './api-types.js';
 export * from './errors.js';
 export { JwksVerifier, type JwksVerifierOptions } from './jwks-verifier.js';
-export { BastionHttp, type BastionHttpOptions, type ClientAuthInput } from './bastion-http.js';
-export { ServiceTokenProvider } from './service-token-provider.js';
+export { BastionHttp, type BastionHttpOptions, type BastionRequestInit, type ClientAuthInput } from './bastion-http.js';
+export { ServiceTokenProvider, type CredentialResolver, type ServiceTokenCredentials } from './service-token-provider.js';
+export { BastionApiClient, type BastionApiClientOptions } from './api-client.js';

package/dist/esm/core/index.js

@@ -1,5 +1,7 @@
 export * from './types.js';
+export * from './api-types.js';
 export * from './errors.js';
 export { JwksVerifier } from './jwks-verifier.js';
 export { BastionHttp } from './bastion-http.js';
 export { ServiceTokenProvider } from './service-token-provider.js';
+export { BastionApiClient } from './api-client.js';

package/dist/esm/core/jwks-verifier.js

@@ -30,7 +30,8 @@ export class JwksVerifier {
         this.ttlMs = options.ttlMs ?? 300_000;
         this.issuer = options.issuer === undefined ? 'bastion' : options.issuer;
         this.logger = options.logger ?? silentLogger;
-        this.fetchImpl = options.fetch ?? fetch;
+        // Late-bound on purpose: a consumer (or its tests) may replace global fetch after construction.
+        this.fetchImpl = options.fetch ?? ((...args) => fetch(...args));
     }
     async verify(token) {
         let kid;

package/dist/esm/core/service-token-provider.d.ts

@@ -1,21 +1,29 @@
 import type { BastionHttp, ClientAuthInput } from './bastion-http.js';
 import { type BastionLogger } from './types.js';
 /**
- * Holds the service-client token for outbound calls and renews it ahead of
- * `exp`. Single-flight: a burst of first calls shares one `POST /auth/client`
- * instead of issuing one per caller — the previous per-service copies had no
- * such guard.
+ * Holds machine tokens for outbound calls and renews each ahead of `exp`.
+ * One credential (the common case) or several keyed by `serviceSlug`, for an
+ * app that calls more than one service with its own client for each. Per
+ * slug: single-flight (a burst of first calls shares one `POST /auth/client`)
+ * and stale-cache fallback (a mint that fails while the old token is still
+ * inside its `exp` keeps serving it).
  */
+/** Credentials looked up per `serviceSlug` on demand — for an app whose targets are configured lazily. */
+export interface CredentialResolver {
+    resolve: (serviceSlug: string) => ClientAuthInput | null | undefined;
+    defaultSlug: string;
+}
+export type ServiceTokenCredentials = ClientAuthInput | Record<string, ClientAuthInput> | CredentialResolver;
 export declare class ServiceTokenProvider {
     private readonly http;
-    private readonly credentials;
     private readonly logger;
-    private token;
-    private expiresAt;
-    private inFlight;
-    /** Tenant the token was issued for — the tenant `POST /events` rows land in. */
-    tenantId: string | null;
-    constructor(http: BastionHttp, credentials: ClientAuthInput, logger?: BastionLogger);
-    getToken(): Promise<string>;
+    private readonly resolveCredential;
+    private readonly defaultSlug;
+    private readonly cache;
+    private readonly inFlight;
+    constructor(http: BastionHttp, credentials: ServiceTokenCredentials, logger?: BastionLogger);
+    /** Tenant of the default credential's token, once minted — the tenant `POST /events` rows land in. */
+    get tenantId(): string | null;
+    getToken(serviceSlug?: string): Promise<string>;
     private refresh;
 }

package/dist/esm/core/service-token-provider.js

@@ -2,42 +2,70 @@ import { decodeJwt } from 'jose';
 import { silentLogger } from './types.js';
 const REFRESH_MARGIN_MS = 5 * 60 * 1000;
 const FALLBACK_TTL_MS = 60 * 60 * 1000;
-/**
- * Holds the service-client token for outbound calls and renews it ahead of
- * `exp`. Single-flight: a burst of first calls shares one `POST /auth/client`
- * instead of issuing one per caller — the previous per-service copies had no
- * such guard.
- */
 export class ServiceTokenProvider {
     http;
-    credentials;
     logger;
-    token = null;
-    expiresAt = 0;
-    inFlight = null;
-    /** Tenant the token was issued for — the tenant `POST /events` rows land in. */
-    tenantId = null;
+    resolveCredential;
+    defaultSlug;
+    cache = new Map();
+    inFlight = new Map();
     constructor(http, credentials, logger = silentLogger) {
         this.http = http;
-        this.credentials = credentials;
         this.logger = logger;
-    }
-    getToken() {
-        if (this.token && Date.now() < this.expiresAt - REFRESH_MARGIN_MS) {
-            return Promise.resolve(this.token);
+        if ('resolve' in credentials && typeof credentials.resolve === 'function') {
+            const resolver = credentials;
+            this.resolveCredential = resolver.resolve;
+            this.defaultSlug = resolver.defaultSlug;
+        }
+        else if ('apiKey' in credentials && typeof credentials.apiKey === 'string') {
+            const single = credentials;
+            this.resolveCredential = (slug) => (slug === single.serviceSlug ? single : null);
+            this.defaultSlug = single.serviceSlug;
+        }
+        else {
+            const record = credentials;
+            const [first] = Object.keys(record);
+            if (!first)
+                throw new Error('ServiceTokenProvider: no credentials configured');
+            this.resolveCredential = (slug) => record[slug];
+            this.defaultSlug = first;
         }
-        this.inFlight ??= this.refresh().finally(() => {
-            this.inFlight = null;
-        });
-        return this.inFlight;
     }
-    async refresh() {
-        const { accessToken } = await this.http.clientAuth(this.credentials);
+    /** Tenant of the default credential's token, once minted — the tenant `POST /events` rows land in. */
+    get tenantId() {
+        return this.cache.get(this.defaultSlug)?.tenantId ?? null;
+    }
+    getToken(serviceSlug = this.defaultSlug) {
+        const cached = this.cache.get(serviceSlug);
+        if (cached && Date.now() < cached.expiresAt - REFRESH_MARGIN_MS)
+            return Promise.resolve(cached.token);
+        const running = this.inFlight.get(serviceSlug);
+        if (running)
+            return running;
+        const pending = this.refresh(serviceSlug)
+            .catch((err) => {
+            if (cached && Date.now() < cached.expiresAt) {
+                this.logger.warn(`bastion: token mint for ${serviceSlug} failed, serving stale cache`);
+                return cached.token;
+            }
+            throw err;
+        })
+            .finally(() => this.inFlight.delete(serviceSlug));
+        this.inFlight.set(serviceSlug, pending);
+        return pending;
+    }
+    async refresh(serviceSlug) {
+        const credential = this.resolveCredential(serviceSlug);
+        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);
-        this.token = accessToken;
-        this.expiresAt = exp ? exp * 1000 : Date.now() + FALLBACK_TTL_MS;
-        this.tenantId = tenantId ?? null;
-        this.logger.log('service client token refreshed');
+        this.cache.set(serviceSlug, {
+            token: accessToken,
+            expiresAt: exp ? exp * 1000 : Date.now() + FALLBACK_TTL_MS,
+            tenantId: tenantId ?? null,
+        });
+        this.logger.log(`service client token refreshed for ${serviceSlug}`);
         return accessToken;
     }
 }

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

@@ -29,6 +29,14 @@ export interface ServiceClientJwtPayload extends CommonClaims {
     scopes: string[];
 }
 export type BastionJwtPayload = UserJwtPayload | ServiceClientJwtPayload;
+/**
+ * For an app backend that accepts its *users'* tokens: the payload must be a
+ * user token (machine tokens are rejected whatever their scopes), minted for
+ * this app — Bastion sets `aud` and `appSlug` to the app slug at issuance, and
+ * one signing key serves the whole fleet, so a valid signature alone proves
+ * nothing about which app the session belongs to.
+ */
+export declare function assertUserTokenFor(payload: BastionJwtPayload, appSlug: string): UserJwtPayload;
 export declare function isServiceClientToken(payload: BastionJwtPayload): payload is ServiceClientJwtPayload;
 export interface TokenResponse {
     accessToken: string;

package/dist/esm/core/types.js

@@ -1,3 +1,22 @@
+import { BastionTokenError } from './errors.js';
+/**
+ * For an app backend that accepts its *users'* tokens: the payload must be a
+ * user token (machine tokens are rejected whatever their scopes), minted for
+ * this app — Bastion sets `aud` and `appSlug` to the app slug at issuance, and
+ * one signing key serves the whole fleet, so a valid signature alone proves
+ * nothing about which app the session belongs to.
+ */
+export function assertUserTokenFor(payload, appSlug) {
+    if (payload.type !== undefined) {
+        throw new BastionTokenError('not_user_token', 'Service token not allowed');
+    }
+    if (payload.aud !== appSlug || payload.appSlug !== appSlug) {
+        throw new BastionTokenError('wrong_app', 'Invalid app context');
+    }
+    if (!payload.sub)
+        throw new BastionTokenError('wrong_app', 'Token without subject');
+    return payload;
+}
 export function isServiceClientToken(payload) {
     return payload.type === 'service_client';
 }

package/dist/esm/nest/bastion-api-client.provider.d.ts

@@ -0,0 +1,13 @@
+import { BastionApiClient } from '../core/api-client.js';
+import { BastionService } from './bastion.service.js';
+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:
+ * an `HttpException` with Bastion's status plus `code`/`upstreamMessage`.
+ */
+export declare class BastionApiClientProvider extends BastionApiClient {
+    constructor(bastion: BastionService, options: BastionModuleOptions);
+}

package/dist/esm/nest/bastion-api-client.provider.js

@@ -0,0 +1,40 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from '@nestjs/common';
+import { BastionApiClient } from '../core/api-client.js';
+import { BastionService } from './bastion.service.js';
+import { BASTION_OPTIONS } from './options.js';
+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:
+ * an `HttpException` with Bastion's status plus `code`/`upstreamMessage`.
+ */
+let BastionApiClientProvider = class BastionApiClientProvider extends BastionApiClient {
+    constructor(bastion, options) {
+        super({
+            http: bastion.http,
+            appSlug: options.serviceSlug,
+            tenantSlug: options.tenantSlug,
+            logger: nestLogger(BastionApiClient.name),
+        });
+    }
+};
+BastionApiClientProvider = __decorate([
+    Injectable(),
+    __param(1, Inject(BASTION_OPTIONS)),
+    __metadata("design:paramtypes", [BastionService, Object])
+], BastionApiClientProvider);
+export { BastionApiClientProvider };

package/dist/esm/nest/bastion-http-exception.d.ts

@@ -0,0 +1,19 @@
+import { HttpException } from '@nestjs/common';
+import { BastionHttp, type BastionRequestInit } from '../core/bastion-http.js';
+import { BastionHttpError, type BastionErrorCode } 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 }`.
+ */
+export declare class BastionHttpException extends HttpException {
+    readonly code: BastionErrorCode;
+    readonly upstreamMessage: string;
+    constructor(code: BastionErrorCode, status: number, upstreamMessage: string);
+    static from(err: BastionHttpError): BastionHttpException;
+}
+/** `BastionHttp` whose failures are `BastionHttpException`s — what `BastionService.http` is. */
+export declare class NestBastionHttp extends BastionHttp {
+    call<T>(method: string, path: string, body?: unknown, init?: BastionRequestInit): Promise<T>;
+}

package/dist/esm/nest/bastion-http-exception.js

@@ -0,0 +1,34 @@
+import { HttpException } from '@nestjs/common';
+import { BastionHttp } from '../core/bastion-http.js';
+import { 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 }`.
+ */
+export class BastionHttpException extends HttpException {
+    code;
+    upstreamMessage;
+    constructor(code, status, upstreamMessage) {
+        super({ code, message: upstreamMessage }, status);
+        this.code = code;
+        this.upstreamMessage = upstreamMessage;
+    }
+    static from(err) {
+        return new BastionHttpException(err.code, err.status, err.message);
+    }
+}
+/** `BastionHttp` whose failures are `BastionHttpException`s — what `BastionService.http` is. */
+export class NestBastionHttp extends BastionHttp {
+    async call(method, path, body, init) {
+        try {
+            return await super.call(method, path, body, init);
+        }
+        catch (err) {
+            if (err instanceof BastionHttpError)
+                throw BastionHttpException.from(err);
+            throw err;
+        }
+    }
+}

package/dist/esm/nest/bastion-jwks.service.d.ts

@@ -1,8 +1,15 @@
-import type { BastionJwtPayload } from '../core/types.js';
+import { type BastionJwtPayload, type UserJwtPayload } from '../core/types.js';
 import { type BastionModuleOptions } from './options.js';
 /** Verifies inbound Bastion tokens against the cached JWKS. Throws `UnauthorizedException` on any failure. */
 export declare class BastionJwksService {
     private readonly verifier;
+    private readonly appSlug;
     constructor(options: BastionModuleOptions);
     verify(token: string): Promise<BastionJwtPayload>;
+    /**
+     * A *user* session token issued for this app (`options.serviceSlug` is the
+     * app's own slug). What an app backend puts behind its own auth guard —
+     * cookie extraction, suspension, age gate stay the app's business.
+     */
+    verifyUserToken(token: string): Promise<UserJwtPayload>;
 }

package/dist/esm/nest/bastion-jwks.service.js

@@ -14,12 +14,15 @@ var BastionJwksService_1;
 import { Inject, Injectable, UnauthorizedException } from '@nestjs/common';
 import { JwksVerifier } from '../core/jwks-verifier.js';
 import { BastionTokenError } from '../core/errors.js';
+import { assertUserTokenFor } from '../core/types.js';
 import { BASTION_OPTIONS } from './options.js';
 import { nestLogger } from './nest-logger.js';
 /** Verifies inbound Bastion tokens against the cached JWKS. Throws `UnauthorizedException` on any failure. */
 let BastionJwksService = BastionJwksService_1 = class BastionJwksService {
     verifier;
+    appSlug;
     constructor(options) {
+        this.appSlug = options.serviceSlug;
         this.verifier = new JwksVerifier({
             baseUrl: options.baseUrl,
             ttlMs: options.jwksTtlMs,
@@ -37,6 +40,22 @@ let BastionJwksService = BastionJwksService_1 = class BastionJwksService {
             throw err;
         }
     }
+    /**
+     * A *user* session token issued for this app (`options.serviceSlug` is the
+     * app's own slug). What an app backend puts behind its own auth guard —
+     * cookie extraction, suspension, age gate stay the app's business.
+     */
+    async verifyUserToken(token) {
+        const payload = await this.verify(token);
+        try {
+            return assertUserTokenFor(payload, this.appSlug);
+        }
+        catch (err) {
+            if (err instanceof BastionTokenError)
+                throw new UnauthorizedException(err.message);
+            throw err;
+        }
+    }
 };
 BastionJwksService = BastionJwksService_1 = __decorate([
     Injectable(),

package/dist/esm/nest/bastion.module.js

@@ -13,6 +13,7 @@ import { BastionAuditService } from './bastion-audit.service.js';
 import { ServiceClientJwtGuard } from './guards/service-client-jwt.guard.js';
 import { BastionUserGuard } from './guards/bastion-user.guard.js';
 import { AuditInterceptor } from './interceptors/audit.interceptor.js';
+import { BastionApiClientProvider } from './bastion-api-client.provider.js';
 const PROVIDERS = [
     BastionJwksService,
     BastionService,
@@ -20,6 +21,7 @@ const PROVIDERS = [
     ServiceClientJwtGuard,
     BastionUserGuard,
     AuditInterceptor,
+    BastionApiClientProvider,
 ];
 /**
  * ```ts

package/dist/esm/nest/bastion.service.d.ts

@@ -1,15 +1,13 @@
-import { BastionHttp } from '../core/bastion-http.js';
+import { type BastionRequestInit } from '../core/bastion-http.js';
+import { NestBastionHttp } from './bastion-http-exception.js';
 import type { AuditEventInput, TokenResponse } from '../core/types.js';
 import { type BastionModuleOptions } from './options.js';
-/** Outbound HTTP to Bastion. A non-2xx answer surfaces as `HttpException` with Bastion's status. */
+/** Outbound HTTP to Bastion. A failure surfaces as `BastionHttpException` (an `HttpException` with Bastion's status, a stable `code` and the upstream message). */
 export declare class BastionService {
     private readonly options;
-    readonly http: BastionHttp;
+    readonly http: NestBastionHttp;
     constructor(options: BastionModuleOptions);
-    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(): Promise<TokenResponse>;
     writeAuditEvent(token: string, data: AuditEventInput): Promise<{
         id: string;

package/dist/esm/nest/bastion.service.js

@@ -10,27 +10,19 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { HttpException, Inject, Injectable } from '@nestjs/common';
-import { BastionHttp } from '../core/bastion-http.js';
-import { BastionHttpError } from '../core/errors.js';
+import { Inject, Injectable } from '@nestjs/common';
+import { NestBastionHttp } from './bastion-http-exception.js';
 import { BASTION_OPTIONS } from './options.js';
-/** Outbound HTTP to Bastion. A non-2xx answer surfaces as `HttpException` with Bastion's status. */
+/** Outbound HTTP to Bastion. A failure surfaces as `BastionHttpException` (an `HttpException` with Bastion's status, a stable `code` and the upstream message). */
 let BastionService = class BastionService {
     options;
     http;
     constructor(options) {
         this.options = options;
-        this.http = new BastionHttp({ baseUrl: options.baseUrl });
+        this.http = new NestBastionHttp({ baseUrl: options.baseUrl, timeoutMs: options.timeoutMs });
     }
-    async call(method, path, body, init) {
-        try {
-            return await this.http.call(method, path, body, init);
-        }
-        catch (err) {
-            if (err instanceof BastionHttpError)
-                throw new HttpException(err.message, err.status);
-            throw err;
-        }
+    call(method, path, body, init) {
+        return this.http.call(method, path, body, init);
     }
     clientAuth() {
         if (!this.options.apiKey) {

package/dist/esm/nest/index.d.ts

@@ -3,6 +3,8 @@ export { BastionModule } from './bastion.module.js';
 export { BASTION_OPTIONS, type BastionModuleOptions, type BastionModuleAsyncOptions } from './options.js';
 export { BastionJwksService } from './bastion-jwks.service.js';
 export { BastionService } from './bastion.service.js';
+export { BastionApiClientProvider } from './bastion-api-client.provider.js';
+export { BastionHttpException, NestBastionHttp } from './bastion-http-exception.js';
 export { BastionAuditService } from './bastion-audit.service.js';
 export { ServiceClientJwtGuard } from './guards/service-client-jwt.guard.js';
 export { BastionUserGuard } from './guards/bastion-user.guard.js';

package/dist/esm/nest/index.js

@@ -3,6 +3,8 @@ export { BastionModule } from './bastion.module.js';
 export { BASTION_OPTIONS } from './options.js';
 export { BastionJwksService } from './bastion-jwks.service.js';
 export { BastionService } from './bastion.service.js';
+export { BastionApiClientProvider } from './bastion-api-client.provider.js';
+export { BastionHttpException, NestBastionHttp } from './bastion-http-exception.js';
 export { BastionAuditService } from './bastion-audit.service.js';
 export { ServiceClientJwtGuard } from './guards/service-client-jwt.guard.js';
 export { BastionUserGuard } from './guards/bastion-user.guard.js';