@iqauth/sdk 2.6.3 → 2.7.0

package/dist/{signIn-CiIBTJIh.d.mts → signIn-BLFnz8SV.d.ts}

@@ -1,5 +1,5 @@
-import { c as ParsedPublishableKey } from './publishableKey-BaR0HoAH.mjs';
-import { J as JwtClaims, d as SessionUser } from './types-DZAflmmq.mjs';
+import { c as ParsedPublishableKey } from './publishableKey-f2kq-rKw.js';
+import { J as JwtClaims, S as SessionUser } from './types-XOV9XPVi.js';
 
 /**
  * SessionManager — core browser-side session state.
@@ -120,11 +120,53 @@ interface SessionManagerOptions {
         refresh?: string;
         access?: string;
     };
+    /**
+     * Task #126: When `debug` is true, the SessionManager emits
+     * `console.debug("[iqauth_session]", evt)` for `bootstrap` and `refresh`
+     * phases. When `onTimingEvent` is set, the same event is also forwarded.
+     * Use to push browser timings into your APM. Events have shape
+     * `{ phase, durationMs, ok, code? }`.
+     */
+    debug?: boolean;
+    onTimingEvent?: (event: {
+        phase: "bootstrap" | "refresh" | "signIn";
+        durationMs: number;
+        ok: boolean;
+        code?: string;
+    }) => void;
 }
 declare class SessionManager {
     private snapshot;
     private listeners;
     private refreshPromise;
+    /**
+     * Cancellation handle for the in-flight refresh, if any. `signOut()` (or a
+     * `session:signout` broadcast from another tab) calls `abort()` so the
+     * refresh response is dropped before it can write a fresh access cookie
+     * on top of the just-cleared session — the second root cause of "ghost
+     * signed-in" sessions after Sign Out.
+     */
+    private refreshAbort;
+    /**
+     * Set to `true` by `signOut()` / `signOutLocal()` for the lifetime of the
+     * call. Used as a safety belt: even if a refresh response arrives while
+     * `refreshAbort` was unable to interrupt the network call (e.g. the body
+     * was already streaming back), `runRefresh` checks this flag before
+     * mutating session state and bails out.
+     */
+    private signoutInProgress;
+    /**
+     * Per-session opaque idempotency token. Sent as `X-IQAuth-Idempotency` on
+     * every /refresh and /signout request the SDK makes through a framework
+     * adapter (Express/Fastify/Hono/Next), so the adapter's `SignoutRegistry`
+     * can collapse a refresh that lands moments after a signout — even when
+     * the two requests are routed to different server instances (multi-replica
+     * deployments).
+     *
+     * Generated lazily on first use, rotated on signout so the next session
+     * starts with a fresh token. Opaque random — never the raw refresh token.
+     */
+    private idempotencyToken;
     private channel;
     private readonly tabId;
     private readonly fetchImpl;
@@ -138,26 +180,59 @@ declare class SessionManager {
     private readonly crossTabLockTimeoutMs;
     private readonly serverManagedSession;
     private readonly refreshCookieName;
+    private readonly debug;
+    private readonly onTimingEvent;
     private proactiveTimer;
     private bootstrapped;
     /** Pending refresh awaited by other tabs after a `refresh:claim` from us. */
     private remoteRefreshWaiters;
     /** Active claims by other tabs (keyed by source tabId). */
     private foreignClaim;
+    /** Resolver for an in-flight cross-tab `session:probe`, set during bootstrap. */
+    private probeResolver;
     constructor(options: SessionManagerOptions);
     get publishableKey(): ParsedPublishableKey;
     get appKey(): string;
     get tenantIdFromKey(): string;
     get issuerUrl(): string;
+    /**
+     * SDK 2.7.0 (Task #124) — The hosted IQAuth host derived from the
+     * publishable key's `iss` claim, normalized to URL form. This is what
+     * `<SignIn/>` and `buildSignInUrl` use to talk to the hosted UI; it
+     * deliberately ignores the `issuer` constructor override so a misrouted
+     * `issuer` (e.g. pointed at the consumer app's own domain) cannot break
+     * the hosted flow. Use {@link issuerUrl} for token / discovery endpoints.
+     */
+    get hostedIssuerUrl(): string;
     /** Cookie name the SDK uses for the refresh token (overridable via `cookieNames.refresh`). */
     get refreshCookie(): string;
+    /**
+     * Returns the current per-session idempotency token, generating one
+     * lazily on first use. Sent as the `X-IQAuth-Idempotency` header on
+     * /refresh and /signout requests so the framework adapter's
+     * `SignoutRegistry` can collapse a refresh-vs-signout race even across
+     * server instances.
+     */
+    getIdempotencyToken(): string;
     getSnapshot(): SessionSnapshot;
     subscribe(listener: (s: SessionSnapshot) => void): () => void;
     /**
      * One-time bootstrap: warm the session from the refresh cookie if present.
      * Safe to call multiple times.
      */
+    /**
+     * Task #126: Public timing-event emitter. Used by the browser sign-in
+     * helpers (redirectToSignIn / handleAuthCallback) to surface signIn-phase
+     * timings through the same `debug` + `onTimingEvent` channel as
+     * bootstrap/refresh. Safe to call from anywhere — internal callers
+     * pre-compute durationMs.
+     */
+    recordTiming(phase: "bootstrap" | "refresh" | "signIn", durationMs: number, ok: boolean, code?: string): void;
+    /** Task #126: emit a session timing event to debug log + onTimingEvent hook. */
+    private emitTiming;
     bootstrap(): Promise<void>;
+    private bootstrapInner;
+    private probePeers;
     /**
      * Single-flight token refresh, coordinated across tabs via BroadcastChannel.
      *
@@ -485,4 +560,4 @@ declare function handleAuthCallback(manager: SessionManager, options?: {
  */
 declare function signOut(manager: SessionManager, opts?: SignOutOptions): Promise<void>;
 
-export { AccountRegistry as A, clearCookie as B, type CallbackResult as C, getCookie as D, setCookie as E, type LinkedIdentity as L, type MagicLinkRequestInput as M, type PasswordlessOptions as P, type RefreshTokenStore as R, SessionManager as S, type UnlinkProviderInput as U, type SessionManagerOptions as a, type SessionSnapshot as b, type SessionStatus as c, beginPasskeyAuthentication as d, beginPasskeyRegistration as e, finishPasskeyAuthentication as f, finishPasskeyRegistration as g, enrollPasskey as h, linkProvider as i, type PasskeyAuthInput as j, type LinkProviderInput as k, listLinkedIdentities as l, MultiAccountTokenStore as m, type AccountRecord as n, buildSignInUrl as o, handleAuthCallback as p, redirectToSignIn as q, requestMagicLink as r, signInWithPasskey as s, signIn as t, unlinkProvider as u, verifyMagicLink as v, signOut as w, type SignInOptions as x, type SignOutOptions as y, REFRESH_COOKIE as z };
+export { AccountRegistry as A, clearCookie as B, type CallbackResult as C, getCookie as D, setCookie as E, type LinkedIdentity as L, type MagicLinkRequestInput as M, type PasswordlessOptions as P, type RefreshTokenStore as R, SessionManager as S, type UnlinkProviderInput as U, type SessionSnapshot as a, type SignInOptions as b, type SignOutOptions as c, type LinkProviderInput as d, type SessionManagerOptions as e, type SessionStatus as f, beginPasskeyAuthentication as g, finishPasskeyAuthentication as h, beginPasskeyRegistration as i, finishPasskeyRegistration as j, enrollPasskey as k, listLinkedIdentities as l, linkProvider as m, type PasskeyAuthInput as n, MultiAccountTokenStore as o, type AccountRecord as p, buildSignInUrl as q, requestMagicLink as r, signInWithPasskey as s, handleAuthCallback as t, unlinkProvider as u, verifyMagicLink as v, redirectToSignIn as w, signIn as x, signOut as y, REFRESH_COOKIE as z };

package/dist/{signIn-CCY4JE5G.mjs → signIn-SHBW6Z4T.mjs}

@@ -4,7 +4,8 @@ import {
   redirectToSignIn,
   signIn,
   signOut
-} from "./chunk-TKZTCPEK.mjs";
+} from "./chunk-GN37E64I.mjs";
+import "./chunk-C2ZTBOAC.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 export {
   buildSignInUrl,

package/dist/{signIn-OCr88Zf8.d.ts → signIn-T-CZ6t6r.d.mts}

@@ -1,5 +1,5 @@
-import { c as ParsedPublishableKey } from './publishableKey-BaR0HoAH.js';
-import { J as JwtClaims, d as SessionUser } from './types-DZAflmmq.js';
+import { c as ParsedPublishableKey } from './publishableKey-f2kq-rKw.mjs';
+import { J as JwtClaims, S as SessionUser } from './types-XOV9XPVi.mjs';
 
 /**
  * SessionManager — core browser-side session state.
@@ -120,11 +120,53 @@ interface SessionManagerOptions {
         refresh?: string;
         access?: string;
     };
+    /**
+     * Task #126: When `debug` is true, the SessionManager emits
+     * `console.debug("[iqauth_session]", evt)` for `bootstrap` and `refresh`
+     * phases. When `onTimingEvent` is set, the same event is also forwarded.
+     * Use to push browser timings into your APM. Events have shape
+     * `{ phase, durationMs, ok, code? }`.
+     */
+    debug?: boolean;
+    onTimingEvent?: (event: {
+        phase: "bootstrap" | "refresh" | "signIn";
+        durationMs: number;
+        ok: boolean;
+        code?: string;
+    }) => void;
 }
 declare class SessionManager {
     private snapshot;
     private listeners;
     private refreshPromise;
+    /**
+     * Cancellation handle for the in-flight refresh, if any. `signOut()` (or a
+     * `session:signout` broadcast from another tab) calls `abort()` so the
+     * refresh response is dropped before it can write a fresh access cookie
+     * on top of the just-cleared session — the second root cause of "ghost
+     * signed-in" sessions after Sign Out.
+     */
+    private refreshAbort;
+    /**
+     * Set to `true` by `signOut()` / `signOutLocal()` for the lifetime of the
+     * call. Used as a safety belt: even if a refresh response arrives while
+     * `refreshAbort` was unable to interrupt the network call (e.g. the body
+     * was already streaming back), `runRefresh` checks this flag before
+     * mutating session state and bails out.
+     */
+    private signoutInProgress;
+    /**
+     * Per-session opaque idempotency token. Sent as `X-IQAuth-Idempotency` on
+     * every /refresh and /signout request the SDK makes through a framework
+     * adapter (Express/Fastify/Hono/Next), so the adapter's `SignoutRegistry`
+     * can collapse a refresh that lands moments after a signout — even when
+     * the two requests are routed to different server instances (multi-replica
+     * deployments).
+     *
+     * Generated lazily on first use, rotated on signout so the next session
+     * starts with a fresh token. Opaque random — never the raw refresh token.
+     */
+    private idempotencyToken;
     private channel;
     private readonly tabId;
     private readonly fetchImpl;
@@ -138,26 +180,59 @@ declare class SessionManager {
     private readonly crossTabLockTimeoutMs;
     private readonly serverManagedSession;
     private readonly refreshCookieName;
+    private readonly debug;
+    private readonly onTimingEvent;
     private proactiveTimer;
     private bootstrapped;
     /** Pending refresh awaited by other tabs after a `refresh:claim` from us. */
     private remoteRefreshWaiters;
     /** Active claims by other tabs (keyed by source tabId). */
     private foreignClaim;
+    /** Resolver for an in-flight cross-tab `session:probe`, set during bootstrap. */
+    private probeResolver;
     constructor(options: SessionManagerOptions);
     get publishableKey(): ParsedPublishableKey;
     get appKey(): string;
     get tenantIdFromKey(): string;
     get issuerUrl(): string;
+    /**
+     * SDK 2.7.0 (Task #124) — The hosted IQAuth host derived from the
+     * publishable key's `iss` claim, normalized to URL form. This is what
+     * `<SignIn/>` and `buildSignInUrl` use to talk to the hosted UI; it
+     * deliberately ignores the `issuer` constructor override so a misrouted
+     * `issuer` (e.g. pointed at the consumer app's own domain) cannot break
+     * the hosted flow. Use {@link issuerUrl} for token / discovery endpoints.
+     */
+    get hostedIssuerUrl(): string;
     /** Cookie name the SDK uses for the refresh token (overridable via `cookieNames.refresh`). */
     get refreshCookie(): string;
+    /**
+     * Returns the current per-session idempotency token, generating one
+     * lazily on first use. Sent as the `X-IQAuth-Idempotency` header on
+     * /refresh and /signout requests so the framework adapter's
+     * `SignoutRegistry` can collapse a refresh-vs-signout race even across
+     * server instances.
+     */
+    getIdempotencyToken(): string;
     getSnapshot(): SessionSnapshot;
     subscribe(listener: (s: SessionSnapshot) => void): () => void;
     /**
      * One-time bootstrap: warm the session from the refresh cookie if present.
      * Safe to call multiple times.
      */
+    /**
+     * Task #126: Public timing-event emitter. Used by the browser sign-in
+     * helpers (redirectToSignIn / handleAuthCallback) to surface signIn-phase
+     * timings through the same `debug` + `onTimingEvent` channel as
+     * bootstrap/refresh. Safe to call from anywhere — internal callers
+     * pre-compute durationMs.
+     */
+    recordTiming(phase: "bootstrap" | "refresh" | "signIn", durationMs: number, ok: boolean, code?: string): void;
+    /** Task #126: emit a session timing event to debug log + onTimingEvent hook. */
+    private emitTiming;
     bootstrap(): Promise<void>;
+    private bootstrapInner;
+    private probePeers;
     /**
      * Single-flight token refresh, coordinated across tabs via BroadcastChannel.
      *
@@ -485,4 +560,4 @@ declare function handleAuthCallback(manager: SessionManager, options?: {
  */
 declare function signOut(manager: SessionManager, opts?: SignOutOptions): Promise<void>;
 
-export { AccountRegistry as A, clearCookie as B, type CallbackResult as C, getCookie as D, setCookie as E, type LinkedIdentity as L, type MagicLinkRequestInput as M, type PasswordlessOptions as P, type RefreshTokenStore as R, SessionManager as S, type UnlinkProviderInput as U, type SessionManagerOptions as a, type SessionSnapshot as b, type SessionStatus as c, beginPasskeyAuthentication as d, beginPasskeyRegistration as e, finishPasskeyAuthentication as f, finishPasskeyRegistration as g, enrollPasskey as h, linkProvider as i, type PasskeyAuthInput as j, type LinkProviderInput as k, listLinkedIdentities as l, MultiAccountTokenStore as m, type AccountRecord as n, buildSignInUrl as o, handleAuthCallback as p, redirectToSignIn as q, requestMagicLink as r, signInWithPasskey as s, signIn as t, unlinkProvider as u, verifyMagicLink as v, signOut as w, type SignInOptions as x, type SignOutOptions as y, REFRESH_COOKIE as z };
+export { AccountRegistry as A, clearCookie as B, type CallbackResult as C, getCookie as D, setCookie as E, type LinkedIdentity as L, type MagicLinkRequestInput as M, type PasswordlessOptions as P, type RefreshTokenStore as R, SessionManager as S, type UnlinkProviderInput as U, type SessionSnapshot as a, type SignInOptions as b, type SignOutOptions as c, type LinkProviderInput as d, type SessionManagerOptions as e, type SessionStatus as f, beginPasskeyAuthentication as g, finishPasskeyAuthentication as h, beginPasskeyRegistration as i, finishPasskeyRegistration as j, enrollPasskey as k, listLinkedIdentities as l, linkProvider as m, type PasskeyAuthInput as n, MultiAccountTokenStore as o, type AccountRecord as p, buildSignInUrl as q, requestMagicLink as r, signInWithPasskey as s, handleAuthCallback as t, unlinkProvider as u, verifyMagicLink as v, redirectToSignIn as w, signIn as x, signOut as y, REFRESH_COOKIE as z };

package/dist/test.mjs

@@ -1,8 +1,8 @@
 import {
   createTestIssuer
-} from "./chunk-MKKZULZR.mjs";
-import "./chunk-WQWBJSSS.mjs";
-import "./chunk-6I6RM4MN.mjs";
+} from "./chunk-WIFG74IK.mjs";
+import "./chunk-HVHNYPDC.mjs";
+import "./chunk-6PJRLRB4.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 export {
   createTestIssuer

package/dist/{tokens-DCyzzn8L.d.mts → tokens-Bqhmqq_R.d.ts}

@@ -1,4 +1,4 @@
-import { J as JwtClaims } from './types-DZAflmmq.mjs';
+import { h as IQAuthClaims, J as JwtClaims } from './types-XOV9XPVi.js';
 
 /**
  * SOURCE REFS:
@@ -45,7 +45,7 @@ declare class TokensModule {
      * Node, browser, and edge runtimes alike — no `node:crypto` dependency.
      * Caches JWKS for 1 hour and refetches once on unknown `kid`.
      */
-    verify(token: string, options?: TokenVerifyOptions): Promise<JwtClaims>;
+    verify<T extends object = {}>(token: string, options?: TokenVerifyOptions): Promise<IQAuthClaims<T> & JwtClaims>;
     /**
      * Decode a JWT without verification. Returns null if malformed.
      */
@@ -58,6 +58,13 @@ declare class TokensModule {
     private refreshJwks;
     /** @internal Exposed for testing — clears JWKS cache */
     clearCache(): void;
+    /**
+     * Task #126: Eagerly populate the JWKS cache so the first verify() call
+     * doesn't pay a network round-trip. Safe to call repeatedly — single-flight
+     * behavior is shared with the lazy refresh path. Errors are swallowed so
+     * callers (e.g. `attachHelpers` auto-prewarm) can fire-and-forget.
+     */
+    prewarm(): Promise<void>;
 }
 
 export { DEFAULT_TOKEN_ISSUER as D, TokensModule as T, DEFAULT_TOKEN_AUDIENCE as a, DEFAULT_CLOCK_TOLERANCE_SECONDS as b, type TokenVerifyOptions as c, type TokensModuleOptions as d };

package/dist/{tokens-aHiGFr_E.d.ts → tokens-CITeoG6P.d.mts}

@@ -1,4 +1,4 @@
-import { J as JwtClaims } from './types-DZAflmmq.js';
+import { h as IQAuthClaims, J as JwtClaims } from './types-XOV9XPVi.mjs';
 
 /**
  * SOURCE REFS:
@@ -45,7 +45,7 @@ declare class TokensModule {
      * Node, browser, and edge runtimes alike — no `node:crypto` dependency.
      * Caches JWKS for 1 hour and refetches once on unknown `kid`.
      */
-    verify(token: string, options?: TokenVerifyOptions): Promise<JwtClaims>;
+    verify<T extends object = {}>(token: string, options?: TokenVerifyOptions): Promise<IQAuthClaims<T> & JwtClaims>;
     /**
      * Decode a JWT without verification. Returns null if malformed.
      */
@@ -58,6 +58,13 @@ declare class TokensModule {
     private refreshJwks;
     /** @internal Exposed for testing — clears JWKS cache */
     clearCache(): void;
+    /**
+     * Task #126: Eagerly populate the JWKS cache so the first verify() call
+     * doesn't pay a network round-trip. Safe to call repeatedly — single-flight
+     * behavior is shared with the lazy refresh path. Errors are swallowed so
+     * callers (e.g. `attachHelpers` auto-prewarm) can fire-and-forget.
+     */
+    prewarm(): Promise<void>;
 }
 
 export { DEFAULT_TOKEN_ISSUER as D, TokensModule as T, DEFAULT_TOKEN_AUDIENCE as a, DEFAULT_CLOCK_TOLERANCE_SECONDS as b, type TokenVerifyOptions as c, type TokensModuleOptions as d };

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

@@ -193,4 +193,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-BdQ2lqfT.d.ts}

@@ -193,4 +193,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-DZAflmmq.d.mts → types-XOV9XPVi.d.mts}

@@ -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,11 @@ interface SessionUser {
     vendorId?: string | null;
     roles: string[];
     entitlements: string[];
+    picture?: string;
+    emailVerified?: boolean;
+    givenName?: string;
+    familyName?: string;
+    locale?: string;
 }
 interface Tenant {
     tenantId: string;
@@ -407,6 +481,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 +496,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 +628,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 +656,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;
@@ -903,4 +992,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, 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 };