@heyatom/bastion-client 0.3.1 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@ 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` (attributes to `req.adminUser`, any `AuditActor` shape: `sub` plus optional `tenantId`/`tenantSlug`/`role`/`appSlug`), `@Public()`, `@RequireScope()`, `@Audit()`, `@CurrentClient()`, `@CurrentAdminUser()`.
 

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

@@ -1,12 +1,20 @@
 import type { BastionHttp } from './bastion-http.js';
 import { type BastionLogger } from './types.js';
-import type { BastionAgeVerificationResult, BastionAuthMethods, BastionClientContext, BastionEmailChangeRequest, BastionLinkTicket, BastionLoginResult, BastionMe, BastionProfile, BastionProfileUpdate, BastionRegisterInput, BastionSession, BastionSocialAccount, BastionTokenPair, BastionTwoFactorConfirmed, BastionTwoFactorSetup, BastionTwoFactorStatus, BastionUserAuditEventsPage } from './api-types.js';
+import type { BastionAgeVerificationResult, BastionAuthMethods, BastionClientContext, BastionEmailChangeRequest, BastionLinkCompleted, BastionLinkTicket, BastionLoginResult, BastionMe, BastionProfile, BastionProfileUpdate, BastionRegisterInput, BastionSession, BastionSocialAccount, BastionTokenPair, BastionTwoFactorConfirmed, BastionTwoFactorSetup, BastionTwoFactorStatus, BastionUserAuditEventsPage } from './api-types.js';
 export interface BastionApiClientOptions {
     http: BastionHttp;
     /** This app's slug — sent as `appSlug` on every user-facing call. */
     appSlug: string;
     /** Required by Bastion when the app is registered in more than one tenant, or is `isGlobal`. */
     tenantSlug?: string;
+    /**
+     * 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>;
@@ -66,20 +75,27 @@ export declare class BastionApiClient {
     }>;
     listSocialAccounts(accessToken: string): Promise<BastionSocialAccount[]>;
     createSocialAccountLinkTicket(accessToken: string, provider: string): Promise<BastionLinkTicket>;
+    /**
+     * Second step of a link: spends the one-time `linkCode` Bastion put on the
+     * redirect to `/auth/callback`. Pass the signed-in user's own token — Bastion
+     * links only if its `sub` is the user the ticket was issued to (403
+     * `OAUTH_LINK_USER_MISMATCH` otherwise; the code is spent either way).
+     */
+    completeSocialAccountLink(accessToken: string, code: string): Promise<BastionLinkCompleted>;
     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;
@@ -154,6 +156,15 @@ class BastionApiClient {
     createSocialAccountLinkTicket(accessToken, provider) {
         return this.call('POST', `/auth/me/social-accounts/${encodeURIComponent(provider)}/link-ticket`, undefined, { token: accessToken });
     }
+    /**
+     * Second step of a link: spends the one-time `linkCode` Bastion put on the
+     * redirect to `/auth/callback`. Pass the signed-in user's own token — Bastion
+     * links only if its `sub` is the user the ticket was issued to (403
+     * `OAUTH_LINK_USER_MISMATCH` otherwise; the code is spent either way).
+     */
+    completeSocialAccountLink(accessToken, code) {
+        return this.call('POST', '/auth/me/social-accounts/link/complete', { code }, { token: accessToken });
+    }
     unlinkSocialAccount(accessToken, provider) {
         return this.call('DELETE', `/auth/me/social-accounts/${encodeURIComponent(provider)}`, undefined, { token: accessToken });
     }
@@ -161,17 +172,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 +192,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 +229,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/api-types.d.ts

@@ -119,6 +119,10 @@ export interface BastionAuthMethods {
 export interface BastionLinkTicket {
     url: string;
 }
+/** `POST /auth/me/social-accounts/link/complete` — the provider now linked (lowercase slug). */
+export interface BastionLinkCompleted {
+    provider: string;
+}
 /** One row of `GET /auth/me/events` — the user-facing projection, deliberately without `ip`/`userAgent`. */
 export interface BastionUserAuditEvent {
     id: string;

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

@@ -15,10 +15,22 @@ 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";
+    /** `completeSocialAccountLink` called with a token that is not the link ticket's owner. The code is spent; start the link again. */
+    readonly OAUTH_LINK_USER_MISMATCH: "OAUTH_LINK_USER_MISMATCH";
     readonly UNAVAILABLE: "UNAVAILABLE";
     readonly UPSTREAM: "UPSTREAM";
 };

package/dist/cjs/core/errors.js

@@ -23,28 +23,58 @@ 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',
+    /** `completeSocialAccountLink` called with a token that is not the link ticket's owner. The code is spent; start the link again. */
+    OAUTH_LINK_USER_MISMATCH: 'OAUTH_LINK_USER_MISMATCH',
     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,
+    exports.BastionErrorCode.OAUTH_LINK_USER_MISMATCH,
+]);
+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/esm/core/api-client.d.ts

@@ -1,12 +1,20 @@
 import type { BastionHttp } from './bastion-http.js';
 import { type BastionLogger } from './types.js';
-import type { BastionAgeVerificationResult, BastionAuthMethods, BastionClientContext, BastionEmailChangeRequest, BastionLinkTicket, BastionLoginResult, BastionMe, BastionProfile, BastionProfileUpdate, BastionRegisterInput, BastionSession, BastionSocialAccount, BastionTokenPair, BastionTwoFactorConfirmed, BastionTwoFactorSetup, BastionTwoFactorStatus, BastionUserAuditEventsPage } from './api-types.js';
+import type { BastionAgeVerificationResult, BastionAuthMethods, BastionClientContext, BastionEmailChangeRequest, BastionLinkCompleted, BastionLinkTicket, BastionLoginResult, BastionMe, BastionProfile, BastionProfileUpdate, BastionRegisterInput, BastionSession, BastionSocialAccount, BastionTokenPair, BastionTwoFactorConfirmed, BastionTwoFactorSetup, BastionTwoFactorStatus, BastionUserAuditEventsPage } from './api-types.js';
 export interface BastionApiClientOptions {
     http: BastionHttp;
     /** This app's slug — sent as `appSlug` on every user-facing call. */
     appSlug: string;
     /** Required by Bastion when the app is registered in more than one tenant, or is `isGlobal`. */
     tenantSlug?: string;
+    /**
+     * 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>;
@@ -66,20 +75,27 @@ export declare class BastionApiClient {
     }>;
     listSocialAccounts(accessToken: string): Promise<BastionSocialAccount[]>;
     createSocialAccountLinkTicket(accessToken: string, provider: string): Promise<BastionLinkTicket>;
+    /**
+     * Second step of a link: spends the one-time `linkCode` Bastion put on the
+     * redirect to `/auth/callback`. Pass the signed-in user's own token — Bastion
+     * links only if its `sub` is the user the ticket was issued to (403
+     * `OAUTH_LINK_USER_MISMATCH` otherwise; the code is spent either way).
+     */
+    completeSocialAccountLink(accessToken: string, code: string): Promise<BastionLinkCompleted>;
     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;
@@ -151,6 +153,15 @@ export class BastionApiClient {
     createSocialAccountLinkTicket(accessToken, provider) {
         return this.call('POST', `/auth/me/social-accounts/${encodeURIComponent(provider)}/link-ticket`, undefined, { token: accessToken });
     }
+    /**
+     * Second step of a link: spends the one-time `linkCode` Bastion put on the
+     * redirect to `/auth/callback`. Pass the signed-in user's own token — Bastion
+     * links only if its `sub` is the user the ticket was issued to (403
+     * `OAUTH_LINK_USER_MISMATCH` otherwise; the code is spent either way).
+     */
+    completeSocialAccountLink(accessToken, code) {
+        return this.call('POST', '/auth/me/social-accounts/link/complete', { code }, { token: accessToken });
+    }
     unlinkSocialAccount(accessToken, provider) {
         return this.call('DELETE', `/auth/me/social-accounts/${encodeURIComponent(provider)}`, undefined, { token: accessToken });
     }
@@ -158,17 +169,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 +189,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 +226,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/api-types.d.ts

@@ -119,6 +119,10 @@ export interface BastionAuthMethods {
 export interface BastionLinkTicket {
     url: string;
 }
+/** `POST /auth/me/social-accounts/link/complete` — the provider now linked (lowercase slug). */
+export interface BastionLinkCompleted {
+    provider: string;
+}
 /** One row of `GET /auth/me/events` — the user-facing projection, deliberately without `ip`/`userAgent`. */
 export interface BastionUserAuditEvent {
     id: string;

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

@@ -15,10 +15,22 @@ 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";
+    /** `completeSocialAccountLink` called with a token that is not the link ticket's owner. The code is spent; start the link again. */
+    readonly OAUTH_LINK_USER_MISMATCH: "OAUTH_LINK_USER_MISMATCH";
     readonly UNAVAILABLE: "UNAVAILABLE";
     readonly UPSTREAM: "UPSTREAM";
 };

package/dist/esm/core/errors.js

@@ -18,28 +18,58 @@ 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',
+    /** `completeSocialAccountLink` called with a token that is not the link ticket's owner. The code is spent; start the link again. */
+    OAUTH_LINK_USER_MISMATCH: 'OAUTH_LINK_USER_MISMATCH',
     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,
+    BastionErrorCode.OAUTH_LINK_USER_MISMATCH,
+]);
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyatom/bastion-client",
-  "version": "0.3.1",
+  "version": "0.5.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)",