@ai-matrx/auth 0.1.4 → 0.2.1

package/dist/organizations.d.ts

@@ -143,6 +143,230 @@ declare function setOrganizationFavourite(db: OrganizationsDb, organizationId: s
 type OrganizationRefusal = "lapsed" | "retry" | null;
 declare function classifyOrganizationRefusal(status: number, body: unknown): OrganizationRefusal;
 
+/**
+ * Organization-question plumbing that is LOGIC, not store binding (moved from the website's
+ * `orgBootstrapGate`, `organizationRefusal`, `childOrganization`, `adminOrganization`).
+ * Pure: every host input is injected; no Redux, no Next, no window.
+ */
+/** How long a write may wait for the first answer before it is refused anyway. */
+declare const ORGANIZATION_RESOLUTION_TIMEOUT_MS = 10000;
+interface OrganizationBootstrapGate {
+    isResolved(): boolean;
+    /** The organization question has been answered (with an organization or without). Idempotent. */
+    markResolved(): void;
+    /** Wait for the answer or the timeout, whichever first. Always resolves; never rejects. */
+    whenResolved(timeoutMs?: number): Promise<void>;
+    /** Tests and in-place identity swaps only. */
+    reset(): void;
+}
+/** "Nobody has looked yet" is a race, not a fact: a held write waits on this, bounded. */
+declare function createOrganizationBootstrapGate(defaultTimeoutMs?: number): OrganizationBootstrapGate;
+/** True when an error body is the server's "you are not a member of the organization you carried". */
+declare function isNotAMemberRefusal(body: unknown): boolean;
+declare const NOT_A_MEMBER_RECHECK_GAP_MS = 30000;
+interface NotAMemberRefusalNotice {
+    /** True when a recheck was started (at most one per gap, so a burst reads memberships once). */
+    notice(body: unknown, now?: number): boolean;
+    reset(): void;
+}
+declare function createNotAMemberRefusalNotice(recheck: () => void, gapMs?: number): NotAMemberRefusalNotice;
+type ParentOrganization = string | {
+    organization_id?: string | null;
+} | null | undefined;
+/**
+ * A record created as part of an existing parent lives in the PARENT's organization; the explicit
+ * one applies only when the parent names none. A disagreement is announced (`onDisagree`,
+ * default console.warn), never obeyed.
+ */
+declare function resolveChildOrganizationId(parent: ParentOrganization, explicit?: string | null, label?: string, onDisagree?: (message: string) => void): string | null;
+/** What the host knows about the admin lane. */
+interface AdminSeatInput {
+    readonly laneOpen: boolean;
+    readonly organizationId?: string | null;
+    readonly organizationName?: string | null;
+}
+interface AdminSeat {
+    readonly id: string;
+    readonly name: string | null;
+}
+/** The admin organization in force right now, or null (off the lane, or none set). */
+declare function resolveAdminSeat(input: AdminSeatInput | null | undefined): AdminSeat | null;
+/** True when the admin seat differs from the person's own active organization (scope/project/task never ride across). */
+declare function adminSeatReplacesUserContext(input: AdminSeatInput | null | undefined, personOrganizationId: string | null | undefined): boolean;
+
+/**
+ * The query key, platform-wide. The server stamps this on every deep link it
+ * emits; `features/admin/users/components/OrganizationsAdminClient.tsx` has
+ * read it since before this module existed. One spelling, in one place.
+ */
+declare const LINK_ORGANIZATION_QUERY_KEY = "org";
+type LinkOrganizationParam = 
+/** No link said anything about an organization. The ladder is untouched. */
+{
+    kind: "absent";
+}
+/** Something was said and it is neither a uuid nor an address. Refused in words, never used. */
+ | {
+    kind: "malformed";
+    raw: string;
+}
+/** A well-formed organization id. Still has to survive the membership check. */
+ | {
+    kind: "named";
+    organizationId: string;
+}
+/** An organization's address (slug). Survives only by matching a membership's slug. */
+ | {
+    kind: "addressed";
+    slug: string;
+};
+/**
+ * Classify one bare `org=` value. The ONE rule for what a value may be, shared
+ * by the URL reader below and the boot resolver's bare-value path.
+ */
+declare function classifyLinkOrganizationValue(raw: string): LinkOrganizationParam;
+/**
+ * Read the key out of a query string, a `URLSearchParams`, or a full URL.
+ * Never throws: a URL this cannot parse is `absent`, because a crash on
+ * arrival is a worse answer than the ladder's own.
+ */
+declare function readLinkOrganizationParam(source: string | URLSearchParams | null | undefined): LinkOrganizationParam;
+interface LinkOrganizationMembership {
+    id: string;
+    name: string;
+    /** The organization's address, so an `addressed` link can be matched. */
+    slug?: string | null;
+}
+interface LinkOrganizationDecisionInput {
+    param: LinkOrganizationParam;
+    /** The person's LIVE memberships. The only authority on what they may open. */
+    memberships: ReadonlyArray<LinkOrganizationMembership>;
+    /** The organization they are working in right now, or null. */
+    currentOrganizationId: string | null;
+    currentOrganizationName?: string | null;
+    /**
+     * The knob `userPreferences.organization.switchOnLinkPrompt` — "switch
+     * organization when a link asks". DEFAULT ON, so an omitted value is `true`.
+     */
+    switchWhenALinkAsks?: boolean;
+    /** The account they are signed in as, for the refusal sentence. */
+    signedInAs?: string | null;
+    /**
+     * The link's organization is one this person is not a member of but IS let into
+     * by a share they accepted (`lib/organizations/linkOrganizationAdmission.ts`).
+     * A share admits and never makes a member, so the answer is `admitted`: nobody
+     * is moved, nothing is refused, and the page opens it as that organization's
+     * guest. Omitted, the answer is exactly what it was before (VERIFIER-15 H4).
+     */
+    admittedByAShare?: boolean;
+    /** Replace any of the default English sentences (a localising host). */
+    messages?: Partial<LinkOrganizationMessages>;
+}
+interface LinkOrganizationMessages {
+    notAMember(signedInAs?: string | null): string;
+    malformed(raw: string): string;
+    switched(toName: string, fromName: string | null): string;
+    offer(toName: string, fromName: string | null): string;
+    offerAction(toName: string): string;
+}
+type LinkOrganizationDecision = 
+/** Nothing to do. No toast, no change. */
+{
+    kind: "no-link";
+}
+/** The link names the organization they are already in. Silent no-op. */
+ | {
+    kind: "already-current";
+    organizationId: string;
+}
+/** Use this organization for this session. `announcement` non-null = they moved. */
+ | {
+    kind: "honoured";
+    organizationId: string;
+    organizationName: string;
+    announcement: string | null;
+}
+/** The knob is off and this would be a real switch. Offer it as a click. */
+ | {
+    kind: "offered";
+    organizationId: string;
+    organizationName: string;
+    message: string;
+    actionLabel: string;
+}
+/**
+ * Not a member, but let in by a share they accepted. Silent: nobody is moved
+ * (a share never makes a member) and nothing was refused (the page opens it).
+ */
+ | {
+    kind: "admitted";
+    organizationId: string;
+}
+/** Malformed, or not theirs. Changes nothing; says so. */
+ | {
+    kind: "refused";
+    reason: "malformed" | "not-a-member";
+    message: string;
+};
+/** What a person reads when the link's organization is not theirs to open. */
+declare function linkOrganizationNotAMemberMessage(signedInAs?: string | null): string;
+/** What a person reads when `org=` is not an organization id at all. */
+declare function linkOrganizationMalformedMessage(raw: string): string;
+/** What a person reads when a link actually moved them. Law 4: never silent. */
+declare function linkOrganizationSwitchAnnouncement(toName: string, fromName: string | null): string;
+/** What a person reads with the knob turned off and a link asking to move them. */
+declare function linkOrganizationOfferMessage(toName: string, fromName: string | null): string;
+/**
+ * The decision. One function, every branch, no side effects.
+ *
+ * 🚨 WHY THE KNOB GOVERNS ONLY A REAL SWITCH. The knob protects the
+ * organization a person is WORKING IN from being yanked out from under them by
+ * a link someone else composed. With `currentOrganizationId === null` there is
+ * nothing to protect and nothing to switch away from: the alternative to
+ * honouring the link is the picker, which is the very dead end this module was
+ * built to end. So the knob turns a SWITCH into an offer; it never turns an
+ * arrival into a refusal. This is deliberate and it is not a hidden default —
+ * with no link present, a null selection stays null exactly as before.
+ */
+declare function decideLinkOrganization(input: LinkOrganizationDecisionInput): LinkOrganizationDecision;
+interface ResolveWithLinkInput<T extends {
+    id: string;
+    name: string;
+    slug?: string | null;
+    joinedAt?: string;
+}> {
+    readonly memberships: readonly T[];
+    /** This tab's held organization (rung 1; a refresh keeps it). */
+    readonly held?: string | null;
+    readonly readAccount: () => Promise<AccountOrganizationChoices>;
+    readonly first?: () => Promise<T | null>;
+    /** The raw `?org=` value, a query string, a URL or URLSearchParams. Omitted = no link. */
+    readonly link?: string | URLSearchParams | null;
+    readonly switchWhenALinkAsks?: boolean | undefined;
+    readonly signedInAs?: string | null | undefined;
+    readonly messages?: Partial<LinkOrganizationMessages> | undefined;
+    /** Asked only when the link already failed the membership check (a share admits, never joins). */
+    readonly admittedByAShare?: ((organizationId: string) => Promise<boolean>) | undefined;
+}
+interface ResolvedWithLink<T> {
+    readonly organization: T;
+    readonly rung: OrganizationRung | "link";
+    /** What the link meant, when it said anything — the host SAYS it (refused / announced / offered). */
+    readonly link: LinkOrganizationDecision;
+}
+/**
+ * The ONE load ladder with the link folded in: held → last active → start-up → first, then the
+ * link's own organization wins ONLY when it is a current membership. Every other link outcome
+ * (refused, offered, already-current, admitted) leaves the ladder's answer standing. Null when
+ * the person has no memberships. A failed read throws through.
+ */
+declare function resolveOrganizationWithLink<T extends {
+    id: string;
+    name: string;
+    slug?: string | null;
+    joinedAt?: string;
+}>(input: ResolveWithLinkInput<T>): Promise<ResolvedWithLink<T> | null>;
+
 /**
  * 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).
@@ -181,7 +405,7 @@ interface ActiveOrganizationSnapshot {
     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 rung: OrganizationRung | "switched" | "link" | null;
     readonly error: string | null;
 }
 declare class NoActiveOrganizationError extends Error {
@@ -214,13 +438,145 @@ interface CreateActiveOrganizationOptions {
     readonly held?: HeldOrganizationStore | undefined;
     /** An extra first rung (the web's `?org=` link). Kept only if it is a current membership. */
     readonly linked?: (() => string | null | undefined) | undefined;
+    /**
+     * The link's own organization (`?org=` uuid or address) as a first-class rung: honoured only when
+     * it is a current membership, otherwise the ladder stands and `onDecision` receives the refusal /
+     * offer / announcement for the host to SAY. Supersedes `linked` when both are given.
+     */
+    readonly link?: {
+        readonly source: () => string | URLSearchParams | null | undefined;
+        readonly switchWhenALinkAsks?: (() => boolean | undefined) | undefined;
+        readonly signedInAs?: (() => string | null | undefined) | undefined;
+        readonly messages?: Partial<LinkOrganizationMessages> | undefined;
+        /** A share admits without making a member (asked only after a not-a-member verdict). */
+        readonly admittedByAShare?: ((organizationId: string) => Promise<boolean>) | undefined;
+        readonly onDecision?: ((decision: LinkOrganizationDecision) => void) | undefined;
+    } | undefined;
+    /**
+     * THE ADMIN SEAT: while the host's admin lane is open, the admin's own organization IS the active
+     * one for every reader (`current()`, `ensureOrgId()`); off the lane the person's own is untouched.
+     * Ignored unless the seat is a current membership. The snapshot always keeps the person's own.
+     */
+    readonly adminSeat?: (() => AdminSeatInput | null | undefined) | undefined;
+    /** Marked resolved whenever the ladder settles (organization or none). */
+    readonly bootstrapGate?: OrganizationBootstrapGate | undefined;
+    /** Minimum gap between ladder re-runs caused by a not-a-member refusal. Default 30 s. */
+    readonly refusalRecheckGapMs?: number | undefined;
     /** Load as soon as it is created (default true). */
     readonly autoLoad?: boolean | undefined;
 }
 /** A held store over a `Storage` (browser `sessionStorage` = per tab), identity-keyed. */
-declare function storageHeldOrganization(storage: Pick<Storage, "getItem" | "setItem" | "removeItem">, key?: string): HeldOrganizationStore;
+declare function storageHeldOrganization(storage: Pick<Storage, "getItem" | "setItem" | "removeItem">, key?: string): HeldOrganizationStore & {
+    read(userId: string): string | null;
+};
 /** Held in memory: the running app's own choice (desktop, scripts, tests). */
 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 AdminSeat, type AdminSeatInput, type CreateActiveOrganizationOptions, type HeldOrganizationStore, LINK_ORGANIZATION_QUERY_KEY, type LadderInput, type LinkOrganizationDecision, type LinkOrganizationDecisionInput, type LinkOrganizationMembership, type LinkOrganizationMessages, type LinkOrganizationParam, MEMBERSHIPS_URL, type MembershipReadClient, NOT_A_MEMBER_RECHECK_GAP_MS, NoActiveOrganizationError, NotAMemberError, type NotAMemberRefusalNotice, ORGANIZATION_CONTEXT_REQUIRED_CODE, ORGANIZATION_ENTITY_TYPE, ORGANIZATION_REQUIRED_CODE, ORGANIZATION_REQUIRED_WIRE_CODE, ORGANIZATION_RESOLUTION_TIMEOUT_MS, type OrganizationBootstrapGate, type OrganizationHoldDetails, type OrganizationHoldSetOn, type OrganizationMembership, type OrganizationMembershipSummary, type OrganizationRefusal, type OrganizationRequiredEnvelope, OrganizationRequiredServerError, type OrganizationRequiredWireMembership, type OrganizationRung, type OrganizationsDb, type ParentOrganization, type ResolveWithLinkInput, type ResolvedOrganization, type ResolvedWithLink, adminSeatReplacesUserContext, classifyLinkOrganizationValue, classifyOrganizationRefusal, createActiveOrganization, createNotAMemberRefusalNotice, createOrganizationBootstrapGate, decideLinkOrganization, extractOrganizationHoldMemberships, isNotAMemberRefusal, isOrganizationRequiredEnvelope, isOrganizationRequiredError, isOrganizationRequiredServerError, linkOrganizationMalformedMessage, linkOrganizationNotAMemberMessage, linkOrganizationOfferMessage, linkOrganizationSwitchAnnouncement, memoryHeldOrganization, oldestMembership, orderOrganizations, organizationMatches, organizationRequired, organizationRequiredEnvelope, organizationRequiredResponse, readAccountOrganizationChoices, readCallerMemberships, readLinkOrganizationParam, readMemberships, readOrganizationFavourites, resolveActiveOrganization, resolveActiveOrganizationLazily, resolveAdminSeat, resolveChildOrganizationId, resolveOrganizationWithLink, setOrganizationFavourite, storageHeldOrganization, toAccountOrganizationChoices, writeLastActiveOrganization, writeStartupOrganization };