@ai-matrx/auth 0.1.3 → 0.2.0

package/dist/matrx-oauth.cjs

@@ -0,0 +1,458 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/matrx-oauth.ts
+var matrx_oauth_exports = {};
+__export(matrx_oauth_exports, {
+  GrantRefusedError: () => GrantRefusedError,
+  MatrxOAuthError: () => MatrxOAuthError,
+  TransientAuthError: () => TransientAuthError,
+  buildAuthorizeUrl: () => buildAuthorizeUrl,
+  codeChallengeFor: () => codeChallengeFor,
+  constantTimeEqual: () => constantTimeEqual,
+  createMatrxOAuth: () => createMatrxOAuth,
+  generateCodeVerifier: () => generateCodeVerifier,
+  generateState: () => generateState,
+  parseCallbackUrl: () => parseCallbackUrl,
+  personIdFromAccessToken: () => personIdFromAccessToken
+});
+module.exports = __toCommonJS(matrx_oauth_exports);
+var MatrxOAuthError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "MatrxOAuthError";
+    this.code = code;
+  }
+};
+var GrantRefusedError = class extends MatrxOAuthError {
+  serverCode;
+  constructor(serverCode, detail) {
+    super("grant_refused", `sign-in refused (${serverCode}): ${detail}`);
+    this.name = "GrantRefusedError";
+    this.serverCode = serverCode;
+  }
+};
+var TransientAuthError = class extends MatrxOAuthError {
+  constructor(detail) {
+    super("transient", detail);
+    this.name = "TransientAuthError";
+  }
+};
+var TERMINAL_CODES = /* @__PURE__ */ new Set([
+  "invalid_grant",
+  "invalid_request",
+  "unauthorized_client",
+  "refresh_token_not_found",
+  "refresh_token_already_used",
+  "session_expired",
+  "session_not_found"
+]);
+function base64UrlEncode(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.byteLength; i++) s += String.fromCharCode(bytes[i]);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecodeToString(input) {
+  const b64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
+  const bin = atob(padded);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return new TextDecoder().decode(bytes);
+}
+function generateCodeVerifier() {
+  return base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)));
+}
+async function codeChallengeFor(verifier) {
+  const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return base64UrlEncode(new Uint8Array(hash));
+}
+function generateState() {
+  return base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)));
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function buildAuthorizeUrl(input) {
+  const url = new URL(`${input.authUrl.replace(/\/+$/, "")}/auth/v1/oauth/authorize`);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", input.clientId);
+  url.searchParams.set("redirect_uri", input.redirectUri);
+  url.searchParams.set("state", input.state);
+  url.searchParams.set("code_challenge", input.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("scope", input.scope);
+  return url.toString();
+}
+function parseCallbackUrl(callbackUrl) {
+  const u = new URL(callbackUrl);
+  const error = u.searchParams.get("error") || u.searchParams.get("error_description");
+  if (error) throw new MatrxOAuthError("callback_error", `OAuth error: ${error}`);
+  const code = u.searchParams.get("code");
+  const returnedState = u.searchParams.get("state");
+  if (!code || !returnedState) throw new MatrxOAuthError("callback_incomplete", "OAuth callback missing code/state");
+  return { code, returnedState };
+}
+function personIdFromAccessToken(token) {
+  const part = token.split(".")[1];
+  if (!part) throw new MatrxOAuthError("invalid_token", "the access token is not a JWT");
+  let payload;
+  try {
+    payload = JSON.parse(base64UrlDecodeToString(part));
+  } catch {
+    throw new MatrxOAuthError("invalid_token", "the access token payload is unreadable");
+  }
+  if (typeof payload.sub !== "string" || payload.sub.length === 0) {
+    throw new MatrxOAuthError("invalid_token", "the access token has no subject");
+  }
+  return {
+    personId: payload.sub,
+    email: typeof payload.email === "string" && payload.email.length > 0 ? payload.email : null,
+    expiresAtMs: typeof payload.exp === "number" ? payload.exp * 1e3 : null
+  };
+}
+function extractErrorMessage(raw) {
+  try {
+    const j = JSON.parse(raw);
+    for (const key of ["error_description", "error_message", "msg", "error", "code"]) {
+      const v = j[key];
+      if (typeof v === "string" && v.length > 0) return v;
+    }
+  } catch {
+  }
+  return null;
+}
+function createMatrxOAuth(config, ports) {
+  if (!config.clientId) {
+    throw new MatrxOAuthError(
+      "config_missing",
+      "The OAuth client id is not set. Register this app as a public PKCE client in the Matrx auth server, then pass its client id."
+    );
+  }
+  if (!config.authUrl || !config.redirectUri) {
+    throw new MatrxOAuthError("config_missing", "The OAuth auth server URL and redirect URI are required.");
+  }
+  if (typeof crypto === "undefined" || !crypto.subtle) {
+    throw new MatrxOAuthError("unsupported_environment", "WebCrypto is not available here, so sign-in cannot run.");
+  }
+  const base = config.authUrl.replace(/\/+$/, "");
+  const scope = config.scope ?? "email profile";
+  const refreshLeadMs = config.refreshLeadMs ?? 6e4;
+  const attemptTtlMs = config.attemptTtlMs ?? 6e5;
+  const timeoutMs = config.requestTimeoutMs ?? 15e3;
+  const prefix = config.storageKeyPrefix ?? "matrx-oauth";
+  const SESSION_KEY = `${prefix}.session`;
+  const ACTIVE_KEY = `${prefix}.active-attempt`;
+  const pendingKey = (state) => `${prefix}.pkce.${state}`;
+  const storage = ports.storage;
+  const pending = ports.pendingStorage ?? ports.storage;
+  const now = ports.now ?? Date.now;
+  const doFetch = (...args) => (ports.fetch ?? fetch)(...args);
+  const listeners = /* @__PURE__ */ new Set();
+  const emit = (e) => {
+    for (const l of [...listeners]) {
+      try {
+        l(e);
+      } catch {
+      }
+    }
+  };
+  let chain = Promise.resolve();
+  const lock = ports.lock ?? ((fn) => {
+    const run = chain.then(fn, fn);
+    chain = run.catch(() => void 0);
+    return run;
+  });
+  const seal = (s) => ports.seal ? ports.seal.encrypt(s) : Promise.resolve(s);
+  const unseal = (s) => ports.seal ? ports.seal.decrypt(s) : Promise.resolve(s);
+  async function loadStored() {
+    const raw = await storage.getItem(SESSION_KEY);
+    if (!raw) return null;
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed?.v !== 1 || typeof parsed.accessToken !== "string" || typeof parsed.refreshToken !== "string") {
+        throw new Error("shape");
+      }
+      return parsed;
+    } catch {
+      await storage.removeItem(SESSION_KEY);
+      emit({ type: "signed_out", reason: "unreadable" });
+      return null;
+    }
+  }
+  const toSession = (s) => ({
+    personId: s.personId,
+    email: s.email,
+    accessToken: s.accessToken,
+    expiresAtMs: s.expiresAtMs
+  });
+  async function clearLocal() {
+    const stored = await loadStored();
+    await storage.removeItem(SESSION_KEY);
+    await pending.removeItem(ACTIVE_KEY);
+    return stored?.accessToken ?? null;
+  }
+  async function tokenRequest(form) {
+    let res;
+    try {
+      res = await doFetch(`${base}/auth/v1/oauth/token`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          accept: "application/json",
+          ...config.publishableKey ? { apikey: config.publishableKey } : {}
+        },
+        body: new URLSearchParams(form).toString(),
+        ...typeof AbortSignal !== "undefined" && "timeout" in AbortSignal ? { signal: AbortSignal.timeout(timeoutMs) } : {}
+      });
+    } catch (error) {
+      throw new TransientAuthError(`the sign-in service is unreachable: ${String(error).slice(0, 200)}`);
+    }
+    const type = res.headers.get("content-type") ?? "";
+    const text = await res.text().catch(() => "");
+    const isExchange = form["grant_type"] === "authorization_code";
+    if (!type.includes("json")) {
+      throw new TransientAuthError(`the sign-in service answered ${res.status} with ${type || "no content type"}`);
+    }
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      throw new TransientAuthError(`the sign-in service answered ${res.status} with unreadable JSON`);
+    }
+    if (res.ok) {
+      const access = body["access_token"];
+      if (typeof access !== "string" || access.length === 0) {
+        throw new TransientAuthError("the token response carried no access token");
+      }
+      const refresh = body["refresh_token"];
+      const expiresIn = typeof body["expires_in"] === "number" && body["expires_in"] > 0 ? body["expires_in"] : 3600;
+      return {
+        accessToken: access,
+        refreshToken: typeof refresh === "string" && refresh.length > 0 ? refresh : null,
+        expiresAtMs: now() + expiresIn * 1e3
+      };
+    }
+    const code = String(body["error"] ?? body["error_code"] ?? res.status);
+    const detail = extractErrorMessage(text) ?? text.slice(0, 200);
+    if (isExchange) {
+      throw new MatrxOAuthError("token_exchange_failed", `Token exchange failed (${res.status}): ${detail}`);
+    }
+    if ((res.status === 400 || res.status === 401 || res.status === 403) && TERMINAL_CODES.has(code)) {
+      throw new GrantRefusedError(code, String(body["error_description"] ?? body["msg"] ?? body["message"] ?? ""));
+    }
+    throw new TransientAuthError(`the sign-in service answered ${res.status} ${code}: ${detail.slice(0, 200)}`);
+  }
+  async function commit(tokens, attemptId) {
+    if (!tokens.refreshToken) {
+      throw new MatrxOAuthError("token_exchange_failed", "Token exchange failed: the sign-in returned no refresh token");
+    }
+    const claims = personIdFromAccessToken(tokens.accessToken);
+    if (ports.beforeCommit) await ports.beforeCommit(tokens.accessToken);
+    const sealed = await seal(tokens.refreshToken);
+    return lock(async () => {
+      if (attemptId !== void 0 && await pending.getItem(ACTIVE_KEY) !== attemptId) {
+        throw new MatrxOAuthError("superseded", "This sign-in attempt was superseded by a newer authentication change");
+      }
+      const stored = {
+        v: 1,
+        clientId: config.clientId,
+        personId: claims.personId,
+        email: claims.email,
+        accessToken: tokens.accessToken,
+        refreshToken: sealed,
+        expiresAtMs: tokens.expiresAtMs
+      };
+      await storage.setItem(SESSION_KEY, JSON.stringify(stored));
+      return toSession(stored);
+    });
+  }
+  async function signIn() {
+    const verifier = generateCodeVerifier();
+    const challenge = await codeChallengeFor(verifier);
+    const state = generateState();
+    const attemptId = `oauth:${state}`;
+    const attempt = { verifier, createdAtMs: now(), attemptId };
+    await lock(async () => {
+      await pending.setItem(pendingKey(state), JSON.stringify(attempt));
+      await pending.setItem(ACTIVE_KEY, attemptId);
+    });
+    try {
+      const url = buildAuthorizeUrl({
+        authUrl: base,
+        clientId: config.clientId,
+        redirectUri: config.redirectUri,
+        state,
+        challenge,
+        scope
+      });
+      const callbackUrl = await ports.openAuthorization(url, { state, redirectUri: config.redirectUri });
+      const { code, returnedState } = parseCallbackUrl(callbackUrl);
+      if (!constantTimeEqual(returnedState, state)) {
+        throw new MatrxOAuthError("state_mismatch", "OAuth state mismatch \u2014 possible CSRF, ignoring response");
+      }
+      const raw = await pending.getItem(pendingKey(state));
+      let recovered = null;
+      try {
+        recovered = raw ? JSON.parse(raw) : null;
+      } catch {
+        recovered = null;
+      }
+      if (!recovered || recovered.verifier !== verifier) {
+        throw new MatrxOAuthError("verifier_lost", "Could not recover code_verifier for this sign-in attempt");
+      }
+      if (now() - recovered.createdAtMs > attemptTtlMs) {
+        throw new MatrxOAuthError("attempt_expired", "This sign-in took too long and expired. Start again.");
+      }
+      const tokens = await tokenRequest({
+        grant_type: "authorization_code",
+        client_id: config.clientId,
+        code,
+        code_verifier: recovered.verifier,
+        redirect_uri: config.redirectUri
+      });
+      const session = await commit(tokens, attemptId);
+      emit({ type: "signed_in", session });
+      return session;
+    } finally {
+      try {
+        await pending.removeItem(pendingKey(state));
+      } catch {
+      }
+    }
+  }
+  let inflight = null;
+  async function refreshNow(rejected) {
+    const stored = await loadStored();
+    if (!stored) return null;
+    if (stored.clientId !== config.clientId) {
+      await lock(clearLocal);
+      emit({ type: "signed_out", reason: "client_changed" });
+      return null;
+    }
+    if (stored.expiresAtMs - now() > refreshLeadMs && (!rejected || stored.accessToken !== rejected)) {
+      return stored.accessToken;
+    }
+    let refreshToken;
+    try {
+      refreshToken = await unseal(stored.refreshToken);
+    } catch {
+      await lock(async () => {
+        const again = await loadStored();
+        if (again && again.refreshToken === stored.refreshToken) await clearLocal();
+      });
+      emit({ type: "signed_out", reason: "unreadable" });
+      return null;
+    }
+    let tokens;
+    try {
+      tokens = await tokenRequest({ grant_type: "refresh_token", client_id: config.clientId, refresh_token: refreshToken });
+    } catch (error) {
+      if (error instanceof GrantRefusedError) {
+        const outcome = await lock(async () => {
+          const current = await loadStored();
+          if (!current) return { kind: "gone" };
+          if (current.refreshToken !== stored.refreshToken) return { kind: "rotated", token: current.accessToken };
+          await clearLocal();
+          return { kind: "cleared" };
+        });
+        if (outcome.kind === "rotated") return outcome.token;
+        if (outcome.kind === "cleared") emit({ type: "signed_out", reason: "session_ended" });
+        return null;
+      }
+      if (stored.expiresAtMs > now() && stored.accessToken !== rejected) return stored.accessToken;
+      throw error;
+    }
+    const claims = personIdFromAccessToken(tokens.accessToken);
+    if (claims.personId !== stored.personId) {
+      await lock(clearLocal);
+      emit({ type: "signed_out", reason: "person_changed" });
+      return null;
+    }
+    const sealedNew = tokens.refreshToken ? await seal(tokens.refreshToken) : stored.refreshToken;
+    const result = await lock(async () => {
+      const current = await loadStored();
+      if (!current) return null;
+      if (current.refreshToken !== stored.refreshToken) return { token: current.accessToken, session: null };
+      const next = {
+        ...current,
+        email: claims.email ?? current.email,
+        accessToken: tokens.accessToken,
+        refreshToken: sealedNew,
+        expiresAtMs: tokens.expiresAtMs
+      };
+      await storage.setItem(SESSION_KEY, JSON.stringify(next));
+      return { token: next.accessToken, session: toSession(next) };
+    });
+    if (!result) return null;
+    if (result.session) emit({ type: "refreshed", session: result.session });
+    return result.token;
+  }
+  function singleFlight(rejected) {
+    inflight ??= refreshNow(rejected).finally(() => {
+      inflight = null;
+    });
+    return inflight;
+  }
+  return {
+    signIn,
+    async getAccessToken() {
+      const stored = await loadStored();
+      if (!stored) return null;
+      if (stored.clientId === config.clientId && stored.expiresAtMs - now() > refreshLeadMs) return stored.accessToken;
+      return singleFlight();
+    },
+    refresh: (rejectedAccessToken) => singleFlight(rejectedAccessToken),
+    async getSession() {
+      const stored = await loadStored();
+      return stored ? toSession(stored) : null;
+    },
+    async getPersonId() {
+      const stored = await loadStored();
+      return stored ? personIdFromAccessToken(stored.accessToken).personId : null;
+    },
+    async signOut() {
+      const access = await lock(clearLocal);
+      emit({ type: "signed_out", reason: "user" });
+      if (!access) return { revoked: null };
+      try {
+        const res = await doFetch(`${base}/auth/v1/logout?scope=local`, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${access}`,
+            ...config.publishableKey ? { apikey: config.publishableKey } : {}
+          }
+        });
+        return { revoked: res.ok || res.status === 401 || res.status === 403 || res.status === 404 };
+      } catch {
+        return { revoked: false };
+      }
+    },
+    onChange(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}

package/dist/matrx-oauth.d.cts

@@ -0,0 +1,181 @@
+import { S as SessionStorage } from './storage-Dqnye4KF.cjs';
+
+/**
+ * "Sign in with AI Matrx" — OAuth 2.1 authorization-code + PKCE (S256) against the AI Matrx auth
+ * server (Supabase's OAuth 2.1 server on https://db.matrxserver.com), written ONCE, host-neutral.
+ *
+ * Two apps used to carry hand-made copies; both now import this:
+ *   - Chrome extension (matrx-extend/src/lib/auth/flow.ts): storage = chrome.storage, redirect
+ *     captured by chrome.identity.launchWebAuthFlow, cross-context `navigator.locks`, AES-GCM
+ *     sealed refresh token.
+ *   - Desktop (matrx-desktop/app/main/auth): storage = the OS-sealed vault, authorize URL opened
+ *     in the system browser, redirect captured by a loopback server on localhost.
+ *
+ * NOTHING host-specific is imported here (no chrome.*, electron, node:*, window). The host injects
+ * ports: `storage` (the package's SessionStorage shape), `openAuthorization`, and optionally
+ * `fetch`, `now`, `lock`, `seal`, `pendingStorage`, `beforeCommit`. Runs on WebCrypto
+ * (browser, extension service worker, Node >= 20).
+ *
+ * Config each app passes in (values they use today; this module hard-codes none of the ids):
+ *   authUrl          both: https://db.matrxserver.com   (endpoints: /auth/v1/oauth/{authorize,token},
+ *                    /auth/v1/logout?scope=local)
+ *   clientId         extension: its own public PKCE client (env WXT_EXTENSION_OAUTH_CLIENT_ID);
+ *                    desktop: "Matrx 2" public client (see matrx-desktop/app/main/auth/config.ts)
+ *   redirectUri      extension: chrome.identity.getRedirectURL() = https://<id>.chromiumapp.org/
+ *                    (Safari: https://www.aimatrx.com/auth/extension-callback);
+ *                    desktop: http://localhost:22140/auth/callback (dev: 22240)
+ *   scope            both: "email profile". NEVER add "openid": the server then tries to mint an
+ *                    ID token and answers 500 "Error generating ID token".
+ *   publishableKey   desktop sends it as `apikey` on token + logout calls; extension on logout.
+ *                    Optional here; sent whenever given.
+ *   refreshLeadMs    extension 60_000, desktop 120_000 (default 60_000)
+ *
+ * Behaviour kept from the extension: verifier PERSISTED locally and only a random nonce travels as
+ * `state` (never the verifier in the URL); one verifier per attempt keyed by state; a newer
+ * attempt/sign-out supersedes an older one; state mismatch refused; the exact user-facing
+ * sentences; the cross-context refresh race guard (if the stored refresh token changed while our
+ * refresh was refused, adopt the winner instead of signing out); optional pre-commit validation.
+ * Kept from the desktop: constant-time state compare, 10 min attempt expiry, terminal-vs-transient
+ * error split (a refused grant ends the session; a network blip / 5xx / captive portal keeps it),
+ * HTML-on-200 is never a token, client-changed sessions dropped, refresh timeout, person id from JWT.
+ */
+
+type MatrxOAuthErrorCode = "config_missing" | "state_mismatch" | "callback_error" | "callback_incomplete" | "attempt_expired" | "verifier_lost" | "superseded" | "token_exchange_failed" | "invalid_token" | "grant_refused" | "transient" | "unsupported_environment";
+declare class MatrxOAuthError extends Error {
+    readonly code: MatrxOAuthErrorCode;
+    constructor(code: MatrxOAuthErrorCode, message: string);
+}
+/** The server refused the grant (revoked, reused, expired): the session is over. Never retried. */
+declare class GrantRefusedError extends MatrxOAuthError {
+    readonly serverCode: string;
+    constructor(serverCode: string, detail: string);
+}
+/** Network down, captive portal, 5xx, 429: try again later; the session is still good. */
+declare class TransientAuthError extends MatrxOAuthError {
+    constructor(detail: string);
+}
+/** RFC 7636 §4.1: 43 chars of base64url from 32 random bytes. */
+declare function generateCodeVerifier(): string;
+/** RFC 7636 §4.2 S256: BASE64URL(SHA256(ASCII(verifier))). */
+declare function codeChallengeFor(verifier: string): Promise<string>;
+/** The `state` value: 256 random bits, ties the callback to this attempt. */
+declare function generateState(): string;
+/** Constant-time string comparison. */
+declare function constantTimeEqual(a: string, b: string): boolean;
+interface AuthorizeUrlInput {
+    authUrl: string;
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    challenge: string;
+    scope: string;
+}
+declare function buildAuthorizeUrl(input: AuthorizeUrlInput): string;
+/** Read `code` and `state` from the redirect the browser landed on; throws on error / missing parts. */
+declare function parseCallbackUrl(callbackUrl: string): {
+    code: string;
+    returnedState: string;
+};
+interface AccessTokenClaims {
+    /** The person id (`sub`). */
+    personId: string;
+    email: string | null;
+    /** Expiry in ms since epoch, or null when the token carries no `exp`. */
+    expiresAtMs: number | null;
+}
+/**
+ * Read `sub`, `email`, `exp` from an access token. The signature is NOT verified here: the token
+ * came straight from the issuer over TLS. Verify-on-receipt belongs to servers.
+ */
+declare function personIdFromAccessToken(token: string): AccessTokenClaims;
+interface MatrxOAuthConfig {
+    /** Auth server origin, e.g. https://db.matrxserver.com */
+    authUrl: string;
+    /** This app's public PKCE client id. */
+    clientId: string;
+    redirectUri: string;
+    /** Default "email profile". Never include "openid". */
+    scope?: string;
+    /** Sent as `apikey` on token + logout calls when given. */
+    publishableKey?: string;
+    /** Refresh this long before expiry. Default 60_000. */
+    refreshLeadMs?: number;
+    /** A started sign-in expires after this. Default 600_000. */
+    attemptTtlMs?: number;
+    /** Token endpoint timeout. Default 15_000. */
+    requestTimeoutMs?: number;
+    /** Storage key namespace. Default "matrx-oauth". */
+    storageKeyPrefix?: string;
+}
+interface OpenAuthorizationContext {
+    state: string;
+    redirectUri: string;
+}
+interface MatrxOAuthPorts {
+    /** Where the session lives between runs (the package's SessionStorage shape). */
+    storage: SessionStorage;
+    /**
+     * Open the authorize URL and resolve with the full redirect URL the browser landed on.
+     * Reject if the person cancelled. Extension: chrome.identity.launchWebAuthFlow.
+     * Desktop: open the system browser and wait on the loopback server.
+     */
+    openAuthorization(authorizeUrl: string, context: OpenAuthorizationContext): Promise<string>;
+    fetch?: typeof fetch;
+    now?: () => number;
+    /** Short-lived attempt state (verifier). Default: `storage`. Extension: chrome.storage.session. */
+    pendingStorage?: SessionStorage;
+    /** Serialises storage mutations across contexts (extension: navigator.locks). Default: in-process. */
+    lock?: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** Seal/unseal the refresh token at rest (extension: AES-GCM). Default: stored as-is. */
+    seal?: {
+        encrypt(plain: string): Promise<string>;
+        decrypt(sealed: string): Promise<string>;
+    };
+    /**
+     * Runs on freshly exchanged tokens BEFORE they displace a working session; throw to refuse
+     * (extension: GET /auth/v1/user). Never call per request.
+     */
+    beforeCommit?: (accessToken: string) => Promise<void>;
+}
+interface MatrxOAuthSession {
+    personId: string;
+    email: string | null;
+    accessToken: string;
+    expiresAtMs: number;
+}
+type MatrxOAuthEvent = {
+    type: "signed_in";
+    session: MatrxOAuthSession;
+} | {
+    type: "refreshed";
+    session: MatrxOAuthSession;
+} | {
+    type: "signed_out";
+    reason: "user" | "session_ended" | "client_changed" | "person_changed" | "unreadable";
+};
+interface TokenSet {
+    accessToken: string;
+    /** Null only if the server chose not to rotate it. */
+    refreshToken: string | null;
+    expiresAtMs: number;
+}
+interface MatrxOAuthClient {
+    /** Run the whole interactive sign-in. Resolves once tokens are stored. */
+    signIn(): Promise<MatrxOAuthSession>;
+    /** A usable access token, refreshing on expiry (single-flight). Null = signed out. Throws on transient failure with no valid token left. */
+    getAccessToken(): Promise<string | null>;
+    /** Force a refresh (alarms, 401 retry). Pass the token the server rejected to refuse adopting it. */
+    refresh(rejectedAccessToken?: string): Promise<string | null>;
+    /** The stored session without refreshing or touching the network. */
+    getSession(): Promise<MatrxOAuthSession | null>;
+    /** The person id from the stored access token, no network. Null = signed out. */
+    getPersonId(): Promise<string | null>;
+    /** Clear local state, then best-effort revoke on the server. Returns whether the server agreed (null = nothing to revoke). */
+    signOut(): Promise<{
+        revoked: boolean | null;
+    }>;
+    onChange(listener: (event: MatrxOAuthEvent) => void): () => void;
+}
+declare function createMatrxOAuth(config: MatrxOAuthConfig, ports: MatrxOAuthPorts): MatrxOAuthClient;
+
+export { type AccessTokenClaims, type AuthorizeUrlInput, GrantRefusedError, type MatrxOAuthClient, type MatrxOAuthConfig, MatrxOAuthError, type MatrxOAuthErrorCode, type MatrxOAuthEvent, type MatrxOAuthPorts, type MatrxOAuthSession, type OpenAuthorizationContext, type TokenSet, TransientAuthError, buildAuthorizeUrl, codeChallengeFor, constantTimeEqual, createMatrxOAuth, generateCodeVerifier, generateState, parseCallbackUrl, personIdFromAccessToken };