@ai-matrx/auth 0.2.0 → 0.2.2

package/dist/matrx-oauth-_Ji8X5Wm.d.cts

@@ -0,0 +1,264 @@
+/**
+ * Session storage per platform — where a Supabase session lives between runs.
+ *
+ * supabase-js takes any `{ getItem, setItem, removeItem }` (sync or async). These are the ones
+ * every Matrx client needs, written once:
+ *
+ *   browser   — `browserStorage("local")` (supabase-js's own default; `"session"` = this tab only)
+ *   Next.js   — the cookie-backed clients in `@ai-matrx/auth/next` (the domain-wide auth cookie)
+ *   extension — `extensionStorage()` over `chrome.storage.local` (shared by popup, side panel and
+ *               service worker; `localStorage` does not exist in a service worker)
+ *   desktop   — `keyValueStorage({ get, set, remove })` over the host's store (Tauri store, keychain)
+ *   Node      — `fileStorage(path)` in `@ai-matrx/auth/node`, or `memoryStorage()` for a one-shot run
+ *
+ * None of these is ever silently swapped for another: a storage the platform does not have throws
+ * a named error at creation, never a quiet in-memory fallback that signs the person out on reload.
+ */
+/** The storage contract supabase-js reads (sync or async methods). */
+interface SessionStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+declare class StorageUnavailableError extends Error {
+    readonly storage: string;
+    constructor(storage: string, reason: string);
+}
+/** In memory only: the session ends with the process (one-shot scripts, tests, server renders). */
+declare function memoryStorage(): SessionStorage & {
+    readonly size: () => number;
+};
+/** The browser's `localStorage` (shared by every tab of the origin) or `sessionStorage` (this tab). */
+declare function browserStorage(kind?: "local" | "session"): SessionStorage;
+/** The structural slice of `chrome.storage.<area>` read here (MV3 promise API). */
+interface ChromeStorageAreaLike {
+    get(keys: string): Promise<Record<string, unknown>>;
+    set(items: Record<string, unknown>): Promise<void>;
+    remove(keys: string): Promise<void>;
+}
+/**
+ * A browser extension's `chrome.storage` area (default `local`): one session for the popup, side
+ * panel, content scripts' relay and the service worker. Pass `area` to inject one (tests, Firefox).
+ */
+declare function extensionStorage(area?: ChromeStorageAreaLike): SessionStorage;
+/** Any async key-value store the host owns (a desktop app's Tauri store or keychain). */
+declare function keyValueStorage(store: {
+    get(key: string): Promise<string | null | undefined>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}): SessionStorage;
+
+/**
+ * "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;
+    /**
+     * Where the authorization server sends the browser back. A function is read at the moment a
+     * sign-in starts or completes (never at creation and never cached), for hosts that only know it
+     * once their identity API is up (the extension's `chrome.identity.getRedirectURL()`). A blank
+     * answer, or `about:blank`, refuses the sign-in with `config_missing`; read-only calls
+     * (`getSession`, `getAccessToken`, `refresh`, `signOut`) never need it.
+     */
+    redirectUri: string | (() => string);
+    /**
+     * Renew through a different endpoint than `/auth/v1/oauth/token` (desktop's test lane: a session
+     * opened by Supabase's own auth renews on `/auth/v1/token?grant_type=refresh_token` with a JSON
+     * body `{ refresh_token }`). Only refresh requests are re-aimed; the code exchange never is.
+     */
+    refreshEndpoint?: {
+        url: string;
+        body?: "form" | "json";
+    };
+    /** 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>;
+    /**
+     * Finish a sign-in whose authorization code was already captured but whose `signIn()` call is gone
+     * (Safari: the background page caught the redirect, then the popup/worker was torn down). Pass the
+     * redirect URL, or the `code` + `state` from it. The PKCE verifier is recovered from the attempt
+     * still held in `pendingStorage` under that `state`; a `state` with no live attempt, or one past
+     * its lifetime, is refused with `verifier_lost` / `attempt_expired` ("start again"), never guessed.
+     */
+    completeSignIn(captured: {
+        callbackUrl: string;
+    } | {
+        code: string;
+        state: string;
+    }): Promise<MatrxOAuthSession>;
+    /**
+     * Store a token set obtained without the browser (a host that already holds a Supabase-minted
+     * session, e.g. desktop's test-only copy sign-in) as this client's session. Runs `beforeCommit`
+     * and emits `signed_in`; needs a refresh token.
+     */
+    adoptTokens(tokens: TokenSet): 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 as A, type ChromeStorageAreaLike as C, GrantRefusedError as G, type MatrxOAuthClient as M, type OpenAuthorizationContext as O, type SessionStorage as S, type TokenSet as T, StorageUnavailableError as a, browserStorage as b, type AuthorizeUrlInput as c, type MatrxOAuthConfig as d, extensionStorage as e, MatrxOAuthError as f, type MatrxOAuthErrorCode as g, type MatrxOAuthEvent as h, type MatrxOAuthPorts as i, type MatrxOAuthSession as j, keyValueStorage as k, TransientAuthError as l, memoryStorage as m, buildAuthorizeUrl as n, codeChallengeFor as o, constantTimeEqual as p, createMatrxOAuth as q, generateCodeVerifier as r, generateState as s, parseCallbackUrl as t, personIdFromAccessToken as u };

package/dist/matrx-oauth-_Ji8X5Wm.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Session storage per platform — where a Supabase session lives between runs.
+ *
+ * supabase-js takes any `{ getItem, setItem, removeItem }` (sync or async). These are the ones
+ * every Matrx client needs, written once:
+ *
+ *   browser   — `browserStorage("local")` (supabase-js's own default; `"session"` = this tab only)
+ *   Next.js   — the cookie-backed clients in `@ai-matrx/auth/next` (the domain-wide auth cookie)
+ *   extension — `extensionStorage()` over `chrome.storage.local` (shared by popup, side panel and
+ *               service worker; `localStorage` does not exist in a service worker)
+ *   desktop   — `keyValueStorage({ get, set, remove })` over the host's store (Tauri store, keychain)
+ *   Node      — `fileStorage(path)` in `@ai-matrx/auth/node`, or `memoryStorage()` for a one-shot run
+ *
+ * None of these is ever silently swapped for another: a storage the platform does not have throws
+ * a named error at creation, never a quiet in-memory fallback that signs the person out on reload.
+ */
+/** The storage contract supabase-js reads (sync or async methods). */
+interface SessionStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+declare class StorageUnavailableError extends Error {
+    readonly storage: string;
+    constructor(storage: string, reason: string);
+}
+/** In memory only: the session ends with the process (one-shot scripts, tests, server renders). */
+declare function memoryStorage(): SessionStorage & {
+    readonly size: () => number;
+};
+/** The browser's `localStorage` (shared by every tab of the origin) or `sessionStorage` (this tab). */
+declare function browserStorage(kind?: "local" | "session"): SessionStorage;
+/** The structural slice of `chrome.storage.<area>` read here (MV3 promise API). */
+interface ChromeStorageAreaLike {
+    get(keys: string): Promise<Record<string, unknown>>;
+    set(items: Record<string, unknown>): Promise<void>;
+    remove(keys: string): Promise<void>;
+}
+/**
+ * A browser extension's `chrome.storage` area (default `local`): one session for the popup, side
+ * panel, content scripts' relay and the service worker. Pass `area` to inject one (tests, Firefox).
+ */
+declare function extensionStorage(area?: ChromeStorageAreaLike): SessionStorage;
+/** Any async key-value store the host owns (a desktop app's Tauri store or keychain). */
+declare function keyValueStorage(store: {
+    get(key: string): Promise<string | null | undefined>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}): SessionStorage;
+
+/**
+ * "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;
+    /**
+     * Where the authorization server sends the browser back. A function is read at the moment a
+     * sign-in starts or completes (never at creation and never cached), for hosts that only know it
+     * once their identity API is up (the extension's `chrome.identity.getRedirectURL()`). A blank
+     * answer, or `about:blank`, refuses the sign-in with `config_missing`; read-only calls
+     * (`getSession`, `getAccessToken`, `refresh`, `signOut`) never need it.
+     */
+    redirectUri: string | (() => string);
+    /**
+     * Renew through a different endpoint than `/auth/v1/oauth/token` (desktop's test lane: a session
+     * opened by Supabase's own auth renews on `/auth/v1/token?grant_type=refresh_token` with a JSON
+     * body `{ refresh_token }`). Only refresh requests are re-aimed; the code exchange never is.
+     */
+    refreshEndpoint?: {
+        url: string;
+        body?: "form" | "json";
+    };
+    /** 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>;
+    /**
+     * Finish a sign-in whose authorization code was already captured but whose `signIn()` call is gone
+     * (Safari: the background page caught the redirect, then the popup/worker was torn down). Pass the
+     * redirect URL, or the `code` + `state` from it. The PKCE verifier is recovered from the attempt
+     * still held in `pendingStorage` under that `state`; a `state` with no live attempt, or one past
+     * its lifetime, is refused with `verifier_lost` / `attempt_expired` ("start again"), never guessed.
+     */
+    completeSignIn(captured: {
+        callbackUrl: string;
+    } | {
+        code: string;
+        state: string;
+    }): Promise<MatrxOAuthSession>;
+    /**
+     * Store a token set obtained without the browser (a host that already holds a Supabase-minted
+     * session, e.g. desktop's test-only copy sign-in) as this client's session. Runs `beforeCommit`
+     * and emits `signed_in`; needs a refresh token.
+     */
+    adoptTokens(tokens: TokenSet): 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 as A, type ChromeStorageAreaLike as C, GrantRefusedError as G, type MatrxOAuthClient as M, type OpenAuthorizationContext as O, type SessionStorage as S, type TokenSet as T, StorageUnavailableError as a, browserStorage as b, type AuthorizeUrlInput as c, type MatrxOAuthConfig as d, extensionStorage as e, MatrxOAuthError as f, type MatrxOAuthErrorCode as g, type MatrxOAuthEvent as h, type MatrxOAuthPorts as i, type MatrxOAuthSession as j, keyValueStorage as k, TransientAuthError as l, memoryStorage as m, buildAuthorizeUrl as n, codeChallengeFor as o, constantTimeEqual as p, createMatrxOAuth as q, generateCodeVerifier as r, generateState as s, parseCallbackUrl as t, personIdFromAccessToken as u };