@mostra/protocol 0.0.0-placeholder → 0.1.0

package/src/diagnostics/diagnostic.ts

@@ -0,0 +1,240 @@
+/**
+ * The one diagnostic object every Mostra interface uses for errors, warnings and hints
+ * (INTERFACES §1 and §13, AX-03).
+ */
+import * as z from "zod";
+import { wireRegistry } from "../wire-registry.ts";
+
+/**
+ * Diagnostic areas. A code is `MOSTRA_<AREA>_<NAME>`. INTERFACES §13 holds the authoritative list,
+ * which only grows.
+ */
+export type DiagnosticArea =
+  | "MANIFEST"
+  | "BUILD"
+  | "TYPE"
+  | "LINT"
+  | "DEP"
+  | "KIT"
+  | "FIELD"
+  | "ACTION"
+  | "LIVE"
+  | "RUNTIME"
+  | "CONSOLE"
+  | "NETWORK"
+  | "A11Y"
+  | "VISUAL"
+  | "SMOKE"
+  | "REGRESSION"
+  | "TERM"
+  | "PUBLISH"
+  | "SUBMIT"
+  | "HOST"
+  | "HOME"
+  | "HYGIENE"
+  | "SECRET"
+  | "SHARE"
+  | "VERIFY"
+  | "TARGET"
+  | "ENV"
+  | "PLATFORM"
+  | "ARTIFACT"
+  | "CLI";
+
+/** Every diagnostic area, in INTERFACES §13 order. */
+export const DIAGNOSTIC_AREAS: readonly DiagnosticArea[] = [
+  "MANIFEST",
+  "BUILD",
+  "TYPE",
+  "LINT",
+  "DEP",
+  "KIT",
+  "FIELD",
+  "ACTION",
+  "LIVE",
+  "RUNTIME",
+  "CONSOLE",
+  "NETWORK",
+  "A11Y",
+  "VISUAL",
+  "SMOKE",
+  "REGRESSION",
+  "TERM",
+  "PUBLISH",
+  "SUBMIT",
+  "HOST",
+  "HOME",
+  "HYGIENE",
+  "SECRET",
+  "SHARE",
+  "VERIFY",
+  "TARGET",
+  "ENV",
+  "PLATFORM",
+  "ARTIFACT",
+  "CLI",
+];
+
+/**
+ * A diagnostic code. Codes are semver surface: once released, a code keeps its meaning and is
+ * never removed (AX-03).
+ */
+export type DiagnosticCode = `MOSTRA_${DiagnosticArea}_${string}`;
+
+/**
+ * How bad it is. `error` is only for definite failures; observations that might be fine are
+ * warnings (D72).
+ */
+export type DiagnosticSeverity = "error" | "warning" | "hint";
+
+/** The stage of work that produced the diagnostic. */
+export type DiagnosticPhase =
+  | "manifest"
+  | "compile"
+  | "lint"
+  | "runtime"
+  | "console"
+  | "network"
+  | "a11y"
+  | "visual"
+  | "smoke"
+  | "regression"
+  | "contract"
+  | "publish"
+  | "host"
+  | "hygiene"
+  | "platform";
+
+/**
+ * A machine-applicable fix. `range` is `[startLine, startColumn, endLine, endColumn]`, 1-based,
+ * with the end exclusive.
+ */
+export interface DiagnosticFix {
+  /** Replace, insert or delete text in `file`, or run `command`. */
+  readonly kind: "replace" | "insert" | "delete" | "command";
+  /** The file to edit, relative to the artifact or project root. */
+  readonly file?: string;
+  /** The span to edit. */
+  readonly range?: readonly [number, number, number, number];
+  /** The replacement or inserted text. */
+  readonly text?: string;
+  /** The command to run, for `kind: "command"`. */
+  readonly command?: string;
+}
+
+/** Where the problem is: a source position (1-based) or a place in a rendered viewport. */
+export type DiagnosticLocation =
+  | { readonly file: string; readonly line: number; readonly column: number }
+  | { readonly viewport: string; readonly selector?: string };
+
+/** One diagnostic (INTERFACES §13). */
+export interface Diagnostic {
+  /** The stable code, `MOSTRA_<AREA>_<NAME>`. */
+  readonly code: DiagnosticCode;
+  /** How bad it is. */
+  readonly severity: DiagnosticSeverity;
+  /** What is wrong, for this occurrence. */
+  readonly message: string;
+  /** What to do: one imperative sentence. */
+  readonly hint?: string;
+  /** A machine-applicable fix, when one exists. */
+  readonly fix?: DiagnosticFix;
+  /** Where the problem is, when it has a place. */
+  readonly location?: DiagnosticLocation;
+  /** The stage of work that produced it. */
+  readonly phase: DiagnosticPhase;
+  /** The code's documentation page: `${docsBase}/errors/${code}` (D37). */
+  readonly docs: string;
+  /** How many identical occurrences this one stands for, when deduplicated. */
+  readonly count?: number;
+}
+
+const positiveInt = z.int().min(1);
+
+/**
+ * Codes on the wire accept any area, so a client keeps working when a newer Mostra reports a code
+ * from an area it doesn't know yet. Producers are typed against {@link DiagnosticArea}.
+ */
+const codeSchema = z
+  .string()
+  .regex(/^MOSTRA_[A-Z0-9]+_[A-Z0-9_]+$/)
+  .register(wireRegistry, {
+    id: "DiagnosticCode",
+    description: "Stable diagnostic code: MOSTRA_<AREA>_<NAME>.",
+  }) as unknown as z.ZodType<DiagnosticCode, string>;
+
+/** The Zod schema of the `DiagnosticSeverity` type. */
+export const DiagnosticSeverity: z.ZodType<DiagnosticSeverity, string> = z
+  .enum(["error", "warning", "hint"])
+  .register(wireRegistry, {
+    id: "DiagnosticSeverity",
+    description: "How bad it is: error only for definite failures.",
+  });
+
+/** The Zod schema of the `DiagnosticPhase` type. */
+export const DiagnosticPhase: z.ZodType<DiagnosticPhase, string> = z
+  .enum([
+    "manifest",
+    "compile",
+    "lint",
+    "runtime",
+    "console",
+    "network",
+    "a11y",
+    "visual",
+    "smoke",
+    "regression",
+    "contract",
+    "publish",
+    "host",
+    "hygiene",
+    "platform",
+  ])
+  .register(wireRegistry, {
+    id: "DiagnosticPhase",
+    description: "The stage of work that produced the diagnostic.",
+  });
+
+/** The Zod schema of the `DiagnosticFix` type. */
+export const DiagnosticFix: z.ZodType<DiagnosticFix> = z
+  .object({
+    kind: z.enum(["replace", "insert", "delete", "command"]),
+    file: z.string().exactOptional(),
+    range: z.tuple([positiveInt, positiveInt, positiveInt, positiveInt]).readonly().exactOptional(),
+    text: z.string().exactOptional(),
+    command: z.string().exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "DiagnosticFix",
+    description:
+      "A machine-applicable fix; range is [startLine, startColumn, endLine, endColumn], 1-based, end exclusive.",
+  });
+
+/** The Zod schema of the `DiagnosticLocation` type. */
+export const DiagnosticLocation: z.ZodType<DiagnosticLocation> = z
+  .union([
+    z.object({ file: z.string(), line: positiveInt, column: positiveInt }),
+    z.object({ viewport: z.string(), selector: z.string().exactOptional() }),
+  ])
+  .register(wireRegistry, {
+    id: "DiagnosticLocation",
+    description: "A 1-based source position, or a place in a rendered viewport.",
+  });
+
+/** The Zod schema of the `Diagnostic` type. */
+export const Diagnostic: z.ZodType<Diagnostic> = z
+  .object({
+    code: codeSchema,
+    severity: DiagnosticSeverity,
+    message: z.string(),
+    hint: z.string().exactOptional(),
+    fix: DiagnosticFix.exactOptional(),
+    location: DiagnosticLocation.exactOptional(),
+    phase: DiagnosticPhase,
+    docs: z.url(),
+    count: positiveInt.exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "Diagnostic",
+    description: "One diagnostic: a stable code, severity, message, hint, fix and docs link.",
+  });

package/src/diagnostics/spec.ts

@@ -0,0 +1,90 @@
+/**
+ * The diagnostic catalog: one entry per code, declared in one source file per area under
+ * `codes/`. The catalog feeds `createDiagnostic`, the generated catalog JSON and one docs
+ * page per code (AX-03).
+ */
+import type {
+  Diagnostic,
+  DiagnosticArea,
+  DiagnosticFix,
+  DiagnosticLocation,
+  DiagnosticPhase,
+  DiagnosticSeverity,
+} from "./diagnostic.ts";
+
+/** Everything Mostra knows about one code, besides the code itself. */
+export interface DiagnosticSpec {
+  /** The severity of every occurrence. */
+  readonly severity: DiagnosticSeverity;
+  /** The stage of work that reports it. */
+  readonly phase: DiagnosticPhase;
+  /** One line naming the condition. It is the docs page's title. */
+  readonly title: string;
+  /** The default hint: one imperative sentence. An occurrence may give a more specific one. */
+  readonly hint: string;
+  /** The docs page body. */
+  readonly docs: {
+    /** What the code means and when Mostra reports it. */
+    readonly explanation: string;
+    /** The minimal fix. */
+    readonly fix: string;
+  };
+  /**
+   * Set when Mostra no longer reports the code, saying what replaced it. Codes are never
+   * removed (AX-03).
+   */
+  readonly deprecated?: string;
+}
+
+/** The catalog of one area: exactly the codes `C`, each with its spec. */
+export type AreaCatalog<C extends `MOSTRA_${DiagnosticArea}_${string}`> = {
+  readonly [K in C]: DiagnosticSpec;
+};
+
+/**
+ * Where diagnostics link by default: the GitHub Pages docs site (D37). Hosts and the runtime pass
+ * their own base when the docs move.
+ */
+export const DEFAULT_DOCS_BASE: string = "https://mostra-dev.github.io/mostra";
+
+/** The docs page for `code` under `docsBase`: `${docsBase}/errors/${code}`. */
+export function docsUrl(code: string, docsBase: string = DEFAULT_DOCS_BASE): string {
+  let end = docsBase.length;
+  while (end > 0 && docsBase.charCodeAt(end - 1) === 47 /* "/" */) end--;
+  return `${docsBase.slice(0, end)}/errors/${code}`;
+}
+
+/** The parts of a diagnostic that belong to one occurrence rather than to its code. */
+export interface DiagnosticDetails {
+  /** What is wrong, for this occurrence. Never include secrets or capability tokens. */
+  readonly message: string;
+  /** Replaces the catalog's default hint when the occurrence allows a more specific one. */
+  readonly hint?: string;
+  /** A machine-applicable fix. */
+  readonly fix?: DiagnosticFix;
+  /** Where the problem is. */
+  readonly location?: DiagnosticLocation;
+  /** How many identical occurrences this one stands for. */
+  readonly count?: number;
+}
+
+/**
+ * Builds a diagnostic for a cataloged code: severity, phase, hint and docs link come from `spec`,
+ * the rest from `details`.
+ */
+export function buildDiagnostic(
+  code: Diagnostic["code"],
+  spec: DiagnosticSpec,
+  details: DiagnosticDetails,
+  docsBase: string = DEFAULT_DOCS_BASE,
+): Diagnostic {
+  const { hint = spec.hint, ...rest } = details;
+  return {
+    code,
+    severity: spec.severity,
+    phase: spec.phase,
+    docs: docsUrl(code, docsBase),
+    hint,
+    ...rest,
+  };
+}

package/src/hygiene.ts

@@ -0,0 +1,224 @@
+/**
+ * Request hygiene (D06, ARCHITECTURE §10, HY-01): the checks every Mostra HTTP endpoint applies
+ * before it acts on a request, as pure functions with no I/O. The gateway runs them on every
+ * request, and `mostra mcp --http` (WP-15) runs the same code (D96), so a request a stranger's
+ * page could send is refused the same way everywhere. None of them limits what an artifact, an
+ * agent or a viewer may do; they only make sure a request comes from the page it claims to.
+ *
+ * ```ts
+ * const refusal = checkRequest(
+ *   { origin: "http://127.0.0.1:23456", hosts: ["127.0.0.1:23456"] },
+ *   { method: "POST", target: "/a/art_…/_mostra/ticket", headers, intent: "mutation", csrf },
+ * );
+ * if (refusal) return respond(refusal.status, refusal.diagnostic);
+ * ```
+ */
+import { type HygieneDiagnosticCode, hygieneDiagnostics } from "./diagnostics/codes/hygiene.ts";
+import type { Diagnostic } from "./diagnostics/diagnostic.ts";
+import { buildDiagnostic } from "./diagnostics/spec.ts";
+
+/** What one listener serves: its own origin and the exact `Host` values it accepts. */
+export interface RequestPolicy {
+  /** The listener's origin, such as `http://127.0.0.1:23456`; `Origin` headers must equal it. */
+  readonly origin: string;
+  /** Every `host:port` this listener answers to (lowercase): its URL host, plus registered tunnels. */
+  readonly hosts: readonly string[];
+}
+
+/**
+ * What a request is for, which decides the checks beyond the envelope:
+ * - `read`: a GET or HEAD of a page or file; a foreign `Origin` is refused, none is fine.
+ * - `stream`: an event stream (GET); same-origin only, by `Origin` or `Sec-Fetch-Site`.
+ * - `upgrade`: a WebSocket upgrade; `Origin` must be present and equal.
+ * - `exchange`: a mutation that starts a session (a capability token or ticket in the body):
+ *   `Origin` and a JSON content type, but no CSRF token yet.
+ * - `mutation`: any other state change: `Origin`, a JSON content type and the session's CSRF
+ *   token in `X-Mostra-CSRF`.
+ */
+export type RequestIntent = "read" | "stream" | "upgrade" | "exchange" | "mutation";
+
+/** One request as the transport received it. */
+export interface RequestFacts {
+  /** The method, as sent. */
+  readonly method: string;
+  /** The request target exactly as sent: an origin-form path with its query. */
+  readonly target: string;
+  /** Every header as `[name, value]` in arrival order, so repeated headers are visible. */
+  readonly headers: readonly (readonly [string, string])[];
+  /** The intent the matched route declared; omit to check only the envelope. */
+  readonly intent?: RequestIntent;
+  /** The session's CSRF token, for `mutation` requests. */
+  readonly csrf?: string;
+}
+
+/** A refused request: the HTTP status to answer with and the diagnostic for its body. */
+export interface Refusal {
+  /** The HTTP status: 400, 401, 403, 404, 410, 415, 421 or 429. */
+  readonly status: number;
+  /** What was refused and why, for the response body and the log. */
+  readonly diagnostic: Diagnostic;
+}
+
+/** The header that carries a session's CSRF token on every mutation (D98). */
+export const CSRF_HEADER = "x-mostra-csrf";
+
+const STATUS: Readonly<Record<HygieneDiagnosticCode, number>> = {
+  MOSTRA_HYGIENE_HOST_REFUSED: 421,
+  MOSTRA_HYGIENE_ORIGIN_REFUSED: 403,
+  MOSTRA_HYGIENE_CSRF_MISSING: 403,
+  MOSTRA_HYGIENE_CONTENT_TYPE: 415,
+  MOSTRA_HYGIENE_REQUEST_MALFORMED: 400,
+  MOSTRA_HYGIENE_SESSION_MISSING: 401,
+  MOSTRA_HYGIENE_TOKEN_INVALID: 401,
+  MOSTRA_HYGIENE_TOKEN_REVOKED: 410,
+  MOSTRA_HYGIENE_SCOPE_DENIED: 403,
+  MOSTRA_HYGIENE_RATE_LIMITED: 429,
+  MOSTRA_HYGIENE_NOT_SERVED: 404,
+  MOSTRA_HYGIENE_SESSION_CONFLICT: 409,
+  MOSTRA_HYGIENE_HEADERS_TOO_LARGE: 431,
+};
+
+/** Builds a refusal with the status the code's HTTP mapping gives (FAILURE_MODEL §8). */
+export function refusal(code: HygieneDiagnosticCode, message: string, status?: number): Refusal {
+  return {
+    status: status ?? STATUS[code],
+    diagnostic: buildDiagnostic(code, hygieneDiagnostics[code], { message }),
+  };
+}
+
+/** Headers that must appear at most once: a second copy could mean two different things. */
+const SINGLE = new Set(["host", "origin", "content-type", "content-length", CSRF_HEADER, "cookie"]);
+
+/** Characters no header value or path may carry: controls other than tab, and DEL. */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is the point.
+const CONTROL = /[\u0000-\u0008\u000a-\u001f\u007f]/;
+
+/** Constant-time comparison of two strings, so timing reveals nothing about a secret. */
+export function safeEqual(a: string, b: string): boolean {
+  let difference = a.length ^ b.length;
+  const length = Math.max(a.length, b.length);
+  for (let index = 0; index < length; index++) {
+    difference |= (a.charCodeAt(index) | 0) ^ (b.charCodeAt(index) | 0);
+  }
+  return difference === 0;
+}
+
+/**
+ * The path a request target names, decoded, or `undefined` when it isn't a safe origin-form path:
+ * absolute and authority forms, `*`, encoded `/` or `\`, `.` or `..` segments (encoded or not),
+ * NUL and other controls, and invalid percent-encoding are all refused.
+ */
+export function safePath(target: string): string | undefined {
+  if (!target.startsWith("/") || target.startsWith("//")) return undefined;
+  const end = target.search(/[?#]/);
+  const raw = end < 0 ? target : target.slice(0, end);
+  if (/%(2f|5c)/i.test(raw) || raw.includes("\\")) return undefined;
+  let path: string;
+  try {
+    path = decodeURIComponent(raw);
+  } catch {
+    return undefined;
+  }
+  if (CONTROL.test(path) || path.includes("\u0000")) return undefined;
+  if (path.split("/").some((segment) => segment === "." || segment === "..")) return undefined;
+  return path;
+}
+
+/** The value of a header (case-insensitive name), or `undefined`. */
+export function headerValue(
+  headers: readonly (readonly [string, string])[],
+  name: string,
+): string | undefined {
+  const lower = name.toLowerCase();
+  return headers.find(([key]) => key.toLowerCase() === lower)?.[1];
+}
+
+/** Whether a `Content-Type` value is JSON (`application/json`, any parameters). */
+export function isJsonContentType(value: string | undefined): boolean {
+  if (value === undefined) return false;
+  return value.split(";")[0]?.trim().toLowerCase() === "application/json";
+}
+
+/**
+ * Checks a request's envelope (the `Host` allowlist, the request target, repeated and malformed
+ * headers) and, when `intent` is given, what that intent needs: `Origin`, the JSON content type
+ * and the CSRF token. Returns the first refusal, or `undefined` when the request may proceed.
+ * Session, token and scope checks follow in the endpoint, which knows its session.
+ */
+export function checkRequest(policy: RequestPolicy, request: RequestFacts): Refusal | undefined {
+  const counts = new Map<string, number>();
+  for (const [name, value] of request.headers) {
+    const lower = name.toLowerCase();
+    counts.set(lower, (counts.get(lower) ?? 0) + 1);
+    if (CONTROL.test(value)) {
+      return refusal(
+        "MOSTRA_HYGIENE_REQUEST_MALFORMED",
+        `The ${lower} header has control characters.`,
+      );
+    }
+  }
+  for (const name of SINGLE) {
+    if ((counts.get(name) ?? 0) > 1) {
+      return refusal("MOSTRA_HYGIENE_REQUEST_MALFORMED", `The request repeats the ${name} header.`);
+    }
+  }
+  const host = headerValue(request.headers, "host")?.toLowerCase();
+  if (host === undefined || !policy.hosts.includes(host)) {
+    return refusal(
+      "MOSTRA_HYGIENE_HOST_REFUSED",
+      host === undefined
+        ? "The request has no Host header."
+        : "The request's Host isn't one this listener serves.",
+    );
+  }
+  if (safePath(request.target) === undefined) {
+    return refusal(
+      "MOSTRA_HYGIENE_REQUEST_MALFORMED",
+      "The request target isn't a plain path inside the served tree.",
+    );
+  }
+  if (request.intent === undefined) return undefined;
+
+  const origin = headerValue(request.headers, "origin");
+  switch (request.intent) {
+    case "read":
+      if (origin !== undefined && origin !== policy.origin) {
+        return refusal("MOSTRA_HYGIENE_ORIGIN_REFUSED", "The request came from another origin.");
+      }
+      return undefined;
+    case "stream": {
+      const site = headerValue(request.headers, "sec-fetch-site");
+      const sameOrigin = origin === undefined ? site === "same-origin" : origin === policy.origin;
+      return sameOrigin
+        ? undefined
+        : refusal("MOSTRA_HYGIENE_ORIGIN_REFUSED", "A stream must be opened by its own origin.");
+    }
+    case "upgrade":
+    case "exchange":
+    case "mutation": {
+      if (origin !== policy.origin) {
+        return refusal(
+          "MOSTRA_HYGIENE_ORIGIN_REFUSED",
+          origin === undefined
+            ? "The request has no Origin header."
+            : "The request came from another origin.",
+        );
+      }
+      if (request.intent === "upgrade") return undefined;
+      if (!isJsonContentType(headerValue(request.headers, "content-type"))) {
+        return refusal("MOSTRA_HYGIENE_CONTENT_TYPE", "The request's body isn't declared as JSON.");
+      }
+      if (request.intent === "exchange") return undefined;
+      const sent = headerValue(request.headers, CSRF_HEADER);
+      if (request.csrf === undefined || sent === undefined || !safeEqual(sent, request.csrf)) {
+        return refusal(
+          "MOSTRA_HYGIENE_CSRF_MISSING",
+          sent === undefined
+            ? `The request has no ${CSRF_HEADER} header.`
+            : `The request's ${CSRF_HEADER} header doesn't match its session.`,
+        );
+      }
+      return undefined;
+    }
+  }
+}