@heyatom/bastion-client 0.8.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 1.0.0
+
+Reads both the current Bastion answers and the `{ data }` envelope Bastion 2.0 will send, so you can upgrade before Bastion does.
+
+### Breaking
+
+- `BastionHttp.call` (and so every `BastionApiClient`, `BastionService.call`, `ServiceTokenProvider` and `BastionHttpException` call) unwraps a success body whose only key is `data` and returns `data`. A page (`{ data, meta }`), an array, any other object and an empty body are returned unchanged. Three Bastion routes answer `{ data }` alone today (`GET /auth/me/tenants`, `GET /admin/apps/:slug/permissions`, `PUT /admin/apps/:slug/roles/:roleId/permissions`): through `call` they now give you the inner array. Read them as `Array.isArray(res) ? res : res.data`, which also works with any later Bastion.
+- `listMyEvents` returns `{ data, meta: { total, page, limit, totalPages } }` (new type `BastionPageMeta`). An older Bastion's `{ data, total, page, limit }` is converted to this shape.
+- `err.code` is the domain code for `PROVIDER_TAKEN`, `ALREADY_LINKED`, `OAUTH_EMAIL_TAKEN`, `AGE_ALREADY_VERIFIED` (previously `CONFLICT`), `AGE_GATE_NOT_CONFIGURED`, `CURRENT_PASSWORD_REQUIRED`, `TWO_FACTOR_CODE_REQUIRED`, `OAUTH_USER_INACTIVE`, `OAUTH_UNDER_MINIMUM_AGE` (previously `UPSTREAM`). `BastionHttpException` forwards that code to your client instead of `CONFLICT` / `BAD_REQUEST` / `FORBIDDEN`. When Bastion sends these codes in `code`, `upstreamCode` is no longer set for them.
+
+### Added
+
+- The error codes above in `BastionErrorCode`.
+- Bastion's `code` is used whenever it is a `BastionErrorCode` and `message` is not itself one, so the code survives a reworded `message`. Message-based classification stays as the fallback for a Bastion that sends no domain `code`.
+
+## 0.9.0
+
+### Added
+
+- `verifyWebhookSignature` verifies [Standard Webhooks](https://www.standardwebhooks.com/) headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`: space-separated `v1,<base64 HMAC-SHA256("<id>.<timestamp>.<body>")>`, secret used as UTF-8). When any of them is present they are the ones checked: same tolerance, any secret against any `v1` entry, `deliveryId` = `webhook-id`, result `version: 'standard'`.
+- Header name constants `WEBHOOK_ID_HEADER`, `WEBHOOK_TIMESTAMP_HEADER`, `WEBHOOK_SIGNATURE_HEADER`.
+
+### Changed
+
+- Without Standard Webhooks headers, `X-Bastion-Signature-V2` is verified exactly as before, so receivers keep working against an older Bastion. Bastion sends both for one release and will then drop V2. `allowLegacySignature` is unchanged.
+- Whitespace-only entries in `secrets` (e.g. `' '` from an unset env var) are ignored instead of keying the HMAC; if none is left the result is `{ ok: false, reason: 'missing' }`. Other secrets are still used byte-exact (not trimmed).
+
+### Breaking (types)
+
+- `VerifyWebhookResult` gains the `version: 'standard'` variant: an exhaustive `switch` on `version` needs the new case.
+
+## 0.8.1
+
+### Added
+
+- Error code `STEP_UP_FAILED`: the 401 Bastion answers when the current password or 2FA code of a step-up protected route is wrong (or the step-up counter is locked). Tells a wrong factor apart from a dead session, also a 401 (`INVALID_CREDENTIALS`). Needs a Bastion that sends `code: 'STEP_UP_FAILED'`; an older one still classifies as `INVALID_CREDENTIALS`.
+
 ## 0.8.0
 
 ### Breaking

package/README.md

@@ -1,3 +1,14 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/heyatomdev/bastion-client/main/docs/brand/banner.png" width="500" alt="HeyAtom @heyatom/bastion-client" />
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@heyatom/bastion-client"><img src="https://img.shields.io/npm/v/@heyatom/bastion-client" alt="npm version" /></a>
+  <a href="https://github.com/heyatomdev/bastion-client/actions/workflows/test.yml"><img src="https://github.com/heyatomdev/bastion-client/actions/workflows/test.yml/badge.svg?branch=main" alt="Test" /></a>
+  <img src="https://img.shields.io/node/v/@heyatom/bastion-client" alt="Node version" />
+  <img src="https://img.shields.io/npm/l/@heyatom/bastion-client" alt="License" />
+</p>
+
 # @heyatom/bastion-client
 
 Client SDK for [Bastion](https://github.com/heyatomdev/bastion), the HeyAtom identity provider.
@@ -136,6 +147,11 @@ export class AuthController {
   from one browser must collapse into one call. Use one client instance per process.
 - `logout` revokes the latest token in the rotation chain and never throws.
 
+## Responses
+
+Calls return Bastion's body. A body whose only key is `data` is unwrapped, so the same code reads
+Bastion with and without the `{ data }` envelope; pages keep their `{ data, meta }` shape.
+
 ## Errors
 
 Every failed call throws `BastionHttpError` (core) or `BastionHttpException` (Nest) with a stable
@@ -143,9 +159,12 @@ Every failed call throws `BastionHttpError` (core) or `BastionHttpException` (Ne
 
 `INVALID_CREDENTIALS`, `EMAIL_NOT_VERIFIED`, `NO_APP_ACCESS`, `ACCOUNT_INACTIVE`,
 `INVALID_APP_CONTEXT` (your configuration, not the user), `INVALID_REFRESH_TOKEN`,
-`INVALID_OAUTH_CODE`, `VALIDATION_FAILED`, `CONFLICT`, `RATE_LIMITED`, the age-gate codes
-(`BIRTH_DATE_REQUIRED`, `BIRTH_DATE_INVALID`, `UNDER_MINIMUM_AGE`), the OAuth flow codes
-(`OAUTH_*`), `UNAVAILABLE` (Bastion unreachable or timed out) and `UPSTREAM`.
+`INVALID_OAUTH_CODE`, `VALIDATION_FAILED`, `STEP_UP_FAILED` (wrong current password or 2FA
+code on a step-up route: the session is fine), `CURRENT_PASSWORD_REQUIRED` and
+`TWO_FACTOR_CODE_REQUIRED` (a step-up field is missing: ask for it), `CONFLICT`,
+`PROVIDER_TAKEN`, `ALREADY_LINKED`, `RATE_LIMITED`, the age-gate codes (`BIRTH_DATE_REQUIRED`,
+`BIRTH_DATE_INVALID`, `UNDER_MINIMUM_AGE`, `AGE_ALREADY_VERIFIED`, `AGE_GATE_NOT_CONFIGURED`),
+the OAuth codes (`OAUTH_*`), `UNAVAILABLE` (Bastion unreachable or timed out) and `UPSTREAM`.
 
 - A 400 carries the field errors in `errors: string[]`. Show them: `message` is only
   "Validation failed".
@@ -206,8 +225,12 @@ if (!result.ok) throw new UnauthorizedException(result.reason);
 // result.deliveryId: store it and ignore repeats
 ```
 
-Checks `X-Bastion-Signature-V2` (timestamp + delivery id + body, 5 min tolerance). Leave
-`allowLegacySignature` off.
+Checks [Standard Webhooks](https://www.standardwebhooks.com/) headers (`webhook-id`,
+`webhook-timestamp`, `webhook-signature`) when present: HMAC-SHA256 over id + timestamp + body,
+5 min tolerance, secret used as a UTF-8 string, `result.deliveryId` = `webhook-id`. Without them
+it falls back to `X-Bastion-Signature-V2` (same guarantees), so it works against an older Bastion
+too; Bastion will stop sending V2 in a later release. `result.version` says which one matched.
+Leave `allowLegacySignature` off.
 
 ## Changelog
 

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

@@ -225,14 +225,20 @@ class BastionApiClient {
     }
     // ── GDPR ─────────────────────────────────────────────────────────────────
     /** The user's own audit trail (`GET /auth/me/events`), paginated. */
-    listMyEvents(accessToken, page = {}) {
+    async listMyEvents(accessToken, page = {}) {
         const params = new URLSearchParams();
         if (page.page !== undefined)
             params.set('page', String(page.page));
         if (page.limit !== undefined)
             params.set('limit', String(page.limit));
         const qs = params.toString();
-        return this.call('GET', `/auth/me/events${qs ? `?${qs}` : ''}`, undefined, { token: accessToken });
+        const res = await this.call('GET', `/auth/me/events${qs ? `?${qs}` : ''}`, undefined, { token: accessToken });
+        // No body (a proxy in between): nothing to normalise, same as every other method.
+        if (!res || typeof res !== 'object' || 'meta' in res)
+            return res;
+        // Bastion before 2.0: the page fields sit next to `data`.
+        const { data, total, page: current, limit } = res;
+        return { data, meta: { total, page: current, limit, totalPages: limit > 0 ? Math.ceil(total / limit) : 0 } };
     }
     exportData(accessToken) {
         return this.call('GET', '/auth/me/export', undefined, { token: accessToken });

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

@@ -136,9 +136,13 @@ export interface BastionUserAuditEvent {
     metadata: unknown;
     createdAt: string;
 }
-export interface BastionUserAuditEventsPage {
-    data: BastionUserAuditEvent[];
+export interface BastionPageMeta {
     total: number;
     page: number;
     limit: number;
+    totalPages: number;
+}
+export interface BastionUserAuditEventsPage {
+    data: BastionUserAuditEvent[];
+    meta: BastionPageMeta;
 }

package/dist/cjs/core/bastion-http.d.ts

@@ -11,6 +11,12 @@ export interface BastionHttpOptions {
      */
     requestId?: () => string | undefined;
 }
+/**
+ * Bastion answers `{ data }` (or `{ data, meta }` for a page) from 2.0; earlier builds answer the
+ * bare body. An object whose only key is `data` gives back `data`; a page, an array, a bare body
+ * or no body passes through unchanged, so every caller reads the same shape from both.
+ */
+export declare function unwrapData(body: unknown): unknown;
 export interface BastionRequestInit {
     token?: string;
     headers?: Record<string, string>;
@@ -24,9 +30,10 @@ export interface ClientAuthInput {
 /**
  * Outbound calls to Bastion. Nothing here verifies inbound tokens — that is
  * `JwksVerifier`. `call` is public so a service can reach any route with the
- * same error handling: a non-2xx answer becomes `BastionHttpError` with the
- * status and a stable `code`; Bastion unreachable or timed out is a 503
- * `UNAVAILABLE`. Pass the browser's IP as `X-Real-IP` on user-facing calls.
+ * same error handling and the same success shape (`unwrapData`): a non-2xx
+ * answer becomes `BastionHttpError` with the status and a stable `code`;
+ * Bastion unreachable or timed out is a 503 `UNAVAILABLE`. Pass the browser's
+ * IP as `X-Real-IP` on user-facing calls.
  */
 export declare class BastionHttp {
     private readonly baseUrl;

package/dist/cjs/core/bastion-http.js

@@ -1,14 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BastionHttp = void 0;
+exports.unwrapData = unwrapData;
 const errors_js_1 = require("./errors.js");
 const REQUEST_ID_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+/**
+ * Bastion answers `{ data }` (or `{ data, meta }` for a page) from 2.0; earlier builds answer the
+ * bare body. An object whose only key is `data` gives back `data`; a page, an array, a bare body
+ * or no body passes through unchanged, so every caller reads the same shape from both.
+ */
+function unwrapData(body) {
+    if (body && typeof body === 'object' && !Array.isArray(body)) {
+        const keys = Object.keys(body);
+        if (keys.length === 1 && keys[0] === 'data')
+            return body.data;
+    }
+    return body;
+}
 /**
  * Outbound calls to Bastion. Nothing here verifies inbound tokens — that is
  * `JwksVerifier`. `call` is public so a service can reach any route with the
- * same error handling: a non-2xx answer becomes `BastionHttpError` with the
- * status and a stable `code`; Bastion unreachable or timed out is a 503
- * `UNAVAILABLE`. Pass the browser's IP as `X-Real-IP` on user-facing calls.
+ * same error handling and the same success shape (`unwrapData`): a non-2xx
+ * answer becomes `BastionHttpError` with the status and a stable `code`;
+ * Bastion unreachable or timed out is a 503 `UNAVAILABLE`. Pass the browser's
+ * IP as `X-Real-IP` on user-facing calls.
  */
 class BastionHttp {
     baseUrl;
@@ -57,7 +72,9 @@ class BastionHttp {
                 : typeof parsed.message === 'string'
                     ? parsed.message
                     : `Bastion error ${res.status}`;
-            // A code Bastion still puts in `message` (UNDER_MINIMUM_AGE under `code: FORBIDDEN`) wins: classify reads it.
+            // A code in `message` wins: an older Bastion sends it under a generic `code` that is also one
+            // of ours (ALREADY_LINKED under `code: CONFLICT`); classify reads it. Otherwise Bastion's
+            // `code` wins when it is one of ours, so a cleaned-up `message` still carries its code.
             const code = (0, errors_js_1.isBastionErrorCode)(message)
                 ? undefined
                 : (0, errors_js_1.isBastionErrorCode)(parsed.code)
@@ -70,7 +87,7 @@ class BastionHttp {
         }
         if (res.status === 204)
             return undefined;
-        return (await res.json().catch(() => undefined));
+        return unwrapData(await res.json().catch(() => undefined));
     }
     clientAuth(input) {
         return this.call('POST', '/auth/client', input);

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

@@ -6,9 +6,9 @@ export declare class BastionTokenError extends Error {
 }
 /**
  * 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.
+ * code instead of on Bastion's message text. Bastion's own `code` is used when
+ * it is one of these; for an older Bastion that sends none, the code is derived
+ * from status + message (`classifyBastionError`).
  */
 export declare const BastionErrorCode: {
     readonly EMAIL_NOT_VERIFIED: "EMAIL_NOT_VERIFIED";
@@ -23,6 +23,8 @@ export declare const BastionErrorCode: {
     readonly INVALID_OAUTH_CODE: "INVALID_OAUTH_CODE";
     /** A 400 carrying field errors (`BastionHttpError.errors`): Bastion's `ValidationPipe`. */
     readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    /** A 401 from a step-up protected route (password change, email change, 2FA setup/confirm/disable, account delete): the current password or 2FA code is wrong, or the step-up counter is locked. The session is fine — do not log the user out. Bastion sends it as `code`; an older Bastion sends a plain 401, classified `INVALID_CREDENTIALS`. */
+    readonly STEP_UP_FAILED: "STEP_UP_FAILED";
     readonly CONFLICT: "CONFLICT";
     readonly RATE_LIMITED: "RATE_LIMITED";
     readonly BIRTH_DATE_REQUIRED: "BIRTH_DATE_REQUIRED";
@@ -34,6 +36,20 @@ export declare const BastionErrorCode: {
     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";
+    /** OAuth signup with an email that a verified account of the tenant already owns. */
+    readonly OAUTH_EMAIL_TAKEN: "OAUTH_EMAIL_TAKEN";
+    readonly OAUTH_USER_INACTIVE: "OAUTH_USER_INACTIVE";
+    readonly OAUTH_UNDER_MINIMUM_AGE: "OAUTH_UNDER_MINIMUM_AGE";
+    /** Linking a provider account that belongs to another user. */
+    readonly PROVIDER_TAKEN: "PROVIDER_TAKEN";
+    /** The user already has an account of this provider linked. */
+    readonly ALREADY_LINKED: "ALREADY_LINKED";
+    readonly AGE_ALREADY_VERIFIED: "AGE_ALREADY_VERIFIED";
+    readonly AGE_GATE_NOT_CONFIGURED: "AGE_GATE_NOT_CONFIGURED";
+    /** A step-up route was called without `currentPassword`. Ask for it; the session is fine. */
+    readonly CURRENT_PASSWORD_REQUIRED: "CURRENT_PASSWORD_REQUIRED";
+    /** A step-up route was called without `twoFactorCode`. Ask for it; the session is fine. */
+    readonly TWO_FACTOR_CODE_REQUIRED: "TWO_FACTOR_CODE_REQUIRED";
     readonly UNAVAILABLE: "UNAVAILABLE";
     readonly UPSTREAM: "UPSTREAM";
 };

package/dist/cjs/core/errors.js

@@ -15,9 +15,9 @@ class BastionTokenError extends Error {
 exports.BastionTokenError = BastionTokenError;
 /**
  * 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.
+ * code instead of on Bastion's message text. Bastion's own `code` is used when
+ * it is one of these; for an older Bastion that sends none, the code is derived
+ * from status + message (`classifyBastionError`).
  */
 exports.BastionErrorCode = {
     EMAIL_NOT_VERIFIED: 'EMAIL_NOT_VERIFIED',
@@ -32,6 +32,8 @@ exports.BastionErrorCode = {
     INVALID_OAUTH_CODE: 'INVALID_OAUTH_CODE',
     /** A 400 carrying field errors (`BastionHttpError.errors`): Bastion's `ValidationPipe`. */
     VALIDATION_FAILED: 'VALIDATION_FAILED',
+    /** A 401 from a step-up protected route (password change, email change, 2FA setup/confirm/disable, account delete): the current password or 2FA code is wrong, or the step-up counter is locked. The session is fine — do not log the user out. Bastion sends it as `code`; an older Bastion sends a plain 401, classified `INVALID_CREDENTIALS`. */
+    STEP_UP_FAILED: 'STEP_UP_FAILED',
     CONFLICT: 'CONFLICT',
     RATE_LIMITED: 'RATE_LIMITED',
     BIRTH_DATE_REQUIRED: 'BIRTH_DATE_REQUIRED',
@@ -43,6 +45,20 @@ exports.BastionErrorCode = {
     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',
+    /** OAuth signup with an email that a verified account of the tenant already owns. */
+    OAUTH_EMAIL_TAKEN: 'OAUTH_EMAIL_TAKEN',
+    OAUTH_USER_INACTIVE: 'OAUTH_USER_INACTIVE',
+    OAUTH_UNDER_MINIMUM_AGE: 'OAUTH_UNDER_MINIMUM_AGE',
+    /** Linking a provider account that belongs to another user. */
+    PROVIDER_TAKEN: 'PROVIDER_TAKEN',
+    /** The user already has an account of this provider linked. */
+    ALREADY_LINKED: 'ALREADY_LINKED',
+    AGE_ALREADY_VERIFIED: 'AGE_ALREADY_VERIFIED',
+    AGE_GATE_NOT_CONFIGURED: 'AGE_GATE_NOT_CONFIGURED',
+    /** A step-up route was called without `currentPassword`. Ask for it; the session is fine. */
+    CURRENT_PASSWORD_REQUIRED: 'CURRENT_PASSWORD_REQUIRED',
+    /** A step-up route was called without `twoFactorCode`. Ask for it; the session is fine. */
+    TWO_FACTOR_CODE_REQUIRED: 'TWO_FACTOR_CODE_REQUIRED',
     UNAVAILABLE: 'UNAVAILABLE',
     UPSTREAM: 'UPSTREAM',
 };
@@ -56,6 +72,15 @@ const CODE_MESSAGES = new Set([
     exports.BastionErrorCode.OAUTH_EMAIL_REQUIRED,
     exports.BastionErrorCode.OAUTH_NO_ACCOUNT,
     exports.BastionErrorCode.OAUTH_LINK_USER_MISMATCH,
+    exports.BastionErrorCode.OAUTH_EMAIL_TAKEN,
+    exports.BastionErrorCode.OAUTH_USER_INACTIVE,
+    exports.BastionErrorCode.OAUTH_UNDER_MINIMUM_AGE,
+    exports.BastionErrorCode.PROVIDER_TAKEN,
+    exports.BastionErrorCode.ALREADY_LINKED,
+    exports.BastionErrorCode.AGE_ALREADY_VERIFIED,
+    exports.BastionErrorCode.AGE_GATE_NOT_CONFIGURED,
+    exports.BastionErrorCode.CURRENT_PASSWORD_REQUIRED,
+    exports.BastionErrorCode.TWO_FACTOR_CODE_REQUIRED,
 ]);
 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;

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

@@ -3,6 +3,10 @@ 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";
+/** Standard Webhooks (standardwebhooks.com) headers, sent alongside v2 during the migration. */
+export declare const WEBHOOK_ID_HEADER = "webhook-id";
+export declare const WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+export declare const WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
 /** 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 {
@@ -33,12 +37,17 @@ export interface VerifyWebhookOptions {
      * left to migrate: leave it off.
      */
     allowLegacySignature?: boolean;
-    /** Max age of `t` on a v2 signature, default 300 s. */
+    /** Max distance of the signed timestamp from now (Standard Webhooks and v2), default 300 s. */
     toleranceSeconds?: number;
     /** For tests. */
     now?: () => number;
 }
 export type VerifyWebhookResult = {
+    ok: true;
+    version: 'standard';
+    timestamp: number;
+    deliveryId: string;
+} | {
     ok: true;
     version: 'v2';
     timestamp: number;
@@ -51,12 +60,17 @@ export type VerifyWebhookResult = {
     reason: 'missing' | 'malformed' | 'stale' | 'mismatch';
 };
 /**
- * Verifies a Bastion delivery. Prefers `X-Bastion-Signature-V2`
+ * Verifies a Bastion delivery. Prefers Standard Webhooks when any of `webhook-id`,
+ * `webhook-timestamp`, `webhook-signature` is present: `webhook-signature` is a
+ * space-separated list of `v1,<base64 HMAC-SHA256(secret, "<id>.<timestamp>.<body>")>`,
+ * keyed with the secret as UTF-8 (not a `whsec_` base64 key); `deliveryId` is `webhook-id`.
+ * Otherwise falls back to `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. 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:
+ * when both of the above are absent **and** `allowLegacySignature` is set. Any of the caller's
+ * `secrets` matching any `v1` entry 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

@@ -1,6 +1,6 @@
 "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.BASTION_LIFECYCLE_EVENTS = exports.WEBHOOK_SIGNATURE_HEADER = exports.WEBHOOK_TIMESTAMP_HEADER = exports.WEBHOOK_ID_HEADER = 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. */
@@ -8,14 +8,18 @@ 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';
+/** Standard Webhooks (standardwebhooks.com) headers, sent alongside v2 during the migration. */
+exports.WEBHOOK_ID_HEADER = 'webhook-id';
+exports.WEBHOOK_TIMESTAMP_HEADER = 'webhook-timestamp';
+exports.WEBHOOK_SIGNATURE_HEADER = 'webhook-signature';
 /** 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;
+    let v = headers[name];
+    if (v === undefined) {
+        const key = Object.keys(headers).find((k) => k.toLowerCase() === name);
+        v = key === undefined ? undefined : headers[key];
+    }
     return Array.isArray(v) ? v[0] : v;
 }
 function macEquals(hexA, hexB) {
@@ -23,20 +27,54 @@ function macEquals(hexA, hexB) {
     const b = Buffer.from(hexB, 'hex');
     return a.length === b.length && a.length > 0 && (0, node_crypto_1.timingSafeEqual)(a, b);
 }
+function isFresh(timestamp, options) {
+    const now = Math.floor((options.now ?? Date.now)() / 1000);
+    return Math.abs(now - timestamp) <= (options.toleranceSeconds ?? 300);
+}
 /**
- * Verifies a Bastion delivery. Prefers `X-Bastion-Signature-V2`
+ * Verifies a Bastion delivery. Prefers Standard Webhooks when any of `webhook-id`,
+ * `webhook-timestamp`, `webhook-signature` is present: `webhook-signature` is a
+ * space-separated list of `v1,<base64 HMAC-SHA256(secret, "<id>.<timestamp>.<body>")>`,
+ * keyed with the secret as UTF-8 (not a `whsec_` base64 key); `deliveryId` is `webhook-id`.
+ * Otherwise falls back to `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. 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:
+ * when both of the above are absent **and** `allowLegacySignature` is set. Any of the caller's
+ * `secrets` matching any `v1` entry 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);
+    const secrets = (Array.isArray(options.secrets) ? options.secrets : [options.secrets]).filter(
+    // A whitespace-only secret is a misconfiguration, never a key; the rest are used byte-exact.
+    (s) => typeof s === 'string' && s.trim() !== '');
     if (secrets.length === 0)
         return { ok: false, reason: 'missing' };
+    const stdId = header(options.headers, exports.WEBHOOK_ID_HEADER);
+    const stdTs = header(options.headers, exports.WEBHOOK_TIMESTAMP_HEADER);
+    const stdSig = header(options.headers, exports.WEBHOOK_SIGNATURE_HEADER);
+    if (stdId || stdTs || stdSig) {
+        const macs = (stdSig ?? '')
+            .split(' ')
+            .map((entry) => entry.split(','))
+            .filter(([version, value]) => version === 'v1' && value)
+            .map(([, value]) => Buffer.from(value, 'base64'));
+        if (!stdId || !stdTs || !/^\d+$/.test(stdTs) || macs.length === 0)
+            return { ok: false, reason: 'malformed' };
+        const timestamp = Number(stdTs);
+        if (!isFresh(timestamp, options))
+            return { ok: false, reason: 'stale' };
+        const signed = Buffer.concat([Buffer.from(`${stdId}.${stdTs}.`, 'utf8'), body]);
+        for (const secret of secrets) {
+            const expected = (0, node_crypto_1.createHmac)('sha256', secret).update(signed).digest();
+            if (macs.some((mac) => mac.length === expected.length && (0, node_crypto_1.timingSafeEqual)(mac, expected))) {
+                return { ok: true, version: 'standard', timestamp, deliveryId: stdId };
+            }
+        }
+        return { ok: false, reason: 'mismatch' };
+    }
     const v2 = header(options.headers, exports.BASTION_SIGNATURE_V2_HEADER);
     if (v2) {
         const parts = v2.split(',').map((p) => p.trim());
@@ -46,8 +84,7 @@ function verifyWebhookSignature(options) {
         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))
+        if (!isFresh(timestamp, options))
             return { ok: false, reason: 'stale' };
         const signed = Buffer.concat([Buffer.from(`${timestamp}.${id}.`, 'utf8'), body]);
         for (const secret of secrets) {

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

@@ -222,14 +222,20 @@ export class BastionApiClient {
     }
     // ── GDPR ─────────────────────────────────────────────────────────────────
     /** The user's own audit trail (`GET /auth/me/events`), paginated. */
-    listMyEvents(accessToken, page = {}) {
+    async listMyEvents(accessToken, page = {}) {
         const params = new URLSearchParams();
         if (page.page !== undefined)
             params.set('page', String(page.page));
         if (page.limit !== undefined)
             params.set('limit', String(page.limit));
         const qs = params.toString();
-        return this.call('GET', `/auth/me/events${qs ? `?${qs}` : ''}`, undefined, { token: accessToken });
+        const res = await this.call('GET', `/auth/me/events${qs ? `?${qs}` : ''}`, undefined, { token: accessToken });
+        // No body (a proxy in between): nothing to normalise, same as every other method.
+        if (!res || typeof res !== 'object' || 'meta' in res)
+            return res;
+        // Bastion before 2.0: the page fields sit next to `data`.
+        const { data, total, page: current, limit } = res;
+        return { data, meta: { total, page: current, limit, totalPages: limit > 0 ? Math.ceil(total / limit) : 0 } };
     }
     exportData(accessToken) {
         return this.call('GET', '/auth/me/export', undefined, { token: accessToken });

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

@@ -136,9 +136,13 @@ export interface BastionUserAuditEvent {
     metadata: unknown;
     createdAt: string;
 }
-export interface BastionUserAuditEventsPage {
-    data: BastionUserAuditEvent[];
+export interface BastionPageMeta {
     total: number;
     page: number;
     limit: number;
+    totalPages: number;
+}
+export interface BastionUserAuditEventsPage {
+    data: BastionUserAuditEvent[];
+    meta: BastionPageMeta;
 }

package/dist/esm/core/bastion-http.d.ts

@@ -11,6 +11,12 @@ export interface BastionHttpOptions {
      */
     requestId?: () => string | undefined;
 }
+/**
+ * Bastion answers `{ data }` (or `{ data, meta }` for a page) from 2.0; earlier builds answer the
+ * bare body. An object whose only key is `data` gives back `data`; a page, an array, a bare body
+ * or no body passes through unchanged, so every caller reads the same shape from both.
+ */
+export declare function unwrapData(body: unknown): unknown;
 export interface BastionRequestInit {
     token?: string;
     headers?: Record<string, string>;
@@ -24,9 +30,10 @@ export interface ClientAuthInput {
 /**
  * Outbound calls to Bastion. Nothing here verifies inbound tokens — that is
  * `JwksVerifier`. `call` is public so a service can reach any route with the
- * same error handling: a non-2xx answer becomes `BastionHttpError` with the
- * status and a stable `code`; Bastion unreachable or timed out is a 503
- * `UNAVAILABLE`. Pass the browser's IP as `X-Real-IP` on user-facing calls.
+ * same error handling and the same success shape (`unwrapData`): a non-2xx
+ * answer becomes `BastionHttpError` with the status and a stable `code`;
+ * Bastion unreachable or timed out is a 503 `UNAVAILABLE`. Pass the browser's
+ * IP as `X-Real-IP` on user-facing calls.
  */
 export declare class BastionHttp {
     private readonly baseUrl;

package/dist/esm/core/bastion-http.js

@@ -1,11 +1,25 @@
 import { BastionErrorCode, BastionHttpError, isBastionErrorCode } from './errors.js';
 const REQUEST_ID_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+/**
+ * Bastion answers `{ data }` (or `{ data, meta }` for a page) from 2.0; earlier builds answer the
+ * bare body. An object whose only key is `data` gives back `data`; a page, an array, a bare body
+ * or no body passes through unchanged, so every caller reads the same shape from both.
+ */
+export function unwrapData(body) {
+    if (body && typeof body === 'object' && !Array.isArray(body)) {
+        const keys = Object.keys(body);
+        if (keys.length === 1 && keys[0] === 'data')
+            return body.data;
+    }
+    return body;
+}
 /**
  * Outbound calls to Bastion. Nothing here verifies inbound tokens — that is
  * `JwksVerifier`. `call` is public so a service can reach any route with the
- * same error handling: a non-2xx answer becomes `BastionHttpError` with the
- * status and a stable `code`; Bastion unreachable or timed out is a 503
- * `UNAVAILABLE`. Pass the browser's IP as `X-Real-IP` on user-facing calls.
+ * same error handling and the same success shape (`unwrapData`): a non-2xx
+ * answer becomes `BastionHttpError` with the status and a stable `code`;
+ * Bastion unreachable or timed out is a 503 `UNAVAILABLE`. Pass the browser's
+ * IP as `X-Real-IP` on user-facing calls.
  */
 export class BastionHttp {
     baseUrl;
@@ -54,7 +68,9 @@ export class BastionHttp {
                 : typeof parsed.message === 'string'
                     ? parsed.message
                     : `Bastion error ${res.status}`;
-            // A code Bastion still puts in `message` (UNDER_MINIMUM_AGE under `code: FORBIDDEN`) wins: classify reads it.
+            // A code in `message` wins: an older Bastion sends it under a generic `code` that is also one
+            // of ours (ALREADY_LINKED under `code: CONFLICT`); classify reads it. Otherwise Bastion's
+            // `code` wins when it is one of ours, so a cleaned-up `message` still carries its code.
             const code = isBastionErrorCode(message)
                 ? undefined
                 : isBastionErrorCode(parsed.code)
@@ -67,7 +83,7 @@ export class BastionHttp {
         }
         if (res.status === 204)
             return undefined;
-        return (await res.json().catch(() => undefined));
+        return unwrapData(await res.json().catch(() => undefined));
     }
     clientAuth(input) {
         return this.call('POST', '/auth/client', input);

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

@@ -6,9 +6,9 @@ export declare class BastionTokenError extends Error {
 }
 /**
  * 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.
+ * code instead of on Bastion's message text. Bastion's own `code` is used when
+ * it is one of these; for an older Bastion that sends none, the code is derived
+ * from status + message (`classifyBastionError`).
  */
 export declare const BastionErrorCode: {
     readonly EMAIL_NOT_VERIFIED: "EMAIL_NOT_VERIFIED";
@@ -23,6 +23,8 @@ export declare const BastionErrorCode: {
     readonly INVALID_OAUTH_CODE: "INVALID_OAUTH_CODE";
     /** A 400 carrying field errors (`BastionHttpError.errors`): Bastion's `ValidationPipe`. */
     readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    /** A 401 from a step-up protected route (password change, email change, 2FA setup/confirm/disable, account delete): the current password or 2FA code is wrong, or the step-up counter is locked. The session is fine — do not log the user out. Bastion sends it as `code`; an older Bastion sends a plain 401, classified `INVALID_CREDENTIALS`. */
+    readonly STEP_UP_FAILED: "STEP_UP_FAILED";
     readonly CONFLICT: "CONFLICT";
     readonly RATE_LIMITED: "RATE_LIMITED";
     readonly BIRTH_DATE_REQUIRED: "BIRTH_DATE_REQUIRED";
@@ -34,6 +36,20 @@ export declare const BastionErrorCode: {
     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";
+    /** OAuth signup with an email that a verified account of the tenant already owns. */
+    readonly OAUTH_EMAIL_TAKEN: "OAUTH_EMAIL_TAKEN";
+    readonly OAUTH_USER_INACTIVE: "OAUTH_USER_INACTIVE";
+    readonly OAUTH_UNDER_MINIMUM_AGE: "OAUTH_UNDER_MINIMUM_AGE";
+    /** Linking a provider account that belongs to another user. */
+    readonly PROVIDER_TAKEN: "PROVIDER_TAKEN";
+    /** The user already has an account of this provider linked. */
+    readonly ALREADY_LINKED: "ALREADY_LINKED";
+    readonly AGE_ALREADY_VERIFIED: "AGE_ALREADY_VERIFIED";
+    readonly AGE_GATE_NOT_CONFIGURED: "AGE_GATE_NOT_CONFIGURED";
+    /** A step-up route was called without `currentPassword`. Ask for it; the session is fine. */
+    readonly CURRENT_PASSWORD_REQUIRED: "CURRENT_PASSWORD_REQUIRED";
+    /** A step-up route was called without `twoFactorCode`. Ask for it; the session is fine. */
+    readonly TWO_FACTOR_CODE_REQUIRED: "TWO_FACTOR_CODE_REQUIRED";
     readonly UNAVAILABLE: "UNAVAILABLE";
     readonly UPSTREAM: "UPSTREAM";
 };

package/dist/esm/core/errors.js

@@ -9,9 +9,9 @@ export class BastionTokenError extends Error {
 }
 /**
  * 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.
+ * code instead of on Bastion's message text. Bastion's own `code` is used when
+ * it is one of these; for an older Bastion that sends none, the code is derived
+ * from status + message (`classifyBastionError`).
  */
 export const BastionErrorCode = {
     EMAIL_NOT_VERIFIED: 'EMAIL_NOT_VERIFIED',
@@ -26,6 +26,8 @@ export const BastionErrorCode = {
     INVALID_OAUTH_CODE: 'INVALID_OAUTH_CODE',
     /** A 400 carrying field errors (`BastionHttpError.errors`): Bastion's `ValidationPipe`. */
     VALIDATION_FAILED: 'VALIDATION_FAILED',
+    /** A 401 from a step-up protected route (password change, email change, 2FA setup/confirm/disable, account delete): the current password or 2FA code is wrong, or the step-up counter is locked. The session is fine — do not log the user out. Bastion sends it as `code`; an older Bastion sends a plain 401, classified `INVALID_CREDENTIALS`. */
+    STEP_UP_FAILED: 'STEP_UP_FAILED',
     CONFLICT: 'CONFLICT',
     RATE_LIMITED: 'RATE_LIMITED',
     BIRTH_DATE_REQUIRED: 'BIRTH_DATE_REQUIRED',
@@ -37,6 +39,20 @@ export const BastionErrorCode = {
     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',
+    /** OAuth signup with an email that a verified account of the tenant already owns. */
+    OAUTH_EMAIL_TAKEN: 'OAUTH_EMAIL_TAKEN',
+    OAUTH_USER_INACTIVE: 'OAUTH_USER_INACTIVE',
+    OAUTH_UNDER_MINIMUM_AGE: 'OAUTH_UNDER_MINIMUM_AGE',
+    /** Linking a provider account that belongs to another user. */
+    PROVIDER_TAKEN: 'PROVIDER_TAKEN',
+    /** The user already has an account of this provider linked. */
+    ALREADY_LINKED: 'ALREADY_LINKED',
+    AGE_ALREADY_VERIFIED: 'AGE_ALREADY_VERIFIED',
+    AGE_GATE_NOT_CONFIGURED: 'AGE_GATE_NOT_CONFIGURED',
+    /** A step-up route was called without `currentPassword`. Ask for it; the session is fine. */
+    CURRENT_PASSWORD_REQUIRED: 'CURRENT_PASSWORD_REQUIRED',
+    /** A step-up route was called without `twoFactorCode`. Ask for it; the session is fine. */
+    TWO_FACTOR_CODE_REQUIRED: 'TWO_FACTOR_CODE_REQUIRED',
     UNAVAILABLE: 'UNAVAILABLE',
     UPSTREAM: 'UPSTREAM',
 };
@@ -50,6 +66,15 @@ const CODE_MESSAGES = new Set([
     BastionErrorCode.OAUTH_EMAIL_REQUIRED,
     BastionErrorCode.OAUTH_NO_ACCOUNT,
     BastionErrorCode.OAUTH_LINK_USER_MISMATCH,
+    BastionErrorCode.OAUTH_EMAIL_TAKEN,
+    BastionErrorCode.OAUTH_USER_INACTIVE,
+    BastionErrorCode.OAUTH_UNDER_MINIMUM_AGE,
+    BastionErrorCode.PROVIDER_TAKEN,
+    BastionErrorCode.ALREADY_LINKED,
+    BastionErrorCode.AGE_ALREADY_VERIFIED,
+    BastionErrorCode.AGE_GATE_NOT_CONFIGURED,
+    BastionErrorCode.CURRENT_PASSWORD_REQUIRED,
+    BastionErrorCode.TWO_FACTOR_CODE_REQUIRED,
 ]);
 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;

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

@@ -3,6 +3,10 @@ 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";
+/** Standard Webhooks (standardwebhooks.com) headers, sent alongside v2 during the migration. */
+export declare const WEBHOOK_ID_HEADER = "webhook-id";
+export declare const WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+export declare const WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
 /** 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 {
@@ -33,12 +37,17 @@ export interface VerifyWebhookOptions {
      * left to migrate: leave it off.
      */
     allowLegacySignature?: boolean;
-    /** Max age of `t` on a v2 signature, default 300 s. */
+    /** Max distance of the signed timestamp from now (Standard Webhooks and v2), default 300 s. */
     toleranceSeconds?: number;
     /** For tests. */
     now?: () => number;
 }
 export type VerifyWebhookResult = {
+    ok: true;
+    version: 'standard';
+    timestamp: number;
+    deliveryId: string;
+} | {
     ok: true;
     version: 'v2';
     timestamp: number;
@@ -51,12 +60,17 @@ export type VerifyWebhookResult = {
     reason: 'missing' | 'malformed' | 'stale' | 'mismatch';
 };
 /**
- * Verifies a Bastion delivery. Prefers `X-Bastion-Signature-V2`
+ * Verifies a Bastion delivery. Prefers Standard Webhooks when any of `webhook-id`,
+ * `webhook-timestamp`, `webhook-signature` is present: `webhook-signature` is a
+ * space-separated list of `v1,<base64 HMAC-SHA256(secret, "<id>.<timestamp>.<body>")>`,
+ * keyed with the secret as UTF-8 (not a `whsec_` base64 key); `deliveryId` is `webhook-id`.
+ * Otherwise falls back to `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. 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:
+ * when both of the above are absent **and** `allowLegacySignature` is set. Any of the caller's
+ * `secrets` matching any `v1` entry 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

@@ -4,14 +4,18 @@ export const BASTION_SIGNATURE_HEADER = 'x-bastion-signature';
 export const BASTION_SIGNATURE_V2_HEADER = 'x-bastion-signature-v2';
 export const BASTION_EVENT_HEADER = 'x-bastion-event';
 export const BASTION_DELIVERY_ID_HEADER = 'x-bastion-delivery-id';
+/** Standard Webhooks (standardwebhooks.com) headers, sent alongside v2 during the migration. */
+export const WEBHOOK_ID_HEADER = 'webhook-id';
+export const WEBHOOK_TIMESTAMP_HEADER = 'webhook-timestamp';
+export const WEBHOOK_SIGNATURE_HEADER = 'webhook-signature';
 /** Sent to every app with a webhook URL, whether or not the user has a role in it. */
 export const 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;
+    let v = headers[name];
+    if (v === undefined) {
+        const key = Object.keys(headers).find((k) => k.toLowerCase() === name);
+        v = key === undefined ? undefined : headers[key];
+    }
     return Array.isArray(v) ? v[0] : v;
 }
 function macEquals(hexA, hexB) {
@@ -19,20 +23,54 @@ function macEquals(hexA, hexB) {
     const b = Buffer.from(hexB, 'hex');
     return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
 }
+function isFresh(timestamp, options) {
+    const now = Math.floor((options.now ?? Date.now)() / 1000);
+    return Math.abs(now - timestamp) <= (options.toleranceSeconds ?? 300);
+}
 /**
- * Verifies a Bastion delivery. Prefers `X-Bastion-Signature-V2`
+ * Verifies a Bastion delivery. Prefers Standard Webhooks when any of `webhook-id`,
+ * `webhook-timestamp`, `webhook-signature` is present: `webhook-signature` is a
+ * space-separated list of `v1,<base64 HMAC-SHA256(secret, "<id>.<timestamp>.<body>")>`,
+ * keyed with the secret as UTF-8 (not a `whsec_` base64 key); `deliveryId` is `webhook-id`.
+ * Otherwise falls back to `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. 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:
+ * when both of the above are absent **and** `allowLegacySignature` is set. Any of the caller's
+ * `secrets` matching any `v1` entry accepts:
  * that is how a secret rotation stays zero-downtime on both sides.
  */
 export 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);
+    const secrets = (Array.isArray(options.secrets) ? options.secrets : [options.secrets]).filter(
+    // A whitespace-only secret is a misconfiguration, never a key; the rest are used byte-exact.
+    (s) => typeof s === 'string' && s.trim() !== '');
     if (secrets.length === 0)
         return { ok: false, reason: 'missing' };
+    const stdId = header(options.headers, WEBHOOK_ID_HEADER);
+    const stdTs = header(options.headers, WEBHOOK_TIMESTAMP_HEADER);
+    const stdSig = header(options.headers, WEBHOOK_SIGNATURE_HEADER);
+    if (stdId || stdTs || stdSig) {
+        const macs = (stdSig ?? '')
+            .split(' ')
+            .map((entry) => entry.split(','))
+            .filter(([version, value]) => version === 'v1' && value)
+            .map(([, value]) => Buffer.from(value, 'base64'));
+        if (!stdId || !stdTs || !/^\d+$/.test(stdTs) || macs.length === 0)
+            return { ok: false, reason: 'malformed' };
+        const timestamp = Number(stdTs);
+        if (!isFresh(timestamp, options))
+            return { ok: false, reason: 'stale' };
+        const signed = Buffer.concat([Buffer.from(`${stdId}.${stdTs}.`, 'utf8'), body]);
+        for (const secret of secrets) {
+            const expected = createHmac('sha256', secret).update(signed).digest();
+            if (macs.some((mac) => mac.length === expected.length && timingSafeEqual(mac, expected))) {
+                return { ok: true, version: 'standard', timestamp, deliveryId: stdId };
+            }
+        }
+        return { ok: false, reason: 'mismatch' };
+    }
     const v2 = header(options.headers, BASTION_SIGNATURE_V2_HEADER);
     if (v2) {
         const parts = v2.split(',').map((p) => p.trim());
@@ -42,8 +80,7 @@ export function verifyWebhookSignature(options) {
         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))
+        if (!isFresh(timestamp, options))
             return { ok: false, reason: 'stale' };
         const signed = Buffer.concat([Buffer.from(`${timestamp}.${id}.`, 'utf8'), body]);
         for (const secret of secrets) {

package/package.json

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