@auth-gate/core 0.1.0

package/dist/index.cjs

@@ -0,0 +1,911 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthGateClient: () => AuthGateClient,
+  AuthGateError: () => AuthGateError,
+  DEFAULT_COOKIE_NAME: () => DEFAULT_COOKIE_NAME,
+  InvalidStateError: () => InvalidStateError,
+  NONCE_COOKIE_NAME: () => NONCE_COOKIE_NAME,
+  REFRESH_TOKEN_COOKIE_NAME: () => REFRESH_TOKEN_COOKIE_NAME,
+  SESSION_MAX_AGE: () => SESSION_MAX_AGE,
+  STATE_TTL_MS: () => STATE_TTL_MS,
+  SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
+  SessionDecryptionError: () => SessionDecryptionError,
+  TokenVerificationError: () => TokenVerificationError,
+  createAuthGateClient: () => createAuthGateClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/crypto/encoding.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function toBase64Url(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(str) {
+  const base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function toHex(bytes) {
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+function encodeUtf8(str) {
+  return encoder.encode(str);
+}
+function decodeUtf8(bytes) {
+  return decoder.decode(bytes);
+}
+function concat(...arrays) {
+  let length = 0;
+  for (const arr of arrays) length += arr.length;
+  const result = new Uint8Array(length);
+  let offset = 0;
+  for (const arr of arrays) {
+    result.set(arr, offset);
+    offset += arr.length;
+  }
+  return result;
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a[i] ^ b[i];
+  }
+  return diff === 0;
+}
+
+// src/crypto/keys.ts
+async function hkdfDerive(secret, info, keylen) {
+  const ikm = encodeUtf8(secret);
+  const baseKey = await crypto.subtle.importKey("raw", ikm, "HKDF", false, [
+    "deriveBits"
+  ]);
+  const bits = await crypto.subtle.deriveBits(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: new Uint8Array(0),
+      info: encodeUtf8(info)
+    },
+    baseKey,
+    keylen * 8
+  );
+  return new Uint8Array(bits);
+}
+async function deriveEncryptionKey(secret) {
+  return hkdfDerive(secret, "authgate-session-encryption", 32);
+}
+async function deriveStateKey(secret) {
+  return hkdfDerive(secret, "authgate-state-signing", 32);
+}
+
+// src/constants.ts
+var DEFAULT_COOKIE_NAME = "__authgate";
+var NONCE_COOKIE_NAME = "__authgate_nonce";
+var REFRESH_TOKEN_COOKIE_NAME = "__authgate_refresh";
+var SESSION_MAX_AGE = 604800;
+var STATE_TTL_MS = 6e5;
+var SUPPORTED_PROVIDERS = [
+  "google",
+  "github",
+  "discord",
+  "azure",
+  "apple"
+];
+
+// src/crypto/session.ts
+var VERSION = 1;
+async function encryptSession(key, user, maxAge = SESSION_MAX_AGE) {
+  const now = Math.floor(Date.now() / 1e3);
+  const payload = {
+    user,
+    iat: now,
+    exp: now + maxAge
+  };
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    key,
+    "AES-GCM",
+    false,
+    ["encrypt"]
+  );
+  const plaintext = encodeUtf8(JSON.stringify(payload));
+  const ciphertextWithTag = new Uint8Array(
+    await crypto.subtle.encrypt(
+      { name: "AES-GCM", iv, tagLength: 128 },
+      cryptoKey,
+      plaintext
+    )
+  );
+  const ciphertext = ciphertextWithTag.subarray(
+    0,
+    ciphertextWithTag.length - 16
+  );
+  const authTag = ciphertextWithTag.subarray(ciphertextWithTag.length - 16);
+  const result = concat(new Uint8Array([VERSION]), iv, authTag, ciphertext);
+  return toBase64Url(result);
+}
+async function decryptSessionPayload(key, cookieValue) {
+  try {
+    const data = fromBase64Url(cookieValue);
+    if (data.length < 30) return null;
+    const version = data[0];
+    if (version !== VERSION) return null;
+    const iv = data.subarray(1, 13);
+    const authTag = data.subarray(13, 29);
+    const ciphertext = data.subarray(29);
+    const ciphertextWithTag = concat(ciphertext, authTag);
+    const cryptoKey = await crypto.subtle.importKey(
+      "raw",
+      key,
+      "AES-GCM",
+      false,
+      ["decrypt"]
+    );
+    const decrypted = new Uint8Array(
+      await crypto.subtle.decrypt(
+        { name: "AES-GCM", iv, tagLength: 128 },
+        cryptoKey,
+        ciphertextWithTag
+      )
+    );
+    const payload = JSON.parse(decodeUtf8(decrypted));
+    const now = Math.floor(Date.now() / 1e3);
+    if (payload.exp <= now) return null;
+    return payload;
+  } catch (e) {
+    return null;
+  }
+}
+async function decryptSession(key, cookieValue) {
+  var _a;
+  const payload = await decryptSessionPayload(key, cookieValue);
+  return (_a = payload == null ? void 0 : payload.user) != null ? _a : null;
+}
+
+// src/crypto/state.ts
+async function createOAuthState(signingKey) {
+  const nonceBytes = crypto.getRandomValues(new Uint8Array(16));
+  const nonce = toHex(nonceBytes);
+  const timestamp = Date.now().toString();
+  const payload = `${nonce}.${timestamp}`;
+  const key = await crypto.subtle.importKey(
+    "raw",
+    signingKey,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sigBytes = new Uint8Array(
+    await crypto.subtle.sign("HMAC", key, encodeUtf8(payload))
+  );
+  const signature = toHex(sigBytes);
+  return {
+    state: `${payload}.${signature}`,
+    nonce
+  };
+}
+async function verifyOAuthState(state, nonce, signingKey) {
+  try {
+    const parts = state.split(".");
+    if (parts.length !== 3) return false;
+    const [stateNonce, timestamp, signature] = parts;
+    const nonceBuf = encodeUtf8(stateNonce);
+    const expectedNonceBuf = encodeUtf8(nonce);
+    if (nonceBuf.length !== expectedNonceBuf.length) return false;
+    if (!constantTimeEqual(nonceBuf, expectedNonceBuf)) return false;
+    const stateTime = parseInt(timestamp, 10);
+    if (isNaN(stateTime) || Date.now() - stateTime > STATE_TTL_MS) return false;
+    const payload = `${stateNonce}.${timestamp}`;
+    const key = await crypto.subtle.importKey(
+      "raw",
+      signingKey,
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["verify"]
+    );
+    const sigBytes = new Uint8Array(signature.length / 2);
+    for (let i = 0; i < signature.length; i += 2) {
+      sigBytes[i / 2] = parseInt(signature.substring(i, i + 2), 16);
+    }
+    return crypto.subtle.verify(
+      "HMAC",
+      key,
+      sigBytes,
+      encodeUtf8(payload)
+    );
+  } catch (e) {
+    return false;
+  }
+}
+
+// src/errors.ts
+var AuthGateError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AuthGateError";
+  }
+};
+var TokenVerificationError = class extends AuthGateError {
+  constructor(message = "Token verification failed") {
+    super(message);
+    this.name = "TokenVerificationError";
+  }
+};
+var SessionDecryptionError = class extends AuthGateError {
+  constructor(message = "Session decryption failed") {
+    super(message);
+    this.name = "SessionDecryptionError";
+  }
+};
+var InvalidStateError = class extends AuthGateError {
+  constructor(message = "Invalid OAuth state") {
+    super(message);
+    this.name = "InvalidStateError";
+  }
+};
+
+// src/client.ts
+var AuthGateClient = class {
+  /**
+   * @param config - Client configuration. See {@link AuthGateConfig}.
+   * @throws {@link AuthGateError} if `sessionSecret` is shorter than 32 characters.
+   */
+  constructor(config) {
+    this.encryptionKey = null;
+    this.stateKey = null;
+    var _a, _b, _c;
+    if (!config.sessionSecret || config.sessionSecret.length < 32) {
+      throw new AuthGateError(
+        "sessionSecret must be at least 32 characters long"
+      );
+    }
+    this.config = __spreadProps(__spreadValues({}, config), {
+      cookieName: (_a = config.cookieName) != null ? _a : DEFAULT_COOKIE_NAME,
+      sessionMaxAge: (_b = config.sessionMaxAge) != null ? _b : SESSION_MAX_AGE,
+      callbackPath: (_c = config.callbackPath) != null ? _c : "/api/auth/callback"
+    });
+    this.keysReady = this.deriveKeys();
+  }
+  async deriveKeys() {
+    const [encKey, stKey] = await Promise.all([
+      deriveEncryptionKey(this.config.sessionSecret),
+      deriveStateKey(this.config.sessionSecret)
+    ]);
+    this.encryptionKey = encKey;
+    this.stateKey = stKey;
+  }
+  async getEncryptionKey() {
+    await this.keysReady;
+    return this.encryptionKey;
+  }
+  async getStateKey() {
+    await this.keysReady;
+    return this.stateKey;
+  }
+  // ---------------------------------------------------------------------------
+  // Token verification
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async verifyToken(token) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5e3);
+    try {
+      const response = await fetch(
+        `${this.config.baseUrl}/api/v1/token/verify`,
+        {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({ token }),
+          signal: controller.signal
+        }
+      );
+      if (!response.ok) {
+        return { valid: false, error: `HTTP ${response.status}` };
+      }
+      return response.json();
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new TokenVerificationError("Token verification timed out");
+      }
+      return { valid: false, error: "Network error" };
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Session encryption
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async encryptSession(user) {
+    const key = await this.getEncryptionKey();
+    return await encryptSession(key, user, this.config.sessionMaxAge);
+  }
+  /**
+   * 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.
+   */
+  async decryptSession(cookieValue) {
+    const key = await this.getEncryptionKey();
+    return await decryptSession(key, cookieValue);
+  }
+  /**
+   * 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
+   */
+  async decryptSessionPayload(cookieValue) {
+    const key = await this.getEncryptionKey();
+    return await decryptSessionPayload(key, cookieValue);
+  }
+  // ---------------------------------------------------------------------------
+  // OAuth state
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async createState() {
+    const key = await this.getStateKey();
+    return await createOAuthState(key);
+  }
+  /**
+   * 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.
+   */
+  async verifyState(state, nonce) {
+    const key = await this.getStateKey();
+    return await verifyOAuthState(state, nonce, key);
+  }
+  // ---------------------------------------------------------------------------
+  // URL builders
+  // ---------------------------------------------------------------------------
+  /**
+   * 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, callbackUrl, options) {
+    if (!SUPPORTED_PROVIDERS.includes(provider)) {
+      throw new AuthGateError(`Unsupported provider: ${provider}`);
+    }
+    const url = new URL(`/api/proxy/${provider}`, this.config.baseUrl);
+    url.searchParams.set("project_id", this.config.projectId);
+    url.searchParams.set("callback_url", callbackUrl);
+    if (options == null ? void 0 : options.linkTo) {
+      url.searchParams.set("link_to", options.linkTo);
+    }
+    return url.toString();
+  }
+  // ---------------------------------------------------------------------------
+  // Email auth
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async emailSignup(data) {
+    return fetch(`${this.config.baseUrl}/api/proxy/email/signup`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        email: data.email,
+        password: data.password,
+        name: data.name,
+        project_id: this.config.projectId,
+        callback_url: data.callbackUrl
+      })
+    });
+  }
+  /**
+   * 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.
+   */
+  async emailSignin(data) {
+    return fetch(`${this.config.baseUrl}/api/proxy/email/signin`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        email: data.email,
+        password: data.password,
+        project_id: this.config.projectId,
+        callback_url: data.callbackUrl
+      })
+    });
+  }
+  /**
+   * 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.
+   */
+  async emailForgotPassword(data) {
+    return fetch(`${this.config.baseUrl}/api/proxy/email/reset-password`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        email: data.email,
+        project_id: this.config.projectId,
+        callback_url: data.callbackUrl
+      })
+    });
+  }
+  /**
+   * 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.
+   */
+  async emailResetPassword(data) {
+    return fetch(
+      `${this.config.baseUrl}/api/proxy/email/reset-password/confirm`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          token: data.token,
+          password: data.password,
+          project_id: this.config.projectId
+        })
+      }
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // Magic link auth
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async magicLinkSend(data) {
+    return fetch(
+      `${this.config.baseUrl}/api/proxy/email/magic-link/send`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          email: data.email,
+          project_id: this.config.projectId,
+          callback_url: data.callbackUrl
+        })
+      }
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // Email verification
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async emailVerifyCode(data) {
+    return fetch(`${this.config.baseUrl}/api/proxy/email/verify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        email: data.email,
+        code: data.code,
+        project_id: this.config.projectId
+      })
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // SMS auth
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async smsSendCode(data) {
+    return fetch(`${this.config.baseUrl}/api/proxy/sms/send-code`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        phone: data.phone,
+        project_id: this.config.projectId,
+        callback_url: data.callbackUrl
+      })
+    });
+  }
+  /**
+   * 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.
+   */
+  async smsVerifyCode(data) {
+    return fetch(`${this.config.baseUrl}/api/proxy/sms/verify-code`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        phone: data.phone,
+        code: data.code,
+        project_id: this.config.projectId,
+        callback_url: data.callbackUrl
+      })
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Session management
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async refreshToken(refreshToken) {
+    try {
+      const response = await fetch(
+        `${this.config.baseUrl}/api/proxy/token/refresh`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            refresh_token: refreshToken,
+            project_id: this.config.projectId
+          })
+        }
+      );
+      if (!response.ok) return null;
+      return response.json();
+    } catch (e) {
+      return 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.
+   */
+  async revokeSession(refreshToken) {
+    try {
+      const response = await fetch(
+        `${this.config.baseUrl}/api/proxy/sessions/revoke`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            refresh_token: refreshToken,
+            project_id: this.config.projectId
+          })
+        }
+      );
+      return response.ok;
+    } catch (e) {
+      return false;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // MFA
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async mfaVerify(data) {
+    return fetch(`${this.config.baseUrl}/api/proxy/mfa/verify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(__spreadProps(__spreadValues({}, data), {
+        project_id: this.config.projectId
+      }))
+    });
+  }
+  /**
+   * 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.
+   */
+  async mfaTotpSetup(token) {
+    return fetch(`${this.config.baseUrl}/api/proxy/mfa/totp/setup`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: "{}"
+    });
+  }
+  /**
+   * 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.
+   */
+  async mfaTotpVerifySetup(token, code) {
+    return fetch(`${this.config.baseUrl}/api/proxy/mfa/totp/verify-setup`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ code })
+    });
+  }
+  /**
+   * 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`.
+   */
+  async mfaTotpDisable(token, code) {
+    return fetch(`${this.config.baseUrl}/api/proxy/mfa/totp`, {
+      method: "DELETE",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ code })
+    });
+  }
+  /**
+   * 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`.
+   */
+  async mfaSmsEnable(token) {
+    return fetch(`${this.config.baseUrl}/api/proxy/mfa/sms/enable`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: "{}"
+    });
+  }
+  /**
+   * Disable SMS-based MFA for the authenticated user.
+   *
+   * @param token - The user's current JWT.
+   * @returns The raw `Response`.
+   */
+  async mfaSmsDisable(token) {
+    return fetch(`${this.config.baseUrl}/api/proxy/mfa/sms`, {
+      method: "DELETE",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: "{}"
+    });
+  }
+  /**
+   * 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.
+   */
+  async mfaBackupCodesGenerate(token) {
+    return fetch(
+      `${this.config.baseUrl}/api/proxy/mfa/backup-codes/generate`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json"
+        },
+        body: "{}"
+      }
+    );
+  }
+  /**
+   * 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.
+   */
+  async mfaStatus(token) {
+    return fetch(`${this.config.baseUrl}/api/proxy/mfa/status`, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${token}` }
+    });
+  }
+  /**
+   * 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`.
+   */
+  async mfaSmsSendCode(challenge) {
+    return fetch(`${this.config.baseUrl}/api/proxy/mfa/sms/send-code`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        challenge,
+        project_id: this.config.projectId
+      })
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Cookie config accessors
+  // ---------------------------------------------------------------------------
+  /** The name of the session cookie (default: `"__authgate"`). */
+  get cookieName() {
+    return this.config.cookieName;
+  }
+  /** The name of the OAuth nonce cookie (`"__authgate_nonce"`). */
+  get nonceCookieName() {
+    return NONCE_COOKIE_NAME;
+  }
+  /** The name of the refresh token cookie (`"__authgate_refresh"`). */
+  get refreshTokenCookieName() {
+    return REFRESH_TOKEN_COOKIE_NAME;
+  }
+  /** The callback path where OAuth redirects are handled (default: `"/api/auth/callback"`). */
+  get callbackPath() {
+    return this.config.callbackPath;
+  }
+  /** The AuthGate project ID. */
+  get projectId() {
+    return this.config.projectId;
+  }
+  /** The AuthGate service base URL. */
+  get baseUrl() {
+    return this.config.baseUrl;
+  }
+  /** Session lifetime in seconds. */
+  get sessionMaxAge() {
+    return this.config.sessionMaxAge;
+  }
+  /**
+   * Get cookie options for the session cookie.
+   *
+   * Returns `secure: true` in production, `httpOnly: true` always.
+   */
+  getSessionCookieOptions() {
+    return {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === "production",
+      sameSite: "lax",
+      maxAge: this.config.sessionMaxAge,
+      path: "/"
+    };
+  }
+  /**
+   * Get cookie options for the OAuth nonce cookie.
+   *
+   * Short-lived (10 minutes) to match the state TTL.
+   */
+  getNonceCookieOptions() {
+    return {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === "production",
+      sameSite: "lax",
+      maxAge: 600,
+      // 10 minutes
+      path: "/"
+    };
+  }
+};
+function createAuthGateClient(config) {
+  return new AuthGateClient(config);
+}