@heyatom/bastion-client 0.2.0 → 0.3.0

package/dist/cjs/core/errors.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BastionHttpError = exports.BastionTokenError = void 0;
+exports.BastionHttpError = exports.BastionErrorCode = exports.BastionTokenError = void 0;
+exports.classifyBastionError = classifyBastionError;
 /** Verification failure. `code` is safe to log; the message is safe to return to the caller. */
 class BastionTokenError extends Error {
     code;
@@ -11,13 +12,54 @@ class BastionTokenError extends Error {
     }
 }
 exports.BastionTokenError = 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.
+ */
+exports.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',
+};
+function classifyBastionError(status, message) {
+    if (message === exports.BastionErrorCode.BIRTH_DATE_REQUIRED ||
+        message === exports.BastionErrorCode.BIRTH_DATE_INVALID ||
+        message === exports.BastionErrorCode.UNDER_MINIMUM_AGE) {
+        return message;
+    }
+    if (status === 403 && /email not verified/i.test(message))
+        return exports.BastionErrorCode.EMAIL_NOT_VERIFIED;
+    if (status === 401) {
+        if (/no access to this app/i.test(message))
+            return exports.BastionErrorCode.NO_APP_ACCESS;
+        if (/inactive|locked/i.test(message))
+            return exports.BastionErrorCode.ACCOUNT_INACTIVE;
+        return exports.BastionErrorCode.INVALID_CREDENTIALS;
+    }
+    if (status === 409)
+        return exports.BastionErrorCode.CONFLICT;
+    if (status === 503)
+        return exports.BastionErrorCode.UNAVAILABLE;
+    return exports.BastionErrorCode.UPSTREAM;
+}
+/** A non-2xx answer from Bastion's HTTP API, or Bastion unreachable (`status` 503, code `UNAVAILABLE`). */
 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);
     }
 }
 exports.BastionHttpError = BastionHttpError;

package/dist/cjs/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/cjs/core/index.js

@@ -14,8 +14,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ServiceTokenProvider = exports.BastionHttp = exports.JwksVerifier = void 0;
+exports.BastionApiClient = exports.ServiceTokenProvider = exports.BastionHttp = exports.JwksVerifier = void 0;
 __exportStar(require("./types.js"), exports);
+__exportStar(require("./api-types.js"), exports);
 __exportStar(require("./errors.js"), exports);
 var jwks_verifier_js_1 = require("./jwks-verifier.js");
 Object.defineProperty(exports, "JwksVerifier", { enumerable: true, get: function () { return jwks_verifier_js_1.JwksVerifier; } });
@@ -23,3 +24,5 @@ var bastion_http_js_1 = require("./bastion-http.js");
 Object.defineProperty(exports, "BastionHttp", { enumerable: true, get: function () { return bastion_http_js_1.BastionHttp; } });
 var service_token_provider_js_1 = require("./service-token-provider.js");
 Object.defineProperty(exports, "ServiceTokenProvider", { enumerable: true, get: function () { return service_token_provider_js_1.ServiceTokenProvider; } });
+var api_client_js_1 = require("./api-client.js");
+Object.defineProperty(exports, "BastionApiClient", { enumerable: true, get: function () { return api_client_js_1.BastionApiClient; } });

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

@@ -33,7 +33,8 @@ class JwksVerifier {
         this.ttlMs = options.ttlMs ?? 300_000;
         this.issuer = options.issuer === undefined ? 'bastion' : options.issuer;
         this.logger = options.logger ?? types_js_1.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/cjs/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/cjs/core/service-token-provider.js

@@ -5,42 +5,70 @@ const jose_1 = require("jose");
 const types_js_1 = require("./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.
- */
 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 = types_js_1.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 } = (0, jose_1.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/cjs/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/cjs/nest/bastion-api-client.provider.js

@@ -0,0 +1,43 @@
+"use strict";
+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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BastionApiClientProvider = void 0;
+const common_1 = require("@nestjs/common");
+const api_client_js_1 = require("../core/api-client.js");
+const bastion_service_js_1 = require("./bastion.service.js");
+const options_js_1 = require("./options.js");
+const nest_logger_js_1 = require("./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 api_client_js_1.BastionApiClient {
+    constructor(bastion, options) {
+        super({
+            http: bastion.http,
+            appSlug: options.serviceSlug,
+            tenantSlug: options.tenantSlug,
+            logger: (0, nest_logger_js_1.nestLogger)(api_client_js_1.BastionApiClient.name),
+        });
+    }
+};
+exports.BastionApiClientProvider = BastionApiClientProvider;
+exports.BastionApiClientProvider = BastionApiClientProvider = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(options_js_1.BASTION_OPTIONS)),
+    __metadata("design:paramtypes", [bastion_service_js_1.BastionService, Object])
+], BastionApiClientProvider);

package/dist/cjs/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/cjs/nest/bastion-http-exception.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NestBastionHttp = exports.BastionHttpException = void 0;
+const common_1 = require("@nestjs/common");
+const bastion_http_js_1 = require("../core/bastion-http.js");
+const errors_js_1 = require("../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 }`.
+ */
+class BastionHttpException extends common_1.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);
+    }
+}
+exports.BastionHttpException = BastionHttpException;
+/** `BastionHttp` whose failures are `BastionHttpException`s — what `BastionService.http` is. */
+class NestBastionHttp extends bastion_http_js_1.BastionHttp {
+    async call(method, path, body, init) {
+        try {
+            return await super.call(method, path, body, init);
+        }
+        catch (err) {
+            if (err instanceof errors_js_1.BastionHttpError)
+                throw BastionHttpException.from(err);
+            throw err;
+        }
+    }
+}
+exports.NestBastionHttp = NestBastionHttp;

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

@@ -16,6 +16,7 @@ const bastion_audit_service_js_1 = require("./bastion-audit.service.js");
 const service_client_jwt_guard_js_1 = require("./guards/service-client-jwt.guard.js");
 const bastion_user_guard_js_1 = require("./guards/bastion-user.guard.js");
 const audit_interceptor_js_1 = require("./interceptors/audit.interceptor.js");
+const bastion_api_client_provider_js_1 = require("./bastion-api-client.provider.js");
 const PROVIDERS = [
     bastion_jwks_service_js_1.BastionJwksService,
     bastion_service_js_1.BastionService,
@@ -23,6 +24,7 @@ const PROVIDERS = [
     service_client_jwt_guard_js_1.ServiceClientJwtGuard,
     bastion_user_guard_js_1.BastionUserGuard,
     audit_interceptor_js_1.AuditInterceptor,
+    bastion_api_client_provider_js_1.BastionApiClientProvider,
 ];
 /**
  * ```ts

package/dist/cjs/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/cjs/nest/bastion.service.js

@@ -14,26 +14,18 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BastionService = void 0;
 const common_1 = require("@nestjs/common");
-const bastion_http_js_1 = require("../core/bastion-http.js");
-const errors_js_1 = require("../core/errors.js");
+const bastion_http_exception_js_1 = require("./bastion-http-exception.js");
 const options_js_1 = require("./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 bastion_http_js_1.BastionHttp({ baseUrl: options.baseUrl });
+        this.http = new bastion_http_exception_js_1.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 errors_js_1.BastionHttpError)
-                throw new common_1.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/cjs/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/cjs/nest/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CROSS_TENANT_ROLE = exports.resolveTenantScope = exports.CurrentAdminUser = exports.CurrentClient = exports.AUDIT_EVENT_KEY = exports.Audit = exports.REQUIRED_SCOPES_KEY = exports.RequireScope = exports.IS_PUBLIC_KEY = exports.Public = exports.AuditInterceptor = exports.BastionUserGuard = exports.ServiceClientJwtGuard = exports.BastionAuditService = exports.BastionService = exports.BastionJwksService = exports.BASTION_OPTIONS = exports.BastionModule = void 0;
+exports.CROSS_TENANT_ROLE = exports.resolveTenantScope = exports.CurrentAdminUser = exports.CurrentClient = exports.AUDIT_EVENT_KEY = exports.Audit = exports.REQUIRED_SCOPES_KEY = exports.RequireScope = exports.IS_PUBLIC_KEY = exports.Public = exports.AuditInterceptor = exports.BastionUserGuard = exports.ServiceClientJwtGuard = exports.BastionAuditService = exports.NestBastionHttp = exports.BastionHttpException = exports.BastionApiClientProvider = exports.BastionService = exports.BastionJwksService = exports.BASTION_OPTIONS = exports.BastionModule = void 0;
 __exportStar(require("../core/index.js"), exports);
 var bastion_module_js_1 = require("./bastion.module.js");
 Object.defineProperty(exports, "BastionModule", { enumerable: true, get: function () { return bastion_module_js_1.BastionModule; } });
@@ -24,6 +24,11 @@ var bastion_jwks_service_js_1 = require("./bastion-jwks.service.js");
 Object.defineProperty(exports, "BastionJwksService", { enumerable: true, get: function () { return bastion_jwks_service_js_1.BastionJwksService; } });
 var bastion_service_js_1 = require("./bastion.service.js");
 Object.defineProperty(exports, "BastionService", { enumerable: true, get: function () { return bastion_service_js_1.BastionService; } });
+var bastion_api_client_provider_js_1 = require("./bastion-api-client.provider.js");
+Object.defineProperty(exports, "BastionApiClientProvider", { enumerable: true, get: function () { return bastion_api_client_provider_js_1.BastionApiClientProvider; } });
+var bastion_http_exception_js_1 = require("./bastion-http-exception.js");
+Object.defineProperty(exports, "BastionHttpException", { enumerable: true, get: function () { return bastion_http_exception_js_1.BastionHttpException; } });
+Object.defineProperty(exports, "NestBastionHttp", { enumerable: true, get: function () { return bastion_http_exception_js_1.NestBastionHttp; } });
 var bastion_audit_service_js_1 = require("./bastion-audit.service.js");
 Object.defineProperty(exports, "BastionAuditService", { enumerable: true, get: function () { return bastion_audit_service_js_1.BastionAuditService; } });
 var service_client_jwt_guard_js_1 = require("./guards/service-client-jwt.guard.js");

package/dist/cjs/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/cjs/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;

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' };
+}