@ai-matrx/auth 0.0.0 → 0.1.1

package/dist/cookies.d.cts

@@ -0,0 +1,109 @@
+export { A as AuthCookie, a as AuthCookieOptions, b as AuthCookieValue, C as CreateAuthCookieArgs, D as DEFAULT_AUTH_COOKIE_NAME, R as ReconciledAuthCookies, c as createAuthCookie, p as parseCookieHeader } from './auth-cookie-DWx6Q3xo.cjs';
+
+/**
+ * THE ACTIVE-ORGANIZATION COOKIE — one browser-stored "which organization am I
+ * acting in" shared by EVERY Matrx web surface on the same apex.
+ *
+ * WHY (2026-09-08, the Workflow Studio `organization_not_selected` incident):
+ * the main app (www.aimatrx.com) remembered the last active organization in
+ * its own IndexedDB/localStorage cache; Workflow Studio (workflows.aimatrx.com)
+ * remembered its own choice under `matrx_studio_org`; the admin dashboard
+ * under `matrx_dashboard_org`. Three origins, three memories, and a person who
+ * had been working in one organization for weeks opened Studio and was
+ * refused on every request until they picked again — a choice they had
+ * already made. Browser storage is per-origin; a cookie issued at the apex
+ * (`Domain=.aimatrx.com`) is the ONE browser-stored value every subdomain can
+ * read, exactly how the platform already shares its login (see
+ * `auth-cookie.ts`). Cookies also ignore ports, so localhost:3000 and
+ * localhost:3101 share it in development.
+ *
+ * WHAT IT IS, AND IS NOT:
+ *   - It is the FIRST rung of the canonical resolution order (stored selection
+ *     → sole membership → make the user pick; a saved default is display-only;
+ *     ruling: common-docs/projects/no-db-assigned-org/PLAN.md row EX-T05). A
+ *     consumer still validates the stored id against live membership and
+ *     drops it when the membership is gone — this module stores, it never
+ *     decides.
+ *   - It is IDENTITY-KEYED: the value carries the user id it was written for,
+ *     and `read(userId)` answers null for anybody else. A second person
+ *     signing in on the same browser must never inherit the first person's
+ *     workspace (the same rule the sync engine applies to every persisted
+ *     slice). Sign-out calls `clear()` on top of that.
+ *   - It is NOT a security boundary. The server admits a request only when
+ *     the `X-Organization-Id` it carries is a verified membership of the
+ *     bearer; this cookie only remembers which of those the person chose.
+ *   - It is NOT httpOnly — hosts read and write it from the browser. Nothing
+ *     secret is in it.
+ *
+ * The Domain attribute is set ONLY on a real apex host (the same rule and the
+ * same reason as the auth cookie: a browser silently rejects a Set-Cookie
+ * whose Domain does not cover the current host). Studio runs on TWO apexes
+ * (workflows.aimatrx.com and studio.app.matrxserver.com), so this takes a
+ * list; the first apex that covers the host wins.
+ */
+declare const DEFAULT_ACTIVE_ORG_COOKIE_NAME = "matrx-active-org";
+/** One year — the same horizon the platform's other preference cookies use. */
+declare const DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE: number;
+interface ActiveOrgCookieOptions {
+    name: string;
+    domain?: string;
+}
+/** The stored fact: WHO chose WHICH organization. */
+interface ActiveOrgSelection {
+    userId: string;
+    organizationId: string;
+}
+interface CreateActiveOrgCookieArgs {
+    /**
+     * The apex domains one selection must span, e.g.
+     * `["aimatrx.com", "matrxserver.com"]`. Order matters only when two apexes
+     * could cover one host, which they never should.
+     */
+    apexDomains: readonly string[];
+    /** Override only for a second, unrelated deployment — never per-app. */
+    cookieName?: string;
+    /** Lifetime in seconds. Defaults to one year. */
+    maxAgeSeconds?: number;
+}
+interface ActiveOrgCookie {
+    cookieName: string;
+    /**
+     * Cookie options for the host serving the current request.
+     * @param host `Host` header or `window.location.hostname` (port tolerated).
+     */
+    optionsForHost(host: string | null | undefined): ActiveOrgCookieOptions;
+    /**
+     * The organization `userId` last chose, from a raw `Cookie` request header
+     * (SSR) — or null when nothing is stored, the value is malformed, or it
+     * belongs to a different person.
+     */
+    readFromCookieHeader(header: string | null | undefined, userId: string | null | undefined): string | null;
+    /** Browser read of the same fact from `document.cookie`. SSR-safe (null). */
+    read(userId: string | null | undefined): string | null;
+    /**
+     * Record `userId`'s choice in the browser at the scope `optionsForHost`
+     * decides for this host. A previous host-only copy is expired first so the
+     * jar never holds two same-name cookies at two scopes (whichever the
+     * browser sent first would win — see `auth-cookie.ts` on split jars).
+     */
+    write(selection: ActiveOrgSelection): void;
+    /**
+     * Forget the selection in the browser — at EVERY scope this host could have
+     * issued it (domain-wide and host-only), so sign-out cannot leave a copy
+     * behind for the next person.
+     */
+    clear(): void;
+    /**
+     * A `Set-Cookie` header value recording `selection` for `host` (null →
+     * an expiring cookie). For servers that want to write it; browsers use
+     * `write`.
+     */
+    serialize(host: string | null | undefined, selection: ActiveOrgSelection | null, secure?: boolean): string;
+}
+/** `<userId>:<organizationId>` — two UUIDs, one separator. */
+declare function encodeActiveOrgSelection(selection: ActiveOrgSelection): string;
+/** Inverse of {@link encodeActiveOrgSelection}. Null for anything malformed. */
+declare function decodeActiveOrgSelection(raw: string | null | undefined): ActiveOrgSelection | null;
+declare function createActiveOrgCookie(args: CreateActiveOrgCookieArgs): ActiveOrgCookie;
+
+export { type ActiveOrgCookie, type ActiveOrgCookieOptions, type ActiveOrgSelection, type CreateActiveOrgCookieArgs, DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE, DEFAULT_ACTIVE_ORG_COOKIE_NAME, createActiveOrgCookie, decodeActiveOrgSelection, encodeActiveOrgSelection };

package/dist/cookies.d.ts

@@ -0,0 +1,109 @@
+export { A as AuthCookie, a as AuthCookieOptions, b as AuthCookieValue, C as CreateAuthCookieArgs, D as DEFAULT_AUTH_COOKIE_NAME, R as ReconciledAuthCookies, c as createAuthCookie, p as parseCookieHeader } from './auth-cookie-DWx6Q3xo.js';
+
+/**
+ * THE ACTIVE-ORGANIZATION COOKIE — one browser-stored "which organization am I
+ * acting in" shared by EVERY Matrx web surface on the same apex.
+ *
+ * WHY (2026-09-08, the Workflow Studio `organization_not_selected` incident):
+ * the main app (www.aimatrx.com) remembered the last active organization in
+ * its own IndexedDB/localStorage cache; Workflow Studio (workflows.aimatrx.com)
+ * remembered its own choice under `matrx_studio_org`; the admin dashboard
+ * under `matrx_dashboard_org`. Three origins, three memories, and a person who
+ * had been working in one organization for weeks opened Studio and was
+ * refused on every request until they picked again — a choice they had
+ * already made. Browser storage is per-origin; a cookie issued at the apex
+ * (`Domain=.aimatrx.com`) is the ONE browser-stored value every subdomain can
+ * read, exactly how the platform already shares its login (see
+ * `auth-cookie.ts`). Cookies also ignore ports, so localhost:3000 and
+ * localhost:3101 share it in development.
+ *
+ * WHAT IT IS, AND IS NOT:
+ *   - It is the FIRST rung of the canonical resolution order (stored selection
+ *     → sole membership → make the user pick; a saved default is display-only;
+ *     ruling: common-docs/projects/no-db-assigned-org/PLAN.md row EX-T05). A
+ *     consumer still validates the stored id against live membership and
+ *     drops it when the membership is gone — this module stores, it never
+ *     decides.
+ *   - It is IDENTITY-KEYED: the value carries the user id it was written for,
+ *     and `read(userId)` answers null for anybody else. A second person
+ *     signing in on the same browser must never inherit the first person's
+ *     workspace (the same rule the sync engine applies to every persisted
+ *     slice). Sign-out calls `clear()` on top of that.
+ *   - It is NOT a security boundary. The server admits a request only when
+ *     the `X-Organization-Id` it carries is a verified membership of the
+ *     bearer; this cookie only remembers which of those the person chose.
+ *   - It is NOT httpOnly — hosts read and write it from the browser. Nothing
+ *     secret is in it.
+ *
+ * The Domain attribute is set ONLY on a real apex host (the same rule and the
+ * same reason as the auth cookie: a browser silently rejects a Set-Cookie
+ * whose Domain does not cover the current host). Studio runs on TWO apexes
+ * (workflows.aimatrx.com and studio.app.matrxserver.com), so this takes a
+ * list; the first apex that covers the host wins.
+ */
+declare const DEFAULT_ACTIVE_ORG_COOKIE_NAME = "matrx-active-org";
+/** One year — the same horizon the platform's other preference cookies use. */
+declare const DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE: number;
+interface ActiveOrgCookieOptions {
+    name: string;
+    domain?: string;
+}
+/** The stored fact: WHO chose WHICH organization. */
+interface ActiveOrgSelection {
+    userId: string;
+    organizationId: string;
+}
+interface CreateActiveOrgCookieArgs {
+    /**
+     * The apex domains one selection must span, e.g.
+     * `["aimatrx.com", "matrxserver.com"]`. Order matters only when two apexes
+     * could cover one host, which they never should.
+     */
+    apexDomains: readonly string[];
+    /** Override only for a second, unrelated deployment — never per-app. */
+    cookieName?: string;
+    /** Lifetime in seconds. Defaults to one year. */
+    maxAgeSeconds?: number;
+}
+interface ActiveOrgCookie {
+    cookieName: string;
+    /**
+     * Cookie options for the host serving the current request.
+     * @param host `Host` header or `window.location.hostname` (port tolerated).
+     */
+    optionsForHost(host: string | null | undefined): ActiveOrgCookieOptions;
+    /**
+     * The organization `userId` last chose, from a raw `Cookie` request header
+     * (SSR) — or null when nothing is stored, the value is malformed, or it
+     * belongs to a different person.
+     */
+    readFromCookieHeader(header: string | null | undefined, userId: string | null | undefined): string | null;
+    /** Browser read of the same fact from `document.cookie`. SSR-safe (null). */
+    read(userId: string | null | undefined): string | null;
+    /**
+     * Record `userId`'s choice in the browser at the scope `optionsForHost`
+     * decides for this host. A previous host-only copy is expired first so the
+     * jar never holds two same-name cookies at two scopes (whichever the
+     * browser sent first would win — see `auth-cookie.ts` on split jars).
+     */
+    write(selection: ActiveOrgSelection): void;
+    /**
+     * Forget the selection in the browser — at EVERY scope this host could have
+     * issued it (domain-wide and host-only), so sign-out cannot leave a copy
+     * behind for the next person.
+     */
+    clear(): void;
+    /**
+     * A `Set-Cookie` header value recording `selection` for `host` (null →
+     * an expiring cookie). For servers that want to write it; browsers use
+     * `write`.
+     */
+    serialize(host: string | null | undefined, selection: ActiveOrgSelection | null, secure?: boolean): string;
+}
+/** `<userId>:<organizationId>` — two UUIDs, one separator. */
+declare function encodeActiveOrgSelection(selection: ActiveOrgSelection): string;
+/** Inverse of {@link encodeActiveOrgSelection}. Null for anything malformed. */
+declare function decodeActiveOrgSelection(raw: string | null | undefined): ActiveOrgSelection | null;
+declare function createActiveOrgCookie(args: CreateActiveOrgCookieArgs): ActiveOrgCookie;
+
+export { type ActiveOrgCookie, type ActiveOrgCookieOptions, type ActiveOrgSelection, type CreateActiveOrgCookieArgs, DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE, DEFAULT_ACTIVE_ORG_COOKIE_NAME, createActiveOrgCookie, decodeActiveOrgSelection, encodeActiveOrgSelection };

package/dist/cookies.js

@@ -0,0 +1,210 @@
+// src/cookies/auth-cookie.ts
+var DEFAULT_AUTH_COOKIE_NAME = "sb-matrx-auth";
+function parseCookieHeader(header) {
+  if (!header) return [];
+  const out = [];
+  for (const pair of header.split(";")) {
+    const eq = pair.indexOf("=");
+    const name = (eq === -1 ? pair : pair.slice(0, eq)).trim();
+    if (!name) continue;
+    const raw = eq === -1 ? "" : pair.slice(eq + 1).trim();
+    let value = raw;
+    try {
+      value = decodeURIComponent(raw);
+    } catch {
+    }
+    out.push({ name, value });
+  }
+  return out;
+}
+function belongsToStorageKey(name, storageKey) {
+  if (name === storageKey) return true;
+  if (!name.startsWith(`${storageKey}.`)) return false;
+  return /^(0|[1-9][0-9]*)$/.test(name.slice(storageKey.length + 1));
+}
+function renamedCookie(cookie, from, to) {
+  if (cookie.name === from) return { ...cookie, name: to };
+  const prefix = `${from}.`;
+  if (!cookie.name.startsWith(prefix)) return null;
+  const chunk = cookie.name.slice(prefix.length);
+  if (!/^(0|[1-9][0-9]*)$/.test(chunk)) return null;
+  return { ...cookie, name: `${to}.${chunk}` };
+}
+function createAuthCookie(args) {
+  const cookieName = args.cookieName ?? DEFAULT_AUTH_COOKIE_NAME;
+  const legacyCookieName = args.legacyCookieName;
+  const apex = args.apexDomain.toLowerCase();
+  const optionsForHost = (host) => {
+    const normalized = (host ?? "").toLowerCase();
+    const hostname = normalized.startsWith("[") ? normalized.slice(1, normalized.indexOf("]")) : normalized === "::1" ? normalized : normalized.split(":")[0] ?? "";
+    const loopback = hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "::1" || /^127(?:\.(?:0|[1-9]\d{0,2})){3}$/.test(hostname) && hostname.split(".").every((part) => Number(part) <= 255);
+    const secure = !loopback;
+    const onApex = hostname === apex || hostname.endsWith(`.${apex}`);
+    return onApex ? { name: cookieName, domain: `.${apex}`, secure } : { name: cookieName, secure };
+  };
+  const isCurrentCookie = (name) => belongsToStorageKey(name, cookieName);
+  const isAuthCookie = (name) => isCurrentCookie(name) || legacyCookieName !== void 0 && (name === legacyCookieName || name.startsWith(`${legacyCookieName}.`));
+  const reconcile = (cookies) => {
+    const seen = /* @__PURE__ */ new Map();
+    const out = [];
+    const shadowed = /* @__PURE__ */ new Set();
+    for (const cookie of cookies) {
+      const at = seen.get(cookie.name);
+      if (at === void 0) {
+        seen.set(cookie.name, out.length);
+        out.push({ name: cookie.name, value: cookie.value });
+        continue;
+      }
+      if (!isAuthCookie(cookie.name)) continue;
+      shadowed.add(cookie.name);
+      const held = out[at];
+      if (held !== void 0 && held.value.length === 0) {
+        out[at] = { name: cookie.name, value: cookie.value };
+      }
+    }
+    const ambiguous = /* @__PURE__ */ new Set();
+    const ambiguousKeys = [];
+    const byName = new Map(out.map((cookie) => [cookie.name, cookie]));
+    const storageKeys = [cookieName, ...legacyCookieName ? [legacyCookieName] : []];
+    for (const storageKey of storageKeys) {
+      const unchunked = byName.get(storageKey);
+      const firstChunk = byName.get(`${storageKey}.0`);
+      if (!unchunked?.value || !firstChunk?.value) continue;
+      ambiguousKeys.push(storageKey);
+      for (const { name } of out) {
+        if (belongsToStorageKey(name, storageKey)) ambiguous.add(name);
+      }
+    }
+    const resolved = ambiguous.size === 0 ? out : out.filter(({ name }) => !ambiguous.has(name));
+    const shadowedNames = [...shadowed];
+    const ambiguousNames = [...ambiguous];
+    return {
+      cookies: resolved,
+      shadowedNames,
+      ambiguousNames,
+      ambiguousKeys,
+      split: shadowedNames.length > 0 || ambiguousNames.length > 0
+    };
+  };
+  return {
+    cookieName,
+    legacyCookieName,
+    optionsForHost,
+    reconcile,
+    browserOptions: () => optionsForHost(
+      typeof window !== "undefined" ? window.location.hostname : null
+    ),
+    isCurrentCookie,
+    migrateLegacyCookies: (cookies) => {
+      if (!legacyCookieName) return [];
+      if (cookies.some(({ name }) => isCurrentCookie(name))) return [];
+      return cookies.flatMap((cookie) => {
+        const renamed = renamedCookie(cookie, legacyCookieName, cookieName);
+        return renamed ? [renamed] : [];
+      });
+    }
+  };
+}
+
+// src/cookies/active-org-cookie.ts
+import { isUuidShape } from "@ai-matrx/kit/uuid";
+var DEFAULT_ACTIVE_ORG_COOKIE_NAME = "matrx-active-org";
+var DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+function encodeActiveOrgSelection(selection) {
+  if (!isUuidShape(selection.userId) || !isUuidShape(selection.organizationId)) {
+    throw new Error(
+      "encodeActiveOrgSelection: userId and organizationId must both be UUIDs."
+    );
+  }
+  return `${selection.userId.toLowerCase()}:${selection.organizationId.toLowerCase()}`;
+}
+function decodeActiveOrgSelection(raw) {
+  if (!raw) return null;
+  const parts = raw.split(":");
+  if (parts.length !== 2) return null;
+  const [userId, organizationId] = parts;
+  if (!isUuidShape(userId) || !isUuidShape(organizationId)) return null;
+  return {
+    userId: userId.toLowerCase(),
+    organizationId: organizationId.toLowerCase()
+  };
+}
+function selectionFor(cookies, cookieName, userId) {
+  if (!userId) return null;
+  const wanted = userId.toLowerCase();
+  for (const cookie of cookies) {
+    if (cookie.name !== cookieName) continue;
+    const decoded = decodeActiveOrgSelection(cookie.value);
+    if (decoded && decoded.userId === wanted) return decoded.organizationId;
+  }
+  return null;
+}
+function attributes(options, maxAge, secure) {
+  const parts = [`Path=/`, `Max-Age=${maxAge}`, `SameSite=Lax`];
+  if (options.domain) parts.push(`Domain=${options.domain}`);
+  if (secure) parts.push("Secure");
+  return parts.join("; ");
+}
+function hasDocument() {
+  return typeof document !== "undefined" && typeof document.cookie === "string";
+}
+function createActiveOrgCookie(args) {
+  const cookieName = args.cookieName ?? DEFAULT_ACTIVE_ORG_COOKIE_NAME;
+  const maxAge = args.maxAgeSeconds ?? DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE;
+  const apexes = args.apexDomains.map((apex) => apex.toLowerCase());
+  const optionsForHost = (host) => {
+    const hostname = (host ?? "").split(":")[0]?.toLowerCase() ?? "";
+    const apex = apexes.find(
+      (candidate) => hostname === candidate || hostname.endsWith(`.${candidate}`)
+    );
+    return apex ? { name: cookieName, domain: `.${apex}` } : { name: cookieName };
+  };
+  const serialize = (host, selection, secure = false) => {
+    const options = optionsForHost(host);
+    if (!selection) {
+      return `${cookieName}=; ${attributes(options, 0, secure)}`;
+    }
+    return `${cookieName}=${encodeActiveOrgSelection(selection)}; ${attributes(options, maxAge, secure)}`;
+  };
+  const browserHost = () => typeof window !== "undefined" ? window.location.hostname : null;
+  const browserSecure = () => typeof window !== "undefined" && window.location.protocol === "https:";
+  const expireHostOnly = (secure) => {
+    document.cookie = `${cookieName}=; ${attributes({ name: cookieName }, 0, secure)}`;
+  };
+  return {
+    cookieName,
+    optionsForHost,
+    serialize,
+    readFromCookieHeader: (header, userId) => selectionFor(parseCookieHeader(header), cookieName, userId),
+    read: (userId) => {
+      if (!hasDocument()) return null;
+      return selectionFor(parseCookieHeader(document.cookie), cookieName, userId);
+    },
+    write: (selection) => {
+      if (!hasDocument()) return;
+      const host = browserHost();
+      const secure = browserSecure();
+      if (optionsForHost(host).domain) expireHostOnly(secure);
+      document.cookie = serialize(host, selection, secure);
+    },
+    clear: () => {
+      if (!hasDocument()) return;
+      const host = browserHost();
+      const secure = browserSecure();
+      expireHostOnly(secure);
+      if (optionsForHost(host).domain) {
+        document.cookie = serialize(host, null, secure);
+      }
+    }
+  };
+}
+export {
+  DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE,
+  DEFAULT_ACTIVE_ORG_COOKIE_NAME,
+  DEFAULT_AUTH_COOKIE_NAME,
+  createActiveOrgCookie,
+  createAuthCookie,
+  decodeActiveOrgSelection,
+  encodeActiveOrgSelection,
+  parseCookieHeader
+};

package/dist/credentials.cjs

@@ -0,0 +1,68 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/credentials.ts
+var credentials_exports = {};
+__export(credentials_exports, {
+  API_KEY_PREFIX: () => API_KEY_PREFIX,
+  MATRX_HEADERS: () => MATRX_HEADERS,
+  credentialToHeaders: () => credentialToHeaders,
+  toCredentialsPort: () => toCredentialsPort
+});
+module.exports = __toCommonJS(credentials_exports);
+var MATRX_HEADERS = {
+  authorization: "Authorization",
+  fingerprint: "X-Fingerprint-ID",
+  organization: "X-Organization-Id",
+  actingUser: "X-Matrx-User-Id",
+  requestId: "X-Request-Id"
+};
+var API_KEY_PREFIX = "mx_";
+function credentialToHeaders(credential) {
+  if (credential === null) return {};
+  switch (credential.kind) {
+    case "user":
+      return { [MATRX_HEADERS.authorization]: `Bearer ${credential.accessToken}` };
+    case "guest":
+      return { [MATRX_HEADERS.fingerprint]: credential.fingerprintId };
+    case "scoped":
+      return { [MATRX_HEADERS.authorization]: `Bearer ${credential.token}` };
+    case "service": {
+      const header = credential.secretHeader ?? MATRX_HEADERS.authorization;
+      const headers = header.toLowerCase() === "authorization" ? { [MATRX_HEADERS.authorization]: `Bearer ${credential.secret}` } : { [header]: credential.secret };
+      if (credential.actingUserId) headers[MATRX_HEADERS.actingUser] = credential.actingUserId;
+      return headers;
+    }
+    case "api_key": {
+      if (!credential.apiKey.startsWith(API_KEY_PREFIX)) {
+        throw new Error(
+          `credentialToHeaders: an api_key credential must start with "${API_KEY_PREFIX}" (AI Matrx API keys look like mx_live_...)`
+        );
+      }
+      return { [MATRX_HEADERS.authorization]: `Bearer ${credential.apiKey}` };
+    }
+  }
+}
+function toCredentialsPort(setting) {
+  if (setting === void 0 || setting === null) return { get: async () => null };
+  if (typeof setting === "function") return { get: async () => setting() };
+  if ("get" in setting && typeof setting.get === "function") return setting;
+  const fixed = setting;
+  return { get: async () => fixed };
+}

package/dist/credentials.d.cts

@@ -0,0 +1,82 @@
+/**
+ * The credentials port — the ONE credential→header mapping for every client
+ * of every AI Matrx server (package lines v3 §3.4; API-key lane C16).
+ *
+ * Five credential kinds, one mapping, in exactly one place. The kind names are
+ * the contract's own `x-matrx-auth` tier names, so a generated operation's
+ * tier and the credential that satisfies it read the same in every language
+ * (TypeScript here; the Python `matrx-api` and future Swift/Kotlin clients
+ * share these header names and shapes — see {@link MATRX_HEADERS}):
+ *
+ * - `user`    — a signed-in person: `Authorization: Bearer <Supabase JWT>`.
+ * - `guest`   — a fingerprint: `X-Fingerprint-ID: <id>`.
+ * - `api_key` — an AI Matrx API key: `Authorization: Bearer mx_live_...`.
+ *   The server's ONE AuthMiddleware disambiguates by shape (`mx_` prefix vs
+ *   three-dot JWT), so `user` and `api_key` ride the same header.
+ * - `service` — one of our servers calling another: the server secret as
+ *   `Authorization: Bearer <secret>` (or in `secretHeader`), plus the acting
+ *   person in `X-Matrx-User-Id` when there is one
+ *   (`matrx_connect.service_auth`).
+ * - `scoped`  — a short-lived capability token (sandbox, desktop app, broker
+ *   client): `Authorization: Bearer <token>` (`matrx_connect.scoped_tokens`).
+ *   Short-lived means the PORT re-reads it per call: hand a `CredentialsPort`
+ *   whose `get()` returns the current token.
+ *
+ * No polling, no readiness loop: readiness is the port's promise.
+ */
+/** Header names every AI Matrx client and server shares (TS, Python, native). */
+declare const MATRX_HEADERS: {
+    readonly authorization: "Authorization";
+    readonly fingerprint: "X-Fingerprint-ID";
+    readonly organization: "X-Organization-Id";
+    readonly actingUser: "X-Matrx-User-Id";
+    readonly requestId: "X-Request-Id";
+};
+/** The credential kinds — identical to the contract's `x-matrx-auth` tiers that carry a credential. */
+type MatrxCredentialKind = MatrxCredential["kind"];
+/** A credential a Matrx client can present. */
+type MatrxCredential = {
+    kind: "user";
+    accessToken: string;
+} | {
+    kind: "guest";
+    fingerprintId: string;
+} | {
+    kind: "api_key";
+    apiKey: string;
+} | {
+    kind: "service";
+    /** The server secret (an existing env value, e.g. MATRX_AIDREAM_SERVICE_TOKEN). */
+    secret: string;
+    /** The person the call acts for, when there is one (`X-Matrx-User-Id`). */
+    actingUserId?: string;
+    /** Where the secret rides. Default `Authorization` (as a Bearer value). */
+    secretHeader?: string;
+} | {
+    kind: "scoped";
+    token: string;
+};
+/**
+ * The async source of the current credential. `get()` resolves when the host
+ * knows its auth state (null = anonymous); `onChange` lets transports refresh
+ * cached headers when the credential rotates.
+ */
+interface CredentialsPort {
+    get(): Promise<MatrxCredential | null>;
+    onChange?(cb: () => void): () => void;
+}
+/** Prefix that marks a bearer token as an AI Matrx API key, never a JWT. */
+declare const API_KEY_PREFIX = "mx_";
+/**
+ * Map a credential to the exact request headers the AI Matrx platform expects.
+ * This is the single place that knowledge lives — transports spread the result
+ * into their request headers and add `X-Organization-Id` from the org context
+ * binding separately.
+ */
+declare function credentialToHeaders(credential: MatrxCredential | null): Record<string, string>;
+/** What `createApi({ credentials })` accepts: a fixed credential, a getter, or a port. */
+type CredentialsSetting = MatrxCredential | null | (() => MatrxCredential | null | Promise<MatrxCredential | null>) | CredentialsPort;
+/** Normalize the ONE credentials setting into a `CredentialsPort`. */
+declare function toCredentialsPort(setting: CredentialsSetting | undefined): CredentialsPort;
+
+export { API_KEY_PREFIX, type CredentialsPort, type CredentialsSetting, MATRX_HEADERS, type MatrxCredential, type MatrxCredentialKind, credentialToHeaders, toCredentialsPort };

package/dist/credentials.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The credentials port — the ONE credential→header mapping for every client
+ * of every AI Matrx server (package lines v3 §3.4; API-key lane C16).
+ *
+ * Five credential kinds, one mapping, in exactly one place. The kind names are
+ * the contract's own `x-matrx-auth` tier names, so a generated operation's
+ * tier and the credential that satisfies it read the same in every language
+ * (TypeScript here; the Python `matrx-api` and future Swift/Kotlin clients
+ * share these header names and shapes — see {@link MATRX_HEADERS}):
+ *
+ * - `user`    — a signed-in person: `Authorization: Bearer <Supabase JWT>`.
+ * - `guest`   — a fingerprint: `X-Fingerprint-ID: <id>`.
+ * - `api_key` — an AI Matrx API key: `Authorization: Bearer mx_live_...`.
+ *   The server's ONE AuthMiddleware disambiguates by shape (`mx_` prefix vs
+ *   three-dot JWT), so `user` and `api_key` ride the same header.
+ * - `service` — one of our servers calling another: the server secret as
+ *   `Authorization: Bearer <secret>` (or in `secretHeader`), plus the acting
+ *   person in `X-Matrx-User-Id` when there is one
+ *   (`matrx_connect.service_auth`).
+ * - `scoped`  — a short-lived capability token (sandbox, desktop app, broker
+ *   client): `Authorization: Bearer <token>` (`matrx_connect.scoped_tokens`).
+ *   Short-lived means the PORT re-reads it per call: hand a `CredentialsPort`
+ *   whose `get()` returns the current token.
+ *
+ * No polling, no readiness loop: readiness is the port's promise.
+ */
+/** Header names every AI Matrx client and server shares (TS, Python, native). */
+declare const MATRX_HEADERS: {
+    readonly authorization: "Authorization";
+    readonly fingerprint: "X-Fingerprint-ID";
+    readonly organization: "X-Organization-Id";
+    readonly actingUser: "X-Matrx-User-Id";
+    readonly requestId: "X-Request-Id";
+};
+/** The credential kinds — identical to the contract's `x-matrx-auth` tiers that carry a credential. */
+type MatrxCredentialKind = MatrxCredential["kind"];
+/** A credential a Matrx client can present. */
+type MatrxCredential = {
+    kind: "user";
+    accessToken: string;
+} | {
+    kind: "guest";
+    fingerprintId: string;
+} | {
+    kind: "api_key";
+    apiKey: string;
+} | {
+    kind: "service";
+    /** The server secret (an existing env value, e.g. MATRX_AIDREAM_SERVICE_TOKEN). */
+    secret: string;
+    /** The person the call acts for, when there is one (`X-Matrx-User-Id`). */
+    actingUserId?: string;
+    /** Where the secret rides. Default `Authorization` (as a Bearer value). */
+    secretHeader?: string;
+} | {
+    kind: "scoped";
+    token: string;
+};
+/**
+ * The async source of the current credential. `get()` resolves when the host
+ * knows its auth state (null = anonymous); `onChange` lets transports refresh
+ * cached headers when the credential rotates.
+ */
+interface CredentialsPort {
+    get(): Promise<MatrxCredential | null>;
+    onChange?(cb: () => void): () => void;
+}
+/** Prefix that marks a bearer token as an AI Matrx API key, never a JWT. */
+declare const API_KEY_PREFIX = "mx_";
+/**
+ * Map a credential to the exact request headers the AI Matrx platform expects.
+ * This is the single place that knowledge lives — transports spread the result
+ * into their request headers and add `X-Organization-Id` from the org context
+ * binding separately.
+ */
+declare function credentialToHeaders(credential: MatrxCredential | null): Record<string, string>;
+/** What `createApi({ credentials })` accepts: a fixed credential, a getter, or a port. */
+type CredentialsSetting = MatrxCredential | null | (() => MatrxCredential | null | Promise<MatrxCredential | null>) | CredentialsPort;
+/** Normalize the ONE credentials setting into a `CredentialsPort`. */
+declare function toCredentialsPort(setting: CredentialsSetting | undefined): CredentialsPort;
+
+export { API_KEY_PREFIX, type CredentialsPort, type CredentialsSetting, MATRX_HEADERS, type MatrxCredential, type MatrxCredentialKind, credentialToHeaders, toCredentialsPort };