@ai-matrx/auth 0.1.3 → 0.2.0

package/dist/organizations.d.cts

@@ -1,5 +1,5 @@
 import { SupabaseClient } from '@supabase/supabase-js';
-import { A as AuthClient } from './session-DhRO4euL.cjs';
+import { A as AuthClient } from './session-DdQiStp6.cjs';
 
 /**
  * @ai-matrx/auth/organizations (moved from @ai-matrx/data/organizations, 2026-10-09) — THE active-organization ladder and the account's organization
@@ -223,4 +223,110 @@ declare function storageHeldOrganization(storage: Pick<Storage, "getItem" | "set
 declare function memoryHeldOrganization(): HeldOrganizationStore;
 declare function createActiveOrganization(options: CreateActiveOrganizationOptions): ActiveOrganization;
 
-export { type AccountOrganizationChoices, type ActiveOrganization, type ActiveOrganizationSnapshot, type ActiveOrganizationStatus, type CreateActiveOrganizationOptions, type HeldOrganizationStore, type LadderInput, NoActiveOrganizationError, NotAMemberError, ORGANIZATION_ENTITY_TYPE, type OrganizationMembership, type OrganizationRefusal, type OrganizationRung, type OrganizationsDb, type ResolvedOrganization, classifyOrganizationRefusal, createActiveOrganization, memoryHeldOrganization, oldestMembership, orderOrganizations, organizationMatches, readAccountOrganizationChoices, readMemberships, readOrganizationFavourites, resolveActiveOrganization, resolveActiveOrganizationLazily, setOrganizationFavourite, storageHeldOrganization, toAccountOrganizationChoices, writeLastActiveOrganization, writeStartupOrganization };
+/**
+ * "This request needs an organization and names none" — the ONE recogniser, the server's throwable
+ * and the wire envelope (moved from the website's `lib/organizations/organizationRequired*.ts`,
+ * 2026-10-12). The envelope is byte-for-byte aidream's `matrx_connect.org_hold.organization_hold_detail`
+ * (`details.organizations`, status 400), so one recogniser covers both servers.
+ *
+ * Ruling (Arman, 2026-09-19): nothing but the picker may choose an organization. A request that
+ * needs one and has none is HELD: the person is shown their memberships, sets one, and it proceeds.
+ */
+/** The wire code both servers answer a missing organization with. */
+declare const ORGANIZATION_REQUIRED_CODE: "organization_required";
+/** Same value, the name the website's callers already read. */
+declare const ORGANIZATION_REQUIRED_WIRE_CODE: "organization_required";
+/** The transport kernel's client-side code for the same refusal (`OrganizationContextError`). */
+declare const ORGANIZATION_CONTEXT_REQUIRED_CODE: "organization_context_required";
+/** aidream's `MEMBERSHIPS_URL` literal — informational parity with the canonical envelope. */
+declare const MEMBERSHIPS_URL: "/auth/organizations";
+/** One organization the refusal offers the person. */
+interface OrganizationMembershipSummary {
+    id: string;
+    name: string;
+    abbreviation?: string;
+}
+type OrganizationRequiredWireMembership = OrganizationMembershipSummary;
+type OrganizationHoldSetOn = "request" | "mcp_connection" | "coding_session";
+/**
+ * True when `err` is the fail-closed "no organization selected" refusal — from a transport kernel
+ * (`code: "organization_context_required"`), a route handler or either server
+ * (`code: "organization_required"`). Matched by CODE, never by message, so it survives a
+ * serialization boundary and copy changes.
+ */
+declare function isOrganizationRequiredError(err: unknown): boolean;
+/** The parsed 400 body of an organization refusal (a plain `fetch` rather than a throwing transport). */
+declare function isOrganizationRequiredEnvelope(body: unknown): body is {
+    code: typeof ORGANIZATION_REQUIRED_CODE;
+    message?: string;
+    user_message?: string;
+    details?: {
+        organizations?: OrganizationMembershipSummary[] | null;
+        memberships_url?: string;
+        set_on?: string;
+        remedy?: string;
+    };
+};
+/**
+ * What organizations does this refusal offer? Reads `.details.organizations` (either server's
+ * envelope or a `BackendApiError`) or `.serverDetail.organizations` (a normalized `ApiCallError`).
+ * `null` = absent or unreadable ("could not ask" — fall back to the picker's list); `[]` is the
+ * honest "you belong to nothing".
+ */
+declare function extractOrganizationHoldMemberships(err: unknown): OrganizationMembershipSummary[] | null;
+/** The refusal, as a throwable. Nothing recovers from it by choosing — choosing is the person's act. */
+declare class OrganizationRequiredServerError extends Error {
+    name: "OrganizationRequiredServerError";
+    readonly code: "organization_required";
+    /** `null` only when the list could not be read ("could not ask"), distinct from `[]`. */
+    readonly memberships: OrganizationMembershipSummary[] | null;
+    constructor(message: string, memberships?: OrganizationMembershipSummary[] | null);
+}
+declare function isOrganizationRequiredServerError(error: unknown): error is OrganizationRequiredServerError;
+/** The minimal client shape `readCallerMemberships` needs (any Supabase client). */
+interface MembershipReadClient {
+    auth: {
+        getClaims(): Promise<{
+            data: {
+                claims?: {
+                    sub?: unknown;
+                };
+            } | null;
+            error: unknown;
+        }>;
+    };
+    schema(name: string): {
+        from(table: string): {
+            select(columns: string): unknown;
+        };
+    };
+}
+/**
+ * The caller's own active organization memberships — the only ones a refusal may offer (reads
+ * `iam.memberships`, never every organization row security returns: for a platform admin that is
+ * every tenant). `null` on any failure, so "could not ask" is never "you belong to nothing".
+ */
+declare function readCallerMemberships(client: MembershipReadClient): Promise<OrganizationMembershipSummary[] | null>;
+/** Refuse, with the choices attached. */
+declare function organizationRequired(client: MembershipReadClient, message: string): Promise<never>;
+interface OrganizationHoldDetails {
+    hold: typeof ORGANIZATION_REQUIRED_CODE;
+    can_choose: true;
+    set_on: OrganizationHoldSetOn;
+    remedy: string;
+    organizations: OrganizationMembershipSummary[] | null;
+    memberships_url: string;
+}
+interface OrganizationRequiredEnvelope {
+    error: typeof ORGANIZATION_REQUIRED_CODE;
+    code: typeof ORGANIZATION_REQUIRED_CODE;
+    message: string;
+    user_message: string;
+    details: OrganizationHoldDetails;
+}
+/** The wire body (status 400) — aidream's `organization_hold_detail`, field for field. */
+declare function organizationRequiredEnvelope(error: OrganizationRequiredServerError, setOn?: OrganizationHoldSetOn): OrganizationRequiredEnvelope;
+/** The standard `Response` (status 400) a route answers the refusal with — no framework needed. */
+declare function organizationRequiredResponse(error: OrganizationRequiredServerError): Response;
+
+export { type AccountOrganizationChoices, type ActiveOrganization, type ActiveOrganizationSnapshot, type ActiveOrganizationStatus, type CreateActiveOrganizationOptions, type HeldOrganizationStore, type LadderInput, MEMBERSHIPS_URL, type MembershipReadClient, NoActiveOrganizationError, NotAMemberError, ORGANIZATION_CONTEXT_REQUIRED_CODE, ORGANIZATION_ENTITY_TYPE, ORGANIZATION_REQUIRED_CODE, ORGANIZATION_REQUIRED_WIRE_CODE, type OrganizationHoldDetails, type OrganizationHoldSetOn, type OrganizationMembership, type OrganizationMembershipSummary, type OrganizationRefusal, type OrganizationRequiredEnvelope, OrganizationRequiredServerError, type OrganizationRequiredWireMembership, type OrganizationRung, type OrganizationsDb, type ResolvedOrganization, classifyOrganizationRefusal, createActiveOrganization, extractOrganizationHoldMemberships, isOrganizationRequiredEnvelope, isOrganizationRequiredError, isOrganizationRequiredServerError, memoryHeldOrganization, oldestMembership, orderOrganizations, organizationMatches, organizationRequired, organizationRequiredEnvelope, organizationRequiredResponse, readAccountOrganizationChoices, readCallerMemberships, readMemberships, readOrganizationFavourites, resolveActiveOrganization, resolveActiveOrganizationLazily, setOrganizationFavourite, storageHeldOrganization, toAccountOrganizationChoices, writeLastActiveOrganization, writeStartupOrganization };

package/dist/organizations.d.ts

@@ -1,5 +1,5 @@
 import { SupabaseClient } from '@supabase/supabase-js';
-import { A as AuthClient } from './session-DhRO4euL.js';
+import { A as AuthClient } from './session-DdQiStp6.js';
 
 /**
  * @ai-matrx/auth/organizations (moved from @ai-matrx/data/organizations, 2026-10-09) — THE active-organization ladder and the account's organization
@@ -223,4 +223,110 @@ declare function storageHeldOrganization(storage: Pick<Storage, "getItem" | "set
 declare function memoryHeldOrganization(): HeldOrganizationStore;
 declare function createActiveOrganization(options: CreateActiveOrganizationOptions): ActiveOrganization;
 
-export { type AccountOrganizationChoices, type ActiveOrganization, type ActiveOrganizationSnapshot, type ActiveOrganizationStatus, type CreateActiveOrganizationOptions, type HeldOrganizationStore, type LadderInput, NoActiveOrganizationError, NotAMemberError, ORGANIZATION_ENTITY_TYPE, type OrganizationMembership, type OrganizationRefusal, type OrganizationRung, type OrganizationsDb, type ResolvedOrganization, classifyOrganizationRefusal, createActiveOrganization, memoryHeldOrganization, oldestMembership, orderOrganizations, organizationMatches, readAccountOrganizationChoices, readMemberships, readOrganizationFavourites, resolveActiveOrganization, resolveActiveOrganizationLazily, setOrganizationFavourite, storageHeldOrganization, toAccountOrganizationChoices, writeLastActiveOrganization, writeStartupOrganization };
+/**
+ * "This request needs an organization and names none" — the ONE recogniser, the server's throwable
+ * and the wire envelope (moved from the website's `lib/organizations/organizationRequired*.ts`,
+ * 2026-10-12). The envelope is byte-for-byte aidream's `matrx_connect.org_hold.organization_hold_detail`
+ * (`details.organizations`, status 400), so one recogniser covers both servers.
+ *
+ * Ruling (Arman, 2026-09-19): nothing but the picker may choose an organization. A request that
+ * needs one and has none is HELD: the person is shown their memberships, sets one, and it proceeds.
+ */
+/** The wire code both servers answer a missing organization with. */
+declare const ORGANIZATION_REQUIRED_CODE: "organization_required";
+/** Same value, the name the website's callers already read. */
+declare const ORGANIZATION_REQUIRED_WIRE_CODE: "organization_required";
+/** The transport kernel's client-side code for the same refusal (`OrganizationContextError`). */
+declare const ORGANIZATION_CONTEXT_REQUIRED_CODE: "organization_context_required";
+/** aidream's `MEMBERSHIPS_URL` literal — informational parity with the canonical envelope. */
+declare const MEMBERSHIPS_URL: "/auth/organizations";
+/** One organization the refusal offers the person. */
+interface OrganizationMembershipSummary {
+    id: string;
+    name: string;
+    abbreviation?: string;
+}
+type OrganizationRequiredWireMembership = OrganizationMembershipSummary;
+type OrganizationHoldSetOn = "request" | "mcp_connection" | "coding_session";
+/**
+ * True when `err` is the fail-closed "no organization selected" refusal — from a transport kernel
+ * (`code: "organization_context_required"`), a route handler or either server
+ * (`code: "organization_required"`). Matched by CODE, never by message, so it survives a
+ * serialization boundary and copy changes.
+ */
+declare function isOrganizationRequiredError(err: unknown): boolean;
+/** The parsed 400 body of an organization refusal (a plain `fetch` rather than a throwing transport). */
+declare function isOrganizationRequiredEnvelope(body: unknown): body is {
+    code: typeof ORGANIZATION_REQUIRED_CODE;
+    message?: string;
+    user_message?: string;
+    details?: {
+        organizations?: OrganizationMembershipSummary[] | null;
+        memberships_url?: string;
+        set_on?: string;
+        remedy?: string;
+    };
+};
+/**
+ * What organizations does this refusal offer? Reads `.details.organizations` (either server's
+ * envelope or a `BackendApiError`) or `.serverDetail.organizations` (a normalized `ApiCallError`).
+ * `null` = absent or unreadable ("could not ask" — fall back to the picker's list); `[]` is the
+ * honest "you belong to nothing".
+ */
+declare function extractOrganizationHoldMemberships(err: unknown): OrganizationMembershipSummary[] | null;
+/** The refusal, as a throwable. Nothing recovers from it by choosing — choosing is the person's act. */
+declare class OrganizationRequiredServerError extends Error {
+    name: "OrganizationRequiredServerError";
+    readonly code: "organization_required";
+    /** `null` only when the list could not be read ("could not ask"), distinct from `[]`. */
+    readonly memberships: OrganizationMembershipSummary[] | null;
+    constructor(message: string, memberships?: OrganizationMembershipSummary[] | null);
+}
+declare function isOrganizationRequiredServerError(error: unknown): error is OrganizationRequiredServerError;
+/** The minimal client shape `readCallerMemberships` needs (any Supabase client). */
+interface MembershipReadClient {
+    auth: {
+        getClaims(): Promise<{
+            data: {
+                claims?: {
+                    sub?: unknown;
+                };
+            } | null;
+            error: unknown;
+        }>;
+    };
+    schema(name: string): {
+        from(table: string): {
+            select(columns: string): unknown;
+        };
+    };
+}
+/**
+ * The caller's own active organization memberships — the only ones a refusal may offer (reads
+ * `iam.memberships`, never every organization row security returns: for a platform admin that is
+ * every tenant). `null` on any failure, so "could not ask" is never "you belong to nothing".
+ */
+declare function readCallerMemberships(client: MembershipReadClient): Promise<OrganizationMembershipSummary[] | null>;
+/** Refuse, with the choices attached. */
+declare function organizationRequired(client: MembershipReadClient, message: string): Promise<never>;
+interface OrganizationHoldDetails {
+    hold: typeof ORGANIZATION_REQUIRED_CODE;
+    can_choose: true;
+    set_on: OrganizationHoldSetOn;
+    remedy: string;
+    organizations: OrganizationMembershipSummary[] | null;
+    memberships_url: string;
+}
+interface OrganizationRequiredEnvelope {
+    error: typeof ORGANIZATION_REQUIRED_CODE;
+    code: typeof ORGANIZATION_REQUIRED_CODE;
+    message: string;
+    user_message: string;
+    details: OrganizationHoldDetails;
+}
+/** The wire body (status 400) — aidream's `organization_hold_detail`, field for field. */
+declare function organizationRequiredEnvelope(error: OrganizationRequiredServerError, setOn?: OrganizationHoldSetOn): OrganizationRequiredEnvelope;
+/** The standard `Response` (status 400) a route answers the refusal with — no framework needed. */
+declare function organizationRequiredResponse(error: OrganizationRequiredServerError): Response;
+
+export { type AccountOrganizationChoices, type ActiveOrganization, type ActiveOrganizationSnapshot, type ActiveOrganizationStatus, type CreateActiveOrganizationOptions, type HeldOrganizationStore, type LadderInput, MEMBERSHIPS_URL, type MembershipReadClient, NoActiveOrganizationError, NotAMemberError, ORGANIZATION_CONTEXT_REQUIRED_CODE, ORGANIZATION_ENTITY_TYPE, ORGANIZATION_REQUIRED_CODE, ORGANIZATION_REQUIRED_WIRE_CODE, type OrganizationHoldDetails, type OrganizationHoldSetOn, type OrganizationMembership, type OrganizationMembershipSummary, type OrganizationRefusal, type OrganizationRequiredEnvelope, OrganizationRequiredServerError, type OrganizationRequiredWireMembership, type OrganizationRung, type OrganizationsDb, type ResolvedOrganization, classifyOrganizationRefusal, createActiveOrganization, extractOrganizationHoldMemberships, isOrganizationRequiredEnvelope, isOrganizationRequiredError, isOrganizationRequiredServerError, memoryHeldOrganization, oldestMembership, orderOrganizations, organizationMatches, organizationRequired, organizationRequiredEnvelope, organizationRequiredResponse, readAccountOrganizationChoices, readCallerMemberships, readMemberships, readOrganizationFavourites, resolveActiveOrganization, resolveActiveOrganizationLazily, setOrganizationFavourite, storageHeldOrganization, toAccountOrganizationChoices, writeLastActiveOrganization, writeStartupOrganization };

package/dist/organizations.js

@@ -138,10 +138,43 @@ function check(door, data, error) {
   if (error) throw new SignInError(door, error.message, error.status, error.code);
   return data;
 }
+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);
@@ -274,6 +307,7 @@ function createActiveOrganization(options) {
   const load = () => {
     if (disposed) return Promise.resolve(current);
     generation += 1;
+    invalidatePerson(client);
     inflight = run(generation).finally(() => {
       inflight = null;
     });
@@ -318,6 +352,7 @@ function createActiveOrganization(options) {
       const organization = snap.memberships.find((m) => m.id === organizationId);
       if (!organization || !snap.userId) throw new NotAMemberError(organizationId);
       generation += 1;
+      invalidatePerson(client);
       await held.write(snap.userId, organizationId);
       publish({ ...snap, status: "ready", organizationId, organization, rung: "switched", error: null });
       await writeLastActiveOrganization(client, organizationId);
@@ -343,17 +378,111 @@ function createActiveOrganization(options) {
   if (options.autoLoad ?? true) void load();
   return api;
 }
+
+// src/organization-required.ts
+var ORGANIZATION_REQUIRED_CODE = "organization_required";
+var ORGANIZATION_REQUIRED_WIRE_CODE = ORGANIZATION_REQUIRED_CODE;
+var ORGANIZATION_CONTEXT_REQUIRED_CODE = "organization_context_required";
+var MEMBERSHIPS_URL = "/auth/organizations";
+function isOrganizationRequiredError(err) {
+  if (!(err instanceof Error)) return false;
+  const code = err.code;
+  return code === ORGANIZATION_CONTEXT_REQUIRED_CODE || code === ORGANIZATION_REQUIRED_CODE;
+}
+function isOrganizationRequiredEnvelope(body) {
+  return typeof body === "object" && body !== null && body.code === ORGANIZATION_REQUIRED_CODE;
+}
+function extractOrganizationHoldMemberships(err) {
+  if (!err || typeof err !== "object") return null;
+  if (err.code !== ORGANIZATION_REQUIRED_CODE) return null;
+  const container = err;
+  return readOrganizationsField(container.details) ?? readOrganizationsField(container.serverDetail);
+}
+function readOrganizationsField(details) {
+  if (!details || typeof details !== "object") return null;
+  const organizations = details.organizations;
+  if (!Array.isArray(organizations)) return null;
+  return organizations.filter(
+    (org) => !!org && typeof org === "object" && typeof org.id === "string" && typeof org.name === "string"
+  );
+}
+var OrganizationRequiredServerError = class extends Error {
+  name = "OrganizationRequiredServerError";
+  code = ORGANIZATION_REQUIRED_CODE;
+  /** `null` only when the list could not be read ("could not ask"), distinct from `[]`. */
+  memberships;
+  constructor(message, memberships = null) {
+    super(message);
+    this.memberships = memberships;
+  }
+};
+function isOrganizationRequiredServerError(error) {
+  return error instanceof OrganizationRequiredServerError || error instanceof Error && error.name === "OrganizationRequiredServerError";
+}
+async function readCallerMemberships(client) {
+  try {
+    const { data: claims } = await client.auth.getClaims();
+    const userId = claims?.claims?.sub;
+    if (typeof userId !== "string" || !userId) return null;
+    const query = client.schema("iam").from("memberships").select("organization_id, organizations:organization_id(id,name,abbreviation)");
+    const { data, error } = await query.eq("user_id", userId).eq("container_type", "organization").eq("status", "active").is("deleted_at", null);
+    if (error || !Array.isArray(data)) return null;
+    const rows = data;
+    return rows.map((row) => ({
+      id: row.organizations?.id ?? row.organization_id,
+      name: row.organizations?.name ?? "Untitled organization",
+      ...row.organizations?.abbreviation ? { abbreviation: row.organizations.abbreviation } : {}
+    })).sort((a, b) => a.name.localeCompare(b.name));
+  } catch {
+    return null;
+  }
+}
+async function organizationRequired(client, message) {
+  throw new OrganizationRequiredServerError(message, await readCallerMemberships(client));
+}
+function organizationRequiredEnvelope(error, setOn = "request") {
+  return {
+    error: ORGANIZATION_REQUIRED_CODE,
+    code: ORGANIZATION_REQUIRED_CODE,
+    message: error.message,
+    user_message: "Choose the organization you're working in, then try again.",
+    details: {
+      hold: ORGANIZATION_REQUIRED_CODE,
+      can_choose: true,
+      set_on: setOn,
+      remedy: "Choose the organization you're working in and send it with the request (the X-Organization-Id header), then try again.",
+      organizations: error.memberships,
+      memberships_url: MEMBERSHIPS_URL
+    }
+  };
+}
+function organizationRequiredResponse(error) {
+  return Response.json(organizationRequiredEnvelope(error), { status: 400 });
+}
 export {
+  MEMBERSHIPS_URL,
   NoActiveOrganizationError,
   NotAMemberError,
+  ORGANIZATION_CONTEXT_REQUIRED_CODE,
   ORGANIZATION_ENTITY_TYPE,
+  ORGANIZATION_REQUIRED_CODE,
+  ORGANIZATION_REQUIRED_WIRE_CODE,
+  OrganizationRequiredServerError,
   classifyOrganizationRefusal,
   createActiveOrganization,
+  extractOrganizationHoldMemberships,
+  isOrganizationRequiredEnvelope,
+  isOrganizationRequiredError,
+  isOrganizationRequiredServerError,
   memoryHeldOrganization,
   oldestMembership,
   orderOrganizations,
   organizationMatches,
+  organizationRequired,
+  organizationRequiredEnvelope,
+  organizationRequiredResponse,
   readAccountOrganizationChoices,
+  readCallerMemberships,
   readMemberships,
   readOrganizationFavourites,
   resolveActiveOrganization,

package/dist/{session-DhRO4euL.d.cts → session-DdQiStp6.d.cts}

@@ -31,7 +31,17 @@ declare class SignInError extends Error {
 }
 /** The stored session (no network unless a refresh is due), or null when signed out. */
 declare function getSession(client: AuthClient): Promise<Session | null>;
-/** The signed-in person, verified by the auth server, or null when signed out. */
+/**
+ * Forget the cached person for this client, so the next {@link getPerson} asks the auth server.
+ * Sign-in, sign-out, a profile edit and an organization switch already call this; call it yourself
+ * only after changing the person outside this package.
+ */
+declare function invalidatePerson(client: AuthClient): void;
+/**
+ * The signed-in person, verified by the auth server, or null when signed out. The verified read is
+ * kept per client until the session changes (sign-in, sign-out, profile edit, organization switch),
+ * so repeated access checks cost zero extra auth-server calls; concurrent callers share one read.
+ */
 declare function getPerson(client: AuthClient): Promise<User | null>;
 /** Hear every session change (sign-in, refresh, sign-out). Returns the unsubscribe. */
 declare function onSessionChange(client: AuthClient, cb: (event: AuthChangeEvent, session: Session | null) => void): () => void;
@@ -99,4 +109,4 @@ declare const userCredentials: typeof sessionCredentials;
  */
 declare function refreshSession(client: AuthClient): Promise<Session>;
 
-export { type AuthClient as A, type SessionSourceLike as S, type UserCredentialsPort as U, SignInError as a, getSession as b, signInWithOAuth as c, signInWithPassword as d, signOut as e, userCredentials as f, getPerson as g, onSessionChange as o, refreshSession as r, sessionCredentials as s, updatePerson as u };
+export { type AuthClient as A, type SessionSourceLike as S, type UserCredentialsPort as U, SignInError as a, getSession as b, signInWithOAuth as c, signInWithPassword as d, signOut as e, userCredentials as f, getPerson as g, invalidatePerson as i, onSessionChange as o, refreshSession as r, sessionCredentials as s, updatePerson as u };

package/dist/{session-DhRO4euL.d.ts → session-DdQiStp6.d.ts}

@@ -31,7 +31,17 @@ declare class SignInError extends Error {
 }
 /** The stored session (no network unless a refresh is due), or null when signed out. */
 declare function getSession(client: AuthClient): Promise<Session | null>;
-/** The signed-in person, verified by the auth server, or null when signed out. */
+/**
+ * Forget the cached person for this client, so the next {@link getPerson} asks the auth server.
+ * Sign-in, sign-out, a profile edit and an organization switch already call this; call it yourself
+ * only after changing the person outside this package.
+ */
+declare function invalidatePerson(client: AuthClient): void;
+/**
+ * The signed-in person, verified by the auth server, or null when signed out. The verified read is
+ * kept per client until the session changes (sign-in, sign-out, profile edit, organization switch),
+ * so repeated access checks cost zero extra auth-server calls; concurrent callers share one read.
+ */
 declare function getPerson(client: AuthClient): Promise<User | null>;
 /** Hear every session change (sign-in, refresh, sign-out). Returns the unsubscribe. */
 declare function onSessionChange(client: AuthClient, cb: (event: AuthChangeEvent, session: Session | null) => void): () => void;
@@ -99,4 +109,4 @@ declare const userCredentials: typeof sessionCredentials;
  */
 declare function refreshSession(client: AuthClient): Promise<Session>;
 
-export { type AuthClient as A, type SessionSourceLike as S, type UserCredentialsPort as U, SignInError as a, getSession as b, signInWithOAuth as c, signInWithPassword as d, signOut as e, userCredentials as f, getPerson as g, onSessionChange as o, refreshSession as r, sessionCredentials as s, updatePerson as u };
+export { type AuthClient as A, type SessionSourceLike as S, type UserCredentialsPort as U, SignInError as a, getSession as b, signInWithOAuth as c, signInWithPassword as d, signOut as e, userCredentials as f, getPerson as g, invalidatePerson as i, onSessionChange as o, refreshSession as r, sessionCredentials as s, updatePerson as u };

package/dist/storage-Dqnye4KF.d.cts

@@ -0,0 +1,51 @@
+/**
+ * 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 { type ChromeStorageAreaLike as C, type SessionStorage as S, StorageUnavailableError as a, browserStorage as b, extensionStorage as e, keyValueStorage as k, memoryStorage as m };

package/dist/storage-Dqnye4KF.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 { type ChromeStorageAreaLike as C, type SessionStorage as S, StorageUnavailableError as a, browserStorage as b, extensionStorage as e, keyValueStorage as k, memoryStorage as m };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/auth",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "AI Matrx sign-in, session and organizations for every app: sign in/out, session storage and refresh per platform (browser, Next.js, extension, desktop, Node), the current person, their organizations and favourites, the one active organization (held requests, never a list filter), and the credentials @ai-matrx/data and @ai-matrx/api read.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -122,6 +122,16 @@
         "default": "./dist/testing.cjs"
       }
     },
+    "./matrx-oauth": {
+      "import": {
+        "types": "./dist/matrx-oauth.d.ts",
+        "default": "./dist/matrx-oauth.js"
+      },
+      "require": {
+        "types": "./dist/matrx-oauth.d.cts",
+        "default": "./dist/matrx-oauth.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "devDependencies": {
@@ -191,5 +201,5 @@
     "test": "vitest run",
     "verify:tarball": "node ./scripts/verify-tarball.mjs"
   },
-  "gitHead": "7ee2d68e156416d62a043d8f5053ff7f0b5792fc"
+  "gitHead": "eeeafb1ae105f78c584681829e13dd69b200abc6"
 }