@ai-matrx/auth 0.0.0 → 0.1.0

package/dist/react.d.cts

@@ -0,0 +1,163 @@
+import { SupabaseClient, Session, User } from '@supabase/supabase-js';
+
+/**
+ * @ai-matrx/auth — sign-in and session doors (moved from @ai-matrx/data/auth, 2026-10-09).
+ *
+ * auth owns Supabase sign-in; @ai-matrx/data reads the same client and session for its doors. A package or app asks these doors instead of reaching into
+ * `client.auth.*`; the session leaves for `@ai-matrx/api` only as the `user` credential
+ * (`sessionCredentials(client)`, the shape api's `CredentialsPort` takes, and the same port
+ * `@ai-matrx/data`'s `createDb(...).credentials` returns), so api reads the token and never
+ * signs anyone in.
+ *
+ *   const session = await getSession(supabase);            // Session | null
+ *   const person  = await getPerson(supabase);             // User | null (verified by the server)
+ *   const stop    = onSessionChange(supabase, (event, session) => …);
+ *   await signInWithPassword(supabase, { email, password }); // throws SignInError
+ *   const { url } = await signInWithOAuth(supabase, { provider: "google", redirectTo });
+ *   await signOut(supabase);
+ *   await updatePerson(supabase, { data: { full_name } });
+ *
+ * Every refusal throws `SignInError` carrying the auth server's own message, status and code.
+ */
+
+/** Any supabase-js client (browser, server, route, extension) — only its `auth` is used here. */
+type AuthClient = Pick<SupabaseClient<any, any, any>, "auth">;
+
+/**
+ * @ai-matrx/auth/organizations (moved from @ai-matrx/data/organizations, 2026-10-09) — THE active-organization ladder and the account's organization
+ * facts, for every Matrx client (the web, Matrx 2, the extension, Studio).
+ *
+ * 🚨 ONE ACTIVE ORGANIZATION, SET ONCE WHEN THE APP LOADS, NEVER NONE (Arman, 2026-10-07;
+ * organizations STATE rules 10–15). The ladder picks what the UI OPENS to; from then on every
+ * request carries the one active organization the person can see. Reads never filter by it.
+ *
+ * THE RUNGS, each kept only if it is a CURRENT membership:
+ *   1. HELD     — what this tab (web) or this running app (desktop, in memory) already works in;
+ *   2. LAST ACTIVE — `users.user_preferences.last_active_organization_id` (follows the person
+ *                 across devices: STATE rule 12);
+ *   3. START-UP — `users.user_preferences.startup_organization_id` (the "Start-up organization"
+ *                 setting);
+ *   4. FIRST    — the oldest active membership.
+ * Zero memberships → null. A failed read THROWS (the host shows "could not check" and a retry,
+ * never a guess). The ladder's own answer never writes anything (rule 14): only a person's click
+ * writes last active.
+ *
+ * Hosts with extra rungs keep them (the web's `?org=` link rung) and call the pure core here.
+ */
+
+/** One organization the person is an active member of, as every picker draws it. */
+interface OrganizationMembership {
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string | null;
+    /** The database-validated 2–3 letters, when the organization has them. */
+    readonly abbreviation: string | null;
+    readonly logoUrl: string | null;
+    /** owner | admin | member (the membership's role). */
+    readonly role: string;
+    /** The person created it (drawn under the favourites, before the rest). */
+    readonly isOwn: boolean;
+    /** Classified in `iam.organizations.settings.test_fixture` — never guessed from a name. */
+    readonly isTestFixture: boolean;
+    /** When the membership began (ISO): the oldest is rung 4. */
+    readonly joinedAt: string;
+}
+type OrganizationRung = "held" | "last-active" | "startup" | "first";
+
+/**
+ * THE ACTIVE ORGANIZATION — one per tab / running app, set once when the app loads, never none
+ * while the person has a membership (Arman, 2026-10-07; organizations STATE rules 10–15).
+ *
+ *   const active = createActiveOrganization({ client: supabase });
+ *   await active.load();                       // the ladder: held → last active → start-up → first
+ *   const orgId = await active.ensureOrgId();  // HELD until the ladder answers; never a guess
+ *   await active.switchTo(otherId);            // a person's click: saves last active for next load
+ *
+ * HELD-REQUEST SEMANTICS. A write or server call that needs the organization asks
+ * `ensureOrgId()`: while the ladder is still resolving the call WAITS (it is held, never sent
+ * without an organization and never sent with a guessed one); once resolved it gets the one
+ * active organization; with zero memberships or a failed read it is REFUSED with a named error.
+ * Acting on a record passes that record's own organization (`ensureOrgId(record.organization_id)`),
+ * which wins and never switches the active one.
+ *
+ * 🚨 NEVER A LIST FILTER. Reads show everything the person can see across all their
+ * organizations; nothing here narrows a read. The active organization is only where new things
+ * are saved and which organization a server call runs in.
+ *
+ * The held id is identity-keyed: a different person signing in on the same device never inherits
+ * the last person's organization, and a sign-out resets the store.
+ */
+
+type ActiveOrganizationStatus = "idle" | "resolving" | "ready" | "none" | "error";
+interface ActiveOrganizationSnapshot {
+    readonly status: ActiveOrganizationStatus;
+    readonly userId: string | null;
+    readonly organizationId: string | null;
+    readonly organization: OrganizationMembership | null;
+    readonly memberships: readonly OrganizationMembership[];
+    /** Which ladder rung answered (or "switched" after a person's click). */
+    readonly rung: OrganizationRung | "switched" | null;
+    readonly error: string | null;
+}
+interface ActiveOrganization {
+    snapshot(): ActiveOrganizationSnapshot;
+    subscribe(listener: () => void): () => void;
+    /** Run the ladder (again). Resolves with the settled snapshot; never throws. */
+    load(): Promise<ActiveOrganizationSnapshot>;
+    /** The active organization id now, or null while resolving / with none. Sync (api's getter). */
+    current(): string | null;
+    /** THE HELD REQUEST: the record's own organization, else the active one once resolved. */
+    ensureOrgId(recordOrganizationId?: string | null): Promise<string>;
+    /** A person's click: switch, remember for this tab, save as last active for the next load. */
+    switchTo(organizationId: string): Promise<void>;
+    /** Feed a server refusal in: a lapsed organization re-runs the ladder. Returns the class. */
+    handleRefusal(status: number, body: unknown): Promise<"lapsed" | "retry" | null>;
+    dispose(): void;
+}
+
+interface SessionIdentitySnapshot<Id extends string = string> {
+    /** `resolving` until the first `getSession()` answers. */
+    readonly state: "resolving" | "resolved";
+    /** Who the session says is acting, or `null` for nobody. */
+    readonly userId: Id | null;
+}
+interface SessionIdentityDiagnostic {
+    level: "info" | "warn" | "error";
+    message: string;
+    remedy?: string | undefined;
+}
+/** The sentences a product says about its own session. */
+interface SessionIdentityWords {
+    /** The product's name as the subject of a sentence, e.g. "Messaging". */
+    readonly product: string;
+    /** Remedy when the client has no auth source. */
+    readonly noAuthSourceRemedy: string;
+    /** Remedy when the session could not be read. */
+    readonly unreadableRemedy: string;
+}
+interface SessionIdentityOptions<Id extends string = string> {
+    /** The host's browser Supabase client (anything with `auth.getSession` / `onAuthStateChange`). */
+    readonly client: unknown;
+    readonly words: SessionIdentityWords;
+    /** Brand the raw id (default: the string itself). */
+    readonly toUserId?: ((id: string) => Id) | undefined;
+    readonly onDiagnostic?: ((event: SessionIdentityDiagnostic) => void) | undefined;
+}
+
+interface SessionState {
+    readonly status: "resolving" | "signed-in" | "signed-out" | "error";
+    readonly session: Session | null;
+    readonly person: User | null;
+    readonly error: string | null;
+}
+/** The current session and person, live across sign-in, refresh, account switch and sign-out. */
+declare function useSession(client: AuthClient): SessionState;
+/** The active organization store's snapshot (stable reference until it moves). */
+declare function useActiveOrganization(store: ActiveOrganization): ActiveOrganizationSnapshot;
+/**
+ * Who is acting, read from the client's session (never handed in as a prop). `resolving` until
+ * the first session read answers; StrictMode-safe (the store is made and disposed in an effect).
+ */
+declare function useSessionIdentity<Id extends string = string>(options: SessionIdentityOptions<Id>): SessionIdentitySnapshot<Id>;
+
+export { type SessionState, useActiveOrganization, useSession, useSessionIdentity };

package/dist/react.d.ts

@@ -0,0 +1,163 @@
+import { SupabaseClient, Session, User } from '@supabase/supabase-js';
+
+/**
+ * @ai-matrx/auth — sign-in and session doors (moved from @ai-matrx/data/auth, 2026-10-09).
+ *
+ * auth owns Supabase sign-in; @ai-matrx/data reads the same client and session for its doors. A package or app asks these doors instead of reaching into
+ * `client.auth.*`; the session leaves for `@ai-matrx/api` only as the `user` credential
+ * (`sessionCredentials(client)`, the shape api's `CredentialsPort` takes, and the same port
+ * `@ai-matrx/data`'s `createDb(...).credentials` returns), so api reads the token and never
+ * signs anyone in.
+ *
+ *   const session = await getSession(supabase);            // Session | null
+ *   const person  = await getPerson(supabase);             // User | null (verified by the server)
+ *   const stop    = onSessionChange(supabase, (event, session) => …);
+ *   await signInWithPassword(supabase, { email, password }); // throws SignInError
+ *   const { url } = await signInWithOAuth(supabase, { provider: "google", redirectTo });
+ *   await signOut(supabase);
+ *   await updatePerson(supabase, { data: { full_name } });
+ *
+ * Every refusal throws `SignInError` carrying the auth server's own message, status and code.
+ */
+
+/** Any supabase-js client (browser, server, route, extension) — only its `auth` is used here. */
+type AuthClient = Pick<SupabaseClient<any, any, any>, "auth">;
+
+/**
+ * @ai-matrx/auth/organizations (moved from @ai-matrx/data/organizations, 2026-10-09) — THE active-organization ladder and the account's organization
+ * facts, for every Matrx client (the web, Matrx 2, the extension, Studio).
+ *
+ * 🚨 ONE ACTIVE ORGANIZATION, SET ONCE WHEN THE APP LOADS, NEVER NONE (Arman, 2026-10-07;
+ * organizations STATE rules 10–15). The ladder picks what the UI OPENS to; from then on every
+ * request carries the one active organization the person can see. Reads never filter by it.
+ *
+ * THE RUNGS, each kept only if it is a CURRENT membership:
+ *   1. HELD     — what this tab (web) or this running app (desktop, in memory) already works in;
+ *   2. LAST ACTIVE — `users.user_preferences.last_active_organization_id` (follows the person
+ *                 across devices: STATE rule 12);
+ *   3. START-UP — `users.user_preferences.startup_organization_id` (the "Start-up organization"
+ *                 setting);
+ *   4. FIRST    — the oldest active membership.
+ * Zero memberships → null. A failed read THROWS (the host shows "could not check" and a retry,
+ * never a guess). The ladder's own answer never writes anything (rule 14): only a person's click
+ * writes last active.
+ *
+ * Hosts with extra rungs keep them (the web's `?org=` link rung) and call the pure core here.
+ */
+
+/** One organization the person is an active member of, as every picker draws it. */
+interface OrganizationMembership {
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string | null;
+    /** The database-validated 2–3 letters, when the organization has them. */
+    readonly abbreviation: string | null;
+    readonly logoUrl: string | null;
+    /** owner | admin | member (the membership's role). */
+    readonly role: string;
+    /** The person created it (drawn under the favourites, before the rest). */
+    readonly isOwn: boolean;
+    /** Classified in `iam.organizations.settings.test_fixture` — never guessed from a name. */
+    readonly isTestFixture: boolean;
+    /** When the membership began (ISO): the oldest is rung 4. */
+    readonly joinedAt: string;
+}
+type OrganizationRung = "held" | "last-active" | "startup" | "first";
+
+/**
+ * THE ACTIVE ORGANIZATION — one per tab / running app, set once when the app loads, never none
+ * while the person has a membership (Arman, 2026-10-07; organizations STATE rules 10–15).
+ *
+ *   const active = createActiveOrganization({ client: supabase });
+ *   await active.load();                       // the ladder: held → last active → start-up → first
+ *   const orgId = await active.ensureOrgId();  // HELD until the ladder answers; never a guess
+ *   await active.switchTo(otherId);            // a person's click: saves last active for next load
+ *
+ * HELD-REQUEST SEMANTICS. A write or server call that needs the organization asks
+ * `ensureOrgId()`: while the ladder is still resolving the call WAITS (it is held, never sent
+ * without an organization and never sent with a guessed one); once resolved it gets the one
+ * active organization; with zero memberships or a failed read it is REFUSED with a named error.
+ * Acting on a record passes that record's own organization (`ensureOrgId(record.organization_id)`),
+ * which wins and never switches the active one.
+ *
+ * 🚨 NEVER A LIST FILTER. Reads show everything the person can see across all their
+ * organizations; nothing here narrows a read. The active organization is only where new things
+ * are saved and which organization a server call runs in.
+ *
+ * The held id is identity-keyed: a different person signing in on the same device never inherits
+ * the last person's organization, and a sign-out resets the store.
+ */
+
+type ActiveOrganizationStatus = "idle" | "resolving" | "ready" | "none" | "error";
+interface ActiveOrganizationSnapshot {
+    readonly status: ActiveOrganizationStatus;
+    readonly userId: string | null;
+    readonly organizationId: string | null;
+    readonly organization: OrganizationMembership | null;
+    readonly memberships: readonly OrganizationMembership[];
+    /** Which ladder rung answered (or "switched" after a person's click). */
+    readonly rung: OrganizationRung | "switched" | null;
+    readonly error: string | null;
+}
+interface ActiveOrganization {
+    snapshot(): ActiveOrganizationSnapshot;
+    subscribe(listener: () => void): () => void;
+    /** Run the ladder (again). Resolves with the settled snapshot; never throws. */
+    load(): Promise<ActiveOrganizationSnapshot>;
+    /** The active organization id now, or null while resolving / with none. Sync (api's getter). */
+    current(): string | null;
+    /** THE HELD REQUEST: the record's own organization, else the active one once resolved. */
+    ensureOrgId(recordOrganizationId?: string | null): Promise<string>;
+    /** A person's click: switch, remember for this tab, save as last active for the next load. */
+    switchTo(organizationId: string): Promise<void>;
+    /** Feed a server refusal in: a lapsed organization re-runs the ladder. Returns the class. */
+    handleRefusal(status: number, body: unknown): Promise<"lapsed" | "retry" | null>;
+    dispose(): void;
+}
+
+interface SessionIdentitySnapshot<Id extends string = string> {
+    /** `resolving` until the first `getSession()` answers. */
+    readonly state: "resolving" | "resolved";
+    /** Who the session says is acting, or `null` for nobody. */
+    readonly userId: Id | null;
+}
+interface SessionIdentityDiagnostic {
+    level: "info" | "warn" | "error";
+    message: string;
+    remedy?: string | undefined;
+}
+/** The sentences a product says about its own session. */
+interface SessionIdentityWords {
+    /** The product's name as the subject of a sentence, e.g. "Messaging". */
+    readonly product: string;
+    /** Remedy when the client has no auth source. */
+    readonly noAuthSourceRemedy: string;
+    /** Remedy when the session could not be read. */
+    readonly unreadableRemedy: string;
+}
+interface SessionIdentityOptions<Id extends string = string> {
+    /** The host's browser Supabase client (anything with `auth.getSession` / `onAuthStateChange`). */
+    readonly client: unknown;
+    readonly words: SessionIdentityWords;
+    /** Brand the raw id (default: the string itself). */
+    readonly toUserId?: ((id: string) => Id) | undefined;
+    readonly onDiagnostic?: ((event: SessionIdentityDiagnostic) => void) | undefined;
+}
+
+interface SessionState {
+    readonly status: "resolving" | "signed-in" | "signed-out" | "error";
+    readonly session: Session | null;
+    readonly person: User | null;
+    readonly error: string | null;
+}
+/** The current session and person, live across sign-in, refresh, account switch and sign-out. */
+declare function useSession(client: AuthClient): SessionState;
+/** The active organization store's snapshot (stable reference until it moves). */
+declare function useActiveOrganization(store: ActiveOrganization): ActiveOrganizationSnapshot;
+/**
+ * Who is acting, read from the client's session (never handed in as a prop). `resolving` until
+ * the first session read answers; StrictMode-safe (the store is made and disposed in an effect).
+ */
+declare function useSessionIdentity<Id extends string = string>(options: SessionIdentityOptions<Id>): SessionIdentitySnapshot<Id>;
+
+export { type SessionState, useActiveOrganization, useSession, useSessionIdentity };

package/dist/react.js

@@ -0,0 +1,186 @@
+"use client";
+"use client";
+
+// src/react.ts
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+
+// src/session.ts
+var SignInError = class extends Error {
+  constructor(door, message, status, code) {
+    super(`${door}: ${message}`);
+    this.door = door;
+    this.status = status;
+    this.code = code;
+    this.name = "SignInError";
+  }
+  door;
+  status;
+  code;
+};
+function check(door, data, error) {
+  if (error) throw new SignInError(door, error.message, error.status, error.code);
+  return data;
+}
+async function getSession(client) {
+  const { data, error } = await client.auth.getSession();
+  return check("getSession", data, error).session;
+}
+function onSessionChange(client, cb) {
+  const { data } = client.auth.onAuthStateChange(cb);
+  return () => data.subscription.unsubscribe();
+}
+
+// src/session-identity.ts
+var RESOLVING = Object.freeze({
+  state: "resolving",
+  userId: null
+});
+var SERVER_SESSION_IDENTITY = RESOLVING;
+function authOf(client) {
+  if (client === null || typeof client !== "object" && typeof client !== "function") return null;
+  const candidate = client.auth;
+  if (candidate === null || typeof candidate !== "object") return null;
+  const auth = candidate;
+  if (typeof auth.getSession !== "function") return null;
+  if (typeof auth.onAuthStateChange !== "function") return null;
+  return auth;
+}
+function sessionUserId(session) {
+  const id = session?.user?.id;
+  return typeof id === "string" && id.length > 0 ? id : null;
+}
+function noAuthSourceMessage(words) {
+  return {
+    message: `${words.product} cannot tell who is signed in: the Supabase client it was given has no auth session source.`,
+    remedy: words.noAuthSourceRemedy
+  };
+}
+function unreadableSessionMessage(words, error) {
+  return `${words.product} could not read the signed-in session: ${String(
+    error?.message ?? error
+  )}`;
+}
+function createSessionIdentity(options) {
+  const { client, onDiagnostic, words } = options;
+  const brand = options.toUserId ?? ((id) => id);
+  const listeners = /* @__PURE__ */ new Set();
+  let current = RESOLVING;
+  let disposed = false;
+  const userIdOf = (session) => {
+    const id = sessionUserId(session);
+    return id === null ? null : brand(id);
+  };
+  const publish = (state, userId) => {
+    if (disposed) return;
+    if (current.state === state && current.userId === userId) return;
+    current = Object.freeze({ state, userId });
+    for (const listener of [...listeners]) listener();
+  };
+  const subscribeOnly = (hasAuthSource) => ({
+    hasAuthSource,
+    snapshot: () => current,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    dispose: () => {
+      disposed = true;
+      listeners.clear();
+    }
+  });
+  const auth = authOf(client);
+  if (auth === null) {
+    onDiagnostic?.({ level: "error", ...noAuthSourceMessage(words) });
+    current = Object.freeze({ state: "resolved", userId: null });
+    return subscribeOnly(false);
+  }
+  void (async () => {
+    try {
+      const result = await auth.getSession();
+      publish("resolved", userIdOf(result?.data?.session));
+    } catch (error) {
+      onDiagnostic?.({
+        level: "warn",
+        message: unreadableSessionMessage(words, error),
+        remedy: words.unreadableRemedy
+      });
+      publish("resolved", null);
+    }
+  })();
+  const subscription = auth.onAuthStateChange((_event, session) => {
+    publish("resolved", userIdOf(session));
+  });
+  const base = subscribeOnly(true);
+  return {
+    hasAuthSource: true,
+    snapshot: base.snapshot,
+    subscribe: base.subscribe,
+    dispose: () => {
+      base.dispose();
+      try {
+        subscription.data.subscription.unsubscribe();
+      } catch {
+      }
+    }
+  };
+}
+
+// src/react.ts
+var RESOLVING2 = Object.freeze({ status: "resolving", session: null, person: null, error: null });
+function useSession(client) {
+  const [state, setState] = useState(RESOLVING2);
+  useEffect(() => {
+    let alive = true;
+    const apply = (session) => {
+      if (!alive) return;
+      setState(
+        session ? { status: "signed-in", session, person: session.user, error: null } : { status: "signed-out", session: null, person: null, error: null }
+      );
+    };
+    getSession(client).then(apply, (e) => {
+      if (alive) setState({ status: "error", session: null, person: null, error: e?.message ?? String(e) });
+    });
+    const stop = onSessionChange(client, (_event, session) => apply(session));
+    return () => {
+      alive = false;
+      stop();
+    };
+  }, [client]);
+  return state;
+}
+var SERVER_ACTIVE = Object.freeze({
+  status: "idle",
+  userId: null,
+  organizationId: null,
+  organization: null,
+  memberships: Object.freeze([]),
+  rung: null,
+  error: null
+});
+function useActiveOrganization(store) {
+  return useSyncExternalStore(store.subscribe, store.snapshot, () => SERVER_ACTIVE);
+}
+var NO_IDENTITY = {
+  subscribe: () => () => {
+  },
+  snapshot: () => SERVER_SESSION_IDENTITY
+};
+function useSessionIdentity(options) {
+  const latest = useRef(options);
+  latest.current = options;
+  const [identity, setIdentity] = useState(null);
+  useEffect(() => {
+    const made = createSessionIdentity(latest.current);
+    setIdentity(made);
+    return () => made.dispose();
+  }, [options.client]);
+  const source = identity ?? NO_IDENTITY;
+  return useSyncExternalStore(source.subscribe, source.snapshot, () => SERVER_SESSION_IDENTITY);
+}
+export {
+  useActiveOrganization,
+  useSession,
+  useSessionIdentity
+};

package/dist/session-4rdIyV28.d.cts

@@ -0,0 +1,102 @@
+import { SupabaseClient, User, Session, AuthChangeEvent, Provider, UserAttributes } from '@supabase/supabase-js';
+
+/**
+ * @ai-matrx/auth — sign-in and session doors (moved from @ai-matrx/data/auth, 2026-10-09).
+ *
+ * auth owns Supabase sign-in; @ai-matrx/data reads the same client and session for its doors. A package or app asks these doors instead of reaching into
+ * `client.auth.*`; the session leaves for `@ai-matrx/api` only as the `user` credential
+ * (`sessionCredentials(client)`, the shape api's `CredentialsPort` takes, and the same port
+ * `@ai-matrx/data`'s `createDb(...).credentials` returns), so api reads the token and never
+ * signs anyone in.
+ *
+ *   const session = await getSession(supabase);            // Session | null
+ *   const person  = await getPerson(supabase);             // User | null (verified by the server)
+ *   const stop    = onSessionChange(supabase, (event, session) => …);
+ *   await signInWithPassword(supabase, { email, password }); // throws SignInError
+ *   const { url } = await signInWithOAuth(supabase, { provider: "google", redirectTo });
+ *   await signOut(supabase);
+ *   await updatePerson(supabase, { data: { full_name } });
+ *
+ * Every refusal throws `SignInError` carrying the auth server's own message, status and code.
+ */
+
+/** Any supabase-js client (browser, server, route, extension) — only its `auth` is used here. */
+type AuthClient = Pick<SupabaseClient<any, any, any>, "auth">;
+/** A refusal from the auth server — its own message, plus status/code when it sent them. */
+declare class SignInError extends Error {
+    readonly door: string;
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    constructor(door: string, message: string, status?: number | undefined, code?: string | undefined);
+}
+/** 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. */
+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;
+declare function signInWithPassword(client: AuthClient, credentials: {
+    email: string;
+    password: string;
+} | {
+    phone: string;
+    password: string;
+}): Promise<{
+    session: Session;
+    person: User;
+}>;
+declare function signInWithOAuth(client: AuthClient, options: {
+    provider: Provider;
+    redirectTo?: string;
+    scopes?: string;
+    queryParams?: Record<string, string>;
+    skipBrowserRedirect?: boolean;
+}): Promise<{
+    provider: Provider;
+    url: string | null;
+}>;
+declare function signOut(client: AuthClient, scope?: "global" | "local" | "others"): Promise<void>;
+/** Change the signed-in person's email, phone, password or metadata. */
+declare function updatePerson(client: AuthClient, attributes: UserAttributes): Promise<User>;
+/** The slice of a client the session credential reads: its `auth`, when it has one. */
+interface SessionSourceLike {
+    auth?: {
+        getSession(): PromiseLike<{
+            data: {
+                session: {
+                    access_token: string;
+                } | null;
+            };
+        }>;
+        onAuthStateChange(cb: (event: string, session: unknown) => void): {
+            data: {
+                subscription: {
+                    unsubscribe(): void;
+                };
+            };
+        };
+    } | undefined;
+}
+/** The `user` credential port (structural; the shape `@ai-matrx/api`'s `CredentialsPort` takes). */
+interface UserCredentialsPort {
+    get(): Promise<{
+        kind: "user";
+        accessToken: string;
+    } | null>;
+    onChange?(cb: () => void): () => void;
+}
+/**
+ * THE ONE session → credential mapping: the current access token as api's `user` credential,
+ * re-read on every call (a refresh rotates it), with `onChange` on every session change.
+ * A client with no `auth` is anonymous (null), never an error.
+ */
+declare function sessionCredentials(client: SessionSourceLike): UserCredentialsPort;
+/** The session as `@ai-matrx/api`'s `user` credential — the name `@ai-matrx/data/auth` shipped. */
+declare const userCredentials: typeof sessionCredentials;
+/**
+ * Refresh the session now (a long-lived script, a desktop app waking from sleep, a tab that was
+ * frozen). Returns the new session; throws `SignInError` when the refresh token is refused.
+ */
+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 };