@iqauth/sdk 2.6.4 → 2.8.1

package/dist/{types-DZAflmmq.d.ts → types-Bn8O-OEd.d.ts}

@@ -36,7 +36,17 @@ interface IQAuthTokenClientConfig extends IQAuthClientConfigBase {
     apiKey?: string;
     accessToken?: string;
     refreshToken?: string;
-    autoRefresh?: boolean;
+    /**
+     * Token auto-refresh strategy.
+     * - `true` (default): proactively refresh when the access token is within 60s of expiry,
+     *   AND retry once on a TOKEN_EXPIRED 401 response.
+     * - `false`: never auto-refresh — caller drives `tokens.refresh()` manually.
+     * - `'app-state'` (mobile only): skip the per-request expiring-soon proactive refresh
+     *   (which fights with React Native's app-suspension lifecycle) and instead refresh on
+     *   AppState `active` transitions. Reactive 401 retry stays enabled. Recognized only by
+     *   `createMobileClient`; passing it to other constructors falls back to `true`.
+     */
+    autoRefresh?: boolean | "app-state";
     onTokenRefresh?: (tokens: TokenPair) => void;
 }
 interface IQAuthBrowserSessionClientConfig extends IQAuthClientConfigBase {
@@ -75,7 +85,66 @@ interface JwtClaims {
         email?: string;
         name?: string;
     };
+    picture?: string;
+    email_verified?: boolean;
+    given_name?: string;
+    family_name?: string;
+    locale?: string;
 }
+/**
+ * Task #127 — Base claims shape (OIDC standard + IQAuth tenant/role).
+ *
+ * Required fields mirror what the IQAuth issuer always emits today; if a
+ * token is missing one of them it would fail `tokens.verify()` against the
+ * expected issuer/audience first, so this type trades runtime checks for
+ * compile-time ergonomics.
+ */
+interface IQAuthBaseClaims {
+    /** Subject — opaque IQAuth user id. */
+    sub: string;
+    /** OIDC issuer URL (e.g. `https://auth.dispositioniq.com`). */
+    iss: string;
+    /** Audience(s) the token was minted for. */
+    aud: string | string[];
+    /** Expiry in seconds since epoch. */
+    exp: number;
+    /** Issued-at in seconds since epoch. */
+    iat: number;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    picture?: string;
+    locale?: string;
+    tenantId?: string;
+    tenantName?: string;
+    tenantSlug?: string;
+    vendorId?: string | null;
+    roles?: string[];
+    entitlements?: string[];
+    sessionId?: string;
+    jti?: string;
+    scopeContext?: ScopeContext;
+    loginMethod?: string;
+    /** RFC 8693 §4.1 actor — present on impersonation tokens. */
+    purpose?: string;
+    act?: {
+        sub: string;
+        email?: string;
+        name?: string;
+    };
+}
+/**
+ * Generic typed claims envelope. The type parameter `T` is structurally
+ * intersected with the base claims so app-specific fields minted via JWT
+ * templates surface with full IntelliSense:
+ *
+ * ```ts
+ * type MyClaims = { plan: "free" | "pro"; orgId: string };
+ * const claims = await client.tokens.verify<MyClaims>(token);
+ * if (claims.plan === "pro" && claims.orgId) { … } // both fields typed
+ * ```
+ */
+type IQAuthClaims<T extends object = {}> = IQAuthBaseClaims & T;
 interface UserProfile {
     id: string;
     email: string;
@@ -102,6 +171,19 @@ interface SessionUser {
     vendorId?: string | null;
     roles: string[];
     entitlements: string[];
+    picture?: string;
+    emailVerified?: boolean;
+    givenName?: string;
+    familyName?: string;
+    locale?: string;
+    /**
+     * Task #171 — When the active session was minted under a source/client
+     * scope (either via a scope_hint, single-resolved scope, or post-pick),
+     * the access token carries a `scopeContext` claim and we project it here
+     * so SDK consumers (`useUser()`, framework adapters) can read the active
+     * scope without re-parsing the JWT. Absent for tenant-wide sessions.
+     */
+    scopeContext?: ScopeContext;
 }
 interface Tenant {
     tenantId: string;
@@ -127,6 +209,24 @@ interface SessionAuthenticatedLoginResult {
     authMode: "session";
     user: SessionUser;
 }
+/**
+ * Task #171 — A user can have multiple source/client scoped memberships in
+ * the same tenant with no tenant-wide role. When login resolves to that
+ * state the backend returns a short-lived `scopeSelectionToken` plus the
+ * list of choices; the caller redeems it via `AuthModule.selectScope`.
+ */
+interface ScopeChoice {
+    membershipId: string;
+    scopeType: "vendor" | "source" | "client";
+    scopeId: string;
+    scopeName: string;
+    roleName: string;
+}
+/** Task #171 — Optional hint forwarded with login / select-tenant / OIDC. */
+interface ScopeHint {
+    type: "vendor" | "source" | "client";
+    id: string;
+}
 type LoginResult = TokenAuthenticatedLoginResult | SessionAuthenticatedLoginResult | {
     status: "mfa_required";
     mfaChallengeToken: string;
@@ -135,6 +235,11 @@ type LoginResult = TokenAuthenticatedLoginResult | SessionAuthenticatedLoginResu
     status: "tenant_selection";
     tenantSelectionToken: string;
     tenants: Tenant[];
+} | {
+    status: "scope_selection";
+    scopeSelectionToken: string;
+    tenantId: string;
+    scopes: ScopeChoice[];
 };
 interface Session {
     id: string;
@@ -407,6 +512,13 @@ interface PermissionNodeManifest {
     metadata?: Record<string, unknown>;
     children?: PermissionNodeManifest[];
 }
+/**
+ * Task #130 — every manifest write must declare its origin environment so a
+ * dev workstation can never silently overwrite a production app's permission
+ * tree. The Admin API rejects writes whose `environment` is missing or not
+ * one of these three values with `{code: "ENVIRONMENT_REQUIRED"}`.
+ */
+type AppManifestEnvironment = "production" | "staging" | "development";
 interface AppManifest {
     key: string;
     name: string;
@@ -415,6 +527,8 @@ interface AppManifest {
     tenantId?: string | null;
     metadata?: Record<string, unknown>;
     permissions: PermissionNodeManifest[];
+    /** Required by `POST /api/v1/apps/sync`. See {@link AppManifestEnvironment}. */
+    environment: AppManifestEnvironment;
 }
 interface AppInfo {
     id: string;
@@ -545,13 +659,17 @@ interface GroupPermission {
     nodeKey?: string | null;
     createdAt?: string;
 }
+/**
+ * Task #130 — `appKey` and `nodeKey` are REQUIRED on this app-scoped admin
+ * call. The legacy `product` / `scope` shape is rejected at the SDK boundary
+ * to prevent the silent-fallback failure mode where a misconfigured value
+ * led to an empty/wrong permission set without any error.
+ */
 interface AddGroupPermissionRequest {
-    product?: string;
-    scope?: string;
+    appKey: string;
+    nodeKey: string;
     effect: string;
     weight?: number;
-    appKey?: string;
-    nodeKey?: string;
 }
 interface InheritanceRelation {
     id: string;
@@ -569,14 +687,16 @@ interface UserPermissionOverride {
     expiresAt?: string | null;
     createdAt?: string;
 }
+/**
+ * Task #130 — `appKey` and `nodeKey` are REQUIRED. See `AddGroupPermissionRequest`
+ * for rationale.
+ */
 interface AddUserOverrideRequest {
-    product?: string;
-    scope?: string;
+    appKey: string;
+    nodeKey: string;
     effect: string;
     weight?: number;
     expiresAt?: string;
-    appKey?: string;
-    nodeKey?: string;
 }
 interface EffectivePermission {
     scope: string;
@@ -629,13 +749,46 @@ interface Invitation {
     invitedBy: string;
     expiresAt?: string;
     createdAt?: string;
+    /** Scope the invite grants into ("tenant" | "vendor" | "source" | "client"). */
+    scopeType?: string | null;
+    /** Scope target id (paired with `scopeType`). */
+    scopeId?: string | null;
+    /** OIDC client bound for post-accept auto-redirect (paired with `redirectUri`). */
+    clientId?: string | null;
+    /** Registered redirect URI the new invitee is sent to after account creation. */
+    redirectUri?: string | null;
+    /** Display name pre-filled on the hosted accept page. */
+    inviteeName?: string | null;
 }
 interface CreateInviteRequest {
     email: string;
-    tenantId: string;
+    /**
+     * Target tenant. Optional for service (API-key) callers — the backend
+     * derives the tenant from the key and rejects a mismatching value. Platform
+     * admins may target any tenant.
+     */
+    tenantId?: string;
     vendorId?: string;
     role: string;
     products?: string[];
+    /** Scope to grant into. Must match the backend's accepted values. */
+    scopeType?: "tenant" | "vendor" | "source" | "client";
+    /** Scope target id (paired with `scopeType`). */
+    scopeId?: string;
+    /**
+     * Opt-in auto-redirect after the invitee creates their account. `clientId`
+     * and `redirectUri` are all-or-nothing — pass both or neither. The backend
+     * validates that `clientId` is an active OIDC client in the invite's tenant
+     * and that `redirectUri` is in that client's registered allowlist, then mints
+     * an OIDC authorization code and 302s the brand-new invitee to
+     * `${redirectUri}?code=…&state=…`. Point this at your app's
+     * `/api/iqauth/callback` so the framework adapter signs the user in on first
+     * paint. Existing-user accepts do NOT auto-redirect (see the integration guide).
+     */
+    clientId?: string;
+    redirectUri?: string;
+    /** Optional display name to pre-fill on the hosted accept page. Never used for auth. */
+    inviteeName?: string;
 }
 interface InviteValidation {
     valid: boolean;
@@ -903,4 +1056,4 @@ interface BackupCodeCountResult {
     remainingBackupCodes: number;
 }
 
-export type { PermissionNodeInfo as $, ApiSuccessResponse as A, BrandingConfig as B, CreateTenantRequest as C, MfaVerifyResult as D, PasswordPolicy as E, MfaPolicy as F, UserPermissions as G, ProvisionUserRequest as H, IQAuthEnvironment as I, JwtClaims as J, ProvisionUserResponse as K, LoginResult as L, MigrateUserRequest as M, ExpressMiddlewareOptions as N, OidcDiscovery as O, PromoteToVendorRequest as P, IQAuthRequestLike as Q, IQAuthResponseLike as R, ScopeContext as S, TokenPair as T, UserProfile as U, IQAuthNextFunction as V, IQAuthRetryConfig as W, IQAuthVerifyConfig as X, PermissionNodeManifest as Y, AppManifest as Z, AppInfo as _, IQAuthClientConfig as a, SignupRequest as a$, AppSyncResult as a0, Role as a1, CreateRoleRequest as a2, UpdateRoleRequest as a3, AssignRoleRequest as a4, UserRoleAssignment as a5, UserGroupAssignment as a6, TenantUser as a7, PermissionGroup as a8, GroupPermission as a9, UpdateSourceRequest as aA, Client as aB, CreateClientRequest as aC, UpdateClientRequest as aD, HierarchyVendor as aE, HierarchySource as aF, HierarchyClient as aG, HierarchyLink as aH, Membership as aI, CreateMembershipRequest as aJ, UpdateMembershipRequest as aK, MembershipWithDetails as aL, AvailableScopesTree as aM, ScopeTreeClient as aN, ScopeTreeSource as aO, ScopeTreeVendor as aP, ScopeSwitchResult as aQ, GdprExportData as aR, PinStatus as aS, PinLoginResult as aT, MfaAvailableMethods as aU, TotpEnrollResult as aV, TotpVerifyResult as aW, SmsEnrollResult as aX, EmailEnrollResult as aY, BackupCodesResult as aZ, BackupCodeCountResult as a_, AddGroupPermissionRequest as aa, InheritanceRelation as ab, UserPermissionOverride as ac, AddUserOverrideRequest as ad, EffectivePermission as ae, PermissionCheckResult as af, ApiKeyInfo as ag, CreateApiKeyRequest as ah, CreateApiKeyResult as ai, ApiKeyIntrospection as aj, Invitation as ak, CreateInviteRequest as al, InviteValidation as am, AcceptInviteRequest as an, WebhookEndpoint as ao, CreateWebhookRequest as ap, CreateWebhookResult as aq, WebhookDelivery as ar, WebhookTestResult as as, Entitlement as at, GrantEntitlementRequest as au, Vendor as av, CreateVendorRequest as aw, UpdateVendorRequest as ax, Source as ay, CreateSourceRequest as az, IQAuthTokenClientConfig as b, HostedClientContext as b0, IQAuthBrowserSessionClientConfig as c, SessionUser as d, Tenant as e, TokenAuthenticatedLoginResult as f, SessionAuthenticatedLoginResult as g, Session as h, TenantInfo as i, UpdateTenantRequest as j, PromoteToVendorResult as k, InviteTenantUserRequest as l, InviteTenantUserResult as m, TenantUserRoleUpdate as n, UpdateBrandingRequest as o, BrandingAsset as p, UploadAssetRequest as q, BrandingDomainMapping as r, JwksKey as s, JwksResponse as t, OidcTokenResponse as u, ApiErrorResponse as v, ApiResponse as w, MfaMethod as x, MfaEnrollment as y, TotpEnrollmentResult as z };
+export type { AppManifest as $, ApiSuccessResponse as A, BrandingConfig as B, CreateTenantRequest as C, ApiErrorResponse as D, ApiResponse as E, MfaMethod as F, MfaEnrollment as G, TotpEnrollmentResult as H, IQAuthBrowserSessionClientConfig as I, JwtClaims as J, MfaVerifyResult as K, LoginResult as L, MigrateUserRequest as M, PasswordPolicy as N, OidcDiscovery as O, PromoteToVendorRequest as P, MfaPolicy as Q, UserPermissions as R, SessionUser as S, TokenPair as T, UserProfile as U, ProvisionUserRequest as V, ProvisionUserResponse as W, ExpressMiddlewareOptions as X, IQAuthRetryConfig as Y, IQAuthVerifyConfig as Z, PermissionNodeManifest as _, IQAuthRequestLike as a, BackupCodesResult as a$, AppInfo as a0, PermissionNodeInfo as a1, AppSyncResult as a2, Role as a3, CreateRoleRequest as a4, UpdateRoleRequest as a5, AssignRoleRequest as a6, UserRoleAssignment as a7, UserGroupAssignment as a8, TenantUser as a9, Source as aA, CreateSourceRequest as aB, UpdateSourceRequest as aC, Client as aD, CreateClientRequest as aE, UpdateClientRequest as aF, HierarchyVendor as aG, HierarchySource as aH, HierarchyClient as aI, HierarchyLink as aJ, Membership as aK, CreateMembershipRequest as aL, UpdateMembershipRequest as aM, MembershipWithDetails as aN, AvailableScopesTree as aO, ScopeTreeClient as aP, ScopeTreeSource as aQ, ScopeTreeVendor as aR, ScopeSwitchResult as aS, GdprExportData as aT, PinStatus as aU, PinLoginResult as aV, MfaAvailableMethods as aW, TotpEnrollResult as aX, TotpVerifyResult as aY, SmsEnrollResult as aZ, EmailEnrollResult as a_, PermissionGroup as aa, GroupPermission as ab, AddGroupPermissionRequest as ac, InheritanceRelation as ad, UserPermissionOverride as ae, AddUserOverrideRequest as af, EffectivePermission as ag, PermissionCheckResult as ah, ApiKeyInfo as ai, CreateApiKeyRequest as aj, CreateApiKeyResult as ak, ApiKeyIntrospection as al, Invitation as am, CreateInviteRequest as an, InviteValidation as ao, AcceptInviteRequest as ap, WebhookEndpoint as aq, CreateWebhookRequest as ar, CreateWebhookResult as as, WebhookDelivery as at, WebhookTestResult as au, Entitlement as av, GrantEntitlementRequest as aw, Vendor as ax, CreateVendorRequest as ay, UpdateVendorRequest as az, IQAuthResponseLike as b, BackupCodeCountResult as b0, ScopeHint as b1, SignupRequest as b2, HostedClientContext as b3, IQAuthNextFunction as c, IQAuthEnvironment as d, IQAuthClientConfig as e, IQAuthTokenClientConfig as f, ScopeContext as g, IQAuthClaims as h, IQAuthBaseClaims as i, Tenant as j, TokenAuthenticatedLoginResult as k, SessionAuthenticatedLoginResult as l, Session as m, TenantInfo as n, UpdateTenantRequest as o, PromoteToVendorResult as p, InviteTenantUserRequest as q, InviteTenantUserResult as r, TenantUserRoleUpdate as s, UpdateBrandingRequest as t, BrandingAsset as u, UploadAssetRequest as v, BrandingDomainMapping as w, JwksKey as x, JwksResponse as y, OidcTokenResponse as z };

package/dist/{types-6bNdxesb.d.ts → types-DnU2LhXR.d.mts}

@@ -45,6 +45,7 @@ interface IQAuthLocaleBundle {
     "signIn.useDifferentAccount": string;
     "signIn.selectTenant": string;
     "signIn.selectTenantSubtitle": string;
+    "signIn.selectScope": string;
     "signIn.dividerOr": string;
     "signIn.preparingExperience": string;
     "signIn.applicationUnavailable": string;
@@ -133,6 +134,11 @@ interface IQAuthLocaleBundle {
     "orgSwitcher.createNew": string;
     "orgSwitcher.manage": string;
     "orgSwitcher.noOrgs": string;
+    "orgSwitcher.mfaRequiredTitle": string;
+    "orgSwitcher.mfaRequiredBody": string;
+    "orgSwitcher.scopeSelectionRequiredTitle": string;
+    "orgSwitcher.scopeSelectionRequiredBody": string;
+    "orgSwitcher.continueInHostedSignIn": string;
     "orgProfile.title": string;
     "orgProfile.generalTab": string;
     "orgProfile.membersTab": string;
@@ -193,4 +199,4 @@ type IQAuthLocaleKey = keyof Omit<IQAuthLocaleBundle, "locale">;
  */
 type IQAuthLocaleOverride = Partial<IQAuthLocaleBundle>;
 
-export type { IQAuthLocaleBundle as I, IQAuthLocaleOverride as a, IQAuthLocaleKey as b };
+export type { IQAuthLocaleBundle as I, IQAuthLocaleKey as a, IQAuthLocaleOverride as b };

package/dist/{types-6bNdxesb.d.mts → types-DnU2LhXR.d.ts}

@@ -45,6 +45,7 @@ interface IQAuthLocaleBundle {
     "signIn.useDifferentAccount": string;
     "signIn.selectTenant": string;
     "signIn.selectTenantSubtitle": string;
+    "signIn.selectScope": string;
     "signIn.dividerOr": string;
     "signIn.preparingExperience": string;
     "signIn.applicationUnavailable": string;
@@ -133,6 +134,11 @@ interface IQAuthLocaleBundle {
     "orgSwitcher.createNew": string;
     "orgSwitcher.manage": string;
     "orgSwitcher.noOrgs": string;
+    "orgSwitcher.mfaRequiredTitle": string;
+    "orgSwitcher.mfaRequiredBody": string;
+    "orgSwitcher.scopeSelectionRequiredTitle": string;
+    "orgSwitcher.scopeSelectionRequiredBody": string;
+    "orgSwitcher.continueInHostedSignIn": string;
     "orgProfile.title": string;
     "orgProfile.generalTab": string;
     "orgProfile.membersTab": string;
@@ -193,4 +199,4 @@ type IQAuthLocaleKey = keyof Omit<IQAuthLocaleBundle, "locale">;
  */
 type IQAuthLocaleOverride = Partial<IQAuthLocaleBundle>;
 
-export type { IQAuthLocaleBundle as I, IQAuthLocaleOverride as a, IQAuthLocaleKey as b };
+export type { IQAuthLocaleBundle as I, IQAuthLocaleKey as a, IQAuthLocaleOverride as b };

package/dist/webhooks.d.mts

@@ -1,24 +1,34 @@
 /**
- * @iqauth/sdk/webhooks — webhook signature verification.
+ * @iqauth/sdk/webhooks — webhook signature verification + event parsing.
  *
- * Mirrors Stripe's `constructEvent` shape. Verifies the `X-IQAuth-Signature`
- * header (format `t=<unix>,v1=<hex hmac sha256>`) emitted by IQAuth's
- * webhook fan-out (src/services/webhook.service.ts). Constant-time compare;
- * tolerance window in seconds (default 300).
+ * IQAuth's webhook fan-out emits a CloudEvents-style envelope:
+ *   { specversion: "1.0", id, type, subject, time, data, tenantId }
  *
- * Usage:
- *   import { verifyWebhookSignature } from "@iqauth/sdk/webhooks";
+ * and signs the raw request body with HMAC-SHA256, exposed via the canonical
+ * header `X-IQAuth-Signature: v1=<hex>`. Legacy header names
+ * (`X-Webhook-Signature`, `X-IQ-Auth-Signature`, `X-Signature`) are also
+ * accepted for one minor with a deprecation log.
+ *
+ * Two entry points:
+ *
+ *   - `verifyWebhookSignature(opts)` — single-secret verifier kept for
+ *      back-compat. Accepts both the modern `v1=<hex>` form (sig over body)
+ *      AND the legacy `t=<unix>,v1=<hex>` form (sig over `${t}.${body}`).
+ *
+ *   - `parseWebhookEvent(rawBody, headers, secrets, opts?)` — modern entry
+ *      point. Verifies the signature against ANY secret in the array
+ *      (rotation-safe, subsumes #28), enforces the CloudEvents envelope, and
+ *      returns a typed `IQAuthEvent` with a stable `idempotencyKey`.
+ *
+ * Usage (Express, 5 lines):
+ *
+ *   import { parseWebhookEvent } from "@iqauth/sdk/webhooks";
  *   app.post("/webhooks/iqauth", express.raw({ type: "application/json" }), (req, res) => {
  *     try {
- *       const evt = verifyWebhookSignature({
- *         payload: req.body, // Buffer or string of the RAW request body
- *         header: req.header("X-IQAuth-Signature"),
- *         secret: process.env.IQAUTH_WEBHOOK_SECRET!,
- *       });
- *       // evt is the parsed JSON event
- *     } catch (err) {
- *       return res.status(400).send(err.message);
- *     }
+ *       const evt = parseWebhookEvent(req.body, req.headers, [process.env.IQAUTH_WEBHOOK_SECRET!]);
+ *       handle(evt); // evt.idempotencyKey is stable across retries
+ *       res.status(200).end();
+ *     } catch (err) { res.status(400).send((err as Error).message); }
  *   });
  */
 interface VerifyWebhookOptions {
@@ -33,6 +43,17 @@ interface VerifyWebhookOptions {
     toleranceSeconds?: number;
     /** Override the current time (seconds since epoch) — for tests. */
     nowSeconds?: number;
+    /**
+     * Security escape hatch (H-3): modern `v1=<hex>`-only deliveries carry no
+     * header `t=`, so freshness is derived from the CloudEvents envelope `time`
+     * field instead. By default a modern delivery that carries NO enforceable
+     * timestamp (no header `t=` and no parseable envelope `time`) is **rejected**
+     * so a captured body cannot be replayed indefinitely.
+     *
+     * Set `true` ONLY for legacy integrations that sign non-envelope bodies with
+     * the modern scheme and accept the replay risk. Defaults to `false` (secure).
+     */
+    allowMissingTimestamp?: boolean;
 }
 interface IQAuthWebhookEvent {
     id?: string;
@@ -42,13 +63,58 @@ interface IQAuthWebhookEvent {
     createdAt?: number | string;
     [key: string]: unknown;
 }
+/**
+ * Canonical CloudEvents-style event surfaced by `parseWebhookEvent`. Includes
+ * a stable `idempotencyKey` (= `id`) so receivers can dedupe retries without
+ * inventing their own subject-extraction logic.
+ */
+interface IQAuthEvent<TData = Record<string, unknown>> {
+    /** CloudEvents `specversion`. Always `"1.0"` in the canonical envelope. */
+    specversion: "1.0";
+    /** Unique event id. Same value as `idempotencyKey`. */
+    id: string;
+    /** Reverse-DNS-like event type (e.g. `user.deactivated`). */
+    type: string;
+    /** Stable per-event subject (e.g. the user id, invitation id, …). */
+    subject: string;
+    /** ISO-8601 UTC timestamp the producer assigned. */
+    time: string;
+    /** Tenant the event was fired for. */
+    tenantId: string;
+    /** Event-type-specific payload. */
+    data: TData;
+    /** Stable dedupe key — receivers MUST treat repeats as no-ops. */
+    idempotencyKey: string;
+    /** Which secret index in the `secrets` array verified the signature.
+     * Useful while rotating secrets — log this to confirm callers have moved
+     * onto the new key before retiring the old one. */
+    verifiedWithSecretIndex: number;
+}
 declare class WebhookSignatureError extends Error {
     code: string;
     constructor(code: string, message: string);
 }
+/** Canonical signature header name. */
+declare const IQAUTH_SIGNATURE_HEADER = "x-iqauth-signature";
+/** Legacy header names accepted for one minor. Receivers SHOULD migrate to
+ * `X-IQAuth-Signature`; verifying via these emits a deprecation log. */
+declare const LEGACY_SIGNATURE_HEADERS: readonly ["x-webhook-signature", "x-iq-auth-signature", "x-signature"];
 /**
  * Verify the signature on a webhook payload and return the parsed event.
  * Throws `WebhookSignatureError` on any verification failure.
+ *
+ * Accepts both the modern `v1=<hex>` header (HMAC over body bytes) and the
+ * legacy `t=<unix>,v1=<hex>` header (HMAC over `${t}.${body}`). Replay-window
+ * tolerance is enforced for BOTH forms (H-3):
+ *   - legacy `t=` deliveries: from the header timestamp (checked pre-verify);
+ *   - modern `v1=`-only deliveries: from the CloudEvents envelope `time` field
+ *     (checked post-verify). A modern delivery that carries no enforceable
+ *     timestamp is rejected unless `allowMissingTimestamp` is set.
+ *
+ * **For canonical Task #129 deliveries, prefer `parseWebhookEvent`** — it
+ * validates the full CloudEvents envelope, supports multi-secret rotation, and
+ * returns a typed event with a stable `idempotencyKey`. `verifyWebhookSignature`
+ * is retained for back-compat with single-secret integrations.
  */
 declare function verifyWebhookSignature(opts: VerifyWebhookOptions): IQAuthWebhookEvent;
 /**
@@ -57,5 +123,35 @@ declare function verifyWebhookSignature(opts: VerifyWebhookOptions): IQAuthWebho
  * branch on validity rather than catch.
  */
 declare function isValidWebhookSignature(opts: VerifyWebhookOptions): boolean;
+interface ParseWebhookEventOptions {
+    /** How many seconds old the envelope `time` (or legacy `t=`) may be. Default 300. */
+    toleranceSeconds?: number;
+    /** Override current time (ms since epoch) — for tests. */
+    nowMs?: number;
+    /** Sink for deprecation logs. Defaults to `console.warn`; pass `() => {}` to silence. */
+    onDeprecation?: (message: string) => void;
+}
+type HeadersLike = Record<string, string | string[] | undefined> | {
+    get(name: string): string | null;
+} | Headers;
+/**
+ * Verify and parse a webhook delivery into the canonical `IQAuthEvent`.
+ *
+ * Signature is verified against EVERY secret in `secrets` (rotation-safe).
+ * Pass `[currentSecret, previousSecret]` during a rotation window so deliveries
+ * signed with either key are accepted.
+ *
+ * Header lookup order:
+ *   1. `X-IQAuth-Signature`  (canonical)
+ *   2. `X-Webhook-Signature` (legacy — emits deprecation log)
+ *   3. `X-IQ-Auth-Signature` (legacy — emits deprecation log)
+ *   4. `X-Signature`         (legacy — emits deprecation log)
+ *
+ * Throws `WebhookSignatureError` (with a `.code` field) on any failure:
+ *   `MISSING_HEADER` | `MISSING_SECRET` | `MALFORMED_HEADER`
+ *   `TIMESTAMP_OUT_OF_TOLERANCE` | `SIGNATURE_MISMATCH`
+ *   `MALFORMED_BODY` | `MALFORMED_ENVELOPE`
+ */
+declare function parseWebhookEvent<TData = Record<string, unknown>>(rawBody: Buffer | Uint8Array | string, headers: HeadersLike, secrets: string[], opts?: ParseWebhookEventOptions): IQAuthEvent<TData>;
 
-export { type IQAuthWebhookEvent, type VerifyWebhookOptions, WebhookSignatureError, isValidWebhookSignature, verifyWebhookSignature };
+export { IQAUTH_SIGNATURE_HEADER, type IQAuthEvent, type IQAuthWebhookEvent, LEGACY_SIGNATURE_HEADERS, type ParseWebhookEventOptions, type VerifyWebhookOptions, WebhookSignatureError, isValidWebhookSignature, parseWebhookEvent, verifyWebhookSignature };

package/dist/webhooks.d.ts

@@ -1,24 +1,34 @@
 /**
- * @iqauth/sdk/webhooks — webhook signature verification.
+ * @iqauth/sdk/webhooks — webhook signature verification + event parsing.
  *
- * Mirrors Stripe's `constructEvent` shape. Verifies the `X-IQAuth-Signature`
- * header (format `t=<unix>,v1=<hex hmac sha256>`) emitted by IQAuth's
- * webhook fan-out (src/services/webhook.service.ts). Constant-time compare;
- * tolerance window in seconds (default 300).
+ * IQAuth's webhook fan-out emits a CloudEvents-style envelope:
+ *   { specversion: "1.0", id, type, subject, time, data, tenantId }
  *
- * Usage:
- *   import { verifyWebhookSignature } from "@iqauth/sdk/webhooks";
+ * and signs the raw request body with HMAC-SHA256, exposed via the canonical
+ * header `X-IQAuth-Signature: v1=<hex>`. Legacy header names
+ * (`X-Webhook-Signature`, `X-IQ-Auth-Signature`, `X-Signature`) are also
+ * accepted for one minor with a deprecation log.
+ *
+ * Two entry points:
+ *
+ *   - `verifyWebhookSignature(opts)` — single-secret verifier kept for
+ *      back-compat. Accepts both the modern `v1=<hex>` form (sig over body)
+ *      AND the legacy `t=<unix>,v1=<hex>` form (sig over `${t}.${body}`).
+ *
+ *   - `parseWebhookEvent(rawBody, headers, secrets, opts?)` — modern entry
+ *      point. Verifies the signature against ANY secret in the array
+ *      (rotation-safe, subsumes #28), enforces the CloudEvents envelope, and
+ *      returns a typed `IQAuthEvent` with a stable `idempotencyKey`.
+ *
+ * Usage (Express, 5 lines):
+ *
+ *   import { parseWebhookEvent } from "@iqauth/sdk/webhooks";
  *   app.post("/webhooks/iqauth", express.raw({ type: "application/json" }), (req, res) => {
  *     try {
- *       const evt = verifyWebhookSignature({
- *         payload: req.body, // Buffer or string of the RAW request body
- *         header: req.header("X-IQAuth-Signature"),
- *         secret: process.env.IQAUTH_WEBHOOK_SECRET!,
- *       });
- *       // evt is the parsed JSON event
- *     } catch (err) {
- *       return res.status(400).send(err.message);
- *     }
+ *       const evt = parseWebhookEvent(req.body, req.headers, [process.env.IQAUTH_WEBHOOK_SECRET!]);
+ *       handle(evt); // evt.idempotencyKey is stable across retries
+ *       res.status(200).end();
+ *     } catch (err) { res.status(400).send((err as Error).message); }
  *   });
  */
 interface VerifyWebhookOptions {
@@ -33,6 +43,17 @@ interface VerifyWebhookOptions {
     toleranceSeconds?: number;
     /** Override the current time (seconds since epoch) — for tests. */
     nowSeconds?: number;
+    /**
+     * Security escape hatch (H-3): modern `v1=<hex>`-only deliveries carry no
+     * header `t=`, so freshness is derived from the CloudEvents envelope `time`
+     * field instead. By default a modern delivery that carries NO enforceable
+     * timestamp (no header `t=` and no parseable envelope `time`) is **rejected**
+     * so a captured body cannot be replayed indefinitely.
+     *
+     * Set `true` ONLY for legacy integrations that sign non-envelope bodies with
+     * the modern scheme and accept the replay risk. Defaults to `false` (secure).
+     */
+    allowMissingTimestamp?: boolean;
 }
 interface IQAuthWebhookEvent {
     id?: string;
@@ -42,13 +63,58 @@ interface IQAuthWebhookEvent {
     createdAt?: number | string;
     [key: string]: unknown;
 }
+/**
+ * Canonical CloudEvents-style event surfaced by `parseWebhookEvent`. Includes
+ * a stable `idempotencyKey` (= `id`) so receivers can dedupe retries without
+ * inventing their own subject-extraction logic.
+ */
+interface IQAuthEvent<TData = Record<string, unknown>> {
+    /** CloudEvents `specversion`. Always `"1.0"` in the canonical envelope. */
+    specversion: "1.0";
+    /** Unique event id. Same value as `idempotencyKey`. */
+    id: string;
+    /** Reverse-DNS-like event type (e.g. `user.deactivated`). */
+    type: string;
+    /** Stable per-event subject (e.g. the user id, invitation id, …). */
+    subject: string;
+    /** ISO-8601 UTC timestamp the producer assigned. */
+    time: string;
+    /** Tenant the event was fired for. */
+    tenantId: string;
+    /** Event-type-specific payload. */
+    data: TData;
+    /** Stable dedupe key — receivers MUST treat repeats as no-ops. */
+    idempotencyKey: string;
+    /** Which secret index in the `secrets` array verified the signature.
+     * Useful while rotating secrets — log this to confirm callers have moved
+     * onto the new key before retiring the old one. */
+    verifiedWithSecretIndex: number;
+}
 declare class WebhookSignatureError extends Error {
     code: string;
     constructor(code: string, message: string);
 }
+/** Canonical signature header name. */
+declare const IQAUTH_SIGNATURE_HEADER = "x-iqauth-signature";
+/** Legacy header names accepted for one minor. Receivers SHOULD migrate to
+ * `X-IQAuth-Signature`; verifying via these emits a deprecation log. */
+declare const LEGACY_SIGNATURE_HEADERS: readonly ["x-webhook-signature", "x-iq-auth-signature", "x-signature"];
 /**
  * Verify the signature on a webhook payload and return the parsed event.
  * Throws `WebhookSignatureError` on any verification failure.
+ *
+ * Accepts both the modern `v1=<hex>` header (HMAC over body bytes) and the
+ * legacy `t=<unix>,v1=<hex>` header (HMAC over `${t}.${body}`). Replay-window
+ * tolerance is enforced for BOTH forms (H-3):
+ *   - legacy `t=` deliveries: from the header timestamp (checked pre-verify);
+ *   - modern `v1=`-only deliveries: from the CloudEvents envelope `time` field
+ *     (checked post-verify). A modern delivery that carries no enforceable
+ *     timestamp is rejected unless `allowMissingTimestamp` is set.
+ *
+ * **For canonical Task #129 deliveries, prefer `parseWebhookEvent`** — it
+ * validates the full CloudEvents envelope, supports multi-secret rotation, and
+ * returns a typed event with a stable `idempotencyKey`. `verifyWebhookSignature`
+ * is retained for back-compat with single-secret integrations.
  */
 declare function verifyWebhookSignature(opts: VerifyWebhookOptions): IQAuthWebhookEvent;
 /**
@@ -57,5 +123,35 @@ declare function verifyWebhookSignature(opts: VerifyWebhookOptions): IQAuthWebho
  * branch on validity rather than catch.
  */
 declare function isValidWebhookSignature(opts: VerifyWebhookOptions): boolean;
+interface ParseWebhookEventOptions {
+    /** How many seconds old the envelope `time` (or legacy `t=`) may be. Default 300. */
+    toleranceSeconds?: number;
+    /** Override current time (ms since epoch) — for tests. */
+    nowMs?: number;
+    /** Sink for deprecation logs. Defaults to `console.warn`; pass `() => {}` to silence. */
+    onDeprecation?: (message: string) => void;
+}
+type HeadersLike = Record<string, string | string[] | undefined> | {
+    get(name: string): string | null;
+} | Headers;
+/**
+ * Verify and parse a webhook delivery into the canonical `IQAuthEvent`.
+ *
+ * Signature is verified against EVERY secret in `secrets` (rotation-safe).
+ * Pass `[currentSecret, previousSecret]` during a rotation window so deliveries
+ * signed with either key are accepted.
+ *
+ * Header lookup order:
+ *   1. `X-IQAuth-Signature`  (canonical)
+ *   2. `X-Webhook-Signature` (legacy — emits deprecation log)
+ *   3. `X-IQ-Auth-Signature` (legacy — emits deprecation log)
+ *   4. `X-Signature`         (legacy — emits deprecation log)
+ *
+ * Throws `WebhookSignatureError` (with a `.code` field) on any failure:
+ *   `MISSING_HEADER` | `MISSING_SECRET` | `MALFORMED_HEADER`
+ *   `TIMESTAMP_OUT_OF_TOLERANCE` | `SIGNATURE_MISMATCH`
+ *   `MALFORMED_BODY` | `MALFORMED_ENVELOPE`
+ */
+declare function parseWebhookEvent<TData = Record<string, unknown>>(rawBody: Buffer | Uint8Array | string, headers: HeadersLike, secrets: string[], opts?: ParseWebhookEventOptions): IQAuthEvent<TData>;
 
-export { type IQAuthWebhookEvent, type VerifyWebhookOptions, WebhookSignatureError, isValidWebhookSignature, verifyWebhookSignature };
+export { IQAUTH_SIGNATURE_HEADER, type IQAuthEvent, type IQAuthWebhookEvent, LEGACY_SIGNATURE_HEADERS, type ParseWebhookEventOptions, type VerifyWebhookOptions, WebhookSignatureError, isValidWebhookSignature, parseWebhookEvent, verifyWebhookSignature };