@auth-gate/core 0.14.0 → 0.15.1

package/dist/index.mjs

@@ -1,1322 +1,1431 @@
-var __defProp = Object.defineProperty;
-var __defProps = Object.defineProperties;
-var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
-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));
-
-// src/crypto/encoding.ts
-var encoder = new TextEncoder();
-var decoder = new TextDecoder();
+//#region src/crypto/encoding.ts
+/**
+* Low-level encoding utilities used internally by the crypto layer.
+*
+* These functions are not exported from the public API — they exist to
+* avoid dependencies on Node.js `Buffer` so the package works in
+* Edge Runtime, Cloudflare Workers, and browsers.
+*
+* @internal
+* @module
+*/
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/** Encode a `Uint8Array` to a URL-safe Base64 string (no padding). */
 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(/=+$/, "");
+	let binary = "";
+	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
+/** Decode a URL-safe Base64 string back to a `Uint8Array`. */
 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;
+	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;
 }
+/** Encode a `Uint8Array` to a lowercase hex string. */
 function toHex(bytes) {
-  let hex = "";
-  for (let i = 0; i < bytes.length; i++) {
-    hex += bytes[i].toString(16).padStart(2, "0");
-  }
-  return hex;
+	let hex = "";
+	for (let i = 0; i < bytes.length; i++) hex += bytes[i].toString(16).padStart(2, "0");
+	return hex;
 }
+/** Encode a UTF-8 string to a `Uint8Array`. */
 function encodeUtf8(str) {
-  return encoder.encode(str);
+	return encoder.encode(str);
 }
+/** Decode a `Uint8Array` to a UTF-8 string. */
 function decodeUtf8(bytes) {
-  return decoder.decode(bytes);
+	return decoder.decode(bytes);
 }
+/** Concatenate multiple `Uint8Array` buffers into a single buffer. */
 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;
+	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;
 }
+/**
+* Constant-time comparison of two byte arrays.
+*
+* Prevents timing side-channel attacks by always comparing every byte
+* regardless of where the first difference occurs.
+*/
 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;
+	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
+//#endregion
+//#region src/crypto/keys.ts
+/**
+* Key derivation using HKDF-SHA256 via the Web Crypto API.
+*
+* Derives deterministic, purpose-specific keys from the user's API key.
+* Each key uses a distinct `info` label so that a single secret produces
+* independent keys for encryption vs. signing.
+*
+* @internal
+* @module
+*/
+/**
+* Derive a key from a secret using HKDF-SHA256.
+*
+* @param secret - The input key material (the user's API key).
+* @param info - A context string that differentiates derived keys.
+* @param keylen - Desired key length in bytes.
+* @returns A `Uint8Array` of `keylen` bytes.
+*/
 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);
+	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: /* @__PURE__ */ new Uint8Array(0),
+		info: encodeUtf8(info)
+	}, baseKey, keylen * 8);
+	return new Uint8Array(bits);
 }
+/**
+* Derive a 256-bit AES-GCM encryption key for session cookies.
+*
+* Uses the info label `"authgate-session-encryption"` to ensure this key
+* is distinct from the state signing key.
+*
+* @param secret - The API key.
+* @returns A 32-byte encryption key.
+*/
 async function deriveEncryptionKey(secret) {
-  return hkdfDerive(secret, "authgate-session-encryption", 32);
+	return hkdfDerive(secret, "authgate-session-encryption", 32);
 }
+/**
+* Derive a 256-bit HMAC-SHA256 signing key for OAuth state parameters.
+*
+* Uses the info label `"authgate-state-signing"` to ensure this key
+* is distinct from the session encryption key.
+*
+* @param secret - The API key.
+* @returns A 32-byte signing key.
+*/
 async function deriveStateKey(secret) {
-  return hkdfDerive(secret, "authgate-state-signing", 32);
+	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"
+//#endregion
+//#region src/constants.ts
+/** Default name for the encrypted session cookie. */
+const DEFAULT_COOKIE_NAME = "__authgate";
+/** Cookie name used to store the OAuth CSRF nonce during the authorization flow. */
+const NONCE_COOKIE_NAME = "__authgate_nonce";
+/** Cookie name used to store the opaque refresh token. */
+const REFRESH_TOKEN_COOKIE_NAME = "__authgate_refresh";
+/**
+* Default session lifetime in seconds (7 days).
+*
+* Can be overridden per-client via {@link AuthGateConfig.sessionMaxAge}
+* or per-project in the AuthGate dashboard under Settings > Session Duration.
+*/
+const SESSION_MAX_AGE = 604800;
+/** Maximum age of an OAuth state parameter before it is considered expired (10 minutes). */
+const STATE_TTL_MS = 6e5;
+/**
+* List of OAuth providers supported by AuthGate.
+*
+* Configure provider credentials in the AuthGate dashboard under Providers.
+*/
+const SUPPORTED_PROVIDERS = [
+	"google",
+	"github",
+	"discord",
+	"azure",
+	"apple"
 ];
-
-// src/crypto/session.ts
-var VERSION = 1;
+//#endregion
+//#region src/crypto/session.ts
+/** Current wire format version. Increment when the binary layout changes. */
+const VERSION = 1;
+/**
+* Encrypt a user object into a session cookie value.
+*
+* Creates a {@link SessionPayload} with `iat`/`exp` timestamps, encrypts it
+* with AES-256-GCM, and returns a Base64url-encoded string suitable for
+* storing in an HTTP cookie.
+*
+* @param key - 32-byte AES-GCM key from {@link deriveEncryptionKey}.
+* @param user - The authenticated user to store in the session.
+* @param maxAge - Session lifetime in seconds. Defaults to {@link SESSION_MAX_AGE}.
+* @returns Base64url-encoded encrypted session string.
+*/
 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);
+	const now = Math.floor(Date.now() / 1e3);
+	const payload = {
+		user,
+		iat: now,
+		exp: now + maxAge
+	};
+	const iv = crypto.getRandomValues(/* @__PURE__ */ 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);
+	return toBase64Url(concat(new Uint8Array([VERSION]), iv, authTag, ciphertext));
 }
+/**
+* Decrypt a session cookie and return the full payload if valid.
+*
+* Returns `null` for any failure (expired, tampered, wrong key, malformed)
+* to prevent oracle attacks — all failures are observationally identical.
+*
+* @param key - 32-byte AES-GCM key from {@link deriveEncryptionKey}.
+* @param cookieValue - The Base64url-encoded encrypted session string.
+* @returns The full session payload, or `null` if the session is invalid/expired.
+* @internal
+*/
 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;
-  }
+	try {
+		const data = fromBase64Url(cookieValue);
+		if (data.length < 30) return null;
+		if (data[0] !== VERSION) return null;
+		const iv = data.subarray(1, 13);
+		const authTag = data.subarray(13, 29);
+		const ciphertextWithTag = concat(data.subarray(29), 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 {
+		return null;
+	}
 }
+/**
+* Decrypt a session cookie value and return the user if the session is still valid.
+*
+* Returns `null` for any failure (expired, tampered, wrong key, malformed)
+* to prevent oracle attacks — all failures are observationally identical.
+*
+* @param key - 32-byte AES-GCM key from {@link deriveEncryptionKey}.
+* @param cookieValue - The Base64url-encoded encrypted session string.
+* @returns The authenticated user, or `null` if the session is invalid/expired.
+*/
 async function decryptSession(key, cookieValue) {
-  var _a;
-  const payload = await decryptSessionPayload(key, cookieValue);
-  return (_a = payload == null ? void 0 : payload.user) != null ? _a : null;
+	return (await decryptSessionPayload(key, cookieValue))?.user ?? null;
 }
-
-// src/crypto/state.ts
+//#endregion
+//#region src/crypto/state.ts
+/**
+* OAuth state parameter creation and verification.
+*
+* The state parameter prevents CSRF attacks during the OAuth authorization
+* flow. It combines a random nonce with a timestamp and HMAC-SHA256
+* signature:
+*
+* ```
+* state = "{nonce}.{timestamp}.{hmac_hex}"
+* ```
+*
+* The nonce is stored in a short-lived httpOnly cookie and compared against
+* the state returned by the OAuth provider's callback.
+*
+* @internal
+* @module
+*/
+/**
+* Create a signed OAuth state parameter and its corresponding nonce.
+*
+* The nonce should be stored in a short-lived cookie (`__authgate_nonce`)
+* and the state should be passed as the `state` query parameter in the
+* OAuth authorization URL.
+*
+* @param signingKey - 32-byte HMAC key from {@link deriveStateKey}.
+* @returns An object with `state` (the full signed string) and `nonce` (hex-encoded random bytes).
+*/
 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
-  };
+	const nonce = toHex(crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16)));
+	const payload = `${nonce}.${Date.now().toString()}`;
+	const key = await crypto.subtle.importKey("raw", signingKey, {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return {
+		state: `${payload}.${toHex(new Uint8Array(await crypto.subtle.sign("HMAC", key, encodeUtf8(payload))))}`,
+		nonce
+	};
 }
+/**
+* Verify an OAuth state parameter against the stored nonce.
+*
+* Performs three checks:
+* 1. **Nonce match** — constant-time comparison against the cookie nonce.
+* 2. **TTL check** — the state must be younger than {@link STATE_TTL_MS} (10 min).
+* 3. **HMAC verification** — via `crypto.subtle.verify` (timing-safe).
+*
+* @param state - The `state` query parameter from the OAuth callback.
+* @param nonce - The nonce value from the `__authgate_nonce` cookie.
+* @param signingKey - 32-byte HMAC key from {@link deriveStateKey}.
+* @returns `true` if all checks pass, `false` otherwise.
+*/
 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;
-  }
+	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 > 6e5) 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 {
+		return false;
+	}
 }
-
-// src/errors.ts
+//#endregion
+//#region src/errors.ts
+/**
+* Base error class for all AuthGate errors.
+*
+* All errors thrown by the `@auth-gate/*` packages extend this class,
+* so you can catch `AuthGateError` to handle any AuthGate-specific failure.
+*
+* @example
+* ```ts
+* try {
+*   await client.verifyToken(token);
+* } catch (err) {
+*   if (err instanceof AuthGateError) {
+*     console.error("AuthGate error:", err.message);
+*   }
+* }
+* ```
+*/
 var AuthGateError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "AuthGateError";
-  }
+	constructor(message) {
+		super(message);
+		this.name = "AuthGateError";
+	}
 };
+/**
+* Thrown when JWT token verification fails or times out.
+*
+* This can occur when the token is malformed, expired, or the
+* AuthGate API is unreachable within the 5-second timeout.
+*/
 var TokenVerificationError = class extends AuthGateError {
-  constructor(message = "Token verification failed") {
-    super(message);
-    this.name = "TokenVerificationError";
-  }
+	constructor(message = "Token verification failed") {
+		super(message);
+		this.name = "TokenVerificationError";
+	}
 };
+/**
+* Thrown when an encrypted session cookie cannot be decrypted.
+*
+* Common causes: the session secret was rotated, the cookie was
+* tampered with, or the cookie format version is unsupported.
+*/
 var SessionDecryptionError = class extends AuthGateError {
-  constructor(message = "Session decryption failed") {
-    super(message);
-    this.name = "SessionDecryptionError";
-  }
+	constructor(message = "Session decryption failed") {
+		super(message);
+		this.name = "SessionDecryptionError";
+	}
 };
+/**
+* Thrown when OAuth state verification fails.
+*
+* This indicates a potential CSRF attack, an expired state parameter
+* (older than 10 minutes), or a nonce mismatch.
+*/
 var InvalidStateError = class extends AuthGateError {
-  constructor(message = "Invalid OAuth state") {
-    super(message);
-    this.name = "InvalidStateError";
-  }
+	constructor(message = "Invalid OAuth state") {
+		super(message);
+		this.name = "InvalidStateError";
+	}
 };
+/**
+* Thrown when the AuthGate SDK is initialized with invalid configuration.
+*
+* Check the error message for details on which config field is invalid
+* and how to fix it.
+*/
 var ConfigurationError = class extends AuthGateError {
-  constructor(message) {
-    super(message);
-    this.name = "ConfigurationError";
-  }
+	constructor(message) {
+		super(message);
+		this.name = "ConfigurationError";
+	}
 };
-
-// src/client.ts
+//#endregion
+//#region src/client.ts
+/**
+* Core client for interacting with the AuthGate authentication proxy.
+*
+* Handles token verification, session cookie encryption/decryption,
+* OAuth state management, and all proxy API calls (email, SMS, MFA).
+*
+* Use {@link createAuthGateClient} for a convenient factory function,
+* or instantiate directly with `new AuthGateClient(config)`.
+*
+* @example
+* ```ts
+* const client = new AuthGateClient({
+*   apiKey: process.env.AUTHGATE_API_KEY!,
+*   baseUrl: "https://www.authgate.dev",
+* });
+* ```
+*/
 var AuthGateClient = class {
-  /**
-   * @param config - Client configuration. See {@link AuthGateConfig}.
-   */
-  constructor(config) {
-    this.encryptionKey = null;
-    this.stateKey = null;
-    var _a, _b, _c;
-    if (!config.apiKey || typeof config.apiKey !== "string" || config.apiKey.trim() === "") {
-      throw new ConfigurationError(
-        "[AuthGate] Missing or empty `apiKey`. Get your API key from the AuthGate dashboard \u2192 Project \u2192 API Key."
-      );
-    }
-    if (!config.baseUrl || typeof config.baseUrl !== "string" || config.baseUrl.trim() === "") {
-      throw new ConfigurationError(
-        '[AuthGate] Missing or empty `baseUrl`. Set this to your AuthGate service URL (e.g. "https://www.authgate.dev").'
-      );
-    }
-    try {
-      new URL(config.baseUrl);
-    } catch (e) {
-      throw new ConfigurationError(
-        `[AuthGate] Invalid \`baseUrl\`: "${config.baseUrl}". Must be a valid URL (e.g. "https://www.authgate.dev").`
-      );
-    }
-    if (config.callbackPath !== void 0 && !config.callbackPath.startsWith("/")) {
-      throw new ConfigurationError(
-        `[AuthGate] Invalid \`callbackPath\`: "${config.callbackPath}". Must start with "/" (e.g. "/api/auth/callback").`
-      );
-    }
-    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.apiKey),
-      deriveStateKey(this.config.apiKey)
-    ]);
-    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}.
-   */
-  async getOAuthUrl(provider, callbackUrl, options) {
-    if (!SUPPORTED_PROVIDERS.includes(provider)) {
-      throw new AuthGateError(`Unsupported provider: ${provider}`);
-    }
-    const response = await fetch(
-      `${this.config.baseUrl}/api/proxy/${provider}`,
-      {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.config.apiKey}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(__spreadValues({
-          callback_url: callbackUrl,
-          state: options == null ? void 0 : options.state,
-          link_to: options == null ? void 0 : options.linkTo
-        }, (options == null ? void 0 : options.locale) && { locale: options.locale }))
-      }
-    );
-    if (!response.ok) {
-      const error = await response.json().catch(() => ({}));
-      throw new AuthGateError(
-        error.error || `OAuth initiation failed: ${response.status}`
-      );
-    }
-    const data = await response.json();
-    return data.redirect_url;
-  }
-  // ---------------------------------------------------------------------------
-  // 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: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify(__spreadValues({
-        email: data.email,
-        password: data.password,
-        name: data.name,
-        callback_url: data.callbackUrl
-      }, data.locale && { locale: data.locale }))
-    });
-  }
-  /**
-   * 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: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify(__spreadValues({
-        email: data.email,
-        password: data.password,
-        callback_url: data.callbackUrl
-      }, data.locale && { locale: data.locale }))
-    });
-  }
-  /**
-   * 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: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify(__spreadValues({
-        email: data.email,
-        callback_url: data.callbackUrl
-      }, data.locale && { locale: data.locale }))
-    });
-  }
-  /**
-   * 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: {
-          Authorization: `Bearer ${this.config.apiKey}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(__spreadValues({
-          token: data.token,
-          password: data.password
-        }, data.locale && { locale: data.locale }))
-      }
-    );
-  }
-  // ---------------------------------------------------------------------------
-  // 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: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify(__spreadValues({
-        email: data.email,
-        callback_url: data.callbackUrl
-      }, data.locale && { locale: data.locale }))
-    });
-  }
-  // ---------------------------------------------------------------------------
-  // 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: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify(__spreadValues({
-        email: data.email,
-        code: data.code
-      }, data.locale && { locale: data.locale }))
-    });
-  }
-  // ---------------------------------------------------------------------------
-  // 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: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        phone: data.phone,
-        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: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        phone: data.phone,
-        code: data.code,
-        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: {
-            Authorization: `Bearer ${this.config.apiKey}`,
-            "Content-Type": "application/json"
-          },
-          body: JSON.stringify({
-            refresh_token: refreshToken
-          })
-        }
-      );
-      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: {
-            Authorization: `Bearer ${this.config.apiKey}`,
-            "Content-Type": "application/json"
-          },
-          body: JSON.stringify({
-            refresh_token: refreshToken
-          })
-        }
-      );
-      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: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify(data)
-    });
-  }
-  /**
-   * 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: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({ challenge })
-    });
-  }
-  // ---------------------------------------------------------------------------
-  // Organizations
-  // ---------------------------------------------------------------------------
-  /**
-   * 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.
-   */
-  async createOrg(data) {
-    return fetch(`${this.config.baseUrl}/api/proxy/orgs`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        name: data.name,
-        slug: data.slug,
-        image_url: data.imageUrl,
-        metadata: data.metadata
-      })
-    });
-  }
-  /**
-   * List all organizations accessible to the current project.
-   *
-   * @returns The raw `Response` from the AuthGate proxy.
-   */
-  async listOrgs() {
-    return fetch(`${this.config.baseUrl}/api/proxy/orgs`, {
-      method: "GET",
-      headers: {
-        Authorization: `Bearer ${this.config.apiKey}`
-      }
-    });
-  }
-  /**
-   * Get a single organization by ID or slug.
-   *
-   * @param orgIdOrSlug - The organization ID or slug.
-   * @returns The raw `Response` from the AuthGate proxy.
-   */
-  async getOrg(orgIdOrSlug) {
-    return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}`, {
-      method: "GET",
-      headers: {
-        Authorization: `Bearer ${this.config.apiKey}`
-      }
-    });
-  }
-  /**
-   * 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.
-   */
-  async updateOrg(orgIdOrSlug, data) {
-    return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}`, {
-      method: "PATCH",
-      headers: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        name: data.name,
-        slug: data.slug,
-        image_url: data.imageUrl,
-        max_members: data.maxMembers,
-        metadata: data.metadata
-      })
-    });
-  }
-  /**
-   * Delete an organization.
-   *
-   * @param orgIdOrSlug - The organization ID or slug.
-   * @returns The raw `Response` from the AuthGate proxy.
-   */
-  async deleteOrg(orgIdOrSlug) {
-    return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}`, {
-      method: "DELETE",
-      headers: {
-        Authorization: `Bearer ${this.config.apiKey}`
-      }
-    });
-  }
-  /**
-   * List all members of an organization.
-   *
-   * @param orgIdOrSlug - The organization ID or slug.
-   * @returns The raw `Response` from the AuthGate proxy.
-   */
-  async listOrgMembers(orgIdOrSlug) {
-    return fetch(
-      `${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/members`,
-      {
-        method: "GET",
-        headers: {
-          Authorization: `Bearer ${this.config.apiKey}`
-        }
-      }
-    );
-  }
-  /**
-   * 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.
-   */
-  async updateOrgMember(orgIdOrSlug, memberId, data) {
-    return fetch(
-      `${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/members/${memberId}`,
-      {
-        method: "PATCH",
-        headers: {
-          Authorization: `Bearer ${this.config.apiKey}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({
-          role_key: data.roleKey
-        })
-      }
-    );
-  }
-  /**
-   * 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.
-   */
-  async removeOrgMember(orgIdOrSlug, memberId) {
-    return fetch(
-      `${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/members/${memberId}`,
-      {
-        method: "DELETE",
-        headers: {
-          Authorization: `Bearer ${this.config.apiKey}`
-        }
-      }
-    );
-  }
-  /**
-   * 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.
-   */
-  async inviteToOrg(orgIdOrSlug, data) {
-    return fetch(
-      `${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/invitations`,
-      {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.config.apiKey}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({
-          email: data.email,
-          role_key: data.roleKey
-        })
-      }
-    );
-  }
-  /**
-   * List all pending invitations for an organization.
-   *
-   * @param orgIdOrSlug - The organization ID or slug.
-   * @returns The raw `Response` from the AuthGate proxy.
-   */
-  async listOrgInvitations(orgIdOrSlug) {
-    return fetch(
-      `${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/invitations`,
-      {
-        method: "GET",
-        headers: {
-          Authorization: `Bearer ${this.config.apiKey}`
-        }
-      }
-    );
-  }
-  /**
-   * 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.
-   */
-  async revokeOrgInvitation(orgIdOrSlug, invitationId) {
-    return fetch(
-      `${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/invitations/${invitationId}`,
-      {
-        method: "DELETE",
-        headers: {
-          Authorization: `Bearer ${this.config.apiKey}`
-        }
-      }
-    );
-  }
-  /**
-   * Accept an organization invitation using a token.
-   *
-   * @param data - The invitation token received via email.
-   * @returns The raw `Response` from the AuthGate proxy.
-   */
-  async acceptOrgInvitation(data) {
-    return fetch(`${this.config.baseUrl}/api/proxy/orgs/invitations/accept`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        token: data.token
-      })
-    });
-  }
-  /**
-   * Leave an organization as the current user.
-   *
-   * @param orgIdOrSlug - The organization ID or slug.
-   * @returns The raw `Response` from the AuthGate proxy.
-   */
-  async leaveOrg(orgIdOrSlug) {
-    return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/leave`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${this.config.apiKey}`,
-        "Content-Type": "application/json"
-      },
-      body: "{}"
-    });
-  }
-  // ---------------------------------------------------------------------------
-  // 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 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: "/"
-    };
-  }
-  // ---------------------------------------------------------------------------
-  // Config validation (async, called by framework factories)
-  // ---------------------------------------------------------------------------
-  /**
-   * 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
-   */
-  async validateConfig(callbackUrl) {
-    try {
-      const response = await fetch(
-        `${this.config.baseUrl}/api/v1/config/validate`,
-        {
-          method: "POST",
-          headers: {
-            Authorization: `Bearer ${this.config.apiKey}`,
-            "Content-Type": "application/json"
-          },
-          body: JSON.stringify({
-            callback_url: callbackUrl
-          })
-        }
-      );
-      if (response.status === 401) {
-        console.error(
-          "\n[AuthGate] \u2717 Invalid API key.\n  The API key you provided is not recognized or has been revoked.\n  \u2192 Go to your AuthGate dashboard \u2192 Project \u2192 API Key to get a valid key.\n"
-        );
-        return;
-      }
-      if (!response.ok) {
-        console.warn(
-          "[AuthGate] Could not validate config (server returned " + response.status + "). Auth flows may fail."
-        );
-        return;
-      }
-      const data = await response.json();
-      if (callbackUrl && data.callback_url_registered === false) {
-        console.error(
-          "\n[AuthGate] \u2717 Callback URL not registered: " + callbackUrl + "\n  This URL must be added to your project's allowed callback URLs.\n  \u2192 Go to your AuthGate dashboard \u2192 Project \u2192 Callback URLs \u2192 Add URL.\n"
-        );
-      }
-    } catch (e) {
-      console.warn(
-        "[AuthGate] Could not reach AuthGate server at " + this.config.baseUrl + " to validate config. Auth flows may fail if the URL is wrong."
-      );
-    }
-  }
+	/**
+	* @param config - Client configuration. See {@link AuthGateConfig}.
+	*/
+	constructor(config) {
+		this.encryptionKey = null;
+		this.stateKey = null;
+		if (!config.apiKey || typeof config.apiKey !== "string" || config.apiKey.trim() === "") throw new ConfigurationError("[AuthGate] Missing or empty `apiKey`. Get your API key from the AuthGate dashboard → Project → API Key.");
+		if (!config.baseUrl || typeof config.baseUrl !== "string" || config.baseUrl.trim() === "") throw new ConfigurationError("[AuthGate] Missing or empty `baseUrl`. Set this to your AuthGate service URL (e.g. \"https://www.authgate.dev\").");
+		try {
+			new URL(config.baseUrl);
+		} catch {
+			throw new ConfigurationError(`[AuthGate] Invalid \`baseUrl\`: "${config.baseUrl}". Must be a valid URL (e.g. "https://www.authgate.dev").`);
+		}
+		if (config.callbackPath !== void 0 && !config.callbackPath.startsWith("/")) throw new ConfigurationError(`[AuthGate] Invalid \`callbackPath\`: "${config.callbackPath}". Must start with "/" (e.g. "/api/auth/callback").`);
+		this.config = {
+			...config,
+			cookieName: config.cookieName ?? "__authgate",
+			sessionMaxAge: config.sessionMaxAge ?? 604800,
+			callbackPath: config.callbackPath ?? "/api/auth/callback"
+		};
+		this.keysReady = this.deriveKeys();
+	}
+	async deriveKeys() {
+		const [encKey, stKey] = await Promise.all([deriveEncryptionKey(this.config.apiKey), deriveStateKey(this.config.apiKey)]);
+		this.encryptionKey = encKey;
+		this.stateKey = stKey;
+	}
+	async getEncryptionKey() {
+		await this.keysReady;
+		return this.encryptionKey;
+	}
+	async getStateKey() {
+		await this.keysReady;
+		return this.stateKey;
+	}
+	/**
+	* 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);
+		}
+	}
+	/**
+	* 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) {
+		return await encryptSession(await this.getEncryptionKey(), 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) {
+		return await decryptSession(await this.getEncryptionKey(), 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) {
+		return await decryptSessionPayload(await this.getEncryptionKey(), cookieValue);
+	}
+	/**
+	* 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() {
+		return await createOAuthState(await this.getStateKey());
+	}
+	/**
+	* 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) {
+		return await verifyOAuthState(state, nonce, await this.getStateKey());
+	}
+	/**
+	* 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}.
+	*/
+	async getOAuthUrl(provider, callbackUrl, options) {
+		if (!SUPPORTED_PROVIDERS.includes(provider)) throw new AuthGateError(`Unsupported provider: ${provider}`);
+		const response = await fetch(`${this.config.baseUrl}/api/proxy/${provider}`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				callback_url: callbackUrl,
+				state: options?.state,
+				link_to: options?.linkTo,
+				...options?.locale && { locale: options.locale }
+			})
+		});
+		if (!response.ok) throw new AuthGateError((await response.json().catch(() => ({}))).error || `OAuth initiation failed: ${response.status}`);
+		return (await response.json()).redirect_url;
+	}
+	/**
+	* 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: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				email: data.email,
+				password: data.password,
+				name: data.name,
+				callback_url: data.callbackUrl,
+				...data.locale && { locale: data.locale }
+			})
+		});
+	}
+	/**
+	* 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: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				email: data.email,
+				password: data.password,
+				callback_url: data.callbackUrl,
+				...data.locale && { locale: data.locale }
+			})
+		});
+	}
+	/**
+	* 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: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				email: data.email,
+				callback_url: data.callbackUrl,
+				...data.locale && { locale: data.locale }
+			})
+		});
+	}
+	/**
+	* 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: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				token: data.token,
+				password: data.password,
+				...data.locale && { locale: data.locale }
+			})
+		});
+	}
+	/**
+	* 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: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				email: data.email,
+				callback_url: data.callbackUrl,
+				...data.locale && { locale: data.locale }
+			})
+		});
+	}
+	/**
+	* 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: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				email: data.email,
+				code: data.code,
+				...data.locale && { locale: data.locale }
+			})
+		});
+	}
+	/**
+	* 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: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				phone: data.phone,
+				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: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				phone: data.phone,
+				code: data.code,
+				callback_url: data.callbackUrl
+			})
+		});
+	}
+	/**
+	* 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.
+	*/
+	async refreshToken(refreshToken) {
+		try {
+			const response = await fetch(`${this.config.baseUrl}/api/proxy/token/refresh`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${this.config.apiKey}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify({ refresh_token: refreshToken })
+			});
+			if (!response.ok) return null;
+			return response.json();
+		} catch {
+			return 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.
+	*/
+	async exchangeCode(code) {
+		try {
+			const response = await fetch(`${this.config.baseUrl}/api/proxy/token/exchange`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${this.config.apiKey}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify({ code })
+			});
+			if (!response.ok) return null;
+			return response.json();
+		} catch {
+			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 {
+			return (await fetch(`${this.config.baseUrl}/api/proxy/sessions/revoke`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${this.config.apiKey}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify({ refresh_token: refreshToken })
+			})).ok;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* 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: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify(data)
+		});
+	}
+	/**
+	* 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: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({ challenge })
+		});
+	}
+	/**
+	* 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.
+	*/
+	async createOrg(data) {
+		return fetch(`${this.config.baseUrl}/api/proxy/orgs`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				name: data.name,
+				slug: data.slug,
+				image_url: data.imageUrl,
+				metadata: data.metadata
+			})
+		});
+	}
+	/**
+	* List all organizations accessible to the current project.
+	*
+	* @returns The raw `Response` from the AuthGate proxy.
+	*/
+	async listOrgs() {
+		return fetch(`${this.config.baseUrl}/api/proxy/orgs`, {
+			method: "GET",
+			headers: { Authorization: `Bearer ${this.config.apiKey}` }
+		});
+	}
+	/**
+	* Get a single organization by ID or slug.
+	*
+	* @param orgIdOrSlug - The organization ID or slug.
+	* @returns The raw `Response` from the AuthGate proxy.
+	*/
+	async getOrg(orgIdOrSlug) {
+		return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}`, {
+			method: "GET",
+			headers: { Authorization: `Bearer ${this.config.apiKey}` }
+		});
+	}
+	/**
+	* 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.
+	*/
+	async updateOrg(orgIdOrSlug, data) {
+		return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}`, {
+			method: "PATCH",
+			headers: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				name: data.name,
+				slug: data.slug,
+				image_url: data.imageUrl,
+				max_members: data.maxMembers,
+				metadata: data.metadata
+			})
+		});
+	}
+	/**
+	* Delete an organization.
+	*
+	* @param orgIdOrSlug - The organization ID or slug.
+	* @returns The raw `Response` from the AuthGate proxy.
+	*/
+	async deleteOrg(orgIdOrSlug) {
+		return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}`, {
+			method: "DELETE",
+			headers: { Authorization: `Bearer ${this.config.apiKey}` }
+		});
+	}
+	/**
+	* List all members of an organization.
+	*
+	* @param orgIdOrSlug - The organization ID or slug.
+	* @returns The raw `Response` from the AuthGate proxy.
+	*/
+	async listOrgMembers(orgIdOrSlug) {
+		return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/members`, {
+			method: "GET",
+			headers: { Authorization: `Bearer ${this.config.apiKey}` }
+		});
+	}
+	/**
+	* 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.
+	*/
+	async updateOrgMember(orgIdOrSlug, memberId, data) {
+		return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/members/${memberId}`, {
+			method: "PATCH",
+			headers: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({ role_key: data.roleKey })
+		});
+	}
+	/**
+	* 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.
+	*/
+	async removeOrgMember(orgIdOrSlug, memberId) {
+		return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/members/${memberId}`, {
+			method: "DELETE",
+			headers: { Authorization: `Bearer ${this.config.apiKey}` }
+		});
+	}
+	/**
+	* 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.
+	*/
+	async inviteToOrg(orgIdOrSlug, data) {
+		return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/invitations`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				email: data.email,
+				role_key: data.roleKey
+			})
+		});
+	}
+	/**
+	* List all pending invitations for an organization.
+	*
+	* @param orgIdOrSlug - The organization ID or slug.
+	* @returns The raw `Response` from the AuthGate proxy.
+	*/
+	async listOrgInvitations(orgIdOrSlug) {
+		return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/invitations`, {
+			method: "GET",
+			headers: { Authorization: `Bearer ${this.config.apiKey}` }
+		});
+	}
+	/**
+	* 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.
+	*/
+	async revokeOrgInvitation(orgIdOrSlug, invitationId) {
+		return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/invitations/${invitationId}`, {
+			method: "DELETE",
+			headers: { Authorization: `Bearer ${this.config.apiKey}` }
+		});
+	}
+	/**
+	* Accept an organization invitation using a token.
+	*
+	* @param data - The invitation token received via email.
+	* @returns The raw `Response` from the AuthGate proxy.
+	*/
+	async acceptOrgInvitation(data) {
+		return fetch(`${this.config.baseUrl}/api/proxy/orgs/invitations/accept`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({ token: data.token })
+		});
+	}
+	/**
+	* Leave an organization as the current user.
+	*
+	* @param orgIdOrSlug - The organization ID or slug.
+	* @returns The raw `Response` from the AuthGate proxy.
+	*/
+	async leaveOrg(orgIdOrSlug) {
+		return fetch(`${this.config.baseUrl}/api/proxy/orgs/${orgIdOrSlug}/leave`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${this.config.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: "{}"
+		});
+	}
+	/** 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 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,
+			path: "/"
+		};
+	}
+	/**
+	* 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
+	*/
+	async validateConfig(callbackUrl) {
+		try {
+			const response = await fetch(`${this.config.baseUrl}/api/v1/config/validate`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${this.config.apiKey}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify({ callback_url: callbackUrl })
+			});
+			if (response.status === 401) {
+				console.error("\n[AuthGate] ✗ Invalid API key.\n  The API key you provided is not recognized or has been revoked.\n  → Go to your AuthGate dashboard → Project → API Key to get a valid key.\n");
+				return;
+			}
+			if (!response.ok) {
+				console.warn("[AuthGate] Could not validate config (server returned " + response.status + "). Auth flows may fail.");
+				return;
+			}
+			const data = await response.json();
+			if (callbackUrl && data.callback_url_registered === false) console.error("\n[AuthGate] ✗ Callback URL not registered: " + callbackUrl + "\n  This URL must be added to your project's allowed callback URLs.\n  → Go to your AuthGate dashboard → Project → Callback URLs → Add URL.\n");
+		} catch {
+			console.warn("[AuthGate] Could not reach AuthGate server at " + this.config.baseUrl + " to validate config. Auth flows may fail if the URL is wrong.");
+		}
+	}
 };
+/**
+* Create an {@link AuthGateClient} instance.
+*
+* Convenience factory — equivalent to `new AuthGateClient(config)`.
+*
+* @param config - Client configuration. See {@link AuthGateConfig}.
+* @returns A configured {@link AuthGateClient}.
+*/
 function createAuthGateClient(config) {
-  return new AuthGateClient(config);
+	return new AuthGateClient(config);
 }
-
-// src/project-config.ts
+//#endregion
+//#region src/project-config.ts
+/**
+* Define your project-level AuthGate configuration.
+*
+* Create an `authgate.config.ts` file in your project root and export
+* the result of this function as the default export. This gives you
+* type safety and IDE autocomplete for the config.
+*
+* The CLI auto-loads `.env` and `.env.local` before importing the
+* config, so `process.env` values are available.
+*
+* @param config - The project configuration object.
+* @returns The same config object (identity function for type inference).
+*
+* @example Minimal setup (env vars provide connection details)
+* ```ts
+* // authgate.config.ts
+* import { defineConfig } from "@auth-gate/core";
+*
+* export default defineConfig({
+*   connection: {
+*     baseUrl: process.env.AUTHGATE_URL,
+*     apiKey: process.env.AUTHGATE_API_KEY,
+*   },
+* });
+* ```
+*
+* @example Monorepo with custom config paths
+* ```ts
+* // authgate.config.ts
+* import { defineConfig } from "@auth-gate/core";
+*
+* export default defineConfig({
+*   connection: {
+*     baseUrl: process.env.AUTHGATE_URL,
+*     apiKey: process.env.AUTHGATE_API_KEY,
+*   },
+*   rbacConfig: "./packages/api/authgate.rbac.ts",
+*   billingConfig: "./packages/api/authgate.billing.ts",
+* });
+* ```
+*
+* @example Then sync with the CLI
+* ```sh
+* # Scaffold the config file
+* npx @auth-gate/rbac init --config
+*
+* # Sync RBAC roles & permissions
+* npx @auth-gate/rbac sync --apply
+*
+* # Sync billing plans & features
+* npx @auth-gate/billing sync --apply
+* ```
+*/
 function defineConfig(config) {
-  return config;
+	return config;
 }
-
-// src/billing.ts
+//#endregion
+//#region src/billing.ts
+/**
+* Check whether the user's entitlements include a specific plan.
+*
+* @param entitlements - The entitlement object from the billing API.
+* @param plan - The plan name to check (case-insensitive).
+* @returns `true` if the user is on the given plan.
+*/
 function hasPlan(entitlements, plan) {
-  if (!(entitlements == null ? void 0 : entitlements.plan)) return false;
-  return entitlements.plan.toLowerCase() === plan.toLowerCase();
+	if (!entitlements?.plan) return false;
+	return entitlements.plan.toLowerCase() === plan.toLowerCase();
 }
+/**
+* Check whether the user's entitlements include a specific feature.
+*
+* @param entitlements - The entitlement object from the billing API.
+* @param feature - The feature name to check (case-insensitive).
+* @returns `true` if the user has the given feature.
+*/
 function hasFeature(entitlements, feature) {
-  if (!(entitlements == null ? void 0 : entitlements.features)) return false;
-  const lower = feature.toLowerCase();
-  return entitlements.features.some((f) => f.toLowerCase() === lower);
+	if (!entitlements?.features) return false;
+	const lower = feature.toLowerCase();
+	return entitlements.features.some((f) => f.toLowerCase() === lower);
 }
+/**
+* Check a specific feature entitlement, returning typed detail with metered usage info.
+*
+* @param entitlements - The extended entitlement object from the billing API.
+* @param feature - The feature name to check (case-insensitive).
+* @returns The typed entitlement detail, or a denied boolean detail if not found.
+*/
 function checkFeature(entitlements, feature) {
-  if (!(entitlements == null ? void 0 : entitlements.featureDetails)) {
-    const allowed = hasFeature(entitlements, feature);
-    return { type: "boolean", feature, allowed };
-  }
-  const lower = feature.toLowerCase();
-  const key = Object.keys(entitlements.featureDetails).find(
-    (k) => k.toLowerCase() === lower
-  );
-  if (key) return entitlements.featureDetails[key];
-  return { type: "boolean", feature, allowed: false };
+	if (!entitlements?.featureDetails) return {
+		type: "boolean",
+		feature,
+		allowed: hasFeature(entitlements, feature)
+	};
+	const lower = feature.toLowerCase();
+	const key = Object.keys(entitlements.featureDetails).find((k) => k.toLowerCase() === lower);
+	if (key) return entitlements.featureDetails[key];
+	return {
+		type: "boolean",
+		feature,
+		allowed: false
+	};
 }
-
-// src/organizations.ts
+//#endregion
+//#region src/organizations.ts
+/**
+* Check whether a membership includes a specific permission.
+*
+* Supports wildcard matching:
+* - `"*"` matches all permissions.
+* - `"resource:*"` matches any permission starting with `"resource:"`.
+*
+* @param membership - The user's org membership (or null).
+* @param permission - The permission string to check, e.g. `"documents:write"`.
+* @returns `true` if the membership grants the permission.
+*/
 function hasPermission(membership, permission) {
-  var _a;
-  if (!((_a = membership == null ? void 0 : membership.role) == null ? void 0 : _a.permissions)) return false;
-  return matchesPermission(membership.role.permissions, permission);
+	if (!membership?.role?.permissions) return false;
+	return matchesPermission(membership.role.permissions, permission);
 }
+/**
+* Check whether a membership has a specific role key.
+*
+* @param membership - The user's org membership (or null).
+* @param roleKey - The role key to check, e.g. `"admin"`.
+* @returns `true` if the membership's role key matches.
+*/
 function hasRole(membership, roleKey) {
-  var _a;
-  if (!((_a = membership == null ? void 0 : membership.role) == null ? void 0 : _a.key)) return false;
-  return membership.role.key === roleKey;
+	if (!membership?.role?.key) return false;
+	return membership.role.key === roleKey;
 }
+/**
+* Check whether a membership has at least one of the given permissions.
+*
+* @param membership - The user's org membership (or null).
+* @param permissions - Array of permission strings.
+* @returns `true` if at least one permission is granted.
+*/
 function hasAnyPermission(membership, permissions) {
-  var _a;
-  if (!((_a = membership == null ? void 0 : membership.role) == null ? void 0 : _a.permissions)) return false;
-  return permissions.some(
-    (p) => matchesPermission(membership.role.permissions, p)
-  );
+	if (!membership?.role?.permissions) return false;
+	return permissions.some((p) => matchesPermission(membership.role.permissions, p));
 }
+/**
+* Check whether a membership has all of the given permissions.
+*
+* @param membership - The user's org membership (or null).
+* @param permissions - Array of permission strings.
+* @returns `true` if every permission is granted.
+*/
 function hasAllPermissions(membership, permissions) {
-  var _a;
-  if (!((_a = membership == null ? void 0 : membership.role) == null ? void 0 : _a.permissions)) return false;
-  return permissions.every(
-    (p) => matchesPermission(membership.role.permissions, p)
-  );
+	if (!membership?.role?.permissions) return false;
+	return permissions.every((p) => matchesPermission(membership.role.permissions, p));
 }
 function matchesPermission(granted, required) {
-  for (const perm of granted) {
-    if (perm === "*") return true;
-    if (perm === required) return true;
-    if (perm.endsWith(":*")) {
-      const prefix = perm.slice(0, -1);
-      if (required.startsWith(prefix)) return true;
-    }
-  }
-  return false;
+	for (const perm of granted) {
+		if (perm === "*") return true;
+		if (perm === required) return true;
+		if (perm.endsWith(":*")) {
+			const prefix = perm.slice(0, -1);
+			if (required.startsWith(prefix)) return true;
+		}
+	}
+	return false;
 }
+/**
+* Merge permissions from a project-level role and an org-level role (union).
+* Either may be null/undefined.
+*/
 function mergePermissions(projectRole, orgMembership) {
-  var _a;
-  const set = /* @__PURE__ */ new Set();
-  if (projectRole == null ? void 0 : projectRole.permissions) {
-    for (const p of projectRole.permissions) set.add(p);
-  }
-  if ((_a = orgMembership == null ? void 0 : orgMembership.role) == null ? void 0 : _a.permissions) {
-    for (const p of orgMembership.role.permissions) set.add(p);
-  }
-  return [...set];
+	const set = /* @__PURE__ */ new Set();
+	if (projectRole?.permissions) for (const p of projectRole.permissions) set.add(p);
+	if (orgMembership?.role?.permissions) for (const p of orgMembership.role.permissions) set.add(p);
+	return [...set];
 }
+/**
+* Check a permission against a merged permission set (project + org).
+* Supports wildcard matching.
+*/
 function hasMergedPermission(projectRole, orgMembership, permission) {
-  const merged = mergePermissions(projectRole, orgMembership);
-  return matchesPermission(merged, permission);
+	return matchesPermission(mergePermissions(projectRole, orgMembership), permission);
 }
-export {
-  AuthGateClient,
-  AuthGateError,
-  ConfigurationError,
-  DEFAULT_COOKIE_NAME,
-  InvalidStateError,
-  NONCE_COOKIE_NAME,
-  REFRESH_TOKEN_COOKIE_NAME,
-  SESSION_MAX_AGE,
-  STATE_TTL_MS,
-  SUPPORTED_PROVIDERS,
-  SessionDecryptionError,
-  TokenVerificationError,
-  checkFeature,
-  createAuthGateClient,
-  defineConfig,
-  hasAllPermissions,
-  hasAnyPermission,
-  hasFeature,
-  hasMergedPermission,
-  hasPermission,
-  hasPlan,
-  hasRole,
-  mergePermissions
-};
+//#endregion
+export { AuthGateClient, AuthGateError, ConfigurationError, DEFAULT_COOKIE_NAME, InvalidStateError, NONCE_COOKIE_NAME, REFRESH_TOKEN_COOKIE_NAME, SESSION_MAX_AGE, STATE_TTL_MS, SUPPORTED_PROVIDERS, SessionDecryptionError, TokenVerificationError, checkFeature, createAuthGateClient, defineConfig, hasAllPermissions, hasAnyPermission, hasFeature, hasMergedPermission, hasPermission, hasPlan, hasRole, mergePermissions };