@ai-matrx/auth 0.1.4 → 0.2.0

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 };

package/dist/matrx-oauth.d.ts

@@ -0,0 +1,181 @@
+import { S as SessionStorage } from './storage-Dqnye4KF.js';
+
+/**
+ * "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 };