@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/src/cli/ui.ts

@@ -0,0 +1,266 @@
+/**
+ * `asturiu-v0-tenant ui` (ADR-074 §7): a page on this machine for the tasks that touch the repository's files, served
+ * by the command line's own process.
+ *
+ * - Loopback only: 127.0.0.1 on a free port. The address is printed once with a one-time token; the token becomes an
+ *   HttpOnly, SameSite=Strict cookie and the address loses it. Every request must carry the Host of that address and
+ *   every write its Origin. There are no CORS headers.
+ * - The key stays in this process. The page never receives it and never signs.
+ * - Each button runs `run()` (the same function the terminal does) with `--json`, from a closed list of actions, and
+ *   shows the answer beside the line to type instead.
+ * - Text from the Engine is data: the page writes it as text, never as markup. Nothing is fetched from elsewhere.
+ */
+import { spawn } from "node:child_process";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import path from "node:path";
+import { run } from "./cli.js";
+import { type Ctx, EXIT, Fail, emit, str } from "./context.js";
+import { UI_PAGE } from "./ui-page.js";
+
+/** One action the page may ask for: the arguments it runs with, and the line the person would type instead. */
+export interface UiAction {
+  argv: string[];
+  shown: string[];
+  /** Whether it writes to the repository or sends to the Engine: the page asks first. */
+  writes: boolean;
+}
+
+const PARTS = ["definitions", "branding", "portal"];
+const KINDS = ["defect", "limitation", "question"];
+
+/**
+ * The closed list of what the page may run. Nothing outside it, and no argument the page sends goes on unchecked:
+ * no keys, no people, no roles, no Customers and no tickets of theirs (§7).
+ */
+export function uiAction(root: string, name: string, p: Record<string, unknown> = {}): UiAction | null {
+  const same = (argv: string[], writes = false): UiAction => ({ argv, shown: argv, writes });
+  switch (name) {
+    case "status":
+    case "doctor":
+    case "engine":
+    case "definitions":
+    case "branding":
+    case "changesets":
+      return same([name]);
+    case "apply": {
+      const parts = Array.isArray(p.parts) ? p.parts.filter((x): x is string => typeof x === "string" && PARTS.includes(x)) : [];
+      return same(["apply", ...new Set(parts)], true);
+    }
+    case "pull":
+      return { argv: ["pull", "--dry-run"], shown: ["pull", "--dry-run"], writes: false };
+    case "pull-write":
+      return { argv: ["pull", "--write"], shown: ["pull", "--write"], writes: true };
+    case "changesets-pull":
+      return same(["changesets", "pull"], true);
+    case "changeset": {
+      const n = Number(p.number);
+      return Number.isInteger(n) && n > 0 && n < 10_000 ? same(["changeset", String(n)]) : null;
+    }
+    case "feedback-queue":
+      return same(["feedback", "queue"]);
+    case "feedback-add": {
+      const file = typeof p.file === "string" ? p.file.trim() : "";
+      const full = path.resolve(root, file);
+      // A file of this repository only: nothing outside it, nothing that is not a regular file.
+      if (!file || !(full === root || full.startsWith(root + path.sep)) || !existsSync(full) || !statSync(full).isFile() || !/\.(md|json)$/i.test(full)) return null;
+      const argv = ["feedback", "add", path.relative(root, full)];
+      if (typeof p.kind === "string" && KINDS.includes(p.kind)) argv.push("--kind", p.kind);
+      if (typeof p.area === "string" && /^[a-z0-9][a-z0-9 ,_-]{0,60}$/i.test(p.area)) argv.push("--area", p.area);
+      return same(argv, true);
+    }
+    case "feedback-drop": {
+      const n = Number(p.number);
+      return Number.isInteger(n) && n > 0 && n < 1000 ? { argv: ["feedback", "drop", String(n), "--yes"], shown: ["feedback", "drop", String(n)], writes: true } : null;
+    }
+    case "feedback-dry-run":
+      return same(["feedback", "send", "--dry-run"]);
+    case "feedback-send":
+      return { argv: ["feedback", "send", "--yes"], shown: ["feedback", "send"], writes: true };
+    default:
+      return null;
+  }
+}
+
+export interface UiRequest {
+  method: string;
+  url: string;
+  headers: Record<string, string | undefined>;
+  body?: string;
+}
+
+export interface UiResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+}
+
+const SAFE_HEADERS = { "cache-control": "no-store", "x-content-type-options": "nosniff", "referrer-policy": "no-referrer", "x-frame-options": "DENY", "cross-origin-resource-policy": "same-origin" };
+
+const equal = (a: string, b: string) => {
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  return x.length === y.length && timingSafeEqual(x, y);
+};
+
+function cookieOf(header: string | undefined, name: string): string | null {
+  for (const part of (header ?? "").split(";")) {
+    const [k, ...v] = part.trim().split("=");
+    if (k === name) return v.join("=");
+  }
+  return null;
+}
+
+/**
+ * The page's request handler, without a socket: what the server runs per request, and what the tests call. `runAction`
+ * runs one action and answers its exit code and its JSON.
+ */
+export function createUiHandler(o: { port: number; token: string; session?: string; command: string; root: string; runAction: (a: UiAction) => Promise<{ exit: number; result: unknown; output: string }> }) {
+  const address = `127.0.0.1:${o.port}`;
+  const origin = `http://${address}`;
+  const cookie = `asturiu_ui_${o.port}`;
+  const session = o.session ?? randomBytes(32).toString("base64url");
+  let token: string | null = o.token;
+  let busy: Promise<unknown> = Promise.resolve();
+
+  const text = (status: number, body: string, extra: Record<string, string> = {}): UiResponse => ({ status, headers: { ...SAFE_HEADERS, "content-type": "text/plain; charset=utf-8", ...extra }, body });
+  const json = (status: number, body: unknown): UiResponse => ({ status, headers: { ...SAFE_HEADERS, "content-type": "application/json; charset=utf-8" }, body: JSON.stringify(body) });
+
+  async function handle(req: UiRequest): Promise<UiResponse> {
+    // The address the page was printed with, and no other: a page another site loads in this browser sends another Host.
+    if (req.headers.host !== address) return text(421, "Open the address this command printed.");
+    const url = new URL(req.url, origin);
+    const signedIn = (() => {
+      const c = cookieOf(req.headers.cookie, cookie);
+      return c !== null && equal(c, session);
+    })();
+
+    if (req.method === "GET" && url.pathname === "/") {
+      const offered = url.searchParams.get("token");
+      if (offered !== null) {
+        // The one-time token: it becomes the cookie once, and the address loses it.
+        if (token === null || !equal(offered, token)) return text(403, "This address has been used already. Run the command again for a new one.");
+        token = null;
+        return { status: 303, headers: { ...SAFE_HEADERS, location: "/", "set-cookie": `${cookie}=${session}; HttpOnly; SameSite=Strict; Path=/`, "content-type": "text/plain; charset=utf-8" }, body: "" };
+      }
+      if (!signedIn) return text(403, "Open the address this command printed, with its token.");
+      const nonce = randomBytes(16).toString("base64");
+      return {
+        status: 200,
+        headers: {
+          ...SAFE_HEADERS,
+          "content-type": "text/html; charset=utf-8",
+          "content-security-policy": `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`,
+        },
+        body: UI_PAGE.replaceAll("__NONCE__", nonce).replaceAll("__COMMAND__", escapeHtml(o.command)),
+      };
+    }
+
+    if (url.pathname === "/api/run") {
+      if (req.method !== "POST") return text(405, "POST only.", { allow: "POST" });
+      if (!signedIn) return json(403, { error: "not signed in to this page" });
+      // A write from another origin never reaches here: the browser sends this page's own Origin, and nothing else is let through.
+      if (req.headers.origin !== origin) return json(403, { error: "wrong origin" });
+      if (!/^application\/json\b/.test(req.headers["content-type"] ?? "")) return json(415, { error: "JSON only" });
+      if ((req.body ?? "").length > 16 * 1024) return json(413, { error: "too large" });
+      let body: { action?: unknown; params?: unknown };
+      try {
+        body = JSON.parse(req.body ?? "{}");
+      } catch {
+        return json(400, { error: "not JSON" });
+      }
+      const name = typeof body.action === "string" ? body.action : "";
+      const params = body.params && typeof body.params === "object" ? (body.params as Record<string, unknown>) : {};
+      const action = uiAction(o.root, name, params);
+      if (!action) return json(400, { error: `not an action this page runs: ${name.slice(0, 40)}` });
+      // One at a time: a command reads and writes the repository's files.
+      const done = busy.then(() => o.runAction(action));
+      busy = done.catch(() => undefined);
+      const r = await done;
+      return json(200, { action: name, exit: r.exit, terminal: `${o.command} ${action.shown.map(quote).join(" ")}`, writes: action.writes, result: r.result, ...(r.result === null ? { output: r.output } : {}) });
+    }
+    return text(404, "Nothing here.");
+  }
+
+  return { handle, address, origin, session };
+}
+
+const quote = (s: string) => (/^[A-Za-z0-9_:./=@-]+$/.test(s) ? s : JSON.stringify(s));
+
+export function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}
+
+/** Runs one action in this process, as the terminal would with `--json`, and answers its exit code and JSON. */
+export function actionRunner(ctx: Ctx) {
+  return async (a: UiAction) => {
+    let output = "";
+    const sink = { write: (s: string) => ((output += s), true), isTTY: false };
+    const exit = await run([...a.argv, "--json"], { root: ctx.root, env: ctx.env, config: ctx.config, fetch: ctx.fetch, invokedAs: ctx.cmd, io: { stdout: sink, stderr: { write: () => true, isTTY: false }, stdin: { isTTY: false } } });
+    let result: unknown = null;
+    try {
+      result = JSON.parse(output);
+    } catch {
+      result = null;
+    }
+    return { exit, result, output: output.slice(0, 64 * 1024) };
+  };
+}
+
+function toUiRequest(req: IncomingMessage, body: string): UiRequest {
+  const headers: Record<string, string | undefined> = {};
+  for (const [k, v] of Object.entries(req.headers)) headers[k] = Array.isArray(v) ? v.join(", ") : v;
+  return { method: req.method ?? "GET", url: req.url ?? "/", headers, body };
+}
+
+export async function cmdUi(ctx: Ctx) {
+  const { t } = ctx;
+  const wanted = Number(str(ctx.flags.port) ?? 0);
+  if (!Number.isInteger(wanted) || wanted < 0 || wanted > 65535) throw new Fail("--port takes a port number, or leave it out for a free one.", { code: EXIT.misunderstood });
+  const token = randomBytes(24).toString("base64url");
+  let handler: ReturnType<typeof createUiHandler> | null = null;
+  const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    req.on("data", (c: Buffer) => {
+      size += c.length;
+      if (size <= 64 * 1024) chunks.push(c);
+    });
+    req.on("end", () => {
+      if (!handler) return res.writeHead(503).end();
+      handler
+        .handle(toUiRequest(req, Buffer.concat(chunks).toString("utf8")))
+        .then((r) => res.writeHead(r.status, r.headers).end(r.body))
+        .catch(() => res.writeHead(500, { "content-type": "text/plain" }).end("The command failed."));
+    });
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", (err: NodeJS.ErrnoException) => reject(new Fail(`The page could not start: ${err.code === "EADDRINUSE" ? `port ${wanted} is taken` : err.message}.`, { hint: err.code === "EPERM" ? "this sandbox forbids a local port: run it in your own terminal" : undefined })));
+    server.listen(wanted, "127.0.0.1", () => resolve());
+  });
+  const port = (server.address() as { port: number }).port;
+  handler = createUiHandler({ port, token, command: ctx.cmd, root: ctx.root, runAction: actionRunner(ctx) });
+  const url = `${handler.origin}/?token=${token}`;
+  if (ctx.json) emit(ctx, { url, note: "The token works once. The page stops with this process." });
+  else {
+    t.banner("Local page", [`127.0.0.1:${port}`, "this machine only"]);
+    t.out(`  ${t.paint.bold("Open")}  ${t.link(url, url)}`);
+    t.out();
+    t.out(`  ${t.paint.gray("The address works once: open it in your browser now. The key stays in this process. Ctrl+C stops the page.")}`);
+    t.out();
+  }
+  if (ctx.flags.open) {
+    const opener = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    try {
+      spawn(opener[0] as string, opener[1] as string[], { detached: true, stdio: "ignore" }).on("error", () => undefined).unref();
+    } catch {
+      // Opening a browser is a courtesy; the address is printed either way.
+    }
+  }
+  await new Promise<void>((resolve) => {
+    const stop = () => server.close(() => resolve());
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+}

package/src/client.ts

@@ -0,0 +1,202 @@
+import { SESSION_HEADER } from "./session.js";
+import type { Page, Problem } from "./types.js";
+
+/**
+ * The Interface API as a Frontend consumes it (components/05-interface-api.md
+ * §Conventions): `X-Asturiu-Session` on every call except session exchange,
+ * `Idempotency-Key` on writes, `If-Match` for concurrency, cursors for
+ * collections, `application/problem+json` for errors — and a `404` that never
+ * distinguishes absent from forbidden.
+ *
+ * Runs wherever `fetch` exists: a Next.js server, an edge runtime, a browser
+ * talking to the Web UI's own `/api/v0` proxy.
+ */
+
+export class InterfaceApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly problem: Problem,
+  ) {
+    super(problem.detail ?? problem.title ?? `HTTP ${status}`);
+    this.name = "InterfaceApiError";
+  }
+
+  get type(): string {
+    return this.problem.type ?? "";
+  }
+  get isUnauthorized(): boolean {
+    return this.status === 401;
+  }
+  get isNotFound(): boolean {
+    return this.status === 404;
+  }
+  get isPaused(): boolean {
+    return this.status === 503 && this.type.endsWith("platform-paused");
+  }
+  get isSuspended(): boolean {
+    return this.status === 403 && this.type.endsWith("account-suspended");
+  }
+  /** `POST /v0/sessions` for someone with no Customer yet, while the Tenant takes no new ones (ADR-044). */
+  get isEnrolmentClosed(): boolean {
+    return this.status === 403 && this.type.endsWith("enrolment-closed");
+  }
+}
+
+export interface CallOptions {
+  body?: unknown;
+  /** Raw payload (Attachment upload) — sent as-is with `contentType`. */
+  raw?: ArrayBuffer | Uint8Array | Blob;
+  contentType?: string;
+  headers?: Record<string, string | undefined>;
+  query?: Record<string, string | number | boolean | undefined | null>;
+  /** Default `true`; `false` for `POST /v0/sessions`, `/v0/status`, `/v0/health`. */
+  session?: boolean;
+  /** Default: a fresh key per `POST`/`PUT`. Pass a stable key to make a retry a replay. */
+  idempotencyKey?: string | false;
+  ifMatch?: number | string;
+  signal?: AbortSignal;
+}
+
+export interface Response<T> {
+  status: number;
+  body: T;
+  headers: Headers;
+}
+
+export interface InterfaceApiClientOptions {
+  /** `http://interface-api:8081` server-side, or the Web UI's own origin for the browser. */
+  baseUrl: string;
+  /** The opaque session identifier, if this client acts for a signed-in Customer. */
+  session?: string | null;
+  /** Path prefix: `/v0` against the Interface API, `/api/v0` against the Web UI proxy. */
+  prefix?: string;
+  /**
+   * The transport carries the session (the Web UI's `HttpOnly` cookie on its
+   * own `/api/v0` proxy): send no header and require no identifier. The
+   * browser never holds the session identifier itself.
+   */
+  ambientSession?: boolean;
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+}
+
+/** The ambient `fetch`, invoked on the global so it is valid as a method of any object. */
+const globalFetch: typeof fetch = (input, init) => globalThis.fetch(input, init);
+
+function safeJson(text: string): unknown {
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+
+export class InterfaceApiClient {
+  readonly baseUrl: string;
+  readonly prefix: string;
+  readonly session: string | null;
+  readonly ambientSession: boolean;
+  private readonly f: typeof fetch;
+  private readonly timeoutMs: number;
+
+  constructor(opts: InterfaceApiClientOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.prefix = opts.prefix ?? "/v0";
+    this.session = opts.session ?? null;
+    this.ambientSession = opts.ambientSession ?? false;
+    // Never store the bare global `fetch` and call it as `this.f(...)`: browsers
+    // then see `this === InterfaceApiClient` and throw
+    // "Failed to execute 'fetch' on 'Window': Illegal invocation" (Node is
+    // lenient, so only the Web UI breaks). Always call through `globalFetch`.
+    this.f = opts.fetch ?? globalFetch;
+    this.timeoutMs = opts.timeoutMs ?? 30000;
+  }
+
+  /** The same client acting for another (or no) session. */
+  withSession(session: string | null): InterfaceApiClient {
+    return new InterfaceApiClient({ baseUrl: this.baseUrl, prefix: this.prefix, session, ambientSession: this.ambientSession, fetch: this.f, timeoutMs: this.timeoutMs });
+  }
+
+  url(path: string, query?: CallOptions["query"]): string {
+    const u = new URL(`${this.baseUrl}${this.prefix}${path.startsWith("/") ? path : `/${path}`}`);
+    for (const [k, v] of Object.entries(query ?? {})) if (v !== undefined && v !== null && v !== "") u.searchParams.set(k, String(v));
+    return u.toString();
+  }
+
+  async call<T = unknown>(method: string, path: string, opts: CallOptions = {}): Promise<Response<T>> {
+    const headers: Record<string, string> = { accept: "application/json, application/problem+json, */*" };
+    for (const [k, v] of Object.entries(opts.headers ?? {})) if (v !== undefined) headers[k.toLowerCase()] = v;
+    if (opts.session !== false && !this.ambientSession) {
+      if (!this.session) throw new InterfaceApiError(401, { type: "urn:asturiu:problem:unauthorized", title: "Unauthorized", status: 401, detail: "no session" });
+      headers[SESSION_HEADER] = this.session;
+    }
+    let body: RequestInit["body"] | undefined;
+    if (opts.raw !== undefined) {
+      body = opts.raw as RequestInit["body"];
+      headers["content-type"] = opts.contentType ?? "application/octet-stream";
+    } else if (opts.body !== undefined) {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(opts.body);
+    }
+    if (["POST", "PUT"].includes(method) && opts.idempotencyKey !== false && !headers["idempotency-key"]) headers["idempotency-key"] = opts.idempotencyKey ?? crypto.randomUUID();
+    if (opts.ifMatch !== undefined) headers["if-match"] = String(opts.ifMatch);
+    const res = await this.f(this.url(path, opts.query), { method, headers, body, signal: opts.signal ?? AbortSignal.timeout(this.timeoutMs), cache: "no-store" } as RequestInit);
+    const text = await res.text();
+    const json = safeJson(text);
+    if (!res.ok) {
+      const problem: Problem = json && typeof json === "object" && "status" in (json as object) ? (json as Problem) : { type: "urn:asturiu:problem:http", title: res.statusText || "Error", status: res.status, detail: typeof json === "object" && json && "raw" in json ? String((json as { raw: string }).raw).slice(0, 300) : undefined };
+      throw new InterfaceApiError(res.status, problem);
+    }
+    return { status: res.status, body: json as T, headers: res.headers };
+  }
+
+  /** Binary download (Attachment content). */
+  async download(path: string, opts: Omit<CallOptions, "body" | "raw"> = {}): Promise<{ status: number; bytes: ArrayBuffer; contentType: string; filename?: string }> {
+    const headers: Record<string, string> = {};
+    if (opts.session !== false && !this.ambientSession) {
+      if (!this.session) throw new InterfaceApiError(401, { type: "urn:asturiu:problem:unauthorized", title: "Unauthorized", status: 401 });
+      headers[SESSION_HEADER] = this.session;
+    }
+    const res = await this.f(this.url(path, opts.query), { method: "GET", headers, signal: opts.signal ?? AbortSignal.timeout(this.timeoutMs), cache: "no-store" } as RequestInit);
+    if (!res.ok) throw new InterfaceApiError(res.status, (safeJson(await res.text()) as Problem) ?? { type: "urn:asturiu:problem:http", title: "Error", status: res.status });
+    const cd = res.headers.get("content-disposition") ?? "";
+    const m = /filename="?([^";]+)"?/.exec(cd);
+    return { status: res.status, bytes: await res.arrayBuffer(), contentType: res.headers.get("content-type") ?? "application/octet-stream", filename: m?.[1] };
+  }
+
+  get<T = unknown>(path: string, query?: CallOptions["query"], opts: CallOptions = {}): Promise<T> {
+    return this.call<T>("GET", path, { ...opts, query }).then((r) => r.body);
+  }
+  post<T = unknown>(path: string, body?: unknown, opts: CallOptions = {}): Promise<T> {
+    return this.call<T>("POST", path, { ...opts, body }).then((r) => r.body);
+  }
+  put<T = unknown>(path: string, body?: unknown, opts: CallOptions = {}): Promise<T> {
+    return this.call<T>("PUT", path, { ...opts, body }).then((r) => r.body);
+  }
+  patch<T = unknown>(path: string, body?: unknown, opts: CallOptions = {}): Promise<T> {
+    return this.call<T>("PATCH", path, { ...opts, body }).then((r) => r.body);
+  }
+  delete<T = unknown>(path: string, opts: CallOptions = {}): Promise<T> {
+    return this.call<T>("DELETE", path, opts).then((r) => r.body);
+  }
+
+  /** Walk every page of a cursor-paginated collection. */
+  async all<T>(path: string, query: CallOptions["query"] = {}, limit = 100): Promise<T[]> {
+    const out: T[] = [];
+    let cursor: string | null = null;
+    do {
+      const page: Page<T> = await this.get<Page<T>>(path, { ...query, limit, cursor: cursor ?? undefined });
+      out.push(...page.items);
+      cursor = page.next_cursor;
+    } while (cursor);
+    return out;
+  }
+}
+
+/** Every caller-facing error becomes a problem shape, so UIs render one thing. */
+export function toProblem(err: unknown): Problem {
+  if (err instanceof InterfaceApiError) return err.problem;
+  if (err instanceof Error) return { type: "urn:asturiu:problem:client", title: err.name, status: 0, detail: err.message };
+  return { type: "urn:asturiu:problem:client", title: "Error", status: 0, detail: String(err) };
+}

package/src/contacts.ts

@@ -0,0 +1,61 @@
+/**
+ * Contacts, handles and disclosure (ADR-024). Pure vocabulary shared by the
+ * Engine, the CLI and every frontend: the pair-state function is the one
+ * place the two rows of a Contact are read into one answer, so it must be the
+ * same everywhere. Dependency-free on purpose.
+ */
+
+/** A holder's own decision about one Contact, stored on its row. */
+export const CONTACT_INTENTS = ["accepted", "incoming", "blocked"] as const;
+export type ContactIntent = (typeof CONTACT_INTENTS)[number];
+
+/** What one side sees, derived from both rows and never stored. */
+export const CONTACT_STATES = ["active", "pending", "incoming", "blocked", "removed"] as const;
+export type ContactState = (typeof CONTACT_STATES)[number];
+
+/** How the Contact came to exist. */
+export const CONTACT_ORIGINS = ["request", "grant", "transfer", "recovery"] as const;
+export type ContactOrigin = (typeof CONTACT_ORIGINS)[number];
+
+/** The profile fields a holder may disclose to one Contact. The handle is always visible to an active Contact and is not on this list. */
+export const DISCLOSABLE_FIELDS = ["display_name", "name", "email", "phone"] as const;
+export type DisclosableField = (typeof DISCLOSABLE_FIELDS)[number];
+
+/**
+ * The counterpart row as the holder's side sees it: an intent when the row
+ * is readable, `missing` when no counterpart row was ever linked (an external
+ * Principal not redeemed yet), `removed` when the linked row is gone (the
+ * counterpart deleted the Contact, or the Customer was deleted).
+ */
+export type CounterpartIntent = ContactIntent | "missing" | "removed";
+
+/**
+ * The state one holder sees. Order matters:
+ *
+ * - my own block is always shown to me as `blocked`;
+ * - a counterpart that is gone is `removed`, whatever I had decided;
+ * - a request I have not answered is `incoming`;
+ * - both accepted is `active`;
+ * - everything else — the counterpart has not answered, has declined
+ *   silently, or has blocked me — reads `pending`. A block is never visible
+ *   to the blocked side.
+ */
+export function contactState(mine: ContactIntent, theirs: CounterpartIntent): ContactState {
+  if (mine === "blocked") return "blocked";
+  if (theirs === "removed") return "removed";
+  if (mine === "incoming") return "incoming";
+  if (theirs === "accepted") return "active";
+  return "pending";
+}
+
+/** Platform-wide handle (ADR-024): lowercase, 3–30 characters, starts with a letter or digit. */
+export const HANDLE_PATTERN = /^[a-z0-9][a-z0-9._-]{2,29}$/;
+
+export function isHandle(value: unknown): value is string {
+  return typeof value === "string" && HANDLE_PATTERN.test(value);
+}
+
+/** Normalise what a person typed as a handle: trim, lower-case, strip a leading `@`. Validation is `isHandle`. */
+export function normalizeHandle(value: string): string {
+  return value.trim().replace(/^@/, "").toLowerCase();
+}