@iqauth/sdk 2.7.0 → 2.8.1

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

@@ -176,6 +176,14 @@ interface SessionUser {
     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;
@@ -201,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;
@@ -209,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;
@@ -718,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;
@@ -992,4 +1056,4 @@ interface BackupCodeCountResult {
     remainingBackupCodes: number;
 }
 
-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, SignupRequest as b1, HostedClientContext as b2, 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 };
+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-BdQ2lqfT.d.mts → 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;

package/dist/{types-BdQ2lqfT.d.ts → 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;

package/dist/webhooks.d.mts

@@ -43,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;
@@ -93,15 +104,17 @@ declare const LEGACY_SIGNATURE_HEADERS: readonly ["x-webhook-signature", "x-iq-a
  * 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}`). Tolerance
- * window is enforced ONLY when a `t=` is present in the header — modern
- * `v1=<hex>`-only deliveries do NOT carry a header timestamp, so this
- * function cannot enforce replay-window protection on them. **For canonical
- * Task #129 deliveries, use `parseWebhookEvent`** — it enforces tolerance
- * via the envelope's `time` field, validates the 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 that pre-date the standardized envelope.
+ * 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;
 /**

package/dist/webhooks.d.ts

@@ -43,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;
@@ -93,15 +104,17 @@ declare const LEGACY_SIGNATURE_HEADERS: readonly ["x-webhook-signature", "x-iq-a
  * 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}`). Tolerance
- * window is enforced ONLY when a `t=` is present in the header — modern
- * `v1=<hex>`-only deliveries do NOT carry a header timestamp, so this
- * function cannot enforce replay-window protection on them. **For canonical
- * Task #129 deliveries, use `parseWebhookEvent`** — it enforces tolerance
- * via the envelope's `time` field, validates the 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 that pre-date the standardized envelope.
+ * 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;
 /**

package/dist/webhooks.js

@@ -113,12 +113,8 @@ function verifyWebhookSignature(opts) {
   }
   const body = toBuffer(opts.payload);
   const { modern, legacy } = computeSignatures(opts.secret, body, t);
-  const matched = v1.some((sig) => {
-    const lower = sig.toLowerCase();
-    if (timingSafeEqualHex(lower, modern)) return true;
-    if (legacy && timingSafeEqualHex(lower, legacy)) return true;
-    return false;
-  });
+  const expected = Number.isFinite(t) ? legacy : modern;
+  const matched = expected !== null && v1.some((sig) => timingSafeEqualHex(sig.toLowerCase(), expected));
   if (!matched) {
     throw new WebhookSignatureError("SIGNATURE_MISMATCH", "Webhook signature does not match expected value");
   }
@@ -128,6 +124,29 @@ function verifyWebhookSignature(opts) {
   } catch {
     throw new WebhookSignatureError("MALFORMED_BODY", "Webhook body is not valid JSON");
   }
+  if (!Number.isFinite(t) && !opts.allowMissingTimestamp) {
+    const rawTime = parsed.time;
+    if (typeof rawTime !== "string" || !rawTime) {
+      throw new WebhookSignatureError(
+        "MISSING_TIMESTAMP",
+        "Modern webhook delivery has no header `t=` and no envelope `time`; cannot enforce replay protection. Use parseWebhookEvent, or set allowMissingTimestamp:true (insecure)."
+      );
+    }
+    const eventMs = Date.parse(rawTime);
+    if (!Number.isFinite(eventMs)) {
+      throw new WebhookSignatureError(
+        "MALFORMED_TIMESTAMP",
+        `Envelope \`time\` is not a valid ISO timestamp: ${rawTime}`
+      );
+    }
+    const nowMs = (opts.nowSeconds ?? Math.floor(Date.now() / 1e3)) * 1e3;
+    if (Math.abs(nowMs - eventMs) > tolerance * 1e3) {
+      throw new WebhookSignatureError(
+        "TIMESTAMP_OUT_OF_TOLERANCE",
+        `Envelope time ${rawTime} is outside the ${tolerance}s tolerance window`
+      );
+    }
+  }
   return parsed;
 }
 function isValidWebhookSignature(opts) {
@@ -197,12 +216,8 @@ function parseWebhookEvent(rawBody, headers, secrets, opts = {}) {
     const secret = secrets[i];
     if (!secret) continue;
     const { modern, legacy } = computeSignatures(secret, body, t);
-    const ok = v1.some((sig) => {
-      const lower = sig.toLowerCase();
-      if (timingSafeEqualHex(lower, modern)) return true;
-      if (legacy && timingSafeEqualHex(lower, legacy)) return true;
-      return false;
-    });
+    const expected = Number.isFinite(t) ? legacy : modern;
+    const ok = expected !== null && v1.some((sig) => timingSafeEqualHex(sig.toLowerCase(), expected));
     if (ok) {
       verifiedIdx = i;
       break;

package/dist/webhooks.mjs

@@ -5,7 +5,7 @@ import {
   isValidWebhookSignature,
   parseWebhookEvent,
   verifyWebhookSignature
-} from "./chunk-PMAFENVI.mjs";
+} from "./chunk-VYQ3ETCK.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 export {
   IQAUTH_SIGNATURE_HEADER,

package/dist/ws.d.mts

@@ -1,5 +1,5 @@
-import { c as TokenVerifyOptions } from './tokens-CITeoG6P.mjs';
-import { J as JwtClaims } from './types-XOV9XPVi.mjs';
+import { c as TokenVerifyOptions } from './tokens-B06VtvUi.mjs';
+import { J as JwtClaims } from './types-Bn8O-OEd.mjs';
 
 /**
  * @iqauth/sdk/ws — WebSocket upgrade auth helper.

package/dist/ws.d.ts

@@ -1,5 +1,5 @@
-import { c as TokenVerifyOptions } from './tokens-Bqhmqq_R.js';
-import { J as JwtClaims } from './types-XOV9XPVi.js';
+import { c as TokenVerifyOptions } from './tokens-9F6ETrzk.js';
+import { J as JwtClaims } from './types-Bn8O-OEd.js';
 
 /**
  * @iqauth/sdk/ws — WebSocket upgrade auth helper.

package/docs/guides/invitations.md

@@ -33,11 +33,76 @@ const result = await client.invites.create({
   role: "user",
   vendorId: "vendor-uuid",        // optional
   products: ["iqcapture"],         // optional product access
+
+  // Optional: auto-land the invitee in your app after they accept
+  // (new users only — see "Auto-redirect after accept" below).
+  redirectUri: "https://app.example.com/iqauth/callback",
+  clientId: "oidc-client-id-for-your-app",
 });
 // result.inviteToken — for programmatic flows
 // In production, user receives email with invite link
 ```
 
+### Auto-redirect after accept (opt-in)
+
+Pass `redirectUri` + `clientId` together when creating the invite to have
+the hosted accept page mint an OIDC authorization code and `302` straight
+into your app after acceptance. The inviter app's existing
+`/api/iqauth/callback` adapter (Express / Fastify / Hono / Next) handles
+the code exchange — no SDK code changes required on the consumer side.
+
+**Constraints (validated at create time):**
+
+- Both fields must be present, or both omitted (half-pairs return `400`).
+- `clientId` must reference an **active OIDC client bound to the same tenant**
+  as the invite. Platform-wide clients (`tenant_id IS NULL`) are rejected.
+- `redirectUri` must match one of the client's registered redirect URIs,
+  using the same normalizing comparator as `/oidc/authorize` (trailing-slash
+  and case-insensitive host).
+- Both checks re-run at accept time; if the client/redirect config drifted
+  after the invite was sent, the accept silently falls back to the default
+  post-accept landing.
+
+**Response shape on `accept()`:**
+
+The `redirectTo` key is **omitted from the response entirely** (not `null`) when:
+
+- the invite was created without `redirectUri` + `clientId` (byte-for-byte back-compat),
+- the accepting user already had an IQAuth account (`existedUser === true`) — see
+  *Known limitations* below,
+- or the client/redirect config changed between create and accept.
+
+When present, `redirectTo` is a fully-qualified URL of the form
+`<redirectUri>?code=<oidc_code>&state=<random>`. Treat it as optional and
+only act on it when present.
+
+**Known limitations (v1):**
+
+- **Existing users.** When the invitee already has an IQAuth account, `redirectTo`
+  is suppressed. The accept endpoint is anonymous (the invite token is the only
+  credential) — minting an OIDC code for a pre-existing account would be an
+  auth-assurance downgrade for any account that has MFA configured.
+- **Multi-membership / scope picker.** Deferred for the same reason.
+- **PKCE / public clients.** The minted code is a confidential-client OIDC code.
+  Public-client / SPA flows that require PKCE are out of scope in v1.
+
+### Bulk-invite redirect
+
+`/api/v1/invites/bulk` accepts a single bulk-level `redirectUri` + `clientId`
+pair applied to every row, validated once before any rows are created:
+
+```typescript
+await client.invites.createBulk({
+  tenantId: "tenant-uuid",
+  invitations: [
+    { email: "alice@example.com", role: "user" },
+    { email: "bob@example.com", role: "user" },
+  ],
+  redirectUri: "https://app.example.com/iqauth/callback",
+  clientId: "oidc-client-id-for-your-app",
+});
+```
+
 ### 2. Validate Token
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iqauth/sdk",
-  "version": "2.7.0",
+  "version": "2.8.1",
   "description": "TypeScript SDK for IQAuth — the canonical way for all IQ projects to integrate with IQAuthService",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -102,7 +102,9 @@
   ],
   "scripts": {
     "build": "tsup src/index.ts src/browser-session.ts src/browser.ts src/react.ts src/react-permissions.ts src/server.ts src/server/handlers.ts src/express.ts src/fastify.ts src/hono.ts src/next.ts src/mobile.ts src/service.ts src/ws.ts src/test.ts src/webhooks.ts src/locales.ts src/cli/index.ts --format cjs,esm --dts --clean --external react --external react-dom --external next/headers --external @tanstack/react-query",
-    "test": "vitest run",
+    "test": "vitest run && vitest run --config vitest.dom.config.mts",
+    "test:node": "vitest run",
+    "test:dom": "vitest run --config vitest.dom.config.mts",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit"
@@ -129,10 +131,13 @@
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.60.5",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/jsonwebtoken": "^9.0.7",
     "@types/node": "^20.0.0",
     "@types/react": "^18.0.0",
     "@types/react-dom": "^18.0.0",
+    "jsdom": "^29.1.1",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
     "tsup": "^8.0.0",