@auth-gate/core 0.14.0 → 0.15.1

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+//#region src/types.d.ts
 /**
  * The authenticated user object returned after successful authentication.
  *
@@ -9,18 +10,18 @@
  * and `picture`, etc.
  */
 interface AuthGateUser {
-    /** Unique user identifier assigned by AuthGate. */
-    id: string;
-    /** User's email address. Present for email/OAuth flows, `null` for SMS-only users. */
-    email: string | null;
-    /** User's phone number in E.164 format. Present for SMS flows, `null` otherwise. */
-    phone: string | null;
-    /** User's display name from the OAuth provider or signup form. */
-    name: string | null;
-    /** URL to the user's profile picture from the OAuth provider. */
-    picture: string | null;
-    /** The authentication provider used (e.g. `"google"`, `"github"`, `"email"`, `"sms"`). */
-    provider: string;
+  /** Unique user identifier assigned by AuthGate. */
+  id: string;
+  /** User's email address. Present for email/OAuth flows, `null` for SMS-only users. */
+  email: string | null;
+  /** User's phone number in E.164 format. Present for SMS flows, `null` otherwise. */
+  phone: string | null;
+  /** User's display name from the OAuth provider or signup form. */
+  name: string | null;
+  /** URL to the user's profile picture from the OAuth provider. */
+  picture: string | null;
+  /** The authentication provider used (e.g. `"google"`, `"github"`, `"email"`, `"sms"`). */
+  provider: string;
 }
 /**
  * Result of verifying a JWT token against the AuthGate API.
@@ -29,14 +30,14 @@ interface AuthGateUser {
  * When `valid` is `false`, `error` describes why verification failed.
  */
 interface TokenVerifyResult {
-    /** Whether the token is valid and not expired. */
-    valid: boolean;
-    /** The authenticated user, present when `valid` is `true`. */
-    user?: AuthGateUser;
-    /** ISO 8601 timestamp when the token expires, present when `valid` is `true`. */
-    expiresAt?: string;
-    /** Human-readable error message, present when `valid` is `false`. */
-    error?: string;
+  /** Whether the token is valid and not expired. */
+  valid: boolean;
+  /** The authenticated user, present when `valid` is `true`. */
+  user?: AuthGateUser;
+  /** ISO 8601 timestamp when the token expires, present when `valid` is `true`. */
+  expiresAt?: string;
+  /** Human-readable error message, present when `valid` is `false`. */
+  error?: string;
 }
 /**
  * Configuration for initializing an {@link AuthGateClient}.
@@ -52,54 +53,54 @@ interface TokenVerifyResult {
  * ```
  */
 interface AuthGateConfig {
-    /** Server-side API key for your AuthGate project. Found in the dashboard under API Key. */
-    apiKey: string;
-    /** Base URL of the AuthGate service (e.g. `"https://www.authgate.dev"`). */
-    baseUrl: string;
-    /**
-     * Name of the session cookie.
-     * @defaultValue `"__authgate"`
-     */
-    cookieName?: string;
-    /**
-     * Session lifetime in seconds. Controls how long the encrypted session cookie
-     * and refresh token remain valid.
-     * @defaultValue `604800` (7 days)
-     */
-    sessionMaxAge?: number;
-    /**
-     * Path where the OAuth callback handler is mounted.
-     * @defaultValue `"/api/auth/callback"`
-     */
-    callbackPath?: string;
+  /** Server-side API key for your AuthGate project. Found in the dashboard under API Key. */
+  apiKey: string;
+  /** Base URL of the AuthGate service (e.g. `"https://www.authgate.dev"`). */
+  baseUrl: string;
+  /**
+   * Name of the session cookie.
+   * @defaultValue `"__authgate"`
+   */
+  cookieName?: string;
+  /**
+   * Session lifetime in seconds. Controls how long the encrypted session cookie
+   * and refresh token remain valid.
+   * @defaultValue `604800` (7 days)
+   */
+  sessionMaxAge?: number;
+  /**
+   * Path where the OAuth callback handler is mounted.
+   * @defaultValue `"/api/auth/callback"`
+   */
+  callbackPath?: string;
 }
 /**
  * Internal payload structure stored inside the encrypted session cookie.
  * Contains the user data plus issued-at and expiration timestamps.
  */
 interface SessionPayload {
-    /** The authenticated user data. */
-    user: AuthGateUser;
-    /** Unix timestamp (seconds) when the session was created. */
-    iat: number;
-    /** Unix timestamp (seconds) when the session expires. */
-    exp: number;
+  /** The authenticated user data. */
+  user: AuthGateUser;
+  /** Unix timestamp (seconds) when the session was created. */
+  iat: number;
+  /** Unix timestamp (seconds) when the session expires. */
+  exp: number;
 }
 /**
  * Options for configuring HTTP cookies set by AuthGate.
  * Maps directly to standard `Set-Cookie` attributes.
  */
 interface CookieOptions {
-    /** Prevents client-side JavaScript from reading the cookie. */
-    httpOnly: boolean;
-    /** Only send the cookie over HTTPS connections. */
-    secure: boolean;
-    /** Controls when the cookie is sent with cross-site requests. */
-    sameSite: "lax" | "strict" | "none";
-    /** Cookie lifetime in seconds. */
-    maxAge: number;
-    /** URL path the cookie is valid for. */
-    path: string;
+  /** Prevents client-side JavaScript from reading the cookie. */
+  httpOnly: boolean;
+  /** Only send the cookie over HTTPS connections. */
+  secure: boolean;
+  /** Controls when the cookie is sent with cross-site requests. */
+  sameSite: "lax" | "strict" | "none";
+  /** Cookie lifetime in seconds. */
+  maxAge: number;
+  /** URL path the cookie is valid for. */
+  path: string;
 }
 /**
  * Supported OAuth provider identifiers.
@@ -114,36 +115,36 @@ type OAuthProvider = "google" | "github" | "discord" | "azure" | "apple";
  * passing the `mfa_challenge` token and available `mfa_methods`.
  */
 interface MfaChallengeResponse {
-    /** Always `true` — indicates MFA is required to complete authentication. */
-    mfa_required: true;
-    /** Opaque challenge token to pass to the MFA verify endpoint. */
-    mfa_challenge: string;
-    /** List of MFA methods the user has enrolled (e.g. `["totp", "sms"]`). */
-    mfa_methods: string[];
+  /** Always `true` — indicates MFA is required to complete authentication. */
+  mfa_required: true;
+  /** Opaque challenge token to pass to the MFA verify endpoint. */
+  mfa_challenge: string;
+  /** List of MFA methods the user has enrolled (e.g. `["totp", "sms"]`). */
+  mfa_methods: string[];
 }
 /**
  * Current MFA enrollment status for a user.
  * Returned by the `/api/proxy/mfa/status` endpoint.
  */
 interface MfaStatus {
-    /** Whether the user has any MFA method enrolled. */
-    enrolled: boolean;
-    /** List of enrolled MFA methods (e.g. `["totp"]`, `["sms", "totp"]`). */
-    methods: string[];
-    /** Whether MFA is required by the project's policy. */
-    required: boolean;
+  /** Whether the user has any MFA method enrolled. */
+  enrolled: boolean;
+  /** List of enrolled MFA methods (e.g. `["totp"]`, `["sms", "totp"]`). */
+  methods: string[];
+  /** Whether MFA is required by the project's policy. */
+  required: boolean;
 }
 /**
  * Response from TOTP setup containing the secret and QR code.
  * Returned by the `/api/proxy/mfa/totp/setup` endpoint.
  */
 interface TotpSetupResponse {
-    /** Base32-encoded TOTP secret for manual entry. */
-    secret: string;
-    /** Data URL of the QR code image (PNG) for scanning with an authenticator app. */
-    qr_code: string;
-    /** `otpauth://` URI for the TOTP secret. */
-    uri: string;
+  /** Base32-encoded TOTP secret for manual entry. */
+  secret: string;
+  /** Data URL of the QR code image (PNG) for scanning with an authenticator app. */
+  qr_code: string;
+  /** `otpauth://` URI for the TOTP secret. */
+  uri: string;
 }
 /**
  * Response from generating new MFA backup codes.
@@ -152,10 +153,11 @@ interface TotpSetupResponse {
  * Each code can only be used once. Generating new codes invalidates all previous ones.
  */
 interface BackupCodesResponse {
-    /** Array of single-use backup codes. Store these securely — they are shown only once. */
-    codes: string[];
+  /** Array of single-use backup codes. Store these securely — they are shown only once. */
+  codes: string[];
 }
-
+//#endregion
+//#region src/client.d.ts
 /**
  * Core client for interacting with the AuthGate authentication proxy.
  *
@@ -174,437 +176,452 @@ interface BackupCodesResponse {
  * ```
  */
 declare class AuthGateClient {
-    private readonly config;
-    private encryptionKey;
-    private stateKey;
-    private keysReady;
-    /**
-     * @param config - Client configuration. See {@link AuthGateConfig}.
-     */
-    constructor(config: AuthGateConfig);
-    private deriveKeys;
-    private getEncryptionKey;
-    private getStateKey;
-    /**
-     * Verify a JWT token against the AuthGate API.
-     *
-     * Makes a server-side `POST /api/v1/token/verify` call using your API key.
-     * Times out after 5 seconds.
-     *
-     * @param token - The JWT token string from the OAuth callback or email/SMS flow.
-     * @returns A {@link TokenVerifyResult} with the user data if valid.
-     * @throws {@link TokenVerificationError} if the request times out.
-     */
-    verifyToken(token: string): Promise<TokenVerifyResult>;
-    /**
-     * Encrypt user data into a session cookie value.
-     *
-     * Uses AES-256-GCM with a key derived from your session secret.
-     * The returned string is safe to store in an httpOnly cookie.
-     *
-     * @param user - The authenticated user to store.
-     * @returns Base64url-encoded encrypted session string.
-     */
-    encryptSession(user: AuthGateUser): Promise<string>;
-    /**
-     * Decrypt a session cookie and return the user if the session is valid.
-     *
-     * Returns `null` if the cookie is expired, tampered with, or encrypted
-     * with a different secret. All failure modes return `null` to prevent
-     * oracle attacks.
-     *
-     * @param cookieValue - The encrypted cookie string.
-     * @returns The user, or `null` if the session is invalid.
-     */
-    decryptSession(cookieValue: string): Promise<AuthGateUser | null>;
-    /**
-     * Decrypt a session cookie and return the full payload (user + timestamps).
-     *
-     * Used internally by middleware to check `iat` for session revalidation.
-     *
-     * @param cookieValue - The encrypted cookie string.
-     * @returns The full session payload, or `null` if invalid.
-     * @internal
-     */
-    decryptSessionPayload(cookieValue: string): Promise<SessionPayload | null>;
-    /**
-     * Create a signed OAuth state parameter and nonce for CSRF protection.
-     *
-     * Store the `nonce` in a short-lived httpOnly cookie and pass `state`
-     * as a query parameter in the OAuth authorization URL.
-     *
-     * @returns `{ state, nonce }` — the state string and its corresponding nonce.
-     */
-    createState(): Promise<{
-        state: string;
-        nonce: string;
-    }>;
-    /**
-     * Verify an OAuth state parameter returned in the callback.
-     *
-     * @param state - The `state` query parameter from the callback.
-     * @param nonce - The nonce from the httpOnly cookie.
-     * @returns `true` if the state is valid and not expired.
-     */
-    verifyState(state: string, nonce: string): Promise<boolean>;
-    /**
-     * Build the OAuth authorization URL for a given provider.
-     *
-     * @param provider - The OAuth provider (e.g. `"google"`, `"github"`).
-     * @param callbackUrl - Your app's callback URL where the user is redirected after auth.
-     * @param options - Optional parameters.
-     * @param options.linkTo - An existing user ID to link this OAuth account to.
-     * @returns The full authorization URL to redirect the user to.
-     * @throws {@link AuthGateError} if the provider is not in {@link SUPPORTED_PROVIDERS}.
-     */
-    getOAuthUrl(provider: OAuthProvider, callbackUrl: string, options?: {
-        state?: string;
-        linkTo?: string;
-        locale?: string;
-    }): Promise<string>;
-    /**
-     * Register a new user with email and password.
-     *
-     * @param data - Signup data including email, password, optional name, and callback URL.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    emailSignup(data: {
-        email: string;
-        password: string;
-        name?: string;
-        callbackUrl: string;
-        locale?: string;
-    }): Promise<Response>;
-    /**
-     * Sign in an existing user with email and password.
-     *
-     * The response may include `mfa_required: true` if the user has MFA enabled,
-     * in which case you should redirect to an MFA verification page.
-     *
-     * @param data - Sign-in data including email, password, and callback URL.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    emailSignin(data: {
-        email: string;
-        password: string;
-        callbackUrl: string;
-        locale?: string;
-    }): Promise<Response>;
-    /**
-     * Send a password reset email to the user.
-     *
-     * @param data - The user's email and the URL to redirect to after clicking the reset link.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    emailForgotPassword(data: {
-        email: string;
-        callbackUrl: string;
-        locale?: string;
-    }): Promise<Response>;
-    /**
-     * Confirm a password reset with the token from the reset email.
-     *
-     * @param data - The reset token and the new password.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    emailResetPassword(data: {
-        token: string;
-        password: string;
-        locale?: string;
-    }): Promise<Response>;
-    /**
-     * Send a magic link email for passwordless authentication.
-     *
-     * @param data - The user's email and callback URL.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    magicLinkSend(data: {
-        email: string;
-        callbackUrl: string;
-        locale?: string;
-    }): Promise<Response>;
-    /**
-     * Verify an email address using a one-time code.
-     *
-     * @param data - The user's email and the verification code.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    emailVerifyCode(data: {
-        email: string;
-        code: string;
-        locale?: string;
-    }): Promise<Response>;
-    /**
-     * Send an SMS verification code to the user's phone number.
-     *
-     * @param data - The phone number (E.164 format) and callback URL.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    smsSendCode(data: {
-        phone: string;
-        callbackUrl: string;
-    }): Promise<Response>;
-    /**
-     * Verify an SMS code and authenticate the user.
-     *
-     * @param data - The phone number, verification code, and callback URL.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    smsVerifyCode(data: {
-        phone: string;
-        code: string;
-        callbackUrl: string;
-    }): Promise<Response>;
-    /**
-     * Exchange a refresh token for a new JWT.
-     *
-     * Refresh tokens are single-use — each call returns a new JWT and
-     * invalidates the previous refresh token (rotation).
-     *
-     * @param refreshToken - The opaque refresh token.
-     * @returns A new JWT and its `expires_in` (seconds), or `null` if the refresh token is invalid.
-     */
-    refreshToken(refreshToken: string): Promise<{
-        token: string;
-        expires_in: number;
-    } | null>;
-    /**
-     * Revoke a session by its refresh token.
-     *
-     * After revocation, the refresh token can no longer be used to obtain
-     * new JWTs. The user will need to re-authenticate.
-     *
-     * @param refreshToken - The opaque refresh token to revoke.
-     * @returns `true` if the session was revoked, `false` on failure.
-     */
-    revokeSession(refreshToken: string): Promise<boolean>;
-    /**
-     * Verify an MFA code to complete authentication.
-     *
-     * Called after a sign-in response includes `mfa_required: true`.
-     *
-     * @param data - The MFA challenge token, verification code, and method.
-     * @returns The raw `Response` — includes a JWT on success.
-     */
-    mfaVerify(data: {
-        challenge: string;
-        code: string;
-        method: "totp" | "sms" | "backup_code";
-    }): Promise<Response>;
-    /**
-     * Begin TOTP (authenticator app) setup for the authenticated user.
-     *
-     * Requires a valid JWT in the `Authorization: Bearer` header.
-     *
-     * @param token - The user's current JWT.
-     * @returns The raw `Response` with TOTP secret, QR code, and URI.
-     */
-    mfaTotpSetup(token: string): Promise<Response>;
-    /**
-     * Confirm TOTP setup by verifying a code from the authenticator app.
-     *
-     * @param token - The user's current JWT.
-     * @param code - The 6-digit TOTP code from the authenticator app.
-     * @returns The raw `Response` — confirms enrollment on success.
-     */
-    mfaTotpVerifySetup(token: string, code: string): Promise<Response>;
-    /**
-     * Disable TOTP for the authenticated user.
-     *
-     * @param token - The user's current JWT.
-     * @param code - A valid TOTP code to confirm the action.
-     * @returns The raw `Response`.
-     */
-    mfaTotpDisable(token: string, code: string): Promise<Response>;
-    /**
-     * Enable SMS-based MFA for the authenticated user.
-     *
-     * Uses the phone number already associated with the user's account.
-     *
-     * @param token - The user's current JWT.
-     * @returns The raw `Response`.
-     */
-    mfaSmsEnable(token: string): Promise<Response>;
-    /**
-     * Disable SMS-based MFA for the authenticated user.
-     *
-     * @param token - The user's current JWT.
-     * @returns The raw `Response`.
-     */
-    mfaSmsDisable(token: string): Promise<Response>;
-    /**
-     * Generate a new set of single-use MFA backup codes.
-     *
-     * Generating new codes invalidates all previously issued backup codes.
-     *
-     * @param token - The user's current JWT.
-     * @returns The raw `Response` with an array of backup codes.
-     */
-    mfaBackupCodesGenerate(token: string): Promise<Response>;
-    /**
-     * Get the current MFA enrollment status for the authenticated user.
-     *
-     * @param token - The user's current JWT.
-     * @returns The raw `Response` with {@link MfaStatus} data.
-     */
-    mfaStatus(token: string): Promise<Response>;
-    /**
-     * Send an SMS code for MFA verification during the challenge flow.
-     *
-     * @param challenge - The MFA challenge token from the sign-in response.
-     * @returns The raw `Response`.
-     */
-    mfaSmsSendCode(challenge: string): Promise<Response>;
-    /**
-     * Create a new organization.
-     *
-     * @param data - Organization creation data including name, slug, optional image URL, and metadata.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    createOrg(data: {
-        name: string;
-        slug: string;
-        imageUrl?: string;
-        metadata?: Record<string, unknown>;
-    }): Promise<Response>;
-    /**
-     * List all organizations accessible to the current project.
-     *
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    listOrgs(): Promise<Response>;
-    /**
-     * Get a single organization by ID or slug.
-     *
-     * @param orgIdOrSlug - The organization ID or slug.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    getOrg(orgIdOrSlug: string): Promise<Response>;
-    /**
-     * Update an organization's details.
-     *
-     * @param orgIdOrSlug - The organization ID or slug.
-     * @param data - Fields to update. All fields are optional.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    updateOrg(orgIdOrSlug: string, data: {
-        name?: string;
-        slug?: string;
-        imageUrl?: string;
-        maxMembers?: number | null;
-        metadata?: Record<string, unknown>;
-    }): Promise<Response>;
-    /**
-     * Delete an organization.
-     *
-     * @param orgIdOrSlug - The organization ID or slug.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    deleteOrg(orgIdOrSlug: string): Promise<Response>;
-    /**
-     * List all members of an organization.
-     *
-     * @param orgIdOrSlug - The organization ID or slug.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    listOrgMembers(orgIdOrSlug: string): Promise<Response>;
-    /**
-     * Update a member's role within an organization.
-     *
-     * @param orgIdOrSlug - The organization ID or slug.
-     * @param memberId - The member's user ID.
-     * @param data - The new role to assign.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    updateOrgMember(orgIdOrSlug: string, memberId: string, data: {
-        roleKey: string;
-    }): Promise<Response>;
-    /**
-     * Remove a member from an organization.
-     *
-     * @param orgIdOrSlug - The organization ID or slug.
-     * @param memberId - The member's user ID.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    removeOrgMember(orgIdOrSlug: string, memberId: string): Promise<Response>;
-    /**
-     * Invite a user to an organization by email.
-     *
-     * @param orgIdOrSlug - The organization ID or slug.
-     * @param data - The invitee's email and optional role.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    inviteToOrg(orgIdOrSlug: string, data: {
-        email: string;
-        roleKey?: string;
-    }): Promise<Response>;
-    /**
-     * List all pending invitations for an organization.
-     *
-     * @param orgIdOrSlug - The organization ID or slug.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    listOrgInvitations(orgIdOrSlug: string): Promise<Response>;
-    /**
-     * Revoke a pending organization invitation.
-     *
-     * @param orgIdOrSlug - The organization ID or slug.
-     * @param invitationId - The invitation ID to revoke.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    revokeOrgInvitation(orgIdOrSlug: string, invitationId: string): Promise<Response>;
-    /**
-     * Accept an organization invitation using a token.
-     *
-     * @param data - The invitation token received via email.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    acceptOrgInvitation(data: {
-        token: string;
-    }): Promise<Response>;
-    /**
-     * Leave an organization as the current user.
-     *
-     * @param orgIdOrSlug - The organization ID or slug.
-     * @returns The raw `Response` from the AuthGate proxy.
-     */
-    leaveOrg(orgIdOrSlug: string): Promise<Response>;
-    /** The name of the session cookie (default: `"__authgate"`). */
-    get cookieName(): string;
-    /** The name of the OAuth nonce cookie (`"__authgate_nonce"`). */
-    get nonceCookieName(): string;
-    /** The name of the refresh token cookie (`"__authgate_refresh"`). */
-    get refreshTokenCookieName(): string;
-    /** The callback path where OAuth redirects are handled (default: `"/api/auth/callback"`). */
-    get callbackPath(): string;
-    /** The AuthGate service base URL. */
-    get baseUrl(): string;
-    /** Session lifetime in seconds. */
-    get sessionMaxAge(): number;
-    /**
-     * Get cookie options for the session cookie.
-     *
-     * Returns `secure: true` in production, `httpOnly: true` always.
-     */
-    getSessionCookieOptions(): CookieOptions;
-    /**
-     * Get cookie options for the OAuth nonce cookie.
-     *
-     * Short-lived (10 minutes) to match the state TTL.
-     */
-    getNonceCookieOptions(): CookieOptions;
-    /**
-     * Validate the SDK configuration against the AuthGate server.
-     *
-     * Checks that the API key is valid and (optionally) that a callback URL
-     * is registered for the project. This is called automatically by framework
-     * factories (`createAuthGate`, `createAuthRoutes`) and logs errors to the
-     * console — it does NOT throw.
-     *
-     * @param callbackUrl - The full callback URL to check registration for.
-     * @internal
-     */
-    validateConfig(callbackUrl?: string): Promise<void>;
+  private readonly config;
+  private encryptionKey;
+  private stateKey;
+  private keysReady;
+  /**
+   * @param config - Client configuration. See {@link AuthGateConfig}.
+   */
+  constructor(config: AuthGateConfig);
+  private deriveKeys;
+  private getEncryptionKey;
+  private getStateKey;
+  /**
+   * Verify a JWT token against the AuthGate API.
+   *
+   * Makes a server-side `POST /api/v1/token/verify` call using your API key.
+   * Times out after 5 seconds.
+   *
+   * @param token - The JWT token string from the OAuth callback or email/SMS flow.
+   * @returns A {@link TokenVerifyResult} with the user data if valid.
+   * @throws {@link TokenVerificationError} if the request times out.
+   */
+  verifyToken(token: string): Promise<TokenVerifyResult>;
+  /**
+   * Encrypt user data into a session cookie value.
+   *
+   * Uses AES-256-GCM with a key derived from your session secret.
+   * The returned string is safe to store in an httpOnly cookie.
+   *
+   * @param user - The authenticated user to store.
+   * @returns Base64url-encoded encrypted session string.
+   */
+  encryptSession(user: AuthGateUser): Promise<string>;
+  /**
+   * Decrypt a session cookie and return the user if the session is valid.
+   *
+   * Returns `null` if the cookie is expired, tampered with, or encrypted
+   * with a different secret. All failure modes return `null` to prevent
+   * oracle attacks.
+   *
+   * @param cookieValue - The encrypted cookie string.
+   * @returns The user, or `null` if the session is invalid.
+   */
+  decryptSession(cookieValue: string): Promise<AuthGateUser | null>;
+  /**
+   * Decrypt a session cookie and return the full payload (user + timestamps).
+   *
+   * Used internally by middleware to check `iat` for session revalidation.
+   *
+   * @param cookieValue - The encrypted cookie string.
+   * @returns The full session payload, or `null` if invalid.
+   * @internal
+   */
+  decryptSessionPayload(cookieValue: string): Promise<SessionPayload | null>;
+  /**
+   * Create a signed OAuth state parameter and nonce for CSRF protection.
+   *
+   * Store the `nonce` in a short-lived httpOnly cookie and pass `state`
+   * as a query parameter in the OAuth authorization URL.
+   *
+   * @returns `{ state, nonce }` — the state string and its corresponding nonce.
+   */
+  createState(): Promise<{
+    state: string;
+    nonce: string;
+  }>;
+  /**
+   * Verify an OAuth state parameter returned in the callback.
+   *
+   * @param state - The `state` query parameter from the callback.
+   * @param nonce - The nonce from the httpOnly cookie.
+   * @returns `true` if the state is valid and not expired.
+   */
+  verifyState(state: string, nonce: string): Promise<boolean>;
+  /**
+   * Build the OAuth authorization URL for a given provider.
+   *
+   * @param provider - The OAuth provider (e.g. `"google"`, `"github"`).
+   * @param callbackUrl - Your app's callback URL where the user is redirected after auth.
+   * @param options - Optional parameters.
+   * @param options.linkTo - An existing user ID to link this OAuth account to.
+   * @returns The full authorization URL to redirect the user to.
+   * @throws {@link AuthGateError} if the provider is not in {@link SUPPORTED_PROVIDERS}.
+   */
+  getOAuthUrl(provider: OAuthProvider, callbackUrl: string, options?: {
+    state?: string;
+    linkTo?: string;
+    locale?: string;
+  }): Promise<string>;
+  /**
+   * Register a new user with email and password.
+   *
+   * @param data - Signup data including email, password, optional name, and callback URL.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  emailSignup(data: {
+    email: string;
+    password: string;
+    name?: string;
+    callbackUrl: string;
+    locale?: string;
+  }): Promise<Response>;
+  /**
+   * Sign in an existing user with email and password.
+   *
+   * The response may include `mfa_required: true` if the user has MFA enabled,
+   * in which case you should redirect to an MFA verification page.
+   *
+   * @param data - Sign-in data including email, password, and callback URL.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  emailSignin(data: {
+    email: string;
+    password: string;
+    callbackUrl: string;
+    locale?: string;
+  }): Promise<Response>;
+  /**
+   * Send a password reset email to the user.
+   *
+   * @param data - The user's email and the URL to redirect to after clicking the reset link.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  emailForgotPassword(data: {
+    email: string;
+    callbackUrl: string;
+    locale?: string;
+  }): Promise<Response>;
+  /**
+   * Confirm a password reset with the token from the reset email.
+   *
+   * @param data - The reset token and the new password.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  emailResetPassword(data: {
+    token: string;
+    password: string;
+    locale?: string;
+  }): Promise<Response>;
+  /**
+   * Send a magic link email for passwordless authentication.
+   *
+   * @param data - The user's email and callback URL.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  magicLinkSend(data: {
+    email: string;
+    callbackUrl: string;
+    locale?: string;
+  }): Promise<Response>;
+  /**
+   * Verify an email address using a one-time code.
+   *
+   * @param data - The user's email and the verification code.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  emailVerifyCode(data: {
+    email: string;
+    code: string;
+    locale?: string;
+  }): Promise<Response>;
+  /**
+   * Send an SMS verification code to the user's phone number.
+   *
+   * @param data - The phone number (E.164 format) and callback URL.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  smsSendCode(data: {
+    phone: string;
+    callbackUrl: string;
+  }): Promise<Response>;
+  /**
+   * Verify an SMS code and authenticate the user.
+   *
+   * @param data - The phone number, verification code, and callback URL.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  smsVerifyCode(data: {
+    phone: string;
+    code: string;
+    callbackUrl: string;
+  }): Promise<Response>;
+  /**
+   * Exchange a refresh token for a new JWT.
+   *
+   * Refresh tokens are single-use: each call invalidates the token it was
+   * given, so callers must store the `refresh_token` it returns or their next
+   * refresh fails.
+   *
+   * @param refreshToken - The opaque refresh token.
+   * @returns A new JWT, its `expires_in` (seconds) and the rotated
+   * `refresh_token`, or `null` if the refresh token is invalid.
+   */
+  refreshToken(refreshToken: string): Promise<{
+    token: string;
+    refresh_token?: string;
+    expires_in: number;
+  } | null>;
+  /**
+   * Exchange a single-use authorization code (delivered on the callback URL)
+   * for the JWT + refresh token. Codes are one-shot and expire after ~60s.
+   *
+   * @param code - The `code` query parameter from the callback redirect.
+   * @returns The tokens, or `null` if the code is invalid/expired/used.
+   */
+  exchangeCode(code: string): Promise<{
+    token: string;
+    refresh_token?: string;
+    mfa_setup_required?: boolean;
+  } | null>;
+  /**
+   * Revoke a session by its refresh token.
+   *
+   * After revocation, the refresh token can no longer be used to obtain
+   * new JWTs. The user will need to re-authenticate.
+   *
+   * @param refreshToken - The opaque refresh token to revoke.
+   * @returns `true` if the session was revoked, `false` on failure.
+   */
+  revokeSession(refreshToken: string): Promise<boolean>;
+  /**
+   * Verify an MFA code to complete authentication.
+   *
+   * Called after a sign-in response includes `mfa_required: true`.
+   *
+   * @param data - The MFA challenge token, verification code, and method.
+   * @returns The raw `Response` — includes a JWT on success.
+   */
+  mfaVerify(data: {
+    challenge: string;
+    code: string;
+    method: "totp" | "sms" | "backup_code";
+  }): Promise<Response>;
+  /**
+   * Begin TOTP (authenticator app) setup for the authenticated user.
+   *
+   * Requires a valid JWT in the `Authorization: Bearer` header.
+   *
+   * @param token - The user's current JWT.
+   * @returns The raw `Response` with TOTP secret, QR code, and URI.
+   */
+  mfaTotpSetup(token: string): Promise<Response>;
+  /**
+   * Confirm TOTP setup by verifying a code from the authenticator app.
+   *
+   * @param token - The user's current JWT.
+   * @param code - The 6-digit TOTP code from the authenticator app.
+   * @returns The raw `Response` — confirms enrollment on success.
+   */
+  mfaTotpVerifySetup(token: string, code: string): Promise<Response>;
+  /**
+   * Disable TOTP for the authenticated user.
+   *
+   * @param token - The user's current JWT.
+   * @param code - A valid TOTP code to confirm the action.
+   * @returns The raw `Response`.
+   */
+  mfaTotpDisable(token: string, code: string): Promise<Response>;
+  /**
+   * Enable SMS-based MFA for the authenticated user.
+   *
+   * Uses the phone number already associated with the user's account.
+   *
+   * @param token - The user's current JWT.
+   * @returns The raw `Response`.
+   */
+  mfaSmsEnable(token: string): Promise<Response>;
+  /**
+   * Disable SMS-based MFA for the authenticated user.
+   *
+   * @param token - The user's current JWT.
+   * @returns The raw `Response`.
+   */
+  mfaSmsDisable(token: string): Promise<Response>;
+  /**
+   * Generate a new set of single-use MFA backup codes.
+   *
+   * Generating new codes invalidates all previously issued backup codes.
+   *
+   * @param token - The user's current JWT.
+   * @returns The raw `Response` with an array of backup codes.
+   */
+  mfaBackupCodesGenerate(token: string): Promise<Response>;
+  /**
+   * Get the current MFA enrollment status for the authenticated user.
+   *
+   * @param token - The user's current JWT.
+   * @returns The raw `Response` with {@link MfaStatus} data.
+   */
+  mfaStatus(token: string): Promise<Response>;
+  /**
+   * Send an SMS code for MFA verification during the challenge flow.
+   *
+   * @param challenge - The MFA challenge token from the sign-in response.
+   * @returns The raw `Response`.
+   */
+  mfaSmsSendCode(challenge: string): Promise<Response>;
+  /**
+   * Create a new organization.
+   *
+   * @param data - Organization creation data including name, slug, optional image URL, and metadata.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  createOrg(data: {
+    name: string;
+    slug: string;
+    imageUrl?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<Response>;
+  /**
+   * List all organizations accessible to the current project.
+   *
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  listOrgs(): Promise<Response>;
+  /**
+   * Get a single organization by ID or slug.
+   *
+   * @param orgIdOrSlug - The organization ID or slug.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  getOrg(orgIdOrSlug: string): Promise<Response>;
+  /**
+   * Update an organization's details.
+   *
+   * @param orgIdOrSlug - The organization ID or slug.
+   * @param data - Fields to update. All fields are optional.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  updateOrg(orgIdOrSlug: string, data: {
+    name?: string;
+    slug?: string;
+    imageUrl?: string;
+    maxMembers?: number | null;
+    metadata?: Record<string, unknown>;
+  }): Promise<Response>;
+  /**
+   * Delete an organization.
+   *
+   * @param orgIdOrSlug - The organization ID or slug.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  deleteOrg(orgIdOrSlug: string): Promise<Response>;
+  /**
+   * List all members of an organization.
+   *
+   * @param orgIdOrSlug - The organization ID or slug.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  listOrgMembers(orgIdOrSlug: string): Promise<Response>;
+  /**
+   * Update a member's role within an organization.
+   *
+   * @param orgIdOrSlug - The organization ID or slug.
+   * @param memberId - The member's user ID.
+   * @param data - The new role to assign.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  updateOrgMember(orgIdOrSlug: string, memberId: string, data: {
+    roleKey: string;
+  }): Promise<Response>;
+  /**
+   * Remove a member from an organization.
+   *
+   * @param orgIdOrSlug - The organization ID or slug.
+   * @param memberId - The member's user ID.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  removeOrgMember(orgIdOrSlug: string, memberId: string): Promise<Response>;
+  /**
+   * Invite a user to an organization by email.
+   *
+   * @param orgIdOrSlug - The organization ID or slug.
+   * @param data - The invitee's email and optional role.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  inviteToOrg(orgIdOrSlug: string, data: {
+    email: string;
+    roleKey?: string;
+  }): Promise<Response>;
+  /**
+   * List all pending invitations for an organization.
+   *
+   * @param orgIdOrSlug - The organization ID or slug.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  listOrgInvitations(orgIdOrSlug: string): Promise<Response>;
+  /**
+   * Revoke a pending organization invitation.
+   *
+   * @param orgIdOrSlug - The organization ID or slug.
+   * @param invitationId - The invitation ID to revoke.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  revokeOrgInvitation(orgIdOrSlug: string, invitationId: string): Promise<Response>;
+  /**
+   * Accept an organization invitation using a token.
+   *
+   * @param data - The invitation token received via email.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  acceptOrgInvitation(data: {
+    token: string;
+  }): Promise<Response>;
+  /**
+   * Leave an organization as the current user.
+   *
+   * @param orgIdOrSlug - The organization ID or slug.
+   * @returns The raw `Response` from the AuthGate proxy.
+   */
+  leaveOrg(orgIdOrSlug: string): Promise<Response>;
+  /** The name of the session cookie (default: `"__authgate"`). */
+  get cookieName(): string;
+  /** The name of the OAuth nonce cookie (`"__authgate_nonce"`). */
+  get nonceCookieName(): string;
+  /** The name of the refresh token cookie (`"__authgate_refresh"`). */
+  get refreshTokenCookieName(): string;
+  /** The callback path where OAuth redirects are handled (default: `"/api/auth/callback"`). */
+  get callbackPath(): string;
+  /** The AuthGate service base URL. */
+  get baseUrl(): string;
+  /** Session lifetime in seconds. */
+  get sessionMaxAge(): number;
+  /**
+   * Get cookie options for the session cookie.
+   *
+   * Returns `secure: true` in production, `httpOnly: true` always.
+   */
+  getSessionCookieOptions(): CookieOptions;
+  /**
+   * Get cookie options for the OAuth nonce cookie.
+   *
+   * Short-lived (10 minutes) to match the state TTL.
+   */
+  getNonceCookieOptions(): CookieOptions;
+  /**
+   * Validate the SDK configuration against the AuthGate server.
+   *
+   * Checks that the API key is valid and (optionally) that a callback URL
+   * is registered for the project. This is called automatically by framework
+   * factories (`createAuthGate`, `createAuthRoutes`) and logs errors to the
+   * console — it does NOT throw.
+   *
+   * @param callbackUrl - The full callback URL to check registration for.
+   * @internal
+   */
+  validateConfig(callbackUrl?: string): Promise<void>;
 }
 /**
  * Create an {@link AuthGateClient} instance.
@@ -615,7 +632,8 @@ declare class AuthGateClient {
  * @returns A configured {@link AuthGateClient}.
  */
 declare function createAuthGateClient(config: AuthGateConfig): AuthGateClient;
-
+//#endregion
+//#region src/constants.d.ts
 /** Default name for the encrypted session cookie. */
 declare const DEFAULT_COOKIE_NAME = "__authgate";
 /** Cookie name used to store the OAuth CSRF nonce during the authorization flow. */
@@ -637,7 +655,8 @@ declare const STATE_TTL_MS = 600000;
  * Configure provider credentials in the AuthGate dashboard under Providers.
  */
 declare const SUPPORTED_PROVIDERS: OAuthProvider[];
-
+//#endregion
+//#region src/errors.d.ts
 /**
  * Base error class for all AuthGate errors.
  *
@@ -656,7 +675,7 @@ declare const SUPPORTED_PROVIDERS: OAuthProvider[];
  * ```
  */
 declare class AuthGateError extends Error {
-    constructor(message: string);
+  constructor(message: string);
 }
 /**
  * Thrown when JWT token verification fails or times out.
@@ -665,7 +684,7 @@ declare class AuthGateError extends Error {
  * AuthGate API is unreachable within the 5-second timeout.
  */
 declare class TokenVerificationError extends AuthGateError {
-    constructor(message?: string);
+  constructor(message?: string);
 }
 /**
  * Thrown when an encrypted session cookie cannot be decrypted.
@@ -674,7 +693,7 @@ declare class TokenVerificationError extends AuthGateError {
  * tampered with, or the cookie format version is unsupported.
  */
 declare class SessionDecryptionError extends AuthGateError {
-    constructor(message?: string);
+  constructor(message?: string);
 }
 /**
  * Thrown when OAuth state verification fails.
@@ -683,7 +702,7 @@ declare class SessionDecryptionError extends AuthGateError {
  * (older than 10 minutes), or a nonce mismatch.
  */
 declare class InvalidStateError extends AuthGateError {
-    constructor(message?: string);
+  constructor(message?: string);
 }
 /**
  * Thrown when the AuthGate SDK is initialized with invalid configuration.
@@ -692,9 +711,10 @@ declare class InvalidStateError extends AuthGateError {
  * and how to fix it.
  */
 declare class ConfigurationError extends AuthGateError {
-    constructor(message: string);
+  constructor(message: string);
 }
-
+//#endregion
+//#region src/project-config.d.ts
 /**
  * Connection details for the AuthGate API.
  *
@@ -703,8 +723,8 @@ declare class ConfigurationError extends AuthGateError {
  * auto-loads `.env` and `.env.local` before importing the config file.
  */
 type AuthGateConnection = {
-    baseUrl?: string;
-    apiKey?: string;
+  baseUrl?: string;
+  apiKey?: string;
 };
 /**
  * Project-level config shape for `authgate.config.ts`.
@@ -717,31 +737,31 @@ type AuthGateConnection = {
  * so you can reference `process.env` directly.
  */
 interface AuthGateProjectConfig {
-    /**
-     * Connection details for the AuthGate API.
-     *
-     * If omitted, the CLI falls back to `AUTHGATE_URL` and `AUTHGATE_API_KEY`
-     * environment variables.
-     */
-    connection?: AuthGateConnection;
-    /**
-     * Path to the RBAC config file (`authgate.rbac.ts`).
-     *
-     * Overrides auto-discovery. Useful in monorepos where the RBAC config
-     * lives in a different directory than the project root.
-     *
-     * @example `"./packages/api/authgate.rbac.ts"`
-     */
-    rbacConfig?: string;
-    /**
-     * Path to the Billing config file (`authgate.billing.ts`).
-     *
-     * Overrides auto-discovery. Useful in monorepos where the billing config
-     * lives in a different directory than the project root.
-     *
-     * @example `"./packages/api/authgate.billing.ts"`
-     */
-    billingConfig?: string;
+  /**
+   * Connection details for the AuthGate API.
+   *
+   * If omitted, the CLI falls back to `AUTHGATE_URL` and `AUTHGATE_API_KEY`
+   * environment variables.
+   */
+  connection?: AuthGateConnection;
+  /**
+   * Path to the RBAC config file (`authgate.rbac.ts`).
+   *
+   * Overrides auto-discovery. Useful in monorepos where the RBAC config
+   * lives in a different directory than the project root.
+   *
+   * @example `"./packages/api/authgate.rbac.ts"`
+   */
+  rbacConfig?: string;
+  /**
+   * Path to the Billing config file (`authgate.billing.ts`).
+   *
+   * Overrides auto-discovery. Useful in monorepos where the billing config
+   * lives in a different directory than the project root.
+   *
+   * @example `"./packages/api/authgate.billing.ts"`
+   */
+  billingConfig?: string;
 }
 /**
  * Define your project-level AuthGate configuration.
@@ -797,90 +817,91 @@ interface AuthGateProjectConfig {
  * ```
  */
 declare function defineConfig(config: AuthGateProjectConfig): AuthGateProjectConfig;
-
+//#endregion
+//#region src/billing.d.ts
 /** A product/plan in the billing catalog. */
 interface BillingPlan {
-    id: string;
-    name: string;
-    description: string | null;
-    features: string[];
-    prices: BillingPrice[];
+  id: string;
+  name: string;
+  description: string | null;
+  features: string[];
+  prices: BillingPrice[];
 }
 /** A price attached to a plan. */
 interface BillingPrice {
-    id: string;
-    type: "recurring" | "metered" | "tiered";
-    amount: number | null;
-    currency: string;
-    interval: "daily" | "weekly" | "monthly" | "yearly";
-    intervalCount: number;
+  id: string;
+  type: "recurring" | "metered" | "tiered";
+  amount: number | null;
+  currency: string;
+  interval: "daily" | "weekly" | "monthly" | "yearly";
+  intervalCount: number;
 }
 /** A single item within a subscription (price + product). */
 interface BillingSubscriptionItem {
+  id: string;
+  quantity: number;
+  price: BillingPrice;
+  product: {
     id: string;
-    quantity: number;
-    price: BillingPrice;
-    product: {
-        id: string;
-        name: string;
-        description: string | null;
-        features: string[];
-    };
+    name: string;
+    description: string | null;
+    features: string[];
+  };
 }
 /** An active subscription for an end user. */
 interface BillingSubscription {
+  id: string;
+  status: "active" | "past_due" | "canceled" | "paused" | "trialing" | "unpaid";
+  /** Convenience: derived from the first subscription item's product. */
+  plan: {
     id: string;
-    status: "active" | "past_due" | "canceled" | "paused" | "trialing" | "unpaid";
-    /** Convenience: derived from the first subscription item's product. */
-    plan: {
-        id: string;
-        name: string;
-    } | null;
-    /** Convenience: derived from the first subscription item's price. */
-    price: BillingPrice | null;
-    /** The full list of subscription items returned by the API. */
-    items: BillingSubscriptionItem[];
-    currentPeriodStart: string;
-    currentPeriodEnd: string;
-    cancelAtPeriodEnd: boolean;
-    trialEnd: string | null;
+    name: string;
+  } | null;
+  /** Convenience: derived from the first subscription item's price. */
+  price: BillingPrice | null;
+  /** The full list of subscription items returned by the API. */
+  items: BillingSubscriptionItem[];
+  currentPeriodStart: string;
+  currentPeriodEnd: string;
+  cancelAtPeriodEnd: boolean;
+  trialEnd: string | null;
 }
 /** Entitlement data for an end user — what plan they're on and what features they have. */
 interface BillingEntitlement {
-    plan: string | null;
-    features: string[];
-    status: string | null;
-    currentPeriodEnd: string | null;
-    cancelAtPeriodEnd: boolean;
+  plan: string | null;
+  features: string[];
+  status: string | null;
+  currentPeriodEnd: string | null;
+  cancelAtPeriodEnd: boolean;
 }
 /** Typed entitlement detail for a boolean feature. */
 interface BooleanEntitlementDetail {
-    type: "boolean";
-    feature: string;
-    allowed: boolean;
+  type: "boolean";
+  feature: string;
+  allowed: boolean;
 }
 /** Typed entitlement detail for a metered feature. */
 interface MeteredEntitlementDetail {
-    type: "metered";
-    feature: string;
-    allowed: boolean;
-    used: number;
-    limit: number;
-    remaining: number;
+  type: "metered";
+  feature: string;
+  allowed: boolean;
+  used: number;
+  limit: number;
+  remaining: number;
 }
 /** A single feature entitlement detail. */
 type EntitlementDetail = BooleanEntitlementDetail | MeteredEntitlementDetail;
 /** Extended entitlement data with typed feature details. */
 interface BillingEntitlementV2 extends BillingEntitlement {
-    /** Typed feature details with metered usage info. */
-    featureDetails?: Record<string, EntitlementDetail>;
+  /** Typed feature details with metered usage info. */
+  featureDetails?: Record<string, EntitlementDetail>;
 }
 /** A single usage event to report. */
 interface UsageEvent {
-    metric: string;
-    quantity: number;
-    idempotencyKey?: string;
-    timestamp?: string;
+  metric: string;
+  quantity: number;
+  idempotencyKey?: string;
+  timestamp?: string;
 }
 /**
  * Check whether the user's entitlements include a specific plan.
@@ -906,52 +927,53 @@ declare function hasFeature(entitlements: BillingEntitlement | null | undefined,
  * @returns The typed entitlement detail, or a denied boolean detail if not found.
  */
 declare function checkFeature(entitlements: BillingEntitlementV2 | null | undefined, feature: string): EntitlementDetail;
-
+//#endregion
+//#region src/organizations.d.ts
 /** An organization within a project. */
 interface Organization {
-    id: string;
-    name: string;
-    slug: string;
-    imageUrl: string | null;
-    metadata: Record<string, unknown> | null;
-    createdAt: string;
+  id: string;
+  name: string;
+  slug: string;
+  imageUrl: string | null;
+  metadata: Record<string, unknown> | null;
+  createdAt: string;
 }
 /** A role definition with its permissions. */
 interface OrgRole {
-    key: string;
-    name: string;
-    permissions: string[];
+  key: string;
+  name: string;
+  permissions: string[];
 }
 /** The current user's membership in an organization. */
 interface OrgMembership {
-    id: string;
-    orgId: string;
-    role: OrgRole;
-    createdAt: string;
+  id: string;
+  orgId: string;
+  role: OrgRole;
+  createdAt: string;
 }
 /** A member of an organization with user details. */
 interface OrgMember {
-    id: string;
-    endUserId: string;
-    name: string | null;
-    email: string | null;
-    avatarUrl: string | null;
-    role: OrgRole;
-    createdAt: string;
+  id: string;
+  endUserId: string;
+  name: string | null;
+  email: string | null;
+  avatarUrl: string | null;
+  role: OrgRole;
+  createdAt: string;
 }
 /** An invitation to join an organization. */
 interface OrgInvitation {
-    id: string;
-    email: string;
-    roleKey: string | null;
-    status: "pending" | "accepted" | "revoked" | "expired";
-    expiresAt: string;
-    createdAt: string;
+  id: string;
+  email: string;
+  roleKey: string | null;
+  status: "pending" | "accepted" | "revoked" | "expired";
+  expiresAt: string;
+  createdAt: string;
 }
 /** An organization paired with the current user's membership. */
 interface OrgWithMembership {
-    organization: Organization;
-    membership: OrgMembership;
+  organization: Organization;
+  membership: OrgMembership;
 }
 /**
  * Check whether a membership includes a specific permission.
@@ -991,10 +1013,18 @@ declare function hasAnyPermission(membership: OrgMembership | null | undefined,
 declare function hasAllPermissions(membership: OrgMembership | null | undefined, permissions: string[]): boolean;
 /** A user's project-level role assignment (no org required). */
 interface UserRoleAssignment {
-    roleKey: string;
-    roleName: string;
-    permissions: string[];
-    assignedAt: string;
+  roleKey: string;
+  roleName: string;
+  permissions: string[];
+  assignedAt: string;
+  /**
+   * Bumped whenever this user's effective permissions change.
+   *
+   * Optional so an older server that does not send it still parses. A client
+   * caching permissions compares this to decide whether to refetch — see
+   * AuthContextValue.permissions.
+   */
+  permissionsEpoch?: number;
 }
 /**
  * Merge permissions from a project-level role and an org-level role (union).
@@ -1006,5 +1036,5 @@ declare function mergePermissions(projectRole: UserRoleAssignment | null | undef
  * Supports wildcard matching.
  */
 declare function hasMergedPermission(projectRole: UserRoleAssignment | null | undefined, orgMembership: OrgMembership | null | undefined, permission: string): boolean;
-
-export { AuthGateClient, type AuthGateConfig, type AuthGateConnection, AuthGateError, type AuthGateProjectConfig, type AuthGateUser, type BackupCodesResponse, type BillingEntitlement, type BillingEntitlementV2, type BillingPlan, type BillingPrice, type BillingSubscription, type BillingSubscriptionItem, type BooleanEntitlementDetail, ConfigurationError, type CookieOptions, DEFAULT_COOKIE_NAME, type EntitlementDetail, InvalidStateError, type MeteredEntitlementDetail, type MfaChallengeResponse, type MfaStatus, NONCE_COOKIE_NAME, type OAuthProvider, type OrgInvitation, type OrgMember, type OrgMembership, type OrgRole, type OrgWithMembership, type Organization, REFRESH_TOKEN_COOKIE_NAME, SESSION_MAX_AGE, STATE_TTL_MS, SUPPORTED_PROVIDERS, SessionDecryptionError, type SessionPayload, TokenVerificationError, type TokenVerifyResult, type TotpSetupResponse, type UsageEvent, type UserRoleAssignment, checkFeature, createAuthGateClient, defineConfig, hasAllPermissions, hasAnyPermission, hasFeature, hasMergedPermission, hasPermission, hasPlan, hasRole, mergePermissions };
+//#endregion
+export { AuthGateClient, type AuthGateConfig, type AuthGateConnection, AuthGateError, type AuthGateProjectConfig, type AuthGateUser, type BackupCodesResponse, type BillingEntitlement, type BillingEntitlementV2, type BillingPlan, type BillingPrice, type BillingSubscription, type BillingSubscriptionItem, type BooleanEntitlementDetail, ConfigurationError, type CookieOptions, DEFAULT_COOKIE_NAME, type EntitlementDetail, InvalidStateError, type MeteredEntitlementDetail, type MfaChallengeResponse, type MfaStatus, NONCE_COOKIE_NAME, type OAuthProvider, type OrgInvitation, type OrgMember, type OrgMembership, type OrgRole, type OrgWithMembership, type Organization, REFRESH_TOKEN_COOKIE_NAME, SESSION_MAX_AGE, STATE_TTL_MS, SUPPORTED_PROVIDERS, SessionDecryptionError, type SessionPayload, TokenVerificationError, type TokenVerifyResult, type TotpSetupResponse, type UsageEvent, type UserRoleAssignment, checkFeature, createAuthGateClient, defineConfig, hasAllPermissions, hasAnyPermission, hasFeature, hasMergedPermission, hasPermission, hasPlan, hasRole, mergePermissions };