@corvushold/guard-sdk 0.5.3

package/dist/index.js

@@ -0,0 +1,990 @@
+import { authenticator } from 'otplib';
+
+// src/errors.ts
+var ApiError = class extends Error {
+  constructor(params) {
+    super(params.message || `HTTP ${params.status}`);
+    this.name = "ApiError";
+    this.status = params.status;
+    this.code = params.code;
+    this.requestId = params.requestId;
+    this.raw = params.raw;
+    this.headers = params.headers;
+  }
+};
+var RateLimitError = class extends ApiError {
+  constructor(params) {
+    super(params);
+    this.name = "RateLimitError";
+    this.retryAfter = params.retryAfter;
+    this.nextRetryAt = params.nextRetryAt;
+  }
+};
+function isApiError(e) {
+  return e instanceof ApiError;
+}
+function isRateLimitError(e) {
+  return e instanceof RateLimitError;
+}
+
+// src/rateLimit.ts
+function parseRetryAfter(retryAfter) {
+  if (!retryAfter) return {};
+  const trimmed = retryAfter.trim();
+  const secs = Number(trimmed);
+  if (!Number.isNaN(secs)) {
+    return { seconds: secs > 0 ? secs : void 0, nextRetryAt: secs > 0 ? new Date(Date.now() + secs * 1e3) : void 0 };
+  }
+  const date = new Date(trimmed);
+  if (!Number.isNaN(date.getTime())) {
+    const ms = date.getTime() - Date.now();
+    const seconds = ms > 0 ? Math.ceil(ms / 1e3) : void 0;
+    return { seconds, nextRetryAt: ms > 0 ? date : void 0 };
+  }
+  return {};
+}
+function toHeadersMap(headers) {
+  const obj = {};
+  headers.forEach((v, k) => {
+    obj[k] = v;
+  });
+  return obj;
+}
+function buildRateLimitError(args) {
+  const { seconds, nextRetryAt } = parseRetryAfter(args.headers.get("retry-after"));
+  return new RateLimitError({
+    status: args.status,
+    message: args.message,
+    requestId: args.requestId,
+    headers: toHeadersMap(args.headers),
+    retryAfter: seconds,
+    nextRetryAt,
+    raw: args.raw
+  });
+}
+
+// src/tokens.ts
+var noopStorage = {
+  getAccessToken: () => null,
+  setAccessToken: () => {
+  },
+  getRefreshToken: () => null,
+  setRefreshToken: () => {
+  },
+  clear: () => {
+  }
+};
+
+// src/storage/inMemory.ts
+var InMemoryStorage = class {
+  constructor() {
+    this.accessToken = null;
+    this.refreshToken = null;
+  }
+  getAccessToken() {
+    return this.accessToken;
+  }
+  setAccessToken(token) {
+    this.accessToken = token ?? null;
+  }
+  getRefreshToken() {
+    return this.refreshToken;
+  }
+  setRefreshToken(token) {
+    this.refreshToken = token ?? null;
+  }
+  clear() {
+    this.accessToken = null;
+    this.refreshToken = null;
+  }
+};
+
+// src/storage/webLocalStorage.ts
+var ACCESS_KEY = "guard_access_token";
+var REFRESH_KEY = "guard_refresh_token";
+function isBrowser() {
+  return typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+}
+var WebLocalStorage = class {
+  constructor(prefix = "") {
+    this.prefix = prefix ? `${prefix}:` : "";
+  }
+  k(key) {
+    return `${this.prefix}${key}`;
+  }
+  getAccessToken() {
+    if (!isBrowser()) return null;
+    return window.localStorage.getItem(this.k(ACCESS_KEY));
+  }
+  setAccessToken(token) {
+    if (!isBrowser()) return;
+    if (token == null) window.localStorage.removeItem(this.k(ACCESS_KEY));
+    else window.localStorage.setItem(this.k(ACCESS_KEY), token);
+  }
+  getRefreshToken() {
+    if (!isBrowser()) return null;
+    return window.localStorage.getItem(this.k(REFRESH_KEY));
+  }
+  setRefreshToken(token) {
+    if (!isBrowser()) return;
+    if (token == null) window.localStorage.removeItem(this.k(REFRESH_KEY));
+    else window.localStorage.setItem(this.k(REFRESH_KEY), token);
+  }
+  clear() {
+    if (!isBrowser()) return;
+    window.localStorage.removeItem(this.k(ACCESS_KEY));
+    window.localStorage.removeItem(this.k(REFRESH_KEY));
+  }
+};
+
+// src/storage/reactNative.ts
+var ACCESS_KEY2 = "guard_access_token";
+var REFRESH_KEY2 = "guard_refresh_token";
+function reactNativeStorageAdapter(AsyncStorage, prefix = "") {
+  const p = prefix ? `${prefix}:` : "";
+  const k = (key) => `${p}${key}`;
+  return {
+    async getAccessToken() {
+      return AsyncStorage.getItem(k(ACCESS_KEY2));
+    },
+    async setAccessToken(token) {
+      if (token == null) return AsyncStorage.removeItem(k(ACCESS_KEY2));
+      return AsyncStorage.setItem(k(ACCESS_KEY2), token);
+    },
+    async getRefreshToken() {
+      return AsyncStorage.getItem(k(REFRESH_KEY2));
+    },
+    async setRefreshToken(token) {
+      if (token == null) return AsyncStorage.removeItem(k(REFRESH_KEY2));
+      return AsyncStorage.setItem(k(REFRESH_KEY2), token);
+    },
+    async clear() {
+      await AsyncStorage.removeItem(k(ACCESS_KEY2));
+      await AsyncStorage.removeItem(k(REFRESH_KEY2));
+    }
+  };
+}
+
+// src/http/interceptors.ts
+function applyRequestInterceptors(input, init, interceptors) {
+  if (!interceptors || interceptors.length === 0) return [input, init];
+  let chain = Promise.resolve([input, init]);
+  for (const fn of interceptors) {
+    chain = chain.then(([i, n]) => Promise.resolve(fn(i, n)));
+  }
+  return chain;
+}
+async function applyResponseInterceptors(response, interceptors) {
+  if (!interceptors || interceptors.length === 0) return response;
+  let res = response;
+  for (const fn of interceptors) {
+    res = await Promise.resolve(fn(res));
+  }
+  return res;
+}
+
+// src/http/transport.ts
+var HttpClient = class {
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+    const fiRaw = opts.fetchImpl ?? globalThis.fetch;
+    if (!fiRaw) throw new Error("No fetch implementation provided and global fetch is unavailable");
+    this.fetchImpl = ((input, init) => fiRaw.call(globalThis, input, init));
+    this.interceptors = opts.interceptors;
+    this.clientHeader = opts.clientHeader ?? "ts-sdk";
+    this.defaultHeaders = { ...opts.defaultHeaders ?? {} };
+    this.credentials = opts.credentials;
+  }
+  buildUrl(path) {
+    if (/^https?:\/\//i.test(path)) return path;
+    if (!path.startsWith("/")) path = `/${path}`;
+    return `${this.baseUrl}${path}`;
+  }
+  async request(path, init = {}) {
+    const url = this.buildUrl(path);
+    const headers = new Headers(init.headers || {});
+    if (!headers.has("content-type")) headers.set("content-type", "application/json");
+    if (!headers.has("accept")) headers.set("accept", "application/json");
+    if (this.clientHeader && !headers.has("x-guard-client")) {
+      headers.set("x-guard-client", this.clientHeader);
+    }
+    for (const [k, v] of Object.entries(this.defaultHeaders)) {
+      if (!headers.has(k)) headers.set(k, v);
+    }
+    const reqInit = { ...init, headers };
+    if (!("credentials" in reqInit) && this.credentials) {
+      reqInit.credentials = this.credentials;
+    }
+    const [finalUrl, finalInit] = await applyRequestInterceptors(url, reqInit, this.interceptors?.request);
+    const res = await this.fetchImpl(finalUrl, finalInit);
+    const res2 = await applyResponseInterceptors(res, this.interceptors?.response);
+    const requestId = res2.headers.get("x-request-id") || void 0;
+    const status = res2.status;
+    if (!res2.ok) {
+      let body = void 0;
+      try {
+        const ct2 = res2.headers.get("content-type") || "";
+        if (ct2.includes("application/json")) body = await res2.clone().json();
+        else body = await res2.clone().text();
+      } catch {
+      }
+      if (status === 429) {
+        throw buildRateLimitError({ status, message: body && body.message || "Too Many Requests", requestId, headers: res2.headers, raw: body });
+      }
+      throw new ApiError({
+        status,
+        message: body && body.message || res2.statusText || `HTTP ${status}`,
+        code: body && body.code ? String(body.code) : void 0,
+        requestId,
+        headers: toHeadersMap(res2.headers),
+        raw: body
+      });
+    }
+    let data = void 0;
+    const ct = res2.headers.get("content-type") || "";
+    if (status !== 204) {
+      if (ct.includes("application/json")) data = await res2.json();
+      else data = await res2.text();
+    }
+    return {
+      data,
+      meta: { status, requestId, headers: toHeadersMap(res2.headers) }
+    };
+  }
+  // Low-level raw request that returns the Response without throwing on non-2xx.
+  // Useful for endpoints like SSO start that intentionally return 3xx redirects.
+  async requestRaw(path, init = {}) {
+    const url = this.buildUrl(path);
+    const headers = new Headers(init.headers || {});
+    if (!headers.has("content-type")) headers.set("content-type", "application/json");
+    if (!headers.has("accept")) headers.set("accept", "application/json");
+    if (this.clientHeader && !headers.has("x-guard-client")) {
+      headers.set("x-guard-client", this.clientHeader);
+    }
+    for (const [k, v] of Object.entries(this.defaultHeaders)) {
+      if (!headers.has(k)) headers.set(k, v);
+    }
+    const reqInit = { ...init, headers };
+    if (!("credentials" in reqInit) && this.credentials) {
+      reqInit.credentials = this.credentials;
+    }
+    const [finalUrl, finalInit] = await applyRequestInterceptors(url, reqInit, this.interceptors?.request);
+    const res = await this.fetchImpl(finalUrl, finalInit);
+    const res2 = await applyResponseInterceptors(res, this.interceptors?.response);
+    return res2;
+  }
+};
+
+// package.json
+var package_default = {
+  version: "0.5.3"};
+
+// src/client.ts
+function isTenantSelectionRequired(data) {
+  const d = data;
+  return !!d && d.error === "tenant_selection_required" && typeof d.message === "string" && Array.isArray(d.tenants);
+}
+function isTokensResp(data) {
+  const d = data;
+  return !!d && (typeof d.access_token === "string" || typeof d.refresh_token === "string");
+}
+function isMfaChallengeResp(data) {
+  const d = data;
+  return !!d && typeof d.challenge_token === "string";
+}
+var GuardClient = class {
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl;
+    this.tenantId = opts.tenantId;
+    this.storage = opts.storage ?? new InMemoryStorage();
+    const mode = opts.authMode ?? "bearer";
+    const authHeaderInterceptor = async (input, init) => {
+      const headers = new Headers(init.headers || {});
+      if (mode === "bearer") {
+        const token = await Promise.resolve(this.storage.getAccessToken());
+        if (token && !headers.has("authorization")) {
+          headers.set("authorization", `Bearer ${token}`);
+        }
+      } else if (mode === "cookie") {
+        headers.set("X-Auth-Mode", "cookie");
+      }
+      return [input, { ...init, headers }];
+    };
+    const defaultHeaders = { ...opts.defaultHeaders ?? {} };
+    const clientHeader = `ts-sdk/${package_default.version}`;
+    let credentialsOpt = void 0;
+    if (mode === "cookie") {
+      credentialsOpt = "include";
+    }
+    this.http = new HttpClient({
+      baseUrl: opts.baseUrl,
+      fetchImpl: opts.fetchImpl,
+      clientHeader,
+      defaultHeaders,
+      interceptors: { request: [authHeaderInterceptor] },
+      credentials: credentialsOpt
+    });
+  }
+  // Low-level request passthrough (internal usage by methods)
+  async request(path, init) {
+    return this.http.request(path, init);
+  }
+  persistTokensFrom(data) {
+    try {
+      if (isTokensResp(data)) {
+        const access = data.access_token ?? null;
+        const refresh = data.refresh_token ?? null;
+        if (access !== void 0) {
+          void this.storage.setAccessToken(access);
+        }
+        if (refresh !== void 0) {
+          void this.storage.setRefreshToken(refresh);
+        }
+      }
+    } catch (_) {
+    }
+  }
+  buildQuery(params) {
+    const usp = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+      if (v === void 0 || v === null) continue;
+      usp.set(k, String(v));
+    }
+    const qs = usp.toString();
+    return qs ? `?${qs}` : "";
+  }
+  // Auth: Password login -> returns tokens (200) or MFA challenge (202)
+  async passwordLogin(body) {
+    const res = await this.request("/v1/auth/password/login", {
+      method: "POST",
+      body: JSON.stringify({ ...body, tenant_id: body.tenant_id ?? this.tenantId })
+    });
+    if (res.meta.status === 200) this.persistTokensFrom(res.data);
+    return res;
+  }
+  // Auth: Password signup -> returns tokens (201 Created)
+  async passwordSignup(body) {
+    const res = await this.request("/v1/auth/password/signup", {
+      method: "POST",
+      body: JSON.stringify({ ...body, tenant_id: body.tenant_id ?? this.tenantId })
+    });
+    if (res.meta.status === 200 || res.meta.status === 201) this.persistTokensFrom(res.data);
+    return res;
+  }
+  // Auth: Verify MFA challenge -> tokens
+  async mfaVerify(body) {
+    const res = await this.request("/v1/auth/mfa/verify", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    if (res.meta.status === 200) this.persistTokensFrom(res.data);
+    return res;
+  }
+  // Auth: Refresh tokens
+  async refresh(body) {
+    let refreshToken = body?.refresh_token ?? null;
+    if (!refreshToken) refreshToken = await Promise.resolve(this.storage.getRefreshToken()) ?? null;
+    const res = await this.request("/v1/auth/refresh", {
+      method: "POST",
+      body: JSON.stringify({ refresh_token: refreshToken })
+    });
+    if (res.meta.status === 200) this.persistTokensFrom(res.data);
+    return res;
+  }
+  // Auth: Logout (revoke refresh token) -> 204
+  async logout(body) {
+    const b = body ?? {};
+    const res = await this.request("/v1/auth/logout", {
+      method: "POST",
+      body: JSON.stringify(b)
+    });
+    if (res.meta.status === 204) {
+      void this.storage.setRefreshToken(null);
+    }
+    return res;
+  }
+  // Auth: Current user profile
+  async me() {
+    return this.request("/v1/auth/me", { method: "GET" });
+  }
+  // Auth: Email discovery (progressive login)
+  async emailDiscover(body) {
+    const headers = {};
+    const tid = body.tenant_id ?? this.tenantId;
+    if (tid) headers["X-Tenant-ID"] = String(tid);
+    return this.request(`/v1/auth/email/discover`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ email: body.email })
+    });
+  }
+  // Auth: Get login options - returns available auth methods for a tenant/email
+  async getLoginOptions(params) {
+    const tid = params?.tenant_id ?? this.tenantId;
+    const qs = this.buildQuery({ email: params?.email, tenant_id: tid });
+    return this.request(`/v1/auth/login-options${qs}`, { method: "GET" });
+  }
+  // --- MFA self-service ---
+  async mfaStartTotp() {
+    return this.request("/v1/auth/mfa/totp/start", { method: "POST" });
+  }
+  async mfaActivateTotp(body) {
+    return this.request("/v1/auth/mfa/totp/activate", { method: "POST", body: JSON.stringify(body) });
+  }
+  async mfaDisableTotp() {
+    return this.request("/v1/auth/mfa/totp/disable", { method: "POST" });
+  }
+  async mfaGenerateBackupCodes(body = {}) {
+    return this.request("/v1/auth/mfa/backup/generate", { method: "POST", body: JSON.stringify({ count: body.count ?? 5 }) });
+  }
+  async mfaCountBackupCodes() {
+    return this.request("/v1/auth/mfa/backup/count", { method: "GET" });
+  }
+  // Tenants: Discover tenants for a given email (used by login tenant selection)
+  async discoverTenants(params) {
+    const qs = this.buildQuery({ email: params.email });
+    return this.request(`/v1/auth/tenants${qs}`, { method: "GET" });
+  }
+  // Tenants: Create
+  async createTenant(body) {
+    return this.request(`/tenants`, { method: "POST", body: JSON.stringify({ name: body.name }) });
+  }
+  // Tenants: Get by ID
+  async getTenant(id) {
+    return this.request(`/tenants/${encodeURIComponent(id)}`, { method: "GET" });
+  }
+  // Tenants: List (admin)
+  async listTenants(params = {}) {
+    const qs = this.buildQuery({
+      q: params.q,
+      page: params.page,
+      page_size: params.page_size,
+      active: typeof params.active === "boolean" ? params.active ? 1 : 0 : params.active
+    });
+    return this.request(`/tenants${qs}`, { method: "GET" });
+  }
+  // Auth: Introspect token (from header or body)
+  async introspect(body) {
+    return this.request("/v1/auth/introspect", {
+      method: "POST",
+      body: JSON.stringify(body ?? {})
+    });
+  }
+  // Auth: Magic link send
+  async magicSend(body) {
+    return this.request("/v1/auth/magic/send", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  // Auth: Magic verify (token in query preferred)
+  async magicVerify(params = {}, body) {
+    const qs = this.buildQuery(params);
+    const res = await this.request(`/v1/auth/magic/verify${qs}`, {
+      method: "GET",
+      // Some servers accept body on GET per spec; include if provided
+      ...body ? { body: JSON.stringify(body) } : {}
+    });
+    if (res.meta.status === 200) this.persistTokensFrom(res.data);
+    return res;
+  }
+  // Auth: Request password reset -> 202 (always, to prevent email enumeration)
+  async passwordResetRequest(body) {
+    return this.request("/v1/auth/password/reset/request", {
+      method: "POST",
+      body: JSON.stringify({ ...body, tenant_id: body.tenant_id ?? this.tenantId })
+    });
+  }
+  // Auth: Confirm password reset -> 200 on success
+  async passwordResetConfirm(body) {
+    return this.request("/v1/auth/password/reset/confirm", {
+      method: "POST",
+      body: JSON.stringify({ ...body, tenant_id: body.tenant_id ?? this.tenantId })
+    });
+  }
+  // Auth: Change password (requires auth) -> 200 on success
+  async changePassword(body) {
+    return this.request("/v1/auth/password/change", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  // Auth: Update profile (first/last name) -> 200 on success
+  async updateProfile(body) {
+    return this.request("/v1/auth/profile", {
+      method: "PATCH",
+      body: JSON.stringify(body)
+    });
+  }
+  // Admin: List users (requires admin role). tenant_id from client or param.
+  async listUsers(params = {}) {
+    const tenant = params.tenant_id ?? this.tenantId;
+    const qs = this.buildQuery({ tenant_id: tenant });
+    return this.request(`/v1/auth/admin/users${qs}`, { method: "GET" });
+  }
+  // Admin: Update user names
+  async updateUserNames(id, body) {
+    const payload = {};
+    if (typeof body?.first_name === "string") payload.first_name = body.first_name;
+    if (typeof body?.last_name === "string") payload.last_name = body.last_name;
+    return this.request(`/v1/auth/admin/users/${encodeURIComponent(id)}`, {
+      method: "PATCH",
+      body: JSON.stringify(payload)
+    });
+  }
+  // Admin: Block user
+  async blockUser(id) {
+    return this.request(`/v1/auth/admin/users/${encodeURIComponent(id)}/block`, { method: "POST" });
+  }
+  // Admin: Unblock user
+  async unblockUser(id) {
+    return this.request(`/v1/auth/admin/users/${encodeURIComponent(id)}/unblock`, { method: "POST" });
+  }
+  // Admin: Verify user email (set email_verified=true)
+  async verifyUserEmail(id) {
+    return this.request(`/v1/auth/admin/users/${encodeURIComponent(id)}/verify-email`, { method: "POST" });
+  }
+  // Admin: Unverify user email (set email_verified=false)
+  async unverifyUserEmail(id) {
+    return this.request(`/v1/auth/admin/users/${encodeURIComponent(id)}/unverify-email`, { method: "POST" });
+  }
+  // Sessions: List sessions. When includeAll=false, filter to active (non-revoked, not expired) client-side to match example app UX.
+  async listSessions(options = {}) {
+    const res = await this.request("/v1/auth/sessions", { method: "GET", cache: "no-store" });
+    if (res.meta.status >= 200 && res.meta.status < 300) {
+      const includeAll = !!options.includeAll;
+      const sessions = Array.isArray(res.data?.sessions) ? res.data.sessions : [];
+      if (!includeAll) {
+        const now = Date.now();
+        const active = sessions.filter((s) => {
+          const revoked = !!s.revoked;
+          const expMs = s.expires_at ? Date.parse(s.expires_at) : 0;
+          return !revoked && expMs > now;
+        });
+        return { data: { sessions: active }, meta: res.meta };
+      }
+    }
+    return res;
+  }
+  // Sessions: Revoke session
+  async revokeSession(id) {
+    return this.request(`/v1/auth/sessions/${encodeURIComponent(id)}/revoke`, { method: "POST" });
+  }
+  // Tenants: Get settings
+  async getTenantSettings(tenantId) {
+    const id = tenantId ?? this.tenantId;
+    if (!id) throw new Error("tenantId is required");
+    return this.request(`/v1/tenants/${encodeURIComponent(id)}/settings`, { method: "GET" });
+  }
+  // Tenants: Update settings
+  async updateTenantSettings(tenantId, settings) {
+    return this.request(`/v1/tenants/${encodeURIComponent(tenantId)}/settings`, {
+      method: "PUT",
+      body: JSON.stringify(settings ?? {})
+    });
+  }
+  /**
+   * Start SSO flow with a provider slug.
+   * Uses V2 tenant-scoped URLs: /auth/sso/t/{tenant_id}/{slug}/login
+   * 
+   * @param providerSlug - The provider slug (e.g., 'okta', 'azure-ad', 'google-saml')
+   * @param params - Optional parameters for the SSO flow
+   * @returns The redirect URL to send the user to for authentication
+   * 
+   * @example
+   * ```ts
+   * const result = await client.startSso('okta', { redirect_url: 'https://myapp.com/callback' });
+   * window.location.href = result.data.redirect_url;
+   * ```
+   */
+  async startSso(providerSlug, params = {}) {
+    const tenant = params.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required for SSO; set via params or client constructor");
+    const qs = this.buildQuery({
+      redirect_url: params.redirect_url,
+      login_hint: params.login_hint,
+      force_authn: params.force_authn
+    });
+    const res = await this.http.requestRaw(
+      `/auth/sso/t/${encodeURIComponent(tenant)}/${encodeURIComponent(providerSlug)}/login${qs}`,
+      { method: "GET", redirect: "manual" }
+    );
+    const loc = res.headers.get("location");
+    const requestId = res.headers.get("x-request-id") || void 0;
+    if (res.status >= 400) {
+      let errorMsg = `SSO start failed with status ${res.status}`;
+      try {
+        const body = await res.json();
+        if (body?.error) errorMsg += `: ${body.error}`;
+      } catch {
+      }
+      throw new Error(`${errorMsg}${requestId ? ` (request: ${requestId})` : ""}`);
+    }
+    if (!loc) {
+      throw new Error(
+        `missing redirect location from SSO start${requestId ? ` (request: ${requestId})` : ""}`
+      );
+    }
+    return {
+      data: { redirect_url: loc },
+      meta: { status: res.status, requestId, headers: toHeadersMap(res.headers) }
+    };
+  }
+  /**
+   * Handle SSO callback and exchange code for tokens.
+   * Uses V2 tenant-scoped URLs: /auth/sso/t/{tenant_id}/{slug}/callback
+   * 
+   * @param providerSlug - The provider slug used in startSso
+   * @param params - Callback parameters (code, state from IdP redirect)
+   * @returns Access and refresh tokens
+   */
+  async handleSsoCallback(providerSlug, params) {
+    const tenant = params.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required for SSO callback");
+    const qs = this.buildQuery({ code: params.code, state: params.state });
+    const res = await this.request(
+      `/auth/sso/t/${encodeURIComponent(tenant)}/${encodeURIComponent(providerSlug)}/callback${qs}`,
+      { method: "GET" }
+    );
+    if (res.meta.status === 200) this.persistTokensFrom(res.data);
+    return res;
+  }
+  /**
+   * Parse SSO callback tokens from URL query parameters or fragment.
+   * Use this when Guard redirects to your app's callback URL with tokens.
+   * 
+   * **Note:** This method has a side effect: when tokens are successfully parsed,
+   * they are automatically persisted to the configured TokenStorage.
+   * 
+   * @param url - The full callback URL or just the query/fragment string (e.g., window.location.search or window.location.hash)
+   * @returns Tokens if access_token is present in URL, null otherwise
+   * 
+   * @remarks
+   * - access_token is required for a successful return
+   * - refresh_token is optional (some flows don't provide it)
+   * - When refresh_token is missing, token refresh via `refresh()` will not be available
+   * - Tokens are persisted to storage on successful parse (side effect)
+   */
+  parseSsoCallbackTokens(url) {
+    try {
+      let searchParams;
+      if (url.startsWith("#")) {
+        searchParams = new URLSearchParams(url.substring(1));
+      } else if (url.startsWith("?") || url.startsWith("/") || url.startsWith("http")) {
+        const needsBase = url.startsWith("?") || url.startsWith("/");
+        const parsed = new URL(needsBase ? `http://x${url}` : url);
+        searchParams = parsed.hash ? new URLSearchParams(parsed.hash.substring(1)) : parsed.searchParams;
+      } else {
+        searchParams = new URLSearchParams(url);
+      }
+      const accessToken = searchParams.get("access_token");
+      const refreshToken = searchParams.get("refresh_token");
+      if (!accessToken) {
+        return null;
+      }
+      const tokens = {
+        access_token: accessToken,
+        refresh_token: refreshToken ?? void 0
+      };
+      this.persistTokensFrom(tokens);
+      return tokens;
+    } catch {
+      return null;
+    }
+  }
+  // SSO: WorkOS Organization Portal link (admin-only on server)
+  async getSsoOrganizationPortalLink(provider, params) {
+    const tenant = params.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    if (!params?.organization_id) throw new Error("organization_id is required");
+    const qs = this.buildQuery({
+      tenant_id: tenant,
+      organization_id: params.organization_id,
+      intent: params.intent
+    });
+    return this.request(`/v1/auth/sso/${provider}/portal-link${qs}`, { method: "GET" });
+  }
+  // SSO: Portal token session exchange (public, portal-token gated)
+  async ssoPortalSession(token) {
+    if (!token || typeof token !== "string") {
+      throw new Error("token is required");
+    }
+    return this.request("/v1/sso/portal/session", {
+      method: "POST",
+      body: JSON.stringify({ token })
+    });
+  }
+  // SSO: Portal provider config (public, portal-token gated)
+  async ssoPortalProvider(token) {
+    if (!token || typeof token !== "string") {
+      throw new Error("token is required");
+    }
+    const headers = { "X-Portal-Token": token };
+    return this.request("/v1/sso/portal/provider", {
+      method: "GET",
+      headers
+    });
+  }
+  // High-level helper: load portal session and provider in one call
+  async loadSsoPortalContext(token) {
+    const sessionRes = await this.ssoPortalSession(token);
+    if (sessionRes.meta.status !== 200 || !sessionRes.data) {
+      const serverError = this.extractErrorDetails(sessionRes.data);
+      const requestId = sessionRes.meta.requestId;
+      throw new Error(
+        `portal session failed with status ${sessionRes.meta.status}` + (serverError ? `: ${serverError}` : "") + (requestId ? ` (request: ${requestId})` : "")
+      );
+    }
+    const providerRes = await this.ssoPortalProvider(token);
+    if (providerRes.meta.status !== 200 || !providerRes.data) {
+      const serverError = this.extractErrorDetails(providerRes.data);
+      const requestId = providerRes.meta.requestId;
+      throw new Error(
+        `portal provider failed with status ${providerRes.meta.status}` + (serverError ? `: ${serverError}` : "") + (requestId ? ` (request: ${requestId})` : "")
+      );
+    }
+    return { session: sessionRes.data, provider: providerRes.data };
+  }
+  // Helper to extract error details from server response
+  extractErrorDetails(data) {
+    if (!data || typeof data !== "object") return null;
+    const obj = data;
+    if (typeof obj.error === "string") return obj.error;
+    if (typeof obj.message === "string") return obj.message;
+    if (typeof obj.description === "string") return obj.description;
+    if (typeof obj.detail === "string") return obj.detail;
+    return null;
+  }
+  // ==============================
+  // SSO Provider Management (Admin-only endpoints)
+  // ==============================
+  // List SSO providers for a tenant
+  async ssoListProviders(params = {}) {
+    const tenant = params.tenant_id ?? this.tenantId;
+    const qs = this.buildQuery({ tenant_id: tenant });
+    return this.request(`/v1/sso/providers${qs}`, { method: "GET" });
+  }
+  // Create a new SSO provider
+  async ssoCreateProvider(body) {
+    return this.request("/v1/sso/providers", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  // Get a specific SSO provider by ID
+  async ssoGetProvider(id) {
+    return this.request(`/v1/sso/providers/${encodeURIComponent(id)}`, {
+      method: "GET"
+    });
+  }
+  // Update an existing SSO provider
+  async ssoUpdateProvider(id, body) {
+    return this.request(`/v1/sso/providers/${encodeURIComponent(id)}`, {
+      method: "PUT",
+      body: JSON.stringify(body)
+    });
+  }
+  // Delete an SSO provider
+  async ssoDeleteProvider(id) {
+    return this.request(`/v1/sso/providers/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+  }
+  // Test SSO provider configuration
+  async ssoTestProvider(id) {
+    return this.request(`/v1/sso/providers/${encodeURIComponent(id)}/test`, {
+      method: "POST"
+    });
+  }
+  /**
+   * Get computed Service Provider (SP) URLs for SAML configuration.
+   * These URLs are needed by admins to configure their Identity Provider (IdP).
+   * URLs use V2 tenant-scoped format: /auth/sso/t/{tenant_id}/{slug}/*
+   * 
+   * @param slug - The provider slug (e.g. 'okta', 'azure-ad')
+   * @param tenantId - Optional tenant ID (uses client's default if not provided)
+   * @returns SP info including Entity ID, ACS URL, SLO URL, Metadata URL, Login URL, and Tenant ID
+   * 
+   * @example
+   * ```ts
+   * const spInfo = await client.ssoGetSPInfo('okta');
+   * console.log(spInfo.data.entity_id);  // https://api.example.com/auth/sso/t/{tenant_id}/okta/metadata
+   * console.log(spInfo.data.acs_url);    // https://api.example.com/auth/sso/t/{tenant_id}/okta/callback
+   * console.log(spInfo.data.tenant_id);  // The tenant UUID used in the URLs
+   * ```
+   */
+  async ssoGetSPInfo(slug, tenantId) {
+    if (!slug) throw new Error("slug is required");
+    const tenant = tenantId ?? this.tenantId;
+    const params = { slug };
+    if (tenant) params.tenant_id = tenant;
+    const qs = this.buildQuery(params);
+    return this.request(`/v1/sso/sp-info${qs}`, { method: "GET" });
+  }
+  // ==============================
+  // RBAC v2 (Admin-only endpoints)
+  // ==============================
+  // RBAC: List all permissions (admin-only)
+  async rbacListPermissions() {
+    return this.request("/v1/auth/admin/rbac/permissions", { method: "GET" });
+  }
+  // RBAC: List roles for a tenant
+  async rbacListRoles(params = {}) {
+    const tenant = params.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    const qs = this.buildQuery({ tenant_id: tenant });
+    return this.request(`/v1/auth/admin/rbac/roles${qs}`, { method: "GET" });
+  }
+  // RBAC: Create role
+  async rbacCreateRole(body) {
+    const tenant = body.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    const payload = { tenant_id: tenant, name: body.name, description: body.description };
+    return this.request("/v1/auth/admin/rbac/roles", { method: "POST", body: JSON.stringify(payload) });
+  }
+  // RBAC: Update role
+  async rbacUpdateRole(id, body) {
+    const tenant = body.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    const payload = { tenant_id: tenant, name: body.name, description: body.description };
+    return this.request(`/v1/auth/admin/rbac/roles/${encodeURIComponent(id)}`, { method: "PATCH", body: JSON.stringify(payload) });
+  }
+  // RBAC: Delete role
+  async rbacDeleteRole(id, params = {}) {
+    const tenant = params.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    const qs = this.buildQuery({ tenant_id: tenant });
+    return this.request(`/v1/auth/admin/rbac/roles/${encodeURIComponent(id)}${qs}`, { method: "DELETE" });
+  }
+  // RBAC: List user roles
+  async rbacListUserRoles(userId, params = {}) {
+    const tenant = params.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    const qs = this.buildQuery({ tenant_id: tenant });
+    return this.request(`/v1/auth/admin/rbac/users/${encodeURIComponent(userId)}/roles${qs}`, { method: "GET" });
+  }
+  // RBAC: Add user role
+  async rbacAddUserRole(userId, body) {
+    const tenant = body.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    const payload = { tenant_id: tenant, role_id: body.role_id };
+    return this.request(`/v1/auth/admin/rbac/users/${encodeURIComponent(userId)}/roles`, { method: "POST", body: JSON.stringify(payload) });
+  }
+  // RBAC: Remove user role
+  async rbacRemoveUserRole(userId, body) {
+    const tenant = body.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    const payload = { tenant_id: tenant, role_id: body.role_id };
+    return this.request(`/v1/auth/admin/rbac/users/${encodeURIComponent(userId)}/roles`, { method: "DELETE", body: JSON.stringify(payload) });
+  }
+  // RBAC: Upsert role permission
+  async rbacUpsertRolePermission(roleId, body) {
+    return this.request(`/v1/auth/admin/rbac/roles/${encodeURIComponent(roleId)}/permissions`, { method: "POST", body: JSON.stringify(body) });
+  }
+  // RBAC: Delete role permission
+  async rbacDeleteRolePermission(roleId, body) {
+    return this.request(`/v1/auth/admin/rbac/roles/${encodeURIComponent(roleId)}/permissions`, { method: "DELETE", body: JSON.stringify(body) });
+  }
+  // RBAC: Resolve user permissions
+  async rbacResolveUserPermissions(userId, params) {
+    const tenant = params?.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    const qs = this.buildQuery({ tenant_id: tenant });
+    return this.request(`/v1/auth/admin/rbac/users/${encodeURIComponent(userId)}/permissions/resolve${qs}`, { method: "GET" });
+  }
+  // ==============================
+  // FGA (Admin-only endpoints)
+  // ==============================
+  // Groups: list
+  async fgaListGroups(params) {
+    const tenant = params?.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    const qs = this.buildQuery({ tenant_id: tenant });
+    return this.request(`/v1/auth/admin/fga/groups${qs}`, { method: "GET" });
+  }
+  // Groups: create
+  async fgaCreateGroup(body) {
+    const tenant = body?.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    const payload = { tenant_id: tenant, name: body.name, description: body?.description ?? null };
+    return this.request(`/v1/auth/admin/fga/groups`, { method: "POST", body: JSON.stringify(payload) });
+  }
+  // Groups: delete
+  async fgaDeleteGroup(id, params) {
+    const tenant = params?.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    const qs = this.buildQuery({ tenant_id: tenant });
+    return this.request(`/v1/auth/admin/fga/groups/${encodeURIComponent(id)}${qs}`, { method: "DELETE" });
+  }
+  // Group membership: add
+  async fgaAddGroupMember(groupId, body) {
+    const payload = { user_id: body.user_id };
+    return this.request(`/v1/auth/admin/fga/groups/${encodeURIComponent(groupId)}/members`, { method: "POST", body: JSON.stringify(payload) });
+  }
+  // Group membership: remove
+  async fgaRemoveGroupMember(groupId, body) {
+    const payload = { user_id: body.user_id };
+    return this.request(`/v1/auth/admin/fga/groups/${encodeURIComponent(groupId)}/members`, { method: "DELETE", body: JSON.stringify(payload) });
+  }
+  // ACL tuples: create
+  async fgaCreateAclTuple(body) {
+    const tenant = body?.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    const payload = { ...body, tenant_id: tenant };
+    return this.request(`/v1/auth/admin/fga/acl/tuples`, { method: "POST", body: JSON.stringify(payload) });
+  }
+  // ACL tuples: delete
+  async fgaDeleteAclTuple(body) {
+    const tenant = body?.tenant_id ?? this.tenantId;
+    if (!tenant) throw new Error("tenant_id is required");
+    const payload = { ...body, tenant_id: tenant };
+    return this.request(`/v1/auth/admin/fga/acl/tuples`, { method: "DELETE", body: JSON.stringify(payload) });
+  }
+  // ==============================
+  // OAuth2 Discovery (RFC 8414)
+  // ==============================
+  /**
+   * Fetch OAuth 2.0 Authorization Server Metadata (RFC 8414)
+   * Returns server capabilities including supported auth modes, endpoints, and grant types.
+   * This endpoint is public and does not require authentication.
+   */
+  async getOAuth2Metadata() {
+    return this.request("/.well-known/oauth-authorization-server", { method: "GET" });
+  }
+  /**
+   * Static helper to discover OAuth2 metadata from any Guard API base URL.
+   * Useful for auto-configuration before creating a GuardClient instance.
+   *
+   * @example
+   * ```ts
+   * const metadata = await GuardClient.discover('https://api.example.com');
+   * console.log(metadata.guard_auth_modes_supported); // ['bearer', 'cookie']
+   * console.log(metadata.guard_auth_mode_default);    // 'bearer'
+   *
+   * // Create client with discovered default auth mode
+   * const client = new GuardClient({
+   *   baseUrl: 'https://api.example.com',
+   *   authMode: metadata.guard_auth_mode_default as 'bearer' | 'cookie'
+   * });
+   * ```
+   */
+  static async discover(baseUrl, fetchImpl) {
+    const fetch = fetchImpl ?? (typeof window !== "undefined" ? window.fetch.bind(window) : globalThis.fetch);
+    const url = `${baseUrl}/.well-known/oauth-authorization-server`;
+    const response = await fetch(url, { method: "GET" });
+    if (!response.ok) {
+      throw new Error(`Discovery failed: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+  }
+};
+function generateTOTPCode(base32Secret) {
+  if (!base32Secret || typeof base32Secret !== "string") {
+    throw new Error("TOTP secret must be a non-empty base32 string");
+  }
+  return authenticator.generate(base32Secret);
+}
+
+export { ApiError, GuardClient, HttpClient, InMemoryStorage, RateLimitError, WebLocalStorage, applyRequestInterceptors, applyResponseInterceptors, buildRateLimitError, generateTOTPCode, isApiError, isMfaChallengeResp, isRateLimitError, isTenantSelectionRequired, isTokensResp, noopStorage, parseRetryAfter, reactNativeStorageAdapter, toHeadersMap };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map