@heyatom/bastion-client 0.3.0 → 0.4.0

package/README.md

@@ -4,9 +4,9 @@ Consumer SDK for [Bastion](https://github.com/heyatomdev/bastion), the HeyAtom i
 Replaces the `src/modules/bastion/` boilerplate every service used to copy by hand.
 
 - `@heyatom/bastion-client` — framework-free core: `JwksVerifier` (kid-indexed cache, unknown-kid refetch with cooldown, stale-on-error), `BastionHttp` (`POST /auth/client`, `POST /events`, any other route), `ServiceTokenProvider` (single-flight refresh ahead of `exp`), payload types.
-- `@heyatom/bastion-client` also carries Bastion's user-API contract: `BastionApiClient` (login, register, OAuth exchange, 2FA, single-flight refresh, logout, sessions, `/me`, profile, social accounts, email/password flows, export, delete), its types (`BastionMe`, `BastionTokenPair`, …) and `BastionErrorCode` (a stable code on every `BastionHttpError`).
+- `@heyatom/bastion-client` also carries Bastion's user-API contract: `BastionApiClient` (login, register, OAuth exchange, 2FA, single-flight refresh, logout, sessions, `/me`, profile, social accounts, email/password flows, export, delete), its types (`BastionMe`, `BastionTokenPair`, …) and `BastionErrorCode` (a stable code on every `BastionHttpError`: credentials, app context, refresh token, OAuth code, age gate, OAuth flow, unavailable, upstream). `refreshMemoryMs` tunes how long a refresh answer is remembered per token (default 60 s).
 - `@heyatom/bastion-client/webhooks` — `verifyWebhookSignature` (`X-Bastion-Signature-V2` with timestamp + delivery id, legacy fallback, secret rotation on both sides), header constants, payload type.
-- `@heyatom/bastion-client/nest` — NestJS: `BastionModule`, `ServiceClientJwtGuard`, `BastionUserGuard`, `BastionAuditService`, `AuditInterceptor`, `@Public()`, `@RequireScope()`, `@Audit()`, `@CurrentClient()`, `@CurrentAdminUser()`.
+- `@heyatom/bastion-client/nest` — NestJS: `BastionModule`, `ServiceClientJwtGuard`, `BastionUserGuard`, `BastionAuditService`, `AuditInterceptor` (attributes to `req.adminUser`, any `AuditActor` shape: `sub` plus optional `tenantId`/`tenantSlug`/`role`/`appSlug`), `@Public()`, `@RequireScope()`, `@Audit()`, `@CurrentClient()`, `@CurrentAdminUser()`.
 
 Ships CJS and ESM. `jose` v6 is ESM-only, so the CJS build relies on Node's `require(esm)` — Node ≥ 20.19 / 22.12. Peer deps: `jose` (always), `@nestjs/common`, `@nestjs/core`, `rxjs`, `reflect-metadata` (for `/nest`).
 

package/dist/cjs/core/api-client.d.ts

@@ -7,6 +7,14 @@ export interface BastionApiClientOptions {
     appSlug: string;
     /** Required by Bastion when the app is registered in more than one tenant, or is `isGlobal`. */
     tenantSlug?: string;
+    /**
+     * How long a refresh answer is remembered per refresh token, default 60 000 ms.
+     * Within the window a second `refresh` with the same (now revoked) token
+     * returns the remembered pair instead of tripping Bastion's reuse detection,
+     * and `logout` still finds the successor. A BFF whose pages fire several
+     * calls before the browser sees the new cookie may want a few minutes.
+     */
+    refreshMemoryMs?: number;
     logger?: BastionLogger;
 }
 /**
@@ -27,6 +35,7 @@ export declare class BastionApiClient {
     private readonly http;
     private readonly appSlug;
     private readonly tenantSlug?;
+    private readonly refreshMemoryMs;
     private readonly logger;
     private readonly inFlight;
     private readonly recent;
@@ -45,7 +54,7 @@ export declare class BastionApiClient {
     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. */
+    /** Revokes the token and any successor issued through `refresh` within the memory window. Never throws. */
     logout(refreshToken: string | null | undefined): Promise<void>;
     listSessions(accessToken: string): Promise<BastionSession[]>;
     revokeSession(accessToken: string, sessionId: string): Promise<void>;
@@ -68,18 +77,18 @@ export declare class BastionApiClient {
     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>;
+    resendVerification(email: string, ctx?: BastionClientContext): Promise<void>;
+    verifyEmail(token: string, ctx?: BastionClientContext): Promise<void>;
+    forgotPassword(email: string, ctx?: BastionClientContext): Promise<void>;
+    resetPassword(token: string, newPassword: string, ctx?: BastionClientContext): Promise<void>;
     changePassword(accessToken: string, currentPassword: string, newPassword: string): Promise<void>;
     requestEmailChange(accessToken: string, input: BastionEmailChangeRequest): Promise<{
         message: string;
     }>;
-    confirmEmailChange(token: string): Promise<{
+    confirmEmailChange(token: string, ctx?: BastionClientContext): Promise<{
         message: string;
     }>;
-    revokeEmailChange(token: string): Promise<{
+    revokeEmailChange(token: string, ctx?: BastionClientContext): Promise<{
         message: string;
     }>;
     /** The user's own audit trail (`GET /auth/me/events`), paginated. */

package/dist/cjs/core/api-client.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BastionApiClient = void 0;
 const node_crypto_1 = require("node:crypto");
 const types_js_1 = require("./types.js");
-const REFRESH_CACHE_MS = 60_000;
+const DEFAULT_REFRESH_MEMORY_MS = 60_000;
 const AUTH_METHODS_CACHE_MS = 5 * 60_000;
 const MAX_ROTATION_HOPS = 32;
 /**
@@ -24,6 +24,7 @@ class BastionApiClient {
     http;
     appSlug;
     tenantSlug;
+    refreshMemoryMs;
     logger;
     inFlight = new Map();
     recent = new Map();
@@ -33,6 +34,7 @@ class BastionApiClient {
         this.http = options.http;
         this.appSlug = options.appSlug;
         this.tenantSlug = options.tenantSlug || undefined;
+        this.refreshMemoryMs = options.refreshMemoryMs ?? DEFAULT_REFRESH_MEMORY_MS;
         this.logger = options.logger ?? types_js_1.silentLogger;
     }
     get appContext() {
@@ -86,7 +88,7 @@ class BastionApiClient {
         this.inFlight.set(key, pending);
         return pending;
     }
-    /** Revokes the token and any successor issued through `refresh` in the last minute. Never throws. */
+    /** Revokes the token and any successor issued through `refresh` within the memory window. Never throws. */
     async logout(refreshToken) {
         if (!refreshToken)
             return;
@@ -161,17 +163,19 @@ class BastionApiClient {
         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 });
+    // Unauthenticated routes: Bastion rate-limits them by IP, so pass the
+    // browser's context or every user behind this backend shares one bucket.
+    resendVerification(email, ctx) {
+        return this.call('POST', '/auth/resend-verification', { email, ...this.appContext }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
-    verifyEmail(token) {
-        return this.call('GET', `/auth/verify-email?token=${encodeURIComponent(token)}`);
+    verifyEmail(token, ctx) {
+        return this.call('GET', `/auth/verify-email?token=${encodeURIComponent(token)}`, undefined, { headers: BastionApiClient.clientHeaders(ctx) });
     }
-    forgotPassword(email) {
-        return this.call('POST', '/auth/forgot-password', { email, ...this.appContext });
+    forgotPassword(email, ctx) {
+        return this.call('POST', '/auth/forgot-password', { email, ...this.appContext }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
-    resetPassword(token, newPassword) {
-        return this.call('POST', '/auth/reset-password', { token, newPassword });
+    resetPassword(token, newPassword, ctx) {
+        return this.call('POST', '/auth/reset-password', { token, newPassword }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
     changePassword(accessToken, currentPassword, newPassword) {
         return this.call('PATCH', '/auth/me/password', { currentPassword, newPassword }, { token: accessToken });
@@ -179,11 +183,11 @@ class BastionApiClient {
     requestEmailChange(accessToken, input) {
         return this.call('PATCH', '/auth/me/email', input, { token: accessToken });
     }
-    confirmEmailChange(token) {
-        return this.call('POST', '/auth/me/confirm-email', { token });
+    confirmEmailChange(token, ctx) {
+        return this.call('POST', '/auth/me/confirm-email', { token }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
-    revokeEmailChange(token) {
-        return this.call('POST', '/auth/me/revoke-email-change', { token });
+    revokeEmailChange(token, ctx) {
+        return this.call('POST', '/auth/me/revoke-email-change', { token }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
     // ── GDPR ─────────────────────────────────────────────────────────────────
     /** The user's own audit trail (`GET /auth/me/events`), paginated. */
@@ -216,10 +220,10 @@ class BastionApiClient {
     }
     prune(now) {
         for (const [key, entry] of this.recent)
-            if (now - entry.at >= REFRESH_CACHE_MS)
+            if (now - entry.at >= this.refreshMemoryMs)
                 this.recent.delete(key);
         for (const [key, entry] of this.successors)
-            if (now - entry.at >= REFRESH_CACHE_MS)
+            if (now - entry.at >= this.refreshMemoryMs)
                 this.successors.delete(key);
     }
 }

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

@@ -15,10 +15,20 @@ export declare const BastionErrorCode: {
     readonly INVALID_CREDENTIALS: "INVALID_CREDENTIALS";
     readonly NO_APP_ACCESS: "NO_APP_ACCESS";
     readonly ACCOUNT_INACTIVE: "ACCOUNT_INACTIVE";
+    /** The app/tenant pair in the request does not resolve: unknown app or tenant, inactive tenant, missing or wrong `tenantSlug`. A configuration error, never the user's. */
+    readonly INVALID_APP_CONTEXT: "INVALID_APP_CONTEXT";
+    /** `POST /auth/refresh` refused the token: expired, unknown, or replayed (the whole family is revoked). Re-authenticate. */
+    readonly INVALID_REFRESH_TOKEN: "INVALID_REFRESH_TOKEN";
+    /** `POST /auth/exchange` refused the one-time OAuth code: expired, already used, or minted for another app. */
+    readonly INVALID_OAUTH_CODE: "INVALID_OAUTH_CODE";
     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 OAUTH_FLOW_INVALID: "OAUTH_FLOW_INVALID";
+    readonly OAUTH_EMAIL_UNVERIFIED: "OAUTH_EMAIL_UNVERIFIED";
+    readonly OAUTH_EMAIL_REQUIRED: "OAUTH_EMAIL_REQUIRED";
+    readonly OAUTH_NO_ACCOUNT: "OAUTH_NO_ACCOUNT";
     readonly UNAVAILABLE: "UNAVAILABLE";
     readonly UPSTREAM: "UPSTREAM";
 };

package/dist/cjs/core/errors.js

@@ -23,28 +23,55 @@ exports.BastionErrorCode = {
     INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
     NO_APP_ACCESS: 'NO_APP_ACCESS',
     ACCOUNT_INACTIVE: 'ACCOUNT_INACTIVE',
+    /** The app/tenant pair in the request does not resolve: unknown app or tenant, inactive tenant, missing or wrong `tenantSlug`. A configuration error, never the user's. */
+    INVALID_APP_CONTEXT: 'INVALID_APP_CONTEXT',
+    /** `POST /auth/refresh` refused the token: expired, unknown, or replayed (the whole family is revoked). Re-authenticate. */
+    INVALID_REFRESH_TOKEN: 'INVALID_REFRESH_TOKEN',
+    /** `POST /auth/exchange` refused the one-time OAuth code: expired, already used, or minted for another app. */
+    INVALID_OAUTH_CODE: 'INVALID_OAUTH_CODE',
     CONFLICT: 'CONFLICT',
     BIRTH_DATE_REQUIRED: 'BIRTH_DATE_REQUIRED',
     BIRTH_DATE_INVALID: 'BIRTH_DATE_INVALID',
     UNDER_MINIMUM_AGE: 'UNDER_MINIMUM_AGE',
+    OAUTH_FLOW_INVALID: 'OAUTH_FLOW_INVALID',
+    OAUTH_EMAIL_UNVERIFIED: 'OAUTH_EMAIL_UNVERIFIED',
+    OAUTH_EMAIL_REQUIRED: 'OAUTH_EMAIL_REQUIRED',
+    OAUTH_NO_ACCOUNT: 'OAUTH_NO_ACCOUNT',
     UNAVAILABLE: 'UNAVAILABLE',
     UPSTREAM: 'UPSTREAM',
 };
+/** Messages Bastion already emits as a bare code: passed through unchanged. */
+const CODE_MESSAGES = new Set([
+    exports.BastionErrorCode.BIRTH_DATE_REQUIRED,
+    exports.BastionErrorCode.BIRTH_DATE_INVALID,
+    exports.BastionErrorCode.UNDER_MINIMUM_AGE,
+    exports.BastionErrorCode.OAUTH_FLOW_INVALID,
+    exports.BastionErrorCode.OAUTH_EMAIL_UNVERIFIED,
+    exports.BastionErrorCode.OAUTH_EMAIL_REQUIRED,
+    exports.BastionErrorCode.OAUTH_NO_ACCOUNT,
+]);
+const APP_CONTEXT_RE = /app not found|tenant not found|tenant is inactive|no tenants configured|tenantslug is required/i;
+const OAUTH_CODE_RE = /already used code|code expired|code\/app mismatch/i;
 function classifyBastionError(status, message) {
-    if (message === exports.BastionErrorCode.BIRTH_DATE_REQUIRED ||
-        message === exports.BastionErrorCode.BIRTH_DATE_INVALID ||
-        message === exports.BastionErrorCode.UNDER_MINIMUM_AGE) {
+    if (CODE_MESSAGES.has(message))
         return message;
-    }
+    if (APP_CONTEXT_RE.test(message) && (status === 401 || status === 400))
+        return exports.BastionErrorCode.INVALID_APP_CONTEXT;
     if (status === 403 && /email not verified/i.test(message))
         return exports.BastionErrorCode.EMAIL_NOT_VERIFIED;
     if (status === 401) {
+        if (/refresh token/i.test(message))
+            return exports.BastionErrorCode.INVALID_REFRESH_TOKEN;
+        if (OAUTH_CODE_RE.test(message))
+            return exports.BastionErrorCode.INVALID_OAUTH_CODE;
         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 === 403 && /no access to this app/i.test(message))
+        return exports.BastionErrorCode.NO_APP_ACCESS;
     if (status === 409)
         return exports.BastionErrorCode.CONFLICT;
     if (status === 503)

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

@@ -29,6 +29,7 @@ let BastionAuditService = BastionAuditService_1 = class BastionAuditService {
     logger = new common_1.Logger(BastionAuditService_1.name);
     tokens;
     tenantMismatchWarned = false;
+    noApiKeyWarned = false;
     constructor(bastion, options) {
         this.bastion = bastion;
         this.tokens = options.apiKey
@@ -50,7 +51,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/cjs/nest/index.d.ts

@@ -5,7 +5,7 @@ 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 { 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/core/api-client.d.ts

@@ -7,6 +7,14 @@ export interface BastionApiClientOptions {
     appSlug: string;
     /** Required by Bastion when the app is registered in more than one tenant, or is `isGlobal`. */
     tenantSlug?: string;
+    /**
+     * How long a refresh answer is remembered per refresh token, default 60 000 ms.
+     * Within the window a second `refresh` with the same (now revoked) token
+     * returns the remembered pair instead of tripping Bastion's reuse detection,
+     * and `logout` still finds the successor. A BFF whose pages fire several
+     * calls before the browser sees the new cookie may want a few minutes.
+     */
+    refreshMemoryMs?: number;
     logger?: BastionLogger;
 }
 /**
@@ -27,6 +35,7 @@ export declare class BastionApiClient {
     private readonly http;
     private readonly appSlug;
     private readonly tenantSlug?;
+    private readonly refreshMemoryMs;
     private readonly logger;
     private readonly inFlight;
     private readonly recent;
@@ -45,7 +54,7 @@ export declare class BastionApiClient {
     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. */
+    /** Revokes the token and any successor issued through `refresh` within the memory window. Never throws. */
     logout(refreshToken: string | null | undefined): Promise<void>;
     listSessions(accessToken: string): Promise<BastionSession[]>;
     revokeSession(accessToken: string, sessionId: string): Promise<void>;
@@ -68,18 +77,18 @@ export declare class BastionApiClient {
     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>;
+    resendVerification(email: string, ctx?: BastionClientContext): Promise<void>;
+    verifyEmail(token: string, ctx?: BastionClientContext): Promise<void>;
+    forgotPassword(email: string, ctx?: BastionClientContext): Promise<void>;
+    resetPassword(token: string, newPassword: string, ctx?: BastionClientContext): Promise<void>;
     changePassword(accessToken: string, currentPassword: string, newPassword: string): Promise<void>;
     requestEmailChange(accessToken: string, input: BastionEmailChangeRequest): Promise<{
         message: string;
     }>;
-    confirmEmailChange(token: string): Promise<{
+    confirmEmailChange(token: string, ctx?: BastionClientContext): Promise<{
         message: string;
     }>;
-    revokeEmailChange(token: string): Promise<{
+    revokeEmailChange(token: string, ctx?: BastionClientContext): Promise<{
         message: string;
     }>;
     /** The user's own audit trail (`GET /auth/me/events`), paginated. */

package/dist/esm/core/api-client.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { silentLogger } from './types.js';
-const REFRESH_CACHE_MS = 60_000;
+const DEFAULT_REFRESH_MEMORY_MS = 60_000;
 const AUTH_METHODS_CACHE_MS = 5 * 60_000;
 const MAX_ROTATION_HOPS = 32;
 /**
@@ -21,6 +21,7 @@ export class BastionApiClient {
     http;
     appSlug;
     tenantSlug;
+    refreshMemoryMs;
     logger;
     inFlight = new Map();
     recent = new Map();
@@ -30,6 +31,7 @@ export class BastionApiClient {
         this.http = options.http;
         this.appSlug = options.appSlug;
         this.tenantSlug = options.tenantSlug || undefined;
+        this.refreshMemoryMs = options.refreshMemoryMs ?? DEFAULT_REFRESH_MEMORY_MS;
         this.logger = options.logger ?? silentLogger;
     }
     get appContext() {
@@ -83,7 +85,7 @@ export class BastionApiClient {
         this.inFlight.set(key, pending);
         return pending;
     }
-    /** Revokes the token and any successor issued through `refresh` in the last minute. Never throws. */
+    /** Revokes the token and any successor issued through `refresh` within the memory window. Never throws. */
     async logout(refreshToken) {
         if (!refreshToken)
             return;
@@ -158,17 +160,19 @@ export class BastionApiClient {
         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 });
+    // Unauthenticated routes: Bastion rate-limits them by IP, so pass the
+    // browser's context or every user behind this backend shares one bucket.
+    resendVerification(email, ctx) {
+        return this.call('POST', '/auth/resend-verification', { email, ...this.appContext }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
-    verifyEmail(token) {
-        return this.call('GET', `/auth/verify-email?token=${encodeURIComponent(token)}`);
+    verifyEmail(token, ctx) {
+        return this.call('GET', `/auth/verify-email?token=${encodeURIComponent(token)}`, undefined, { headers: BastionApiClient.clientHeaders(ctx) });
     }
-    forgotPassword(email) {
-        return this.call('POST', '/auth/forgot-password', { email, ...this.appContext });
+    forgotPassword(email, ctx) {
+        return this.call('POST', '/auth/forgot-password', { email, ...this.appContext }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
-    resetPassword(token, newPassword) {
-        return this.call('POST', '/auth/reset-password', { token, newPassword });
+    resetPassword(token, newPassword, ctx) {
+        return this.call('POST', '/auth/reset-password', { token, newPassword }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
     changePassword(accessToken, currentPassword, newPassword) {
         return this.call('PATCH', '/auth/me/password', { currentPassword, newPassword }, { token: accessToken });
@@ -176,11 +180,11 @@ export class BastionApiClient {
     requestEmailChange(accessToken, input) {
         return this.call('PATCH', '/auth/me/email', input, { token: accessToken });
     }
-    confirmEmailChange(token) {
-        return this.call('POST', '/auth/me/confirm-email', { token });
+    confirmEmailChange(token, ctx) {
+        return this.call('POST', '/auth/me/confirm-email', { token }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
-    revokeEmailChange(token) {
-        return this.call('POST', '/auth/me/revoke-email-change', { token });
+    revokeEmailChange(token, ctx) {
+        return this.call('POST', '/auth/me/revoke-email-change', { token }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
     // ── GDPR ─────────────────────────────────────────────────────────────────
     /** The user's own audit trail (`GET /auth/me/events`), paginated. */
@@ -213,10 +217,10 @@ export class BastionApiClient {
     }
     prune(now) {
         for (const [key, entry] of this.recent)
-            if (now - entry.at >= REFRESH_CACHE_MS)
+            if (now - entry.at >= this.refreshMemoryMs)
                 this.recent.delete(key);
         for (const [key, entry] of this.successors)
-            if (now - entry.at >= REFRESH_CACHE_MS)
+            if (now - entry.at >= this.refreshMemoryMs)
                 this.successors.delete(key);
     }
 }

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

@@ -15,10 +15,20 @@ export declare const BastionErrorCode: {
     readonly INVALID_CREDENTIALS: "INVALID_CREDENTIALS";
     readonly NO_APP_ACCESS: "NO_APP_ACCESS";
     readonly ACCOUNT_INACTIVE: "ACCOUNT_INACTIVE";
+    /** The app/tenant pair in the request does not resolve: unknown app or tenant, inactive tenant, missing or wrong `tenantSlug`. A configuration error, never the user's. */
+    readonly INVALID_APP_CONTEXT: "INVALID_APP_CONTEXT";
+    /** `POST /auth/refresh` refused the token: expired, unknown, or replayed (the whole family is revoked). Re-authenticate. */
+    readonly INVALID_REFRESH_TOKEN: "INVALID_REFRESH_TOKEN";
+    /** `POST /auth/exchange` refused the one-time OAuth code: expired, already used, or minted for another app. */
+    readonly INVALID_OAUTH_CODE: "INVALID_OAUTH_CODE";
     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 OAUTH_FLOW_INVALID: "OAUTH_FLOW_INVALID";
+    readonly OAUTH_EMAIL_UNVERIFIED: "OAUTH_EMAIL_UNVERIFIED";
+    readonly OAUTH_EMAIL_REQUIRED: "OAUTH_EMAIL_REQUIRED";
+    readonly OAUTH_NO_ACCOUNT: "OAUTH_NO_ACCOUNT";
     readonly UNAVAILABLE: "UNAVAILABLE";
     readonly UPSTREAM: "UPSTREAM";
 };

package/dist/esm/core/errors.js

@@ -18,28 +18,55 @@ export const BastionErrorCode = {
     INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
     NO_APP_ACCESS: 'NO_APP_ACCESS',
     ACCOUNT_INACTIVE: 'ACCOUNT_INACTIVE',
+    /** The app/tenant pair in the request does not resolve: unknown app or tenant, inactive tenant, missing or wrong `tenantSlug`. A configuration error, never the user's. */
+    INVALID_APP_CONTEXT: 'INVALID_APP_CONTEXT',
+    /** `POST /auth/refresh` refused the token: expired, unknown, or replayed (the whole family is revoked). Re-authenticate. */
+    INVALID_REFRESH_TOKEN: 'INVALID_REFRESH_TOKEN',
+    /** `POST /auth/exchange` refused the one-time OAuth code: expired, already used, or minted for another app. */
+    INVALID_OAUTH_CODE: 'INVALID_OAUTH_CODE',
     CONFLICT: 'CONFLICT',
     BIRTH_DATE_REQUIRED: 'BIRTH_DATE_REQUIRED',
     BIRTH_DATE_INVALID: 'BIRTH_DATE_INVALID',
     UNDER_MINIMUM_AGE: 'UNDER_MINIMUM_AGE',
+    OAUTH_FLOW_INVALID: 'OAUTH_FLOW_INVALID',
+    OAUTH_EMAIL_UNVERIFIED: 'OAUTH_EMAIL_UNVERIFIED',
+    OAUTH_EMAIL_REQUIRED: 'OAUTH_EMAIL_REQUIRED',
+    OAUTH_NO_ACCOUNT: 'OAUTH_NO_ACCOUNT',
     UNAVAILABLE: 'UNAVAILABLE',
     UPSTREAM: 'UPSTREAM',
 };
+/** Messages Bastion already emits as a bare code: passed through unchanged. */
+const CODE_MESSAGES = new Set([
+    BastionErrorCode.BIRTH_DATE_REQUIRED,
+    BastionErrorCode.BIRTH_DATE_INVALID,
+    BastionErrorCode.UNDER_MINIMUM_AGE,
+    BastionErrorCode.OAUTH_FLOW_INVALID,
+    BastionErrorCode.OAUTH_EMAIL_UNVERIFIED,
+    BastionErrorCode.OAUTH_EMAIL_REQUIRED,
+    BastionErrorCode.OAUTH_NO_ACCOUNT,
+]);
+const APP_CONTEXT_RE = /app not found|tenant not found|tenant is inactive|no tenants configured|tenantslug is required/i;
+const OAUTH_CODE_RE = /already used code|code expired|code\/app mismatch/i;
 export function classifyBastionError(status, message) {
-    if (message === BastionErrorCode.BIRTH_DATE_REQUIRED ||
-        message === BastionErrorCode.BIRTH_DATE_INVALID ||
-        message === BastionErrorCode.UNDER_MINIMUM_AGE) {
+    if (CODE_MESSAGES.has(message))
         return message;
-    }
+    if (APP_CONTEXT_RE.test(message) && (status === 401 || status === 400))
+        return BastionErrorCode.INVALID_APP_CONTEXT;
     if (status === 403 && /email not verified/i.test(message))
         return BastionErrorCode.EMAIL_NOT_VERIFIED;
     if (status === 401) {
+        if (/refresh token/i.test(message))
+            return BastionErrorCode.INVALID_REFRESH_TOKEN;
+        if (OAUTH_CODE_RE.test(message))
+            return BastionErrorCode.INVALID_OAUTH_CODE;
         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 === 403 && /no access to this app/i.test(message))
+        return BastionErrorCode.NO_APP_ACCESS;
     if (status === 409)
         return BastionErrorCode.CONFLICT;
     if (status === 503)

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

@@ -5,7 +5,7 @@ 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 { 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyatom/bastion-client",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Consumer SDK for the Bastion identity provider: JWKS verification, service-client auth, audit writes, NestJS guards",
   "license": "MIT",
   "author": "Andrea Tombolato <hey@heyatom.dev> (https://heyatom.dev)",