@ai-matrx/auth 0.1.4 → 0.2.0

package/dist/node.js

@@ -1,3 +1,135 @@
+// src/server-auth.ts
+import { createClient } from "@supabase/supabase-js";
+
+// src/claims.ts
+import {
+  AuthError,
+  AuthSessionMissingError
+} from "@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 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 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 : [];
+}
+
+// src/server-auth.ts
+function createServerAuth(options) {
+  const warn = options.warn ?? ((m) => console.warn(m));
+  const resolveOnce = async () => {
+    const client = await options.createClient();
+    const {
+      data: { user },
+      error
+    } = await getClaimsUser(client, void 0, { jwks: { keys: pinnedSigningKeysFor(options.supabaseUrl) } });
+    const authUnavailable = !user && error !== null && isAuthTransportFailure(error);
+    if (authUnavailable) {
+      warn(
+        `[getServerAuth] identity could not be verified on this attempt \u2014 rendering without a user, NOT as signed out. Cause: ${error?.name ?? "unknown"}: ${error?.message ?? ""}`
+      );
+    }
+    return { isAuthenticated: !!user, user, authUnavailable, ...accountFlagsFor(user) };
+  };
+  const door = async () => {
+    const first = await resolveOnce();
+    if (!first.authUnavailable) return first;
+    await new Promise((resolve) => setTimeout(resolve, options.retryAfterMs ?? 250));
+    const second = await resolveOnce();
+    if (!second.authUnavailable) warn("[getServerAuth] identity verified on the retry \u2014 the first attempt's budget was spent.");
+    return second;
+  };
+  return options.cache ? options.cache(door) : door;
+}
+async function verifyRequest(request, options) {
+  const header = request.headers.get("Authorization") ?? request.headers.get("authorization");
+  if (header?.startsWith("Bearer ")) {
+    const token = header.slice(7);
+    const client2 = createClient(options.url, options.publishableKey, {
+      global: { headers: { Authorization: `Bearer ${token}` } },
+      auth: { persistSession: false, autoRefreshToken: false }
+    });
+    const { data: data2, error: error2 } = await getClaimsUser(client2, token, {
+      jwks: { keys: pinnedSigningKeysFor(options.url) }
+    });
+    return { user: data2.user, error: error2 };
+  }
+  if (!options.cookieClient) return { user: null, error: null };
+  const client = await options.cookieClient();
+  const { data, error } = await getClaimsUser(client, void 0, { jwks: { keys: pinnedSigningKeysFor(options.url) } });
+  return { user: data.user, error };
+}
+function createServiceClient(options) {
+  const url = options.url?.trim();
+  const key = options.secretKey?.trim();
+  if (!url) throw new Error("createServiceClient: the Supabase URL is not configured");
+  if (!key) throw new Error("createServiceClient: the secret key (SUPABASE_SECRET_KEY) is not configured");
+  return createClient(url, key, { auth: { persistSession: false, autoRefreshToken: false } });
+}
+
 // src/node.ts
 function builtin(name) {
   const get = globalThis.process?.getBuiltinModule;
@@ -32,5 +164,8 @@ function fileStorage(path) {
   };
 }
 export {
-  fileStorage
+  createServerAuth,
+  createServiceClient,
+  fileStorage,
+  verifyRequest
 };

package/dist/organizations.cjs

@@ -20,16 +20,29 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/organizations.ts
 var organizations_exports = {};
 __export(organizations_exports, {
+  MEMBERSHIPS_URL: () => MEMBERSHIPS_URL,
   NoActiveOrganizationError: () => NoActiveOrganizationError,
   NotAMemberError: () => NotAMemberError,
+  ORGANIZATION_CONTEXT_REQUIRED_CODE: () => ORGANIZATION_CONTEXT_REQUIRED_CODE,
   ORGANIZATION_ENTITY_TYPE: () => ORGANIZATION_ENTITY_TYPE,
+  ORGANIZATION_REQUIRED_CODE: () => ORGANIZATION_REQUIRED_CODE,
+  ORGANIZATION_REQUIRED_WIRE_CODE: () => ORGANIZATION_REQUIRED_WIRE_CODE,
+  OrganizationRequiredServerError: () => OrganizationRequiredServerError,
   classifyOrganizationRefusal: () => classifyOrganizationRefusal,
   createActiveOrganization: () => createActiveOrganization,
+  extractOrganizationHoldMemberships: () => extractOrganizationHoldMemberships,
+  isOrganizationRequiredEnvelope: () => isOrganizationRequiredEnvelope,
+  isOrganizationRequiredError: () => isOrganizationRequiredError,
+  isOrganizationRequiredServerError: () => isOrganizationRequiredServerError,
   memoryHeldOrganization: () => memoryHeldOrganization,
   oldestMembership: () => oldestMembership,
   orderOrganizations: () => orderOrganizations,
   organizationMatches: () => organizationMatches,
+  organizationRequired: () => organizationRequired,
+  organizationRequiredEnvelope: () => organizationRequiredEnvelope,
+  organizationRequiredResponse: () => organizationRequiredResponse,
   readAccountOrganizationChoices: () => readAccountOrganizationChoices,
+  readCallerMemberships: () => readCallerMemberships,
   readMemberships: () => readMemberships,
   readOrganizationFavourites: () => readOrganizationFavourites,
   resolveActiveOrganization: () => resolveActiveOrganization,
@@ -422,3 +435,84 @@ 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 });
+}

package/dist/organizations.d.cts

@@ -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

@@ -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

@@ -378,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/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 };