@userbox/react 0.0.0-stage → 1.0.0-alpha.0

package/dist/index.js

@@ -0,0 +1,1199 @@
+import * as React from 'react';
+import { createContext, useMemo, useState, useRef, useEffect, useCallback, useContext } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/react/UserboxProvider.tsx
+
+// src/core/errors.ts
+var ERROR_KINDS = /* @__PURE__ */ new Set([
+  "missing_credentials",
+  "auth_failed",
+  "refresh_failed",
+  "permission_fetch_failed",
+  "network",
+  "misconfigured"
+]);
+function isUserboxError(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return typeof candidate.kind === "string" && ERROR_KINDS.has(candidate.kind) && typeof candidate.message === "string";
+}
+function missingCredentials(message, requestId) {
+  return requestId ? { kind: "missing_credentials", message, requestId } : { kind: "missing_credentials", message };
+}
+function authFailed(message, httpStatus, code, requestId) {
+  return requestId ? { kind: "auth_failed", message, httpStatus, code, requestId } : { kind: "auth_failed", message, httpStatus, code };
+}
+function refreshFailed(message, httpStatus, code, requestId) {
+  return requestId ? { kind: "refresh_failed", message, httpStatus, code, requestId } : { kind: "refresh_failed", message, httpStatus, code };
+}
+function permissionFetchFailed(message, httpStatus, code, workspaceId, requestId) {
+  return requestId ? {
+    kind: "permission_fetch_failed",
+    message,
+    httpStatus,
+    code,
+    workspaceId,
+    requestId
+  } : { kind: "permission_fetch_failed", message, httpStatus, code, workspaceId };
+}
+function networkError(message) {
+  return { kind: "network", message };
+}
+function misconfigured(field, message) {
+  return { kind: "misconfigured", message, field };
+}
+
+// src/core/permission-cache.ts
+var PermissionCache = class {
+  entries = /* @__PURE__ */ new Map();
+  get(workspaceId) {
+    return this.entries.get(workspaceId);
+  }
+  has(workspaceId) {
+    return this.entries.has(workspaceId);
+  }
+  setLoading(workspaceId, promise) {
+    this.entries.set(workspaceId, {
+      state: "loading",
+      promise,
+      startedAt: Date.now()
+    });
+  }
+  setLoaded(workspaceId, permissions) {
+    const frozen = freezeSet(permissions);
+    this.entries.set(workspaceId, {
+      state: "loaded",
+      permissions: frozen,
+      fetchedAt: Date.now()
+    });
+  }
+  setError(workspaceId, error) {
+    const prior = this.entries.get(workspaceId);
+    const lastGood = prior && prior.state === "loaded" ? prior.permissions : void 0;
+    this.entries.set(workspaceId, lastGood !== void 0 ? { state: "error", error, failedAt: Date.now(), lastGood } : { state: "error", error, failedAt: Date.now() });
+  }
+  clear() {
+    this.entries.clear();
+  }
+  snapshot() {
+    return new Map(this.entries);
+  }
+};
+function freezeSet(values) {
+  const s = /* @__PURE__ */ new Set();
+  for (const v of values) {
+    if (typeof v === "string") s.add(v);
+  }
+  return s;
+}
+
+// src/core/redirect.ts
+var SLUG_REGEX = /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/;
+var MAX_RETURN_TO_LENGTH = 2048;
+function assertValidSlug(slug) {
+  if (typeof slug !== "string" || slug.length === 0) {
+    throw misconfiguredField("tenantSlug", "tenantSlug is required");
+  }
+  if (!SLUG_REGEX.test(slug)) {
+    throw misconfiguredField(
+      "tenantSlug",
+      "tenantSlug must match /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/"
+    );
+  }
+}
+function deriveAuthOrigin(baseUrl, tenantSlug) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw misconfiguredField("baseUrl", "baseUrl must be a valid absolute URL");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw misconfiguredField("baseUrl", "baseUrl must be http(s)");
+  }
+  const host = url.hostname;
+  const dotIdx = host.indexOf(".");
+  if (dotIdx === -1) {
+    throw misconfiguredField(
+      "baseUrl",
+      "baseUrl host must have at least two DNS labels (e.g. api.example.localhost)"
+    );
+  }
+  const parent = host.substring(dotIdx + 1);
+  const port = url.port ? `:${url.port}` : "";
+  return `${url.protocol}//${tenantSlug}.auth.${parent}${port}`;
+}
+function buildAuthSurfaceUrl(input) {
+  assertValidSlug(input.tenantSlug);
+  assertValidReturnTo(input.returnTo);
+  const origin = input.baseAuthUrl ?? deriveAuthOrigin(input.baseUrl, input.tenantSlug);
+  const trimmed = origin.replace(/\/+$/, "");
+  const u = new URL(trimmed + input.path);
+  u.searchParams.set("return_to", input.returnTo);
+  u.searchParams.set("state", input.state);
+  u.searchParams.set("flow_id", input.flowId);
+  return u.toString();
+}
+function assertValidReturnTo(returnTo, currentOrigin) {
+  if (typeof returnTo !== "string" || returnTo.length === 0) {
+    throw misconfiguredField("callbackUrl", "returnTo is required");
+  }
+  if (returnTo.length > MAX_RETURN_TO_LENGTH) {
+    throw misconfiguredField(
+      "callbackUrl",
+      `returnTo exceeds maximum length (${MAX_RETURN_TO_LENGTH})`
+    );
+  }
+  let parsed;
+  try {
+    parsed = new URL(returnTo);
+  } catch {
+    throw misconfiguredField("callbackUrl", "returnTo must be an absolute URL");
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw misconfiguredField("callbackUrl", "returnTo must be http(s)");
+  }
+  const origin = safeWindowOrigin();
+  if (origin && parsed.origin !== origin) {
+    throw misconfiguredField(
+      "callbackUrl",
+      "returnTo must be same-origin with the calling app"
+    );
+  }
+}
+function safeWindowOrigin() {
+  if (typeof window === "undefined") return null;
+  if (typeof window.location?.origin !== "string") return null;
+  return window.location.origin;
+}
+function misconfiguredField(field, message) {
+  return misconfigured(field, message);
+}
+
+// src/core/http.ts
+async function request(input) {
+  const headers = {
+    "X-Tenant-ID": input.tenantSlug,
+    Accept: "application/json",
+    ...input.headers
+  };
+  if (input.accessToken) {
+    headers.Authorization = `Bearer ${input.accessToken}`;
+  }
+  const init = {
+    method: input.method ?? "GET",
+    headers
+  };
+  if (input.body !== void 0) {
+    headers["Content-Type"] = "application/json";
+    init.body = JSON.stringify(input.body);
+  }
+  if (input.credentials !== void 0) {
+    init.credentials = input.credentials;
+  }
+  if (input.signal) init.signal = input.signal;
+  let response;
+  try {
+    response = await fetch(input.url, init);
+  } catch (err) {
+    return {
+      ok: false,
+      error: networkError(humaniseNetworkError(err))
+    };
+  }
+  const requestId = response.headers.get("X-Request-ID") ?? void 0;
+  if (response.status === 204) {
+    return { ok: true, data: void 0, requestId };
+  }
+  let parsed = null;
+  const text = await response.text();
+  if (text.length > 0) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = null;
+    }
+  }
+  if (response.ok) {
+    return { ok: true, data: parsed, requestId };
+  }
+  const shape = parsed ?? {};
+  const code = typeof shape.code === "string" ? shape.code : "UNKNOWN";
+  const message = typeof shape.error === "string" ? shape.error : `HTTP ${response.status}`;
+  const error = mapServerError(input, response.status, code, message, requestId);
+  return { ok: false, error };
+}
+function mapServerError(input, status, code, message, requestId) {
+  switch (input.errorKind) {
+    case "refresh":
+      return refreshFailed(message, status, code, requestId);
+    case "permissions":
+      return permissionFetchFailed(
+        message,
+        status,
+        code,
+        input.workspaceId ?? "",
+        requestId
+      );
+    case "auth":
+    default:
+      return authFailed(message, status, code, requestId);
+  }
+}
+function humaniseNetworkError(err) {
+  if (err instanceof DOMException && err.name === "AbortError") {
+    return "Request aborted";
+  }
+  if (err instanceof Error) return err.message || "Network error";
+  return "Network error";
+}
+
+// src/core/token.ts
+function base64UrlDecode(input) {
+  let s = input.replace(/-/g, "+").replace(/_/g, "/");
+  while (s.length % 4 !== 0) s += "=";
+  if (typeof atob === "function") return atob(s);
+  return Buffer.from(s, "base64").toString("binary");
+}
+function decodeJwtClaims(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    throw asAuthFailed("Malformed JWT");
+  }
+  const payload = parts[1];
+  if (!payload) throw asAuthFailed("Malformed JWT payload");
+  let json;
+  try {
+    json = base64UrlDecode(payload);
+  } catch {
+    throw asAuthFailed("Malformed JWT payload");
+  }
+  let obj;
+  try {
+    obj = JSON.parse(json);
+  } catch {
+    throw asAuthFailed("Malformed JWT payload");
+  }
+  if (typeof obj !== "object" || obj === null) {
+    throw asAuthFailed("Malformed JWT payload");
+  }
+  const claims = obj;
+  const sub = typeof claims.sub === "string" ? claims.sub : null;
+  const tid = typeof claims.tid === "string" ? claims.tid : null;
+  const exp = typeof claims.exp === "number" ? claims.exp : null;
+  const jti = typeof claims.jti === "string" ? claims.jti : void 0;
+  if (!sub || !tid || exp === null) {
+    throw asAuthFailed("JWT missing required claims (sub/tid/exp)");
+  }
+  return jti ? { sub, tid, exp, jti } : { sub, tid, exp };
+}
+function asAuthFailed(message) {
+  return authFailed(message, 401, "MALFORMED_JWT");
+}
+
+// src/core/refresh-engine.ts
+var RETRY_DELAYS_MS = [1e3, 3e3, 9e3];
+var PERMANENT_HTTP_STATUSES = /* @__PURE__ */ new Set([400, 401, 403]);
+var CLAIM_WINDOW_MS = 200;
+var RefreshEngine = class {
+  options;
+  now;
+  timer = null;
+  inFlight = null;
+  failureCount = 0;
+  permanentlyFailed = false;
+  sessionExpiredFired = false;
+  channel = null;
+  currentSession = null;
+  constructor(options) {
+    this.options = options;
+    this.now = options.now ?? Date.now;
+    this.setupChannel();
+  }
+  setupChannel() {
+    if (!this.options.broadcastChannelName) return;
+    if (typeof BroadcastChannel === "undefined") return;
+    try {
+      this.channel = new BroadcastChannel(
+        `userbox-refresh-${this.options.broadcastChannelName}`
+      );
+      this.channel.addEventListener("message", (evt) => {
+        this.handleBroadcast(evt.data);
+      });
+    } catch {
+      this.channel = null;
+    }
+  }
+  handleBroadcast(data) {
+    if (!data || typeof data !== "object") return;
+    const msg = data;
+    if (msg.type !== "session" || typeof msg.session !== "object" || msg.session === null) return;
+    const session = msg.session;
+    if (typeof session.accessToken !== "string" || typeof session.accessTokenExpiresAt !== "number" || typeof session.refreshExpiresAt !== "number" || typeof session.user !== "object" || session.user === null) {
+      return;
+    }
+    const u = session.user;
+    if (typeof u.id !== "string" || typeof u.tenantId !== "string") return;
+    const normalised = {
+      accessToken: session.accessToken,
+      accessTokenExpiresAt: session.accessTokenExpiresAt,
+      refreshExpiresAt: session.refreshExpiresAt,
+      user: {
+        id: u.id,
+        tenantId: u.tenantId,
+        email: typeof u.email === "string" ? u.email : null,
+        fullName: typeof u.fullName === "string" ? u.fullName : null
+      }
+    };
+    this.adoptSession(normalised);
+  }
+  adoptSession(session) {
+    if (this.currentSession && this.currentSession.user.id !== session.user.id) {
+      this.permanentlyFailed = true;
+      this.clearTimer();
+      this.options.onError(authFailed("Session identity changed unexpectedly", 401, "IDENTITY_SWAP"));
+      this.fireSessionExpiredOnce();
+      return;
+    }
+    this.currentSession = session;
+    this.options.onSession(session);
+    this.scheduleNextRefresh();
+  }
+  /**
+   * Adopt the initial session (e.g. from the callback flow). Subsequent
+   * refreshes are scheduled automatically.
+   */
+  primeSession(session) {
+    this.permanentlyFailed = false;
+    this.sessionExpiredFired = false;
+    this.failureCount = 0;
+    this.currentSession = session;
+    this.scheduleNextRefresh();
+  }
+  hasSession() {
+    return this.currentSession !== null;
+  }
+  isPermanentlyFailed() {
+    return this.permanentlyFailed;
+  }
+  getSession() {
+    return this.currentSession;
+  }
+  async refresh() {
+    if (this.permanentlyFailed) {
+      return {
+        kind: "permanent_fail",
+        error: authFailed("Refresh already permanently failed", 401, "PERMANENT_FAIL")
+      };
+    }
+    if (this.inFlight) return this.inFlight;
+    this.inFlight = this.performRefreshWithCoordination().finally(() => {
+      this.inFlight = null;
+    });
+    return this.inFlight;
+  }
+  async performRefreshWithCoordination() {
+    if (this.channel) {
+      const winner = await this.claimRefreshWindow();
+      if (winner) return winner;
+    }
+    return this.performRefresh();
+  }
+  claimRefreshWindow() {
+    return new Promise((resolve) => {
+      let resolved = false;
+      const channel = this.channel;
+      if (!channel) {
+        resolve(null);
+        return;
+      }
+      const listener = (evt) => {
+        if (resolved) return;
+        if (!evt.data || typeof evt.data !== "object") return;
+        const msg = evt.data;
+        if (msg.type !== "session") return;
+        const previous = this.currentSession;
+        this.handleBroadcast(evt.data);
+        if (this.currentSession && this.currentSession !== previous) {
+          resolved = true;
+          channel.removeEventListener("message", listener);
+          resolve({
+            kind: "ok",
+            session: this.currentSession,
+            rawRefreshToken: null,
+            nextRefreshIn: this.computeNextRefreshIn(this.currentSession)
+          });
+        }
+      };
+      channel.addEventListener("message", listener);
+      try {
+        channel.postMessage({ type: "claim" });
+      } catch {
+      }
+      setTimeout(() => {
+        if (resolved) return;
+        channel.removeEventListener("message", listener);
+        resolve(null);
+      }, CLAIM_WINDOW_MS);
+    });
+  }
+  async performRefresh() {
+    const body = this.options.tokenStorage === "memory" ? { refresh_token: this.options.sessionStore.getRefreshToken() ?? "" } : {};
+    const res = await request({
+      url: this.options.refreshUrl,
+      method: "POST",
+      tenantSlug: this.options.tenantSlug,
+      body,
+      // Under cookie mode the refresh cookie may live on a different origin
+      // (tenant backend). Same-origin keeps memory mode safe.
+      credentials: this.options.tokenStorage === "cookie" ? "include" : "same-origin",
+      errorKind: "refresh"
+    });
+    if (!res.ok) {
+      const error = res.error;
+      const status = error.kind === "refresh_failed" || error.kind === "auth_failed" ? error.httpStatus : 0;
+      if (error.kind === "refresh_failed" && PERMANENT_HTTP_STATUSES.has(status)) {
+        return this.transitionPermanent(error);
+      }
+      return this.transitionTransient(error);
+    }
+    const data = res.data;
+    const accessToken = typeof data.access_token === "string" ? data.access_token : "";
+    const expiresIn = typeof data.expires_in === "number" ? data.expires_in : 0;
+    const refreshExpiresIn = typeof data.refresh_expires_in === "number" ? data.refresh_expires_in : expiresIn;
+    if (!accessToken || expiresIn <= 0) {
+      return this.transitionTransient(
+        authFailed("Refresh response missing access_token / expires_in", 500, "MALFORMED_RESPONSE")
+      );
+    }
+    let claims;
+    try {
+      claims = decodeJwtClaims(accessToken);
+    } catch (e) {
+      const err = e;
+      return this.transitionPermanent(err);
+    }
+    const newRefreshToken = typeof data.refresh_token === "string" ? data.refresh_token : null;
+    if (this.options.tokenStorage === "memory" && newRefreshToken) {
+      this.options.sessionStore.setRefreshToken(newRefreshToken);
+    }
+    const previousUserId = this.currentSession?.user.id ?? null;
+    if (previousUserId && previousUserId !== claims.sub) {
+      const err = authFailed("Session identity changed unexpectedly", 401, "IDENTITY_SWAP");
+      return this.transitionPermanent(err);
+    }
+    const session = {
+      accessToken,
+      accessTokenExpiresAt: this.now() + expiresIn * 1e3,
+      refreshExpiresAt: this.now() + refreshExpiresIn * 1e3,
+      user: {
+        id: claims.sub,
+        tenantId: claims.tid,
+        email: this.currentSession?.user.email ?? null,
+        fullName: this.currentSession?.user.fullName ?? null
+      }
+    };
+    this.failureCount = 0;
+    this.currentSession = session;
+    this.options.onSession(session);
+    this.scheduleNextRefresh();
+    this.broadcast(session);
+    return {
+      kind: "ok",
+      session,
+      rawRefreshToken: newRefreshToken,
+      nextRefreshIn: this.computeNextRefreshIn(session)
+    };
+  }
+  transitionPermanent(error) {
+    this.permanentlyFailed = true;
+    this.clearTimer();
+    this.options.onError(error);
+    this.fireSessionExpiredOnce();
+    return { kind: "permanent_fail", error };
+  }
+  transitionTransient(error) {
+    this.failureCount += 1;
+    this.options.onError(error);
+    if (this.failureCount >= RETRY_DELAYS_MS.length) {
+      const escalated = authFailed(
+        "Refresh transient failures exceeded retry budget",
+        503,
+        "REFRESH_RETRY_BUDGET"
+      );
+      this.transitionPermanent(escalated);
+      return { kind: "transient_fail", error, retryInMs: 0 };
+    }
+    const retryInMs = RETRY_DELAYS_MS[this.failureCount - 1] ?? 9e3;
+    this.scheduleTimer(retryInMs);
+    return { kind: "transient_fail", error, retryInMs };
+  }
+  fireSessionExpiredOnce() {
+    if (this.sessionExpiredFired) return;
+    this.sessionExpiredFired = true;
+    this.options.onSessionExpired();
+  }
+  computeNextRefreshIn(session) {
+    const ttl = session.accessTokenExpiresAt - this.now();
+    const reserved = Math.max(
+      ttl * this.options.refreshThresholdPct,
+      this.options.proactiveSkewMs
+    );
+    const next = ttl - reserved;
+    return Math.max(next, 0);
+  }
+  scheduleNextRefresh() {
+    if (!this.currentSession) return;
+    if (this.permanentlyFailed) return;
+    const delay = this.computeNextRefreshIn(this.currentSession);
+    this.scheduleTimer(delay);
+  }
+  scheduleTimer(delay) {
+    this.clearTimer();
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.refresh();
+    }, delay);
+  }
+  clearTimer() {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+  broadcast(session) {
+    if (!this.channel) return;
+    try {
+      this.channel.postMessage({ type: "session", session });
+    } catch {
+    }
+  }
+  /** Test/teardown hook. */
+  dispose() {
+    this.clearTimer();
+    if (this.channel) {
+      try {
+        this.channel.close();
+      } catch {
+      }
+      this.channel = null;
+    }
+  }
+};
+
+// src/core/session-store.ts
+var MemoryStore = class {
+  kind = "memory";
+  token = null;
+  getRefreshToken() {
+    return this.token;
+  }
+  setRefreshToken(token) {
+    this.token = token;
+  }
+};
+var CookieStore = class {
+  kind = "cookie";
+  // The browser owns the cookie; the SDK never reads or writes it directly.
+  getRefreshToken() {
+    return null;
+  }
+  setRefreshToken(_token) {
+  }
+};
+function createSessionStore(kind) {
+  return kind === "memory" ? new MemoryStore() : new CookieStore();
+}
+var UserboxContext = createContext(null);
+var DEFAULT_REFRESH_THRESHOLD_PCT = 0.2;
+var DEFAULT_PROACTIVE_SKEW_MS = 5e3;
+function validateConfig(props) {
+  if (typeof props.tenantSlug !== "string" || props.tenantSlug.length === 0) {
+    throw misconfigured("tenantSlug", "tenantSlug is required");
+  }
+  assertValidSlug(props.tenantSlug);
+  if (typeof props.baseUrl !== "string" || props.baseUrl.length === 0) {
+    throw misconfigured("baseUrl", "baseUrl is required");
+  }
+  if (props.baseUrl.endsWith("/")) {
+    throw misconfigured("baseUrl", "baseUrl must not have a trailing slash");
+  }
+  if (props.tokenStorage !== "memory" && props.tokenStorage !== "cookie") {
+    throw misconfigured("tokenStorage", "tokenStorage must be 'memory' or 'cookie'");
+  }
+  const refreshUrl = props.refreshUrl ?? (props.tokenStorage === "cookie" ? "/api/auth/refresh" : `${props.baseUrl}/v1/auth/refresh`);
+  const config = Object.freeze({
+    tenantSlug: props.tenantSlug,
+    baseUrl: props.baseUrl,
+    baseAuthUrl: props.baseAuthUrl,
+    tokenStorage: props.tokenStorage,
+    refreshUrl,
+    refreshThresholdPct: props.refreshThresholdPct ?? DEFAULT_REFRESH_THRESHOLD_PCT,
+    proactiveSkewMs: props.proactiveSkewMs ?? DEFAULT_PROACTIVE_SKEW_MS,
+    onSessionExpired: props.onSessionExpired,
+    onError: props.onError
+  });
+  return config;
+}
+var UserboxProvider = (props) => {
+  const parent = React.useContext(UserboxContext);
+  if (parent) {
+    throw misconfigured("tenantSlug", "UserboxProvider cannot be nested");
+  }
+  const config = useMemo(() => validateConfig(props), [
+    props.tenantSlug,
+    props.baseUrl,
+    props.baseAuthUrl,
+    props.tokenStorage,
+    props.refreshUrl,
+    props.refreshThresholdPct,
+    props.proactiveSkewMs
+  ]);
+  const [state, setState] = useState({
+    session: null,
+    isLoaded: false,
+    permissionsVersion: 0
+  });
+  const cacheRef = useRef(new PermissionCache());
+  const sessionStoreRef = useRef(null);
+  const engineRef = useRef(null);
+  const userMeFetchedRef = useRef(null);
+  if (!sessionStoreRef.current) {
+    sessionStoreRef.current = createSessionStore(config.tokenStorage);
+  }
+  if (!engineRef.current) {
+    engineRef.current = new RefreshEngine({
+      tenantSlug: config.tenantSlug,
+      baseUrl: config.baseUrl,
+      refreshUrl: config.refreshUrl,
+      tokenStorage: config.tokenStorage,
+      sessionStore: sessionStoreRef.current,
+      refreshThresholdPct: config.refreshThresholdPct,
+      proactiveSkewMs: config.proactiveSkewMs,
+      onSession: (session) => {
+        setState((s) => ({ ...s, session, isLoaded: true }));
+      },
+      onSessionExpired: () => {
+        cacheRef.current.clear();
+        setState((s) => ({
+          session: null,
+          isLoaded: true,
+          permissionsVersion: s.permissionsVersion + 1
+        }));
+        config.onSessionExpired?.();
+      },
+      onError: (err) => {
+        config.onError?.(err);
+      },
+      broadcastChannelName: config.tenantSlug
+    });
+  }
+  useEffect(() => {
+    const engine = engineRef.current;
+    let cancelled = false;
+    void (async () => {
+      const result = await engine.refresh();
+      if (cancelled) return;
+      if (result.kind !== "ok") {
+        setState((s) => ({ ...s, session: null, isLoaded: true }));
+      }
+    })();
+    return () => {
+      cancelled = true;
+      engine.dispose();
+    };
+  }, []);
+  useEffect(() => {
+    const session = state.session;
+    if (!session) return;
+    if (userMeFetchedRef.current === session.user.id && session.user.email !== null) {
+      return;
+    }
+    let cancelled = false;
+    void (async () => {
+      const res = await request({
+        url: `${config.baseUrl}/v1/users/me`,
+        tenantSlug: config.tenantSlug,
+        accessToken: session.accessToken,
+        errorKind: "auth"
+      });
+      if (cancelled) return;
+      if (!res.ok) {
+        return;
+      }
+      const data = res.data;
+      const email = typeof data?.email === "string" ? data.email : null;
+      const fullName = typeof data?.full_name === "string" ? data.full_name : null;
+      userMeFetchedRef.current = session.user.id;
+      setState((s) => {
+        if (!s.session || s.session.user.id !== session.user.id) return s;
+        const next = {
+          ...s.session,
+          user: { ...s.session.user, email, fullName }
+        };
+        return { ...s, session: next };
+      });
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [state.session, config.baseUrl, config.tenantSlug]);
+  const ensurePermissions = useCallback(
+    (workspaceId) => {
+      const cache = cacheRef.current;
+      if (cache.has(workspaceId)) return;
+      const engine = engineRef.current;
+      const session = engine.getSession();
+      if (!session) return;
+      const url = `${config.baseUrl}/v1/access/permissions?user_id=${encodeURIComponent(
+        session.user.id
+      )}&workspace_id=${encodeURIComponent(workspaceId)}`;
+      const promise = (async () => {
+        const res = await request({
+          url,
+          tenantSlug: config.tenantSlug,
+          accessToken: session.accessToken,
+          errorKind: "permissions",
+          workspaceId
+        });
+        if (!res.ok) {
+          cache.setError(workspaceId, res.error);
+          config.onError?.(res.error);
+          setState((s) => ({ ...s, permissionsVersion: s.permissionsVersion + 1 }));
+          return /* @__PURE__ */ new Set();
+        }
+        const list = Array.isArray(res.data?.permissions) ? res.data.permissions.filter(
+          (x) => typeof x === "string"
+        ) : [];
+        cache.setLoaded(workspaceId, list);
+        setState((s) => ({ ...s, permissionsVersion: s.permissionsVersion + 1 }));
+        return new Set(list);
+      })();
+      cache.setLoading(workspaceId, promise);
+    },
+    [config.baseUrl, config.tenantSlug]
+  );
+  const adoptCallbackSession = useCallback(
+    (session, rawRefreshToken) => {
+      const engine = engineRef.current;
+      if (config.tokenStorage === "memory" && rawRefreshToken) {
+        sessionStoreRef.current?.setRefreshToken(rawRefreshToken);
+      }
+      engine.primeSession(session);
+      setState((s) => ({ ...s, session, isLoaded: true }));
+    },
+    [config.tokenStorage]
+  );
+  const navigate = useCallback((url) => {
+    if (typeof window !== "undefined") {
+      window.location.href = url;
+    }
+  }, []);
+  const signOut = useCallback(
+    async (redirectUri) => {
+      const engine = engineRef.current;
+      const session = engine.getSession();
+      const refreshToken = config.tokenStorage === "memory" ? sessionStoreRef.current?.getRefreshToken() ?? null : null;
+      sessionStoreRef.current?.setRefreshToken(null);
+      cacheRef.current.clear();
+      setState((s) => ({
+        session: null,
+        isLoaded: true,
+        permissionsVersion: s.permissionsVersion + 1
+      }));
+      if (config.tokenStorage === "memory") try {
+        const body = { refresh_token: refreshToken ?? "" };
+        const res = await request({
+          url: `${config.baseUrl}/v1/auth/logout`,
+          method: "POST",
+          tenantSlug: config.tenantSlug,
+          accessToken: session?.accessToken ?? null,
+          body,
+          credentials: "same-origin",
+          errorKind: "auth"
+        });
+        if (!res.ok) {
+          const err = res.error;
+          if (!(err.kind === "auth_failed" && err.code === "INVALID_REFRESH_TOKEN")) {
+            config.onError?.(err);
+          }
+        }
+      } catch (err) {
+        config.onError?.(authFailed("logout failed", 0, "LOGOUT_FAILED"));
+      }
+      if (config.tokenStorage === "cookie") {
+        try {
+          await request({
+            url: config.refreshUrl,
+            method: "POST",
+            tenantSlug: config.tenantSlug,
+            accessToken: session?.accessToken ?? null,
+            body: { action: "logout" },
+            credentials: "include",
+            errorKind: "auth"
+          });
+        } catch {
+        }
+      }
+      navigate(redirectUri ?? (typeof window !== "undefined" ? window.location.origin : "/"));
+    },
+    [config, navigate]
+  );
+  const contextValue = useMemo(
+    () => ({
+      session: state.session,
+      isLoaded: state.isLoaded,
+      permissionCache: cacheRef.current,
+      ensurePermissions,
+      permissionsVersion: state.permissionsVersion,
+      navigate,
+      signOut,
+      config,
+      refreshEngine: engineRef.current,
+      adoptCallbackSession
+    }),
+    [
+      state.session,
+      state.isLoaded,
+      state.permissionsVersion,
+      ensurePermissions,
+      navigate,
+      signOut,
+      config,
+      adoptCallbackSession
+    ]
+  );
+  return /* @__PURE__ */ jsx(UserboxContext.Provider, { value: contextValue, children: props.children });
+};
+function useSession() {
+  const ctx = useContext(UserboxContext);
+  if (!ctx) {
+    throw misconfigured(
+      "tenantSlug",
+      "useSession() must be called inside a <UserboxProvider>"
+    );
+  }
+  if (!ctx.isLoaded) {
+    return { isLoaded: false, isSignedIn: false, user: null };
+  }
+  if (!ctx.session) {
+    return { isLoaded: true, isSignedIn: false, user: null };
+  }
+  return { isLoaded: true, isSignedIn: true, user: ctx.session.user };
+}
+function useAccessToken() {
+  const ctx = useContext(UserboxContext);
+  if (!ctx) {
+    throw misconfigured(
+      "tenantSlug",
+      "useAccessToken() must be called inside a <UserboxProvider>"
+    );
+  }
+  return ctx.session?.accessToken ?? null;
+}
+var EMPTY_SET = /* @__PURE__ */ new Set();
+function usePermissions(workspaceId) {
+  const ctx = useContext(UserboxContext);
+  if (!ctx) {
+    throw misconfigured(
+      "tenantSlug",
+      "usePermissions() must be called inside a <UserboxProvider>"
+    );
+  }
+  useEffect(() => {
+    if (!workspaceId) return;
+    if (!ctx.session) return;
+    ctx.ensurePermissions(workspaceId);
+  }, [workspaceId, ctx.session, ctx]);
+  return useMemo(() => {
+    if (!workspaceId) {
+      return { permissions: EMPTY_SET, isLoaded: false, error: null };
+    }
+    const entry = ctx.permissionCache.get(workspaceId);
+    if (!entry) {
+      return { permissions: EMPTY_SET, isLoaded: false, error: null };
+    }
+    if (entry.state === "loaded") {
+      return { permissions: entry.permissions, isLoaded: true, error: null };
+    }
+    if (entry.state === "error") {
+      return {
+        permissions: entry.lastGood ?? EMPTY_SET,
+        isLoaded: true,
+        error: entry.error
+      };
+    }
+    return { permissions: EMPTY_SET, isLoaded: false, error: null };
+  }, [workspaceId, ctx.permissionCache, ctx.permissionsVersion]);
+}
+
+// src/react/usePermission.ts
+function usePermission(workspaceId, permissionKey) {
+  const { permissions, isLoaded } = usePermissions(workspaceId);
+  const allowed = isLoaded ? permissions.has(permissionKey) : false;
+  return { allowed, isLoaded };
+}
+
+// src/core/state-nonce.ts
+var STORAGE_KEY = "ub.auth.state";
+var MAX_FLOW_AGE_MS = 10 * 60 * 1e3;
+function getStorage() {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+function readMap(storage) {
+  try {
+    const raw = storage.getItem(STORAGE_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) return {};
+    const out = {};
+    for (const [k, v] of Object.entries(parsed)) {
+      if (typeof v !== "object" || v === null) continue;
+      const flow = v;
+      if (typeof flow.nonce === "string" && typeof flow.createdAt === "number") {
+        out[k] = { nonce: flow.nonce, createdAt: flow.createdAt };
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+function writeMap(storage, map) {
+  try {
+    storage.setItem(STORAGE_KEY, JSON.stringify(map));
+  } catch {
+  }
+}
+function pruneStale(map, now) {
+  const out = {};
+  for (const [k, v] of Object.entries(map)) {
+    if (now - v.createdAt <= MAX_FLOW_AGE_MS) out[k] = v;
+  }
+  return out;
+}
+function generateRandom() {
+  if (typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  if (typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.getRandomValues === "function") {
+    const buf = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(buf);
+    return Array.from(buf, (b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  return `${Date.now().toString(16)}-${Math.random().toString(16).slice(2)}`;
+}
+function issueNonce() {
+  const flowId = generateRandom();
+  const nonce = generateRandom();
+  const storage = getStorage();
+  if (storage) {
+    const map = pruneStale(readMap(storage), Date.now());
+    map[flowId] = { nonce, createdAt: Date.now() };
+    writeMap(storage, map);
+  }
+  return { flowId, nonce };
+}
+function consumeNonce(flowId) {
+  const storage = getStorage();
+  if (!storage) return null;
+  const map = pruneStale(readMap(storage), Date.now());
+  const entry = map[flowId];
+  if (!entry) {
+    writeMap(storage, map);
+    return null;
+  }
+  delete map[flowId];
+  writeMap(storage, map);
+  return entry.nonce;
+}
+
+// src/react/useSignIn.ts
+function useSignIn() {
+  const ctx = useContext(UserboxContext);
+  if (!ctx) {
+    throw misconfigured(
+      "tenantSlug",
+      "useSignIn() must be called inside a <UserboxProvider>"
+    );
+  }
+  const signIn = useCallback(
+    (opts) => {
+      const returnTo = opts?.returnTo ?? (typeof window !== "undefined" ? window.location.href : "/");
+      assertValidReturnTo(returnTo);
+      const { flowId, nonce } = issueNonce();
+      const url = buildAuthSurfaceUrl({
+        tenantSlug: ctx.config.tenantSlug,
+        baseUrl: ctx.config.baseUrl,
+        baseAuthUrl: ctx.config.baseAuthUrl,
+        path: "/login",
+        returnTo,
+        state: nonce,
+        flowId
+      });
+      ctx.navigate(url);
+    },
+    [ctx]
+  );
+  return { signIn };
+}
+function useSignUp() {
+  const ctx = useContext(UserboxContext);
+  if (!ctx) {
+    throw misconfigured(
+      "tenantSlug",
+      "useSignUp() must be called inside a <UserboxProvider>"
+    );
+  }
+  const signUp = useCallback(
+    (opts) => {
+      const returnTo = opts?.returnTo ?? (typeof window !== "undefined" ? window.location.href : "/");
+      assertValidReturnTo(returnTo);
+      const { flowId, nonce } = issueNonce();
+      const url = buildAuthSurfaceUrl({
+        tenantSlug: ctx.config.tenantSlug,
+        baseUrl: ctx.config.baseUrl,
+        baseAuthUrl: ctx.config.baseAuthUrl,
+        path: "/signup",
+        returnTo,
+        state: nonce,
+        flowId
+      });
+      ctx.navigate(url);
+    },
+    [ctx]
+  );
+  return { signUp };
+}
+function useSignOut() {
+  const ctx = useContext(UserboxContext);
+  if (!ctx) {
+    throw misconfigured(
+      "tenantSlug",
+      "useSignOut() must be called inside a <UserboxProvider>"
+    );
+  }
+  const signOut = useCallback(
+    async (opts) => {
+      await ctx.signOut(opts?.redirectUri);
+    },
+    [ctx]
+  );
+  return { signOut };
+}
+function parseHash(hash) {
+  const out = {};
+  const raw = hash.startsWith("#") ? hash.slice(1) : hash;
+  if (!raw) return out;
+  for (const piece of raw.split("&")) {
+    const [k, v] = piece.split("=");
+    if (!k) continue;
+    out[decodeURIComponent(k)] = v ? decodeURIComponent(v) : "";
+  }
+  return out;
+}
+var UserboxCallback = ({
+  onSuccess,
+  onError
+}) => {
+  const ctx = useContext(UserboxContext);
+  const ranRef = useRef(false);
+  useEffect(() => {
+    if (ranRef.current) return;
+    ranRef.current = true;
+    if (!ctx) return;
+    if (typeof window === "undefined") return;
+    const hash = window.location.hash;
+    const params = parseHash(hash);
+    if (!hash || Object.keys(params).length === 0) {
+      return;
+    }
+    const stripFragment = () => {
+      const { pathname, search } = window.location;
+      try {
+        window.history.replaceState(null, "", pathname + search);
+      } catch {
+      }
+    };
+    if (params.error) {
+      stripFragment();
+      const err = authFailed(
+        params.error_description || params.error,
+        400,
+        params.error
+      );
+      onError?.(err);
+      return;
+    }
+    const accessToken = params.access_token;
+    const refreshToken = params.refresh_token;
+    const expiresIn = Number.parseInt(params.expires_in ?? "0", 10);
+    const refreshExpiresIn = Number.parseInt(
+      params.refresh_expires_in ?? params.expires_in ?? "0",
+      10
+    );
+    const state = params.state;
+    const flowId = params.flow_id;
+    if (!accessToken || !refreshToken || !expiresIn) {
+      onError?.(missingCredentials("Callback URL missing access_token / refresh_token / expires_in"));
+      return;
+    }
+    if (!flowId || !state) {
+      stripFragment();
+      onError?.(authFailed("Callback URL missing state/flow_id", 400, "STATE_MISSING"));
+      return;
+    }
+    const expectedNonce = consumeNonce(flowId);
+    if (expectedNonce === null || expectedNonce !== state) {
+      stripFragment();
+      onError?.(authFailed("Callback state mismatch \u2014 possible CSRF", 400, "STATE_MISMATCH"));
+      return;
+    }
+    let claims;
+    try {
+      claims = decodeJwtClaims(accessToken);
+    } catch (e) {
+      stripFragment();
+      onError?.(e);
+      return;
+    }
+    const session = {
+      accessToken,
+      accessTokenExpiresAt: Date.now() + expiresIn * 1e3,
+      refreshExpiresAt: Date.now() + refreshExpiresIn * 1e3,
+      user: {
+        id: claims.sub,
+        tenantId: claims.tid,
+        email: null,
+        fullName: null
+      }
+    };
+    if (ctx.config.tokenStorage === "cookie") {
+      void (async () => {
+        const res = await request({
+          url: ctx.config.refreshUrl,
+          method: "POST",
+          tenantSlug: ctx.config.tenantSlug,
+          body: { action: "init", refresh_token: refreshToken },
+          credentials: "include",
+          errorKind: "auth"
+        });
+        if (!res.ok) onError?.(res.error);
+      })();
+    }
+    ctx.adoptCallbackSession(session, refreshToken);
+    stripFragment();
+    onSuccess?.({ user: session.user });
+  }, [ctx, onError, onSuccess]);
+  return null;
+};
+
+export { UserboxCallback, UserboxProvider, isUserboxError, useAccessToken, usePermission, usePermissions, useSession, useSignIn, useSignOut, useSignUp };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map