@heyatom/bastion-client 0.6.0 → 0.7.1

package/README.md

@@ -5,7 +5,7 @@ Replaces the `src/modules/bastion/` boilerplate every service used to copy by ha
 
 - `@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`: 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/webhooks` — `verifyWebhookSignature` (`X-Bastion-Signature-V2` with timestamp + delivery id, legacy fallback only with `allowLegacySignature: true` (off by default since 0.7.0), 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()`.
 
 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

@@ -50,8 +50,13 @@ export declare class BastionApiClient {
     register(input: BastionRegisterInput, ctx?: BastionClientContext): Promise<{
         message: string;
     }>;
-    /** Trades the one-time OAuth code for tokens. */
-    exchange(code: string, ctx?: BastionClientContext): Promise<BastionLoginResult>;
+    /**
+     * Trades the one-time OAuth code for tokens. `state` is the value the app put
+     * on the initiate URL, read back from its own cookie/session (never from the
+     * callback query): Bastion refuses a code minted under a different one, which
+     * is what stops an attacker's code from being redeemed in a victim's browser.
+     */
+    exchange(code: string, ctx?: BastionClientContext, state?: string): 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` within the memory window. Never throws. */
@@ -81,7 +86,11 @@ export declare class BastionApiClient {
      * 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>;
+    /** Step-up: `currentPassword` when the account has one, `twoFactorCode` when 2FA is on. */
+    completeSocialAccountLink(accessToken: string, code: string, stepUp?: {
+        currentPassword?: string;
+        twoFactorCode?: string;
+    }): Promise<BastionLinkCompleted>;
     unlinkSocialAccount(accessToken: string, provider: string): Promise<void>;
     updateSocialAccountSyncAvatar(accessToken: string, provider: string, syncAvatar: boolean): Promise<BastionSocialAccount>;
     resendVerification(email: string, ctx?: BastionClientContext): Promise<void>;

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

@@ -61,9 +61,14 @@ class BastionApiClient {
     register(input, ctx) {
         return this.call('POST', '/auth/register', { ...input, ...this.appContext }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
-    /** Trades the one-time OAuth code for tokens. */
-    exchange(code, ctx) {
-        return this.call('POST', '/auth/exchange', { code, appSlug: this.appSlug }, { headers: BastionApiClient.clientHeaders(ctx) });
+    /**
+     * Trades the one-time OAuth code for tokens. `state` is the value the app put
+     * on the initiate URL, read back from its own cookie/session (never from the
+     * callback query): Bastion refuses a code minted under a different one, which
+     * is what stops an attacker's code from being redeemed in a victim's browser.
+     */
+    exchange(code, ctx, state) {
+        return this.call('POST', '/auth/exchange', { code, appSlug: this.appSlug, ...(state !== undefined ? { state } : {}) }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
     completeTwoFactor(twoFactorToken, code, ctx) {
         return this.call('POST', '/auth/2fa/authenticate', { twoFactorToken, code }, { headers: BastionApiClient.clientHeaders(ctx) });
@@ -162,8 +167,9 @@ class BastionApiClient {
      * 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 });
+    /** Step-up: `currentPassword` when the account has one, `twoFactorCode` when 2FA is on. */
+    completeSocialAccountLink(accessToken, code, stepUp = {}) {
+        return this.call('POST', '/auth/me/social-accounts/link/complete', { code, ...stepUp }, { token: accessToken });
     }
     unlinkSocialAccount(accessToken, provider) {
         return this.call('DELETE', `/auth/me/social-accounts/${encodeURIComponent(provider)}`, undefined, { token: accessToken });

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

@@ -25,6 +25,13 @@ export interface VerifyWebhookOptions {
     headers: Record<string, string | string[] | undefined>;
     /** Your webhook secret, plus the previous one during a rotation. */
     secrets: string | string[];
+    /**
+     * Accept the legacy body-only `X-Bastion-Signature` when v2 is absent.
+     * Default `false`: legacy carries no timestamp or delivery id, so accepting
+     * it lets anyone holding an old delivery replay it by stripping the v2
+     * header. Opt in only while migrating a consumer that cannot see v2 yet.
+     */
+    allowLegacySignature?: boolean;
     /** Max age of `t` on a v2 signature, default 300 s. */
     toleranceSeconds?: number;
     /** For tests. */
@@ -46,9 +53,9 @@ export type VerifyWebhookResult = {
  * 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:
+ * delivery is rejected without trusting any unsigned header. The legacy
+ * `X-Bastion-Signature: sha256=<hex>` over the body alone is accepted only
+ * when v2 is absent **and** `allowLegacySignature` is set. 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

@@ -27,9 +27,9 @@ function macEquals(hexA, hexB) {
  * 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:
+ * delivery is rejected without trusting any unsigned header. The legacy
+ * `X-Bastion-Signature: sha256=<hex>` over the body alone is accepted only
+ * when v2 is absent **and** `allowLegacySignature` is set. 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) {
@@ -57,6 +57,8 @@ function verifyWebhookSignature(options) {
         }
         return { ok: false, reason: 'mismatch' };
     }
+    if (!options.allowLegacySignature)
+        return { ok: false, reason: 'missing' };
     const legacy = header(options.headers, exports.BASTION_SIGNATURE_HEADER);
     if (!legacy)
         return { ok: false, reason: 'missing' };

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

@@ -50,8 +50,13 @@ export declare class BastionApiClient {
     register(input: BastionRegisterInput, ctx?: BastionClientContext): Promise<{
         message: string;
     }>;
-    /** Trades the one-time OAuth code for tokens. */
-    exchange(code: string, ctx?: BastionClientContext): Promise<BastionLoginResult>;
+    /**
+     * Trades the one-time OAuth code for tokens. `state` is the value the app put
+     * on the initiate URL, read back from its own cookie/session (never from the
+     * callback query): Bastion refuses a code minted under a different one, which
+     * is what stops an attacker's code from being redeemed in a victim's browser.
+     */
+    exchange(code: string, ctx?: BastionClientContext, state?: string): 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` within the memory window. Never throws. */
@@ -81,7 +86,11 @@ export declare class BastionApiClient {
      * 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>;
+    /** Step-up: `currentPassword` when the account has one, `twoFactorCode` when 2FA is on. */
+    completeSocialAccountLink(accessToken: string, code: string, stepUp?: {
+        currentPassword?: string;
+        twoFactorCode?: string;
+    }): Promise<BastionLinkCompleted>;
     unlinkSocialAccount(accessToken: string, provider: string): Promise<void>;
     updateSocialAccountSyncAvatar(accessToken: string, provider: string, syncAvatar: boolean): Promise<BastionSocialAccount>;
     resendVerification(email: string, ctx?: BastionClientContext): Promise<void>;

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

@@ -58,9 +58,14 @@ export class BastionApiClient {
     register(input, ctx) {
         return this.call('POST', '/auth/register', { ...input, ...this.appContext }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
-    /** Trades the one-time OAuth code for tokens. */
-    exchange(code, ctx) {
-        return this.call('POST', '/auth/exchange', { code, appSlug: this.appSlug }, { headers: BastionApiClient.clientHeaders(ctx) });
+    /**
+     * Trades the one-time OAuth code for tokens. `state` is the value the app put
+     * on the initiate URL, read back from its own cookie/session (never from the
+     * callback query): Bastion refuses a code minted under a different one, which
+     * is what stops an attacker's code from being redeemed in a victim's browser.
+     */
+    exchange(code, ctx, state) {
+        return this.call('POST', '/auth/exchange', { code, appSlug: this.appSlug, ...(state !== undefined ? { state } : {}) }, { headers: BastionApiClient.clientHeaders(ctx) });
     }
     completeTwoFactor(twoFactorToken, code, ctx) {
         return this.call('POST', '/auth/2fa/authenticate', { twoFactorToken, code }, { headers: BastionApiClient.clientHeaders(ctx) });
@@ -159,8 +164,9 @@ export class BastionApiClient {
      * 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 });
+    /** Step-up: `currentPassword` when the account has one, `twoFactorCode` when 2FA is on. */
+    completeSocialAccountLink(accessToken, code, stepUp = {}) {
+        return this.call('POST', '/auth/me/social-accounts/link/complete', { code, ...stepUp }, { token: accessToken });
     }
     unlinkSocialAccount(accessToken, provider) {
         return this.call('DELETE', `/auth/me/social-accounts/${encodeURIComponent(provider)}`, undefined, { token: accessToken });

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

@@ -25,6 +25,13 @@ export interface VerifyWebhookOptions {
     headers: Record<string, string | string[] | undefined>;
     /** Your webhook secret, plus the previous one during a rotation. */
     secrets: string | string[];
+    /**
+     * Accept the legacy body-only `X-Bastion-Signature` when v2 is absent.
+     * Default `false`: legacy carries no timestamp or delivery id, so accepting
+     * it lets anyone holding an old delivery replay it by stripping the v2
+     * header. Opt in only while migrating a consumer that cannot see v2 yet.
+     */
+    allowLegacySignature?: boolean;
     /** Max age of `t` on a v2 signature, default 300 s. */
     toleranceSeconds?: number;
     /** For tests. */
@@ -46,9 +53,9 @@ export type VerifyWebhookResult = {
  * 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:
+ * delivery is rejected without trusting any unsigned header. The legacy
+ * `X-Bastion-Signature: sha256=<hex>` over the body alone is accepted only
+ * when v2 is absent **and** `allowLegacySignature` is set. 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/esm/webhooks/index.js

@@ -23,9 +23,9 @@ function macEquals(hexA, hexB) {
  * 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:
+ * delivery is rejected without trusting any unsigned header. The legacy
+ * `X-Bastion-Signature: sha256=<hex>` over the body alone is accepted only
+ * when v2 is absent **and** `allowLegacySignature` is set. Any of the caller's `secrets` matching any `v1=` accepts:
  * that is how a secret rotation stays zero-downtime on both sides.
  */
 export function verifyWebhookSignature(options) {
@@ -53,6 +53,8 @@ export function verifyWebhookSignature(options) {
         }
         return { ok: false, reason: 'mismatch' };
     }
+    if (!options.allowLegacySignature)
+        return { ok: false, reason: 'missing' };
     const legacy = header(options.headers, BASTION_SIGNATURE_HEADER);
     if (!legacy)
         return { ok: false, reason: 'missing' };

package/package.json

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