@ai-matrx/auth 0.2.0 → 0.2.2

package/dist/index.d.cts

@@ -1,11 +1,127 @@
-export { A as AuthClient, S as SessionSourceLike, a as SignInError, U as UserCredentialsPort, g as getPerson, b as getSession, i as invalidatePerson, o as onSessionChange, r as refreshSession, s as sessionCredentials, c as signInWithOAuth, d as signInWithPassword, e as signOut, u as updatePerson, f as userCredentials } from './session-DdQiStp6.cjs';
-import { S as SessionStorage } from './storage-Dqnye4KF.cjs';
-export { C as ChromeStorageAreaLike, a as StorageUnavailableError, b as browserStorage, e as extensionStorage, k as keyValueStorage, m as memoryStorage } from './storage-Dqnye4KF.cjs';
-import { SupabaseClient } from '@supabase/supabase-js';
+import { H as HeldOrganizationStore, A as AuthClient } from './active-organization-Dy4UtiyR.cjs';
+export { S as SessionSourceLike, a as SignInError, U as UserCredentialsPort, g as getPerson, b as getSession, i as invalidatePerson, o as onSessionChange, r as refreshSession, s as sessionCredentials, c as signInWithOAuth, d as signInWithPassword, e as signOut, u as updatePerson, f as userCredentials } from './active-organization-Dy4UtiyR.cjs';
+import { S as SessionStorage, M as MatrxOAuthClient } from './matrx-oauth-_Ji8X5Wm.cjs';
+export { C as ChromeStorageAreaLike, a as StorageUnavailableError, b as browserStorage, e as extensionStorage, k as keyValueStorage, m as memoryStorage } from './matrx-oauth-_Ji8X5Wm.cjs';
+import { SupabaseClient, User } from '@supabase/supabase-js';
 export { AuthChangeEvent, Session, User, UserAttributes } from '@supabase/supabase-js';
 export { CredentialsPort, MatrxCredential, MatrxCredentialKind } from './credentials.cjs';
 export { A as ApiClaimsUser, C as ClaimsCacheOptions, a as ClaimsCapableClient, b as ClaimsResult, P as PROJECT_SIGNING_KEYS, c as PROJECT_SIGNING_KEY_AUTHORITIES, d as accountFlagsFor, e as confirmUnverifiableSession, f as createClaimsCache, g as getClaimsUser, i as isAuthTransportFailure, h as isSignedOutError, j as isUnverifiableTokenError, k as isUnverifiableTokenRefusal, p as pinnedSigningKeysFor, u as userFromClaims } from './claims-DXdbe3cW.cjs';
 
+/** How long a request may wait for the first auth report before going anyway. */
+declare const SESSION_ATTACH_BUDGET_MS = 3000;
+/** How long a refused request may wait for a session before it gives up. */
+declare const SESSION_RECOVERY_BUDGET_MS = 5000;
+/** After one wait expires, how long every other request skips the wait. */
+declare const WAIT_COOLDOWN_MS = 30000;
+/** What the client knows about its own session right now. */
+type BarrierSessionState = "unknown" | "attached" | "expected" | "absent";
+/** The marker written into an error capture's `session_state`. */
+type BarrierSessionMarker = "attached" | "pre_attach" | "signed_out" | "unknown";
+/** What the wrapper knows about the call it is about to make. */
+interface BarrierCallContext {
+    schema?: string;
+    relation?: string;
+}
+/** A barrier announcement the host records (the host adds its own source/operation fields). */
+interface BarrierReport {
+    code: "SESSION_BARRIER_RECOVERED" | "SESSION_BARRIER_UNRECOVERED";
+    message: string;
+    schema?: string | undefined;
+    relation?: string | undefined;
+    status: 401;
+    sessionState: BarrierSessionMarker;
+    /** True only for a failure (a repaired read is news for an inspector, not a repair queue). */
+    durable: boolean;
+}
+interface RefusalLike {
+    error?: {
+        code?: string;
+        message?: string;
+    } | null;
+    status?: number;
+}
+/** The slice of `client.auth` the barrier binds to. */
+interface BarrierAuth {
+    getSession(): Promise<{
+        data: {
+            session: {
+                access_token?: string;
+            } | null;
+        };
+        error: unknown;
+    }>;
+    onAuthStateChange(callback: (event: string, session: unknown) => void): unknown;
+    getClaims?: (jwt?: string, options?: {
+        jwks?: {
+            keys: any[];
+        };
+    }) => Promise<{
+        data: unknown;
+        error: {
+            name?: string;
+            code?: string;
+            status?: number;
+            message?: string;
+        } | null;
+    }>;
+    signOut?: (options: {
+        scope: "local";
+    }) => Promise<unknown>;
+}
+interface SessionBarrierOptions {
+    /** Record an announcement (Error Inspector / durable repair queue). */
+    report(event: BarrierReport): void;
+    /** Doors that serve a guest honestly: a 42501 there is a real refusal, never retried. */
+    isAnonymousByDesign?(schema: string | undefined, relation: string | undefined): boolean;
+    /** The one door that must never wait (the error sink). */
+    bypassesSessionWait?(relation: string | undefined): boolean;
+    /** End a session the database can never verify on this device and send the person to sign in. */
+    endUnverifiable?(auth: {
+        signOut: NonNullable<BarrierAuth["signOut"]>;
+    }, where: {
+        door: string;
+        via: "postgrest" | "claims";
+    }): Promise<void>;
+    /** Stamp every capture in the host with `sessionStateMarker()` (a probe, so the store needs no import). */
+    setSessionStateProbe?(probe: (() => BarrierSessionMarker) | null): void;
+    /** URL the client talks to — decides which pinned signing keys confirm "unverifiable". */
+    supabaseUrl?: string | null | undefined;
+    attachBudgetMs?: number;
+    recoveryBudgetMs?: number;
+    waitCooldownMs?: number;
+    /** Where the cookie string comes from; `null` = cannot tell. Default: `document.cookie`, `null` when unreadable. */
+    readCookie?(): string | null;
+    /** Browser-only gate. Default: `typeof window !== "undefined"`. */
+    isBrowser?(): boolean;
+    now?(): number;
+    warn?(message: string): void;
+}
+interface SessionBarrier {
+    install(client: unknown): void;
+    reset(): void;
+    /** Drive the signal without a client (tests, or a host that hears auth elsewhere). */
+    announceSession(present: boolean | null): void;
+    authCookiePresent(): boolean | null;
+    sessionStateNow(): BarrierSessionState;
+    sessionStateMarker(): BarrierSessionMarker;
+    hasAttachedSession(): boolean;
+    whenSessionAttached(listener: () => void): () => void;
+    canSendImmediately(ctx: BarrierCallContext): boolean;
+    awaitSessionBeforeSend(ctx: BarrierCallContext): Promise<void>;
+    isSessionRefusal(result: RefusalLike): boolean;
+    shouldRecoverSession(ctx: BarrierCallContext): boolean;
+    endSessionIfUnverifiable(ctx: BarrierCallContext, result: RefusalLike): Promise<boolean>;
+    recoverSessionForRetry(ctx: BarrierCallContext): Promise<boolean>;
+    reportSessionRetryOutcome(ctx: BarrierCallContext, retried: RefusalLike): void;
+}
+/**
+ * Is this result the database saying "your request carried no identity"? The discriminator is HTTP 401:
+ * a 42501 at 403 is a REAL grant gap for `authenticated` and must never be retried.
+ */
+declare function isSessionRefusal(result: RefusalLike): boolean;
+/** One barrier per browser client (module scope in the host is the tab). */
+declare function createSessionBarrier(options: SessionBarrierOptions): SessionBarrier;
+
 /**
  * `createAuthClient` — the one Supabase client factory OUTSIDE Next.js (Next apps use
  * `@ai-matrx/auth/next`, whose cookie clients carry the domain-wide auth cookie).
@@ -36,4 +152,44 @@ declare class SecretKeyRefusedError extends Error {
 }
 declare function createAuthClient<Database = any>(options: CreateAuthClientOptions): SupabaseClient<Database>;
 
-export { type CreateAuthClientOptions, SecretKeyRefusedError, SessionStorage, createAuthClient };
+/**
+ * An app that signs in with "Sign in with AI Matrx" (`createMatrxOAuth`) keeps its OWN session; it
+ * has no GoTrue session behind its Supabase client (the extension's client reads its bearer through
+ * supabase-js's `accessToken` hook, and `client.auth` on such a client throws). The session doors
+ * (`getSession`, `getPerson`, `onSessionChange`), `useSession` and the active organization all read
+ * `client.auth`. These two helpers give them one, built from the OAuth client:
+ *
+ *   const oauth = createMatrxOAuth(config, ports);
+ *   const client = withOAuthSession(supabaseWithAccessTokenHook, oauth);   // db + a real `auth`
+ *   const { session } = useSession(client);
+ *   const active = createActiveOrganization({ client, held: heldOrganizationInStorage(extensionStorage(chrome.storage.session)) });
+ *
+ * The `auth` is the slice those doors use: `getSession`, `getUser`, `refreshSession`, `signOut`,
+ * `onAuthStateChange`. Password / OAuth-provider sign-in and profile edits are not part of it and
+ * refuse by name.
+ */
+
+interface OAuthAuthClientOptions {
+    /**
+     * The person for an access token. Default: built locally from the token's claims (id, email) with
+     * no network. Pass the host's verified read (the extension's JWKS claims check) to return
+     * more fields; return null for "this token is not a person" (signed out).
+     */
+    readonly readUser?: ((accessToken: string) => Promise<User | null>) | undefined;
+}
+/** `{ auth }` for the session doors, backed by an OAuth client's own session. */
+declare function oauthAuthClient(oauth: MatrxOAuthClient, options?: OAuthAuthClientOptions): AuthClient;
+/**
+ * The data client (any supabase-js client: `rpc`, `schema`, `from`) with the OAuth session as its
+ * `auth`. Nothing is read from the client's own `auth` (which throws on an `accessToken`-hook
+ * client).
+ */
+declare function withOAuthSession<C extends object>(db: C, oauth: MatrxOAuthClient, options?: OAuthAuthClientOptions): C & AuthClient;
+/**
+ * A held-organization store over any async {@link SessionStorage} (identity-keyed): the extension's
+ * `chrome.storage.session` / `.local` through `extensionStorage(area)`. A stored choice for a
+ * different person reads as none.
+ */
+declare function heldOrganizationInStorage(storage: SessionStorage, key?: string): HeldOrganizationStore;
+
+export { AuthClient, type BarrierAuth, type BarrierCallContext, type BarrierReport, type BarrierSessionMarker, type BarrierSessionState, type CreateAuthClientOptions, type OAuthAuthClientOptions, type RefusalLike, SESSION_ATTACH_BUDGET_MS, SESSION_RECOVERY_BUDGET_MS, SecretKeyRefusedError, type SessionBarrier, type SessionBarrierOptions, SessionStorage, WAIT_COOLDOWN_MS, createAuthClient, createSessionBarrier, heldOrganizationInStorage, isSessionRefusal, oauthAuthClient, withOAuthSession };

package/dist/index.d.ts

@@ -1,11 +1,127 @@
-export { A as AuthClient, S as SessionSourceLike, a as SignInError, U as UserCredentialsPort, g as getPerson, b as getSession, i as invalidatePerson, o as onSessionChange, r as refreshSession, s as sessionCredentials, c as signInWithOAuth, d as signInWithPassword, e as signOut, u as updatePerson, f as userCredentials } from './session-DdQiStp6.js';
-import { S as SessionStorage } from './storage-Dqnye4KF.js';
-export { C as ChromeStorageAreaLike, a as StorageUnavailableError, b as browserStorage, e as extensionStorage, k as keyValueStorage, m as memoryStorage } from './storage-Dqnye4KF.js';
-import { SupabaseClient } from '@supabase/supabase-js';
+import { H as HeldOrganizationStore, A as AuthClient } from './active-organization-Dy4UtiyR.js';
+export { S as SessionSourceLike, a as SignInError, U as UserCredentialsPort, g as getPerson, b as getSession, i as invalidatePerson, o as onSessionChange, r as refreshSession, s as sessionCredentials, c as signInWithOAuth, d as signInWithPassword, e as signOut, u as updatePerson, f as userCredentials } from './active-organization-Dy4UtiyR.js';
+import { S as SessionStorage, M as MatrxOAuthClient } from './matrx-oauth-_Ji8X5Wm.js';
+export { C as ChromeStorageAreaLike, a as StorageUnavailableError, b as browserStorage, e as extensionStorage, k as keyValueStorage, m as memoryStorage } from './matrx-oauth-_Ji8X5Wm.js';
+import { SupabaseClient, User } from '@supabase/supabase-js';
 export { AuthChangeEvent, Session, User, UserAttributes } from '@supabase/supabase-js';
 export { CredentialsPort, MatrxCredential, MatrxCredentialKind } from './credentials.js';
 export { A as ApiClaimsUser, C as ClaimsCacheOptions, a as ClaimsCapableClient, b as ClaimsResult, P as PROJECT_SIGNING_KEYS, c as PROJECT_SIGNING_KEY_AUTHORITIES, d as accountFlagsFor, e as confirmUnverifiableSession, f as createClaimsCache, g as getClaimsUser, i as isAuthTransportFailure, h as isSignedOutError, j as isUnverifiableTokenError, k as isUnverifiableTokenRefusal, p as pinnedSigningKeysFor, u as userFromClaims } from './claims-DXdbe3cW.js';
 
+/** How long a request may wait for the first auth report before going anyway. */
+declare const SESSION_ATTACH_BUDGET_MS = 3000;
+/** How long a refused request may wait for a session before it gives up. */
+declare const SESSION_RECOVERY_BUDGET_MS = 5000;
+/** After one wait expires, how long every other request skips the wait. */
+declare const WAIT_COOLDOWN_MS = 30000;
+/** What the client knows about its own session right now. */
+type BarrierSessionState = "unknown" | "attached" | "expected" | "absent";
+/** The marker written into an error capture's `session_state`. */
+type BarrierSessionMarker = "attached" | "pre_attach" | "signed_out" | "unknown";
+/** What the wrapper knows about the call it is about to make. */
+interface BarrierCallContext {
+    schema?: string;
+    relation?: string;
+}
+/** A barrier announcement the host records (the host adds its own source/operation fields). */
+interface BarrierReport {
+    code: "SESSION_BARRIER_RECOVERED" | "SESSION_BARRIER_UNRECOVERED";
+    message: string;
+    schema?: string | undefined;
+    relation?: string | undefined;
+    status: 401;
+    sessionState: BarrierSessionMarker;
+    /** True only for a failure (a repaired read is news for an inspector, not a repair queue). */
+    durable: boolean;
+}
+interface RefusalLike {
+    error?: {
+        code?: string;
+        message?: string;
+    } | null;
+    status?: number;
+}
+/** The slice of `client.auth` the barrier binds to. */
+interface BarrierAuth {
+    getSession(): Promise<{
+        data: {
+            session: {
+                access_token?: string;
+            } | null;
+        };
+        error: unknown;
+    }>;
+    onAuthStateChange(callback: (event: string, session: unknown) => void): unknown;
+    getClaims?: (jwt?: string, options?: {
+        jwks?: {
+            keys: any[];
+        };
+    }) => Promise<{
+        data: unknown;
+        error: {
+            name?: string;
+            code?: string;
+            status?: number;
+            message?: string;
+        } | null;
+    }>;
+    signOut?: (options: {
+        scope: "local";
+    }) => Promise<unknown>;
+}
+interface SessionBarrierOptions {
+    /** Record an announcement (Error Inspector / durable repair queue). */
+    report(event: BarrierReport): void;
+    /** Doors that serve a guest honestly: a 42501 there is a real refusal, never retried. */
+    isAnonymousByDesign?(schema: string | undefined, relation: string | undefined): boolean;
+    /** The one door that must never wait (the error sink). */
+    bypassesSessionWait?(relation: string | undefined): boolean;
+    /** End a session the database can never verify on this device and send the person to sign in. */
+    endUnverifiable?(auth: {
+        signOut: NonNullable<BarrierAuth["signOut"]>;
+    }, where: {
+        door: string;
+        via: "postgrest" | "claims";
+    }): Promise<void>;
+    /** Stamp every capture in the host with `sessionStateMarker()` (a probe, so the store needs no import). */
+    setSessionStateProbe?(probe: (() => BarrierSessionMarker) | null): void;
+    /** URL the client talks to — decides which pinned signing keys confirm "unverifiable". */
+    supabaseUrl?: string | null | undefined;
+    attachBudgetMs?: number;
+    recoveryBudgetMs?: number;
+    waitCooldownMs?: number;
+    /** Where the cookie string comes from; `null` = cannot tell. Default: `document.cookie`, `null` when unreadable. */
+    readCookie?(): string | null;
+    /** Browser-only gate. Default: `typeof window !== "undefined"`. */
+    isBrowser?(): boolean;
+    now?(): number;
+    warn?(message: string): void;
+}
+interface SessionBarrier {
+    install(client: unknown): void;
+    reset(): void;
+    /** Drive the signal without a client (tests, or a host that hears auth elsewhere). */
+    announceSession(present: boolean | null): void;
+    authCookiePresent(): boolean | null;
+    sessionStateNow(): BarrierSessionState;
+    sessionStateMarker(): BarrierSessionMarker;
+    hasAttachedSession(): boolean;
+    whenSessionAttached(listener: () => void): () => void;
+    canSendImmediately(ctx: BarrierCallContext): boolean;
+    awaitSessionBeforeSend(ctx: BarrierCallContext): Promise<void>;
+    isSessionRefusal(result: RefusalLike): boolean;
+    shouldRecoverSession(ctx: BarrierCallContext): boolean;
+    endSessionIfUnverifiable(ctx: BarrierCallContext, result: RefusalLike): Promise<boolean>;
+    recoverSessionForRetry(ctx: BarrierCallContext): Promise<boolean>;
+    reportSessionRetryOutcome(ctx: BarrierCallContext, retried: RefusalLike): void;
+}
+/**
+ * Is this result the database saying "your request carried no identity"? The discriminator is HTTP 401:
+ * a 42501 at 403 is a REAL grant gap for `authenticated` and must never be retried.
+ */
+declare function isSessionRefusal(result: RefusalLike): boolean;
+/** One barrier per browser client (module scope in the host is the tab). */
+declare function createSessionBarrier(options: SessionBarrierOptions): SessionBarrier;
+
 /**
  * `createAuthClient` — the one Supabase client factory OUTSIDE Next.js (Next apps use
  * `@ai-matrx/auth/next`, whose cookie clients carry the domain-wide auth cookie).
@@ -36,4 +152,44 @@ declare class SecretKeyRefusedError extends Error {
 }
 declare function createAuthClient<Database = any>(options: CreateAuthClientOptions): SupabaseClient<Database>;
 
-export { type CreateAuthClientOptions, SecretKeyRefusedError, SessionStorage, createAuthClient };
+/**
+ * An app that signs in with "Sign in with AI Matrx" (`createMatrxOAuth`) keeps its OWN session; it
+ * has no GoTrue session behind its Supabase client (the extension's client reads its bearer through
+ * supabase-js's `accessToken` hook, and `client.auth` on such a client throws). The session doors
+ * (`getSession`, `getPerson`, `onSessionChange`), `useSession` and the active organization all read
+ * `client.auth`. These two helpers give them one, built from the OAuth client:
+ *
+ *   const oauth = createMatrxOAuth(config, ports);
+ *   const client = withOAuthSession(supabaseWithAccessTokenHook, oauth);   // db + a real `auth`
+ *   const { session } = useSession(client);
+ *   const active = createActiveOrganization({ client, held: heldOrganizationInStorage(extensionStorage(chrome.storage.session)) });
+ *
+ * The `auth` is the slice those doors use: `getSession`, `getUser`, `refreshSession`, `signOut`,
+ * `onAuthStateChange`. Password / OAuth-provider sign-in and profile edits are not part of it and
+ * refuse by name.
+ */
+
+interface OAuthAuthClientOptions {
+    /**
+     * The person for an access token. Default: built locally from the token's claims (id, email) with
+     * no network. Pass the host's verified read (the extension's JWKS claims check) to return
+     * more fields; return null for "this token is not a person" (signed out).
+     */
+    readonly readUser?: ((accessToken: string) => Promise<User | null>) | undefined;
+}
+/** `{ auth }` for the session doors, backed by an OAuth client's own session. */
+declare function oauthAuthClient(oauth: MatrxOAuthClient, options?: OAuthAuthClientOptions): AuthClient;
+/**
+ * The data client (any supabase-js client: `rpc`, `schema`, `from`) with the OAuth session as its
+ * `auth`. Nothing is read from the client's own `auth` (which throws on an `accessToken`-hook
+ * client).
+ */
+declare function withOAuthSession<C extends object>(db: C, oauth: MatrxOAuthClient, options?: OAuthAuthClientOptions): C & AuthClient;
+/**
+ * A held-organization store over any async {@link SessionStorage} (identity-keyed): the extension's
+ * `chrome.storage.session` / `.local` through `extensionStorage(area)`. A stored choice for a
+ * different person reads as none.
+ */
+declare function heldOrganizationInStorage(storage: SessionStorage, key?: string): HeldOrganizationStore;
+
+export { AuthClient, type BarrierAuth, type BarrierCallContext, type BarrierReport, type BarrierSessionMarker, type BarrierSessionState, type CreateAuthClientOptions, type OAuthAuthClientOptions, type RefusalLike, SESSION_ATTACH_BUDGET_MS, SESSION_RECOVERY_BUDGET_MS, SecretKeyRefusedError, type SessionBarrier, type SessionBarrierOptions, SessionStorage, WAIT_COOLDOWN_MS, createAuthClient, createSessionBarrier, heldOrganizationInStorage, isSessionRefusal, oauthAuthClient, withOAuthSession };