@heyatom/bastion-client 0.2.0 → 0.3.1

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

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/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-audit.service.d.ts

@@ -1,7 +1,17 @@
 import { OnModuleInit } from '@nestjs/common';
-import type { UserJwtPayload } from '../core/types.js';
 import { BastionService } from './bastion.service.js';
 import { type BastionModuleOptions } from './options.js';
+/**
+ * The fields `writeAsAdmin` reads from an actor. A `UserJwtPayload` fits, and
+ * so does a consumer's own admin payload that carries extra fields.
+ */
+export interface AuditActor {
+    sub: string;
+    tenantId?: string;
+    tenantSlug?: string;
+    role?: string;
+    appSlug?: string;
+}
 /**
  * Fire-and-forget audit writes to `POST /events` under this service's own
  * machine token. Never throws: a failed write is logged, the request that
@@ -12,6 +22,7 @@ export declare class BastionAuditService implements OnModuleInit {
     private readonly logger;
     private readonly tokens;
     private tenantMismatchWarned;
+    private noApiKeyWarned;
     constructor(bastion: BastionService, options: BastionModuleOptions);
     onModuleInit(): Promise<void>;
     /** Tenant of this service's machine token, once known. */
@@ -25,5 +36,5 @@ export declare class BastionAuditService implements OnModuleInit {
      * belongs to the same tenant as this service's token — Bastion rejects a
      * foreign userId silently — otherwise the actor goes into `metadata`.
      */
-    writeAsAdmin(event: string, actor: UserJwtPayload | undefined, metadata?: Record<string, unknown>): Promise<void>;
+    writeAsAdmin(event: string, actor: AuditActor | undefined, metadata?: Record<string, unknown>): Promise<void>;
 }

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

@@ -26,6 +26,7 @@ let BastionAuditService = BastionAuditService_1 = class BastionAuditService {
     logger = new Logger(BastionAuditService_1.name);
     tokens;
     tenantMismatchWarned = false;
+    noApiKeyWarned = false;
     constructor(bastion, options) {
         this.bastion = bastion;
         this.tokens = options.apiKey
@@ -47,7 +48,12 @@ let BastionAuditService = BastionAuditService_1 = class BastionAuditService {
     }
     async write(event, opts = {}) {
         if (!this.tokens) {
-            this.logger.warn(`audit write skipped, no apiKey configured event=${event}`);
+            // Once, not per event: a consumer that verifies tokens but never writes
+            // audit (no apiKey on purpose) would otherwise log every skipped write.
+            if (!this.noApiKeyWarned) {
+                this.noApiKeyWarned = true;
+                this.logger.warn(`audit writes skipped, no apiKey configured (first event=${event})`);
+            }
             return;
         }
         let token;

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.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,7 +3,9 @@ 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 { BastionAuditService } from './bastion-audit.service.js';
+export { BastionApiClientProvider } from './bastion-api-client.provider.js';
+export { BastionHttpException, NestBastionHttp } from './bastion-http-exception.js';
+export { BastionAuditService, type AuditActor } from './bastion-audit.service.js';
 export { ServiceClientJwtGuard } from './guards/service-client-jwt.guard.js';
 export { BastionUserGuard } from './guards/bastion-user.guard.js';
 export { AuditInterceptor } from './interceptors/audit.interceptor.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';

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

@@ -9,6 +9,8 @@ export interface BastionModuleOptions {
     apiKey?: string;
     /** Required by Bastion when the app is `isGlobal` or registered in more than one tenant. */
     tenantSlug?: string;
+    /** Per-request timeout for outbound calls, default 8 000 ms. */
+    timeoutMs?: number;
     /** `BASTION_JWKS_TTL_MS`, default 300 000. */
     jwksTtlMs?: number;
     /** Expected `iss`. Default `'bastion'`; `null` disables the check. */

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

@@ -0,0 +1,54 @@
+/** Headers Bastion sends with every delivery. Lower-case, as Node exposes them. */
+export declare const BASTION_SIGNATURE_HEADER = "x-bastion-signature";
+export declare const BASTION_SIGNATURE_V2_HEADER = "x-bastion-signature-v2";
+export declare const BASTION_EVENT_HEADER = "x-bastion-event";
+export declare const 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. */
+export declare const BASTION_LIFECYCLE_EVENTS: readonly ["user.deleted", "user.expired_unverified", "user.deactivated"];
+export interface BastionWebhookPayload {
+    event: string;
+    tenantSlug?: string;
+    userId?: string;
+    timestamp?: string;
+    /** `auth.email_changed` */
+    newEmail?: string;
+    /** `auth.email_verified` */
+    email?: string;
+    /** `user.deleted` from the age gate carries `under_minimum_age`; absent otherwise. */
+    reason?: string;
+    [key: string]: unknown;
+}
+export interface VerifyWebhookOptions {
+    /** The request body exactly as received — never a re-serialized object. */
+    rawBody: Buffer | string;
+    /** Request headers (any case). */
+    headers: Record<string, string | string[] | undefined>;
+    /** Your webhook secret, plus the previous one during a rotation. */
+    secrets: string | string[];
+    /** Max age of `t` on a v2 signature, default 300 s. */
+    toleranceSeconds?: number;
+    /** For tests. */
+    now?: () => number;
+}
+export type VerifyWebhookResult = {
+    ok: true;
+    version: 'v2';
+    timestamp: number;
+    deliveryId: string;
+} | {
+    ok: true;
+    version: 'legacy';
+} | {
+    ok: false;
+    reason: 'missing' | 'malformed' | 'stale' | 'mismatch';
+};
+/**
+ * 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.
+ */
+export declare function verifyWebhookSignature(options: VerifyWebhookOptions): VerifyWebhookResult;