@ai-matrx/auth 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog — @ai-matrx/auth
 
+## 0.2.0
+
+**The apps' own identity, server-door and sign-in copies move in (consolidation U1).**
+- `.` — `getClaimsUser` (local JWKS claims read, never `getUser()`), `pinnedSigningKeysFor` + the live
+  project's public signing key, `isAuthTransportFailure`, `isSignedOutError`, `userFromClaims`,
+  `accountFlagsFor`, the unverifiable-session detectors (`isUnverifiableTokenRefusal`,
+  `isUnverifiableTokenError`, `confirmUnverifiableSession`) and `createClaimsCache` (the browser's
+  de-duplicated claims read). From the website's `utils/supabase/{claimsUser,projectSigningKeys,
+  clientClaimsCache,unverifiableSession}.ts`; media carried an identical copy.
+- `/next` and `/node` — `createServerAuth` (THE server identity door: claims, one retry on a fresh
+  client, React `cache` injected), `verifyRequest` (Bearer-or-cookie for API routes),
+  `createServiceClient` (the one server-only secret-key client).
+- `/organizations` — the organization-required refusal: `isOrganizationRequiredError`,
+  `OrganizationRequiredServerError`, `organizationRequired`, `readCallerMemberships`,
+  `organizationRequiredEnvelope` / `organizationRequiredResponse` (aidream's envelope field for field),
+  `extractOrganizationHoldMemberships`.
+- `/matrx-oauth` (new section) — "Sign in with AI Matrx" OAuth 2.1 + PKCE for non-web hosts:
+  `createMatrxOAuth(config, ports)` with single-flight refresh, host-injected storage, browser opener,
+  lock and refresh-token sealing; PKCE primitives. From the extension's `lib/auth/flow.ts` and the
+  desktop's `app/main/auth/{pkce,oauth-client}.ts`.
+Tests: `claims.test.ts` (17), `matrx-oauth.test.ts` (18).
+
+## 0.1.4
+
+**Fix: `getPerson` no longer calls the auth server on every access check (Wave 0).** The verified
+person is now kept per client until the session changes: concurrent callers share one read, and
+sign-in, sign-out, `updatePerson`, an organization switch (`switchTo`), an active-organization
+reload, and the `SIGNED_IN` / `SIGNED_OUT` / `USER_UPDATED` events drop it. A token refresh keeps
+it; signed-out answers and failures are never cached. New export `invalidatePerson(client)` for a
+change made outside this package. Tests: `session.test.ts` "getPerson asks the auth server once per
+session", "asks again after sign-in, sign-out ...", "a signed-out answer or a failure is never cached".
+
 ## 0.1.3
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/README.md

@@ -31,3 +31,14 @@ Session storage: browser `browserStorage()`, extension `extensionStorage()`, des
 
 The active organization is never a list filter: reads show everything the person can see; the
 active organization is only where new things are saved and which organization a server call runs in.
+
+## Sections added in 0.2.0 — one entry point each
+
+| Need | Import |
+|---|---|
+| Who is calling (local claims; browser de-dup) | `getClaimsUser`, `createClaimsCache` from `@ai-matrx/auth` |
+| Server identity in a Next app | `createServerAuth({ createClient, supabaseUrl, cache })` from `@ai-matrx/auth/next` |
+| API route caller (Bearer or cookie) | `verifyRequest(request, { url, publishableKey, cookieClient })` from `@ai-matrx/auth/node` (or `/next`) |
+| Server-only secret-key client | `createServiceClient({ url, secretKey })` from `@ai-matrx/auth/node` (or `/next`) |
+| "Needs an organization" refusal | `isOrganizationRequiredError`, `organizationRequired`, `organizationRequiredResponse` from `@ai-matrx/auth/organizations` |
+| Sign in with AI Matrx (extension, desktop, CLI) | `createMatrxOAuth(config, { storage, openAuthorization })` from `@ai-matrx/auth/matrx-oauth` |

package/dist/claims-DXdbe3cW.d.cts

@@ -0,0 +1,138 @@
+import { JwtPayload, UserAppMetadata, UserMetadata, JWK, AuthError } from '@supabase/supabase-js';
+
+/**
+ * THE identity read every server and client path shares (moved from the website's
+ * `utils/supabase/{claimsUser,projectSigningKeys,unverifiableSession}.ts`, 2026-10-12).
+ *
+ * Verifies the access token LOCALLY (WebCrypto against the project's JWKS; the live project signs
+ * ES256) and never asks the auth server who the caller is. `getClaims()`, NEVER `getUser()`:
+ * `getUser()` is one auth-server round trip per call, with auth-js retrying a stalled refresh for
+ * up to 30s — on 2026-09-20 and 09-21 that put 504s in front of real people.
+ *
+ * Framework-free: no `next/*`, no `window` at import time. Server doors (`createServerAuth` in
+ * `/next`, `verifyRequest` in `/node`) and the browser's de-duplicated read (`createClaimsCache`)
+ * are thin wrappers over `getClaimsUser`.
+ */
+
+/**
+ * The verified caller, built from the access token's claims. `id` is `sub`; `app_metadata` /
+ * `user_metadata` default to `{}` so a reader never null-checks what `getUser()` always handed it.
+ */
+interface ApiClaimsUser extends JwtPayload {
+    /** The `sub` claim — the user id. */
+    id: string;
+    app_metadata: UserAppMetadata;
+    user_metadata: UserMetadata;
+}
+/** Any Supabase client — the only thing this door needs is `auth.getClaims`. */
+type ClaimsCapableClient = {
+    auth: {
+        getClaims(jwt?: string, options?: {
+            jwks?: {
+                keys: JWK[];
+            };
+        }): Promise<{
+            data: {
+                claims?: JwtPayload;
+            } | null;
+            error: AuthError | null;
+        }>;
+    };
+};
+interface ClaimsResult {
+    data: {
+        user: ApiClaimsUser | null;
+    };
+    error: AuthError | null;
+}
+/**
+ * `client.auth.getUser()` without the auth-server round trip, in the SAME envelope, with one
+ * deliberate distinction:
+ *  - CONFIRMED SIGNED OUT (no session, no token) → `{ user: null, error: null }` — a settled fact.
+ *  - COULD NOT VERIFY (authority/JWKS unreachable, malformed or badly-signed token, a verified
+ *    token without `sub`) → `error` kept, so a retry branch fires and a screen never paints
+ *    "signed out" over an outage.
+ * Pass `jwt` when the token is in hand (a Bearer header). `options.jwks` are known public keys
+ * tried BEFORE any JWKS fetch (`pinnedSigningKeysFor`) — can only remove a network call.
+ */
+declare function getClaimsUser(client: ClaimsCapableClient, jwt?: string, options?: {
+    jwks: {
+        keys: JWK[];
+    };
+}): Promise<ClaimsResult>;
+/**
+ * Could we not REACH a verdict (transport failure, spent budget), as opposed to a token we reached
+ * a verdict on? Too narrow reads an outage as a logout; too wide holds a person with a forged or
+ * rotated-key token on "reload in a moment" forever while the proxy sends them to /login. This is
+ * the same line the `/next` middleware pass draws.
+ */
+declare function isAuthTransportFailure(error: unknown): boolean;
+/** Is this `getClaims()` error the settled fact "nobody is signed in"? */
+declare function isSignedOutError(error: AuthError | {
+    name?: string;
+    code?: string;
+}): boolean;
+/** The verified claims as a `{ id, ... }` user, or `null` when there are none. */
+declare function userFromClaims(claims: JwtPayload | undefined): ApiClaimsUser | null;
+/**
+ * GUEST vs ACCOUNT. A signed-in session is a person with an ACCOUNT or a GUEST (anonymous session,
+ * `is_anonymous: true`). Account UI (menu, billing, sign-out, org picker) keys on `hasAccount`.
+ */
+declare function accountFlagsFor(claims: {
+    is_anonymous?: boolean;
+} | null | undefined): {
+    isGuest: boolean;
+    hasAccount: boolean;
+};
+/** The auth authorities the keys below were issued by (live, by every name it answers to). */
+declare const PROJECT_SIGNING_KEY_AUTHORITIES: readonly string[];
+declare const PROJECT_SIGNING_KEYS: JWK[];
+/** The pinned keys for the authority at `supabaseUrl`; none for any other authority. */
+declare function pinnedSigningKeysFor(supabaseUrl: string | null | undefined): JWK[];
+interface AuthErrorLike {
+    name?: string | undefined;
+    code?: string | undefined;
+    status?: number | undefined;
+    message?: string | undefined;
+}
+/** Is this PostgREST result the database saying "I cannot verify this token"? (Not expiry.) */
+declare function isUnverifiableTokenRefusal(result: {
+    error?: {
+        code?: string;
+        message?: string;
+    } | null;
+    status?: number;
+}): boolean;
+/** Is this `getClaims()` error the authority's SETTLED verdict that the token is not its own? */
+declare function isUnverifiableTokenError(error: AuthErrorLike | null | undefined): boolean;
+/** Ask the authority once: is the stored session's token one it can verify? */
+declare function confirmUnverifiableSession(auth: {
+    getClaims(jwt?: string, options?: {
+        jwks?: {
+            keys: JWK[];
+        };
+    }): Promise<{
+        data: unknown;
+        error: AuthErrorLike | null;
+    }>;
+}, supabaseUrl: string | null | undefined): Promise<boolean>;
+interface ClaimsCacheOptions {
+    /** The URL the client talks to — decides which pinned keys apply. */
+    supabaseUrl: string | null | undefined;
+    /** How long one verdict is shared (default 2s; any identity-changing event clears it at once). */
+    ttlMs?: number;
+    /** Called when the authority settled that the browser's token is not one of its own. */
+    onUnverifiable?: () => void;
+}
+/**
+ * The current browser session's verified claims, de-duplicated: callers within `ttlMs` share one
+ * verification (and so one JWKS fetch on a cold cache). Browser-only: a server request must never
+ * share another request's verdict — servers call `getClaimsUser` / `createServerAuth`.
+ */
+declare function createClaimsCache(client: ClaimsCapableClient & {
+    auth: {
+        onAuthStateChange(cb: (event: string) => void): unknown;
+    };
+}, options: ClaimsCacheOptions): () => Promise<ClaimsResult>;
+
+export { type ApiClaimsUser as A, type ClaimsCacheOptions as C, PROJECT_SIGNING_KEYS as P, type ClaimsCapableClient as a, type ClaimsResult as b, PROJECT_SIGNING_KEY_AUTHORITIES as c, accountFlagsFor as d, confirmUnverifiableSession as e, createClaimsCache as f, getClaimsUser as g, isSignedOutError as h, isAuthTransportFailure as i, isUnverifiableTokenError as j, isUnverifiableTokenRefusal as k, pinnedSigningKeysFor as p, userFromClaims as u };

package/dist/claims-DXdbe3cW.d.ts

@@ -0,0 +1,138 @@
+import { JwtPayload, UserAppMetadata, UserMetadata, JWK, AuthError } from '@supabase/supabase-js';
+
+/**
+ * THE identity read every server and client path shares (moved from the website's
+ * `utils/supabase/{claimsUser,projectSigningKeys,unverifiableSession}.ts`, 2026-10-12).
+ *
+ * Verifies the access token LOCALLY (WebCrypto against the project's JWKS; the live project signs
+ * ES256) and never asks the auth server who the caller is. `getClaims()`, NEVER `getUser()`:
+ * `getUser()` is one auth-server round trip per call, with auth-js retrying a stalled refresh for
+ * up to 30s — on 2026-09-20 and 09-21 that put 504s in front of real people.
+ *
+ * Framework-free: no `next/*`, no `window` at import time. Server doors (`createServerAuth` in
+ * `/next`, `verifyRequest` in `/node`) and the browser's de-duplicated read (`createClaimsCache`)
+ * are thin wrappers over `getClaimsUser`.
+ */
+
+/**
+ * The verified caller, built from the access token's claims. `id` is `sub`; `app_metadata` /
+ * `user_metadata` default to `{}` so a reader never null-checks what `getUser()` always handed it.
+ */
+interface ApiClaimsUser extends JwtPayload {
+    /** The `sub` claim — the user id. */
+    id: string;
+    app_metadata: UserAppMetadata;
+    user_metadata: UserMetadata;
+}
+/** Any Supabase client — the only thing this door needs is `auth.getClaims`. */
+type ClaimsCapableClient = {
+    auth: {
+        getClaims(jwt?: string, options?: {
+            jwks?: {
+                keys: JWK[];
+            };
+        }): Promise<{
+            data: {
+                claims?: JwtPayload;
+            } | null;
+            error: AuthError | null;
+        }>;
+    };
+};
+interface ClaimsResult {
+    data: {
+        user: ApiClaimsUser | null;
+    };
+    error: AuthError | null;
+}
+/**
+ * `client.auth.getUser()` without the auth-server round trip, in the SAME envelope, with one
+ * deliberate distinction:
+ *  - CONFIRMED SIGNED OUT (no session, no token) → `{ user: null, error: null }` — a settled fact.
+ *  - COULD NOT VERIFY (authority/JWKS unreachable, malformed or badly-signed token, a verified
+ *    token without `sub`) → `error` kept, so a retry branch fires and a screen never paints
+ *    "signed out" over an outage.
+ * Pass `jwt` when the token is in hand (a Bearer header). `options.jwks` are known public keys
+ * tried BEFORE any JWKS fetch (`pinnedSigningKeysFor`) — can only remove a network call.
+ */
+declare function getClaimsUser(client: ClaimsCapableClient, jwt?: string, options?: {
+    jwks: {
+        keys: JWK[];
+    };
+}): Promise<ClaimsResult>;
+/**
+ * Could we not REACH a verdict (transport failure, spent budget), as opposed to a token we reached
+ * a verdict on? Too narrow reads an outage as a logout; too wide holds a person with a forged or
+ * rotated-key token on "reload in a moment" forever while the proxy sends them to /login. This is
+ * the same line the `/next` middleware pass draws.
+ */
+declare function isAuthTransportFailure(error: unknown): boolean;
+/** Is this `getClaims()` error the settled fact "nobody is signed in"? */
+declare function isSignedOutError(error: AuthError | {
+    name?: string;
+    code?: string;
+}): boolean;
+/** The verified claims as a `{ id, ... }` user, or `null` when there are none. */
+declare function userFromClaims(claims: JwtPayload | undefined): ApiClaimsUser | null;
+/**
+ * GUEST vs ACCOUNT. A signed-in session is a person with an ACCOUNT or a GUEST (anonymous session,
+ * `is_anonymous: true`). Account UI (menu, billing, sign-out, org picker) keys on `hasAccount`.
+ */
+declare function accountFlagsFor(claims: {
+    is_anonymous?: boolean;
+} | null | undefined): {
+    isGuest: boolean;
+    hasAccount: boolean;
+};
+/** The auth authorities the keys below were issued by (live, by every name it answers to). */
+declare const PROJECT_SIGNING_KEY_AUTHORITIES: readonly string[];
+declare const PROJECT_SIGNING_KEYS: JWK[];
+/** The pinned keys for the authority at `supabaseUrl`; none for any other authority. */
+declare function pinnedSigningKeysFor(supabaseUrl: string | null | undefined): JWK[];
+interface AuthErrorLike {
+    name?: string | undefined;
+    code?: string | undefined;
+    status?: number | undefined;
+    message?: string | undefined;
+}
+/** Is this PostgREST result the database saying "I cannot verify this token"? (Not expiry.) */
+declare function isUnverifiableTokenRefusal(result: {
+    error?: {
+        code?: string;
+        message?: string;
+    } | null;
+    status?: number;
+}): boolean;
+/** Is this `getClaims()` error the authority's SETTLED verdict that the token is not its own? */
+declare function isUnverifiableTokenError(error: AuthErrorLike | null | undefined): boolean;
+/** Ask the authority once: is the stored session's token one it can verify? */
+declare function confirmUnverifiableSession(auth: {
+    getClaims(jwt?: string, options?: {
+        jwks?: {
+            keys: JWK[];
+        };
+    }): Promise<{
+        data: unknown;
+        error: AuthErrorLike | null;
+    }>;
+}, supabaseUrl: string | null | undefined): Promise<boolean>;
+interface ClaimsCacheOptions {
+    /** The URL the client talks to — decides which pinned keys apply. */
+    supabaseUrl: string | null | undefined;
+    /** How long one verdict is shared (default 2s; any identity-changing event clears it at once). */
+    ttlMs?: number;
+    /** Called when the authority settled that the browser's token is not one of its own. */
+    onUnverifiable?: () => void;
+}
+/**
+ * The current browser session's verified claims, de-duplicated: callers within `ttlMs` share one
+ * verification (and so one JWKS fetch on a cold cache). Browser-only: a server request must never
+ * share another request's verdict — servers call `getClaimsUser` / `createServerAuth`.
+ */
+declare function createClaimsCache(client: ClaimsCapableClient & {
+    auth: {
+        onAuthStateChange(cb: (event: string) => void): unknown;
+    };
+}, options: ClaimsCacheOptions): () => Promise<ClaimsResult>;
+
+export { type ApiClaimsUser as A, type ClaimsCacheOptions as C, PROJECT_SIGNING_KEYS as P, type ClaimsCapableClient as a, type ClaimsResult as b, PROJECT_SIGNING_KEY_AUTHORITIES as c, accountFlagsFor as d, confirmUnverifiableSession as e, createClaimsCache as f, getClaimsUser as g, isSignedOutError as h, isAuthTransportFailure as i, isUnverifiableTokenError as j, isUnverifiableTokenRefusal as k, pinnedSigningKeysFor as p, userFromClaims as u };

package/dist/index.cjs

@@ -20,24 +20,37 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  PROJECT_SIGNING_KEYS: () => PROJECT_SIGNING_KEYS,
+  PROJECT_SIGNING_KEY_AUTHORITIES: () => PROJECT_SIGNING_KEY_AUTHORITIES,
   SecretKeyRefusedError: () => SecretKeyRefusedError,
   SignInError: () => SignInError,
   StorageUnavailableError: () => StorageUnavailableError,
+  accountFlagsFor: () => accountFlagsFor,
   browserStorage: () => browserStorage,
+  confirmUnverifiableSession: () => confirmUnverifiableSession,
   createAuthClient: () => createAuthClient,
+  createClaimsCache: () => createClaimsCache,
   extensionStorage: () => extensionStorage,
+  getClaimsUser: () => getClaimsUser,
   getPerson: () => getPerson,
   getSession: () => getSession,
+  invalidatePerson: () => invalidatePerson,
+  isAuthTransportFailure: () => isAuthTransportFailure,
+  isSignedOutError: () => isSignedOutError,
+  isUnverifiableTokenError: () => isUnverifiableTokenError,
+  isUnverifiableTokenRefusal: () => isUnverifiableTokenRefusal,
   keyValueStorage: () => keyValueStorage,
   memoryStorage: () => memoryStorage,
   onSessionChange: () => onSessionChange,
+  pinnedSigningKeysFor: () => pinnedSigningKeysFor,
   refreshSession: () => refreshSession,
   sessionCredentials: () => sessionCredentials,
   signInWithOAuth: () => signInWithOAuth,
   signInWithPassword: () => signInWithPassword,
   signOut: () => signOut,
   updatePerson: () => updatePerson,
-  userCredentials: () => userCredentials
+  userCredentials: () => userCredentials,
+  userFromClaims: () => userFromClaims
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -62,10 +75,43 @@ async function getSession(client) {
   const { data, error } = await client.auth.getSession();
   return check("getSession", data, error).session;
 }
+var personCache = /* @__PURE__ */ new WeakMap();
+function personEntry(client) {
+  let entry = personCache.get(client);
+  if (!entry) {
+    const fresh = { read: null, epoch: 0 };
+    entry = fresh;
+    personCache.set(client, fresh);
+    const subscribe = client.auth?.onAuthStateChange;
+    if (typeof subscribe === "function") {
+      subscribe.call(client.auth, async (event) => {
+        if (event === "SIGNED_IN" || event === "SIGNED_OUT" || event === "USER_UPDATED") invalidatePerson(client);
+      });
+    }
+  }
+  return entry;
+}
+function invalidatePerson(client) {
+  const entry = personCache.get(client);
+  if (!entry) return;
+  entry.epoch += 1;
+  entry.read = null;
+}
 async function getPerson(client) {
-  const { data, error } = await client.auth.getUser();
-  if (error && (error.name === "AuthSessionMissingError" || error.status === 401)) return null;
-  return check("getPerson", data, error).user;
+  const entry = personEntry(client);
+  if (entry.read) return entry.read;
+  const epoch = entry.epoch;
+  const read = (async () => {
+    const { data, error } = await client.auth.getUser();
+    if (error && (error.name === "AuthSessionMissingError" || error.status === 401)) return null;
+    return check("getPerson", data, error).user;
+  })();
+  entry.read = read;
+  const settle = (keep) => {
+    if (entry.epoch === epoch && entry.read === read && !keep) entry.read = null;
+  };
+  read.then((user) => settle(user !== null), () => settle(false));
+  return read;
 }
 function onSessionChange(client, cb) {
   const { data } = client.auth.onAuthStateChange(cb);
@@ -73,6 +119,7 @@ function onSessionChange(client, cb) {
 }
 async function signInWithPassword(client, credentials) {
   const { data, error } = await client.auth.signInWithPassword(credentials);
+  invalidatePerson(client);
   const ok = check("signInWithPassword", data, error);
   return { session: ok.session, person: ok.user };
 }
@@ -84,10 +131,12 @@ async function signInWithOAuth(client, options) {
 }
 async function signOut(client, scope = "global") {
   const { error } = await client.auth.signOut({ scope });
+  invalidatePerson(client);
   check("signOut", null, error);
 }
 async function updatePerson(client, attributes) {
   const { data, error } = await client.auth.updateUser(attributes);
+  invalidatePerson(client);
   return check("updatePerson", data, error).user;
 }
 function sessionCredentials(client) {
@@ -187,3 +236,125 @@ function createAuthClient(options) {
   if (options.detectSessionInUrl !== void 0) auth["detectSessionInUrl"] = options.detectSessionInUrl;
   return (0, import_supabase_js.createClient)(options.url, options.key, { auth });
 }
+
+// src/claims.ts
+var import_supabase_js2 = require("@supabase/supabase-js");
+async function getClaimsUser(client, jwt, options) {
+  const { data, error } = options ? await client.auth.getClaims(jwt, options) : await client.auth.getClaims(jwt);
+  if (error) {
+    if (isSignedOutError(error)) return { data: { user: null }, error: null };
+    return { data: { user: null }, error };
+  }
+  if (!data?.claims) return { data: { user: null }, error: null };
+  const user = userFromClaims(data.claims);
+  if (!user) {
+    return {
+      data: { user: null },
+      error: new import_supabase_js2.AuthError("Verified token carries no `sub` claim", 401, "bad_jwt")
+    };
+  }
+  return { data: { user }, error: null };
+}
+var BUDGET_EXHAUSTED_STATUS = 408;
+var BUDGET_EXHAUSTED_CODE = "auth_budget_exhausted";
+function isAuthTransportFailure(error) {
+  if (!error || typeof error !== "object") return false;
+  const name = String(error.name ?? "");
+  if (name === "AuthRetryableFetchError" || name === "TimeoutError" || name === "AbortError") return true;
+  const status = error.status;
+  if (status === 0 || status === 504 || status === 503) return true;
+  return status === BUDGET_EXHAUSTED_STATUS || error.code === BUDGET_EXHAUSTED_CODE;
+}
+function isSignedOutError(error) {
+  return error instanceof import_supabase_js2.AuthSessionMissingError || error.name === "AuthSessionMissingError" || error.code === "session_not_found";
+}
+function userFromClaims(claims) {
+  if (!claims || typeof claims.sub !== "string") return null;
+  return {
+    ...claims,
+    id: claims.sub,
+    app_metadata: claims.app_metadata ?? {},
+    user_metadata: claims.user_metadata ?? {}
+  };
+}
+function accountFlagsFor(claims) {
+  if (!claims) return { isGuest: false, hasAccount: false };
+  const isGuest = claims.is_anonymous === true;
+  return { isGuest, hasAccount: !isGuest };
+}
+var PROJECT_SIGNING_KEY_AUTHORITIES = [
+  "db.matrxserver.com",
+  "brsgrqvjdzwihsvnfqkf.supabase.co"
+];
+var PROJECT_SIGNING_KEYS = [
+  {
+    alg: "ES256",
+    crv: "P-256",
+    ext: true,
+    key_ops: ["verify"],
+    kid: "a00aed0b-202c-483a-91ff-fc74719a3bb2",
+    kty: "EC",
+    use: "sig",
+    x: "guqOsgjJqGVU6g_K0iIXKrzixlkeXKOqkPUQCconp6U",
+    y: "39zQtkzlfQuPf_MtIhYmMdxNQpIR2Pkl11AToywaslY"
+  }
+];
+function pinnedSigningKeysFor(supabaseUrl) {
+  if (!supabaseUrl) return [];
+  let host;
+  try {
+    host = new URL(supabaseUrl).host.toLowerCase();
+  } catch {
+    return [];
+  }
+  return PROJECT_SIGNING_KEY_AUTHORITIES.includes(host) ? PROJECT_SIGNING_KEYS : [];
+}
+function isUnverifiableTokenRefusal(result) {
+  if (result.status !== 401) return false;
+  if (result.error?.code !== "PGRST301") return false;
+  return !/expired/i.test(result.error?.message ?? "");
+}
+function isUnverifiableTokenError(error) {
+  if (!error) return false;
+  const name = String(error.name ?? "");
+  if (name === "AuthRetryableFetchError" || name === "TimeoutError" || name === "AbortError") return false;
+  if (name === "AuthSessionMissingError" || error.code === "session_not_found") return false;
+  const status = error.status;
+  if (status === 0 || status === 408 || status === 503 || status === 504) return false;
+  if (/expired/i.test(error.message ?? "")) return false;
+  return error.code === "bad_jwt" || name === "AuthInvalidJwtError";
+}
+async function confirmUnverifiableSession(auth, supabaseUrl) {
+  try {
+    const { error } = await auth.getClaims(void 0, { jwks: { keys: pinnedSigningKeysFor(supabaseUrl) } });
+    return isUnverifiableTokenError(error);
+  } catch {
+    return false;
+  }
+}
+function createClaimsCache(client, options) {
+  const ttl = options.ttlMs ?? 2e3;
+  let cached = null;
+  let inflight = null;
+  let listening = false;
+  return () => {
+    if (!listening) {
+      listening = true;
+      client.auth.onAuthStateChange((event) => {
+        if (event === "SIGNED_OUT" || event === "SIGNED_IN" || event === "TOKEN_REFRESHED" || event === "USER_UPDATED") {
+          cached = null;
+        }
+      });
+    }
+    if (cached && cached.expiresAt > Date.now()) return Promise.resolve(cached.value);
+    if (inflight) return inflight;
+    inflight = getClaimsUser(client, void 0, { jwks: { keys: pinnedSigningKeysFor(options.supabaseUrl) } }).then((result) => {
+      if (isUnverifiableTokenError(result.error)) options.onUnverifiable?.();
+      cached = { value: result, expiresAt: Date.now() + ttl };
+      return result;
+    }).finally(() => {
+      inflight = null;
+    });
+    return inflight;
+  };
+}

package/dist/index.d.cts

@@ -1,57 +1,10 @@
-export { A as AuthClient, S as SessionSourceLike, a as SignInError, U as UserCredentialsPort, g as getPerson, b as getSession, 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-DhRO4euL.cjs';
+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';
 export { AuthChangeEvent, Session, User, UserAttributes } from '@supabase/supabase-js';
 export { CredentialsPort, MatrxCredential, MatrxCredentialKind } from './credentials.cjs';
-
-/**
- * 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;
+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';
 
 /**
  * `createAuthClient` — the one Supabase client factory OUTSIDE Next.js (Next apps use
@@ -83,4 +36,4 @@ declare class SecretKeyRefusedError extends Error {
 }
 declare function createAuthClient<Database = any>(options: CreateAuthClientOptions): SupabaseClient<Database>;
 
-export { type ChromeStorageAreaLike, type CreateAuthClientOptions, SecretKeyRefusedError, type SessionStorage, StorageUnavailableError, browserStorage, createAuthClient, extensionStorage, keyValueStorage, memoryStorage };
+export { type CreateAuthClientOptions, SecretKeyRefusedError, SessionStorage, createAuthClient };