@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-node/src/mounts.ts

@@ -0,0 +1,296 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+import { Duplex } from "node:stream";
+import { createHmac, randomBytes } from "node:crypto";
+
+/**
+ * Where a mount is served and how much of the request path belongs to it.
+ */
+export type MountContext = {
+  /** Public path prefix this mount owns, e.g. `/hosted/ab12…`. */
+  mountPath: string;
+  /**
+   * Request target with `mountPath` removed; always starts with `/` and keeps
+   * any query string, so a handler can parse it as a URL and see both.
+   */
+  subPath: string;
+};
+
+export type MountRequestHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  context: MountContext,
+) => void;
+
+export type MountUpgradeHandler = (
+  req: IncomingMessage,
+  socket: Duplex,
+  head: Buffer,
+  context: MountContext,
+) => void;
+
+export type MountHandlers = {
+  request: MountRequestHandler;
+  /** Only needed by mounts that speak WebSocket (e.g. PeerJS signalling). */
+  upgrade?: MountUpgradeHandler;
+};
+
+/** A live mount, handed back to the service that registered it. */
+export type MountHandle = {
+  /** Public URL clients should be pointed at. */
+  url: string;
+  /** Path prefix of `url`, useful for clients configured by host/port/path. */
+  path: string;
+  release(): void;
+};
+
+type MountRecord = {
+  owner: string;
+  /** The space the runtime lives in; see `boardSpace`. */
+  space: string;
+  runtimeId: string;
+  serviceUuid: string;
+  handlers: MountHandlers;
+};
+
+/** Requests under this prefix are served by mounts rather than the REST API. */
+export const MOUNT_PREFIX = "/hosted";
+
+/**
+ * Routes public traffic to services that need to expose an endpoint, without
+ * any of them binding a port of their own.
+ *
+ * A service asks for a mount and gets back an opaque, server-assigned id. That
+ * id — rather than a port or a caller-chosen path — is what makes the endpoint
+ * addressable, which matters for three reasons:
+ *
+ * - Ports are a single machine-wide namespace. With several tenants on one
+ *   host, a service asking for a specific port is a land grab: the second
+ *   claimant fails, and whoever wins receives traffic the other expected.
+ * - Runtime ids are only unique per tenant (boards ship stable ones like
+ *   `node`), so they cannot appear in a globally-routable path.
+ * - These endpoints are deliberately unauthenticated — they exist to be called
+ *   by outside parties. An unguessable id therefore doubles as the capability
+ *   to reach them, and it carries no user identifier that a public URL would
+ *   otherwise leak.
+ *
+ * The id is **derived, not drawn**: an HMAC of who owns the mount, which board
+ * and runtime it is in, and what it is called, keyed by a secret only the
+ * server holds. Randomness would be just as unguessable and was what this did
+ * first, but it made the address change every time a board was loaded — so
+ * anything outside pointing at it (a webhook configured in somebody else's
+ * product) broke on every restart, and a board could not be redeployed without
+ * reconfiguring its callers.
+ *
+ * Deriving it keeps the address stable across reloads, restarts and redeploys
+ * while keeping the secret out of the board: the board says only what the mount
+ * is *called*, which is not sensitive, and the server turns that into an
+ * address nobody can compute without the key. Rotating the key rotates every
+ * endpoint, and renaming one mount rotates only that one.
+ */
+export class MountRegistry {
+  /**
+   * Every claim to an address, oldest first. An address is derived from what
+   * the mount is called, so more than one runtime may claim the same one: a
+   * runtime rebuilt under its id claims it before the one it replaces lets
+   * go, and a board open in a client and also deployed holds two copies of
+   * each of its mounts. One claim answers — see `answering` — and the others
+   * are kept, so that releasing one leaves the address with whoever still
+   * claims it.
+   */
+  private readonly mounts = new Map<string, MountRecord[]>();
+  private readonly secret: string;
+
+  /**
+   * @param publicUrlFor Resolves a mount path to the URL clients should use.
+   *   Returns undefined before the server is listening, since the port is not
+   *   known until then.
+   * @param secret Keys the id derivation. A server that is given none draws one
+   *   for this process, which is the old behaviour: addresses that work but do
+   *   not survive a restart. `index.ts` persists one so they do.
+   */
+  constructor(
+    private readonly publicUrlFor: (mountPath: string) => string | undefined,
+    secret?: string,
+  ) {
+    this.secret = secret || randomBytes(32).toString("hex");
+  }
+
+  /**
+   * The address a given mount always gets.
+   *
+   * Every part that identifies the mount goes in, so two services cannot derive
+   * the same id: the tenant, the board, the runtime, and the mount's name. NUL
+   * separates them, as it cannot occur in any of them — the same reasoning as
+   * `tenantKey` in the server.
+   */
+  private deriveId(
+    owner: string,
+    boardName: string,
+    runtimeId: string,
+    name: string,
+  ): string {
+    return createHmac("sha256", this.secret)
+      .update([owner, boardName, runtimeId, name].join("\u0000"))
+      .digest("hex")
+      .slice(0, 32);
+  }
+
+  register(
+    owner: string,
+    runtimeId: string,
+    serviceUuid: string,
+    handlers: MountHandlers,
+    // What the mount is called, and the board's, so the address survives a
+    // reload. A service that names nothing is identified by its own uuid, which
+    // is stable in a board file too.
+    options: { boardName?: string; mountName?: string; space?: string } = {},
+  ): MountHandle | null {
+    const mountId = this.deriveId(
+      owner,
+      options.boardName ?? "",
+      runtimeId,
+      options.mountName || serviceUuid,
+    );
+    const mountPath = `${MOUNT_PREFIX}/${mountId}`;
+    const url = this.publicUrlFor(mountPath);
+    if (!url) {
+      return null;
+    }
+
+    const record: MountRecord = {
+      owner,
+      space: options.space ?? owner,
+      runtimeId,
+      serviceUuid,
+      handlers,
+    };
+    this.mounts.set(mountId, [...(this.mounts.get(mountId) ?? []), record]);
+    return {
+      url,
+      path: mountPath,
+      // This claim and no other.
+      release: () => this.drop(mountId, (claim) => claim === record),
+    };
+  }
+
+  /**
+   * The claim that answers at an address: a deployed board's before a
+   * client's, and the newest of its kind. A board somebody deployed is meant
+   * to be reachable whoever else has it open, so opening it in a client
+   * neither takes its address nor, on leaving, takes the address away.
+   */
+  private answering(mountId: string): MountRecord | undefined {
+    const claims = this.mounts.get(mountId) ?? [];
+    const deployed = claims.filter((claim) => claim.space !== claim.owner);
+    return deployed.at(-1) ?? claims.at(-1);
+  }
+
+  private drop(mountId: string, gone: (claim: MountRecord) => boolean): void {
+    const claims = this.mounts.get(mountId);
+    if (!claims) {
+      return;
+    }
+    const kept = claims.filter((claim) => !gone(claim));
+    if (kept.length === 0) {
+      this.mounts.delete(mountId);
+    } else if (kept.length !== claims.length) {
+      this.mounts.set(mountId, kept);
+    }
+  }
+
+  /**
+   * Drop every mount belonging to a runtime. Services release their own mounts
+   * on destroy; this is the backstop so a torn-down runtime can never leave a
+   * publicly reachable endpoint behind.
+   */
+  releaseRuntime(space: string, runtimeId: string): void {
+    for (const mountId of [...this.mounts.keys()]) {
+      this.drop(
+        mountId,
+        (claim) => claim.space === space && claim.runtimeId === runtimeId,
+      );
+    }
+  }
+
+  /** Drops the mounts of what a tenant's clients created; a deployed board's
+   *  go with its runtimes. */
+  releaseOwner(owner: string): void {
+    for (const mountId of [...this.mounts.keys()]) {
+      this.drop(mountId, (claim) => claim.space === owner);
+    }
+  }
+
+  get size(): number {
+    return this.mounts.size;
+  }
+
+  /** Number of live mounts for a tenant, for quota checks. */
+  countForOwner(owner: string): number {
+    let count = 0;
+    for (const claims of this.mounts.values()) {
+      count += claims.filter((claim) => claim.owner === owner).length;
+    }
+    return count;
+  }
+
+  /**
+   * Serve a request if it targets a mount. Returns false when the path is not
+   * a mount path, so the caller can fall through to the REST API.
+   */
+  handleRequest(req: IncomingMessage, res: ServerResponse): boolean {
+    const resolved = this.resolve(req.url);
+    if (!resolved) {
+      return false;
+    }
+    resolved.record.handlers.request(req, res, resolved.context);
+    return true;
+  }
+
+  /**
+   * Serve a WebSocket upgrade if it targets a mount. Returns false when the
+   * path is not a mount path. A mount without an upgrade handler still returns
+   * true — the request was addressed to it, and refusing it here is correct
+   * rather than letting it fall through to runtime socket handling.
+   */
+  handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): boolean {
+    const resolved = this.resolve(req.url);
+    if (!resolved) {
+      return false;
+    }
+    const upgrade = resolved.record.handlers.upgrade;
+    if (!upgrade) {
+      socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+      socket.destroy();
+      return true;
+    }
+    upgrade(req, socket, head, resolved.context);
+    return true;
+  }
+
+  private resolve(
+    rawUrl: string | undefined,
+  ): { record: MountRecord; context: MountContext } | null {
+    if (!rawUrl) {
+      return null;
+    }
+    // The base is a placeholder for parsing; only the path and query matter.
+    const { pathname, search } = new URL(rawUrl, "http://localhost");
+    if (!pathname.startsWith(`${MOUNT_PREFIX}/`)) {
+      return null;
+    }
+
+    const remainder = pathname.slice(MOUNT_PREFIX.length + 1);
+    const slash = remainder.indexOf("/");
+    const mountId = slash === -1 ? remainder : remainder.slice(0, slash);
+    const record = this.answering(mountId);
+    if (!record) {
+      return null;
+    }
+
+    const subPath = (slash === -1 ? "/" : remainder.slice(slash)) + search;
+    return {
+      record,
+      context: { mountPath: `${MOUNT_PREFIX}/${mountId}`, subPath },
+    };
+  }
+}

package/bundle/hkp-node/src/origins.ts

@@ -0,0 +1,201 @@
+/**
+ * Which browser pages may call this server, and when a request that carries no
+ * credential is let in.
+ *
+ * Being reachable only from this machine is not the same as being called only
+ * by this machine's owner: a page in their browser is a local caller too, and
+ * any site can address `127.0.0.1`. So a request admitted without a credential
+ * — a server running without auth — must also not come from a foreign page,
+ * and must address the server by a name the server knows. A browser states the
+ * first in `Origin` (or, on a request it sends without one, in
+ * `Sec-Fetch-Site`) and the second in `Host`; a page cannot forge either.
+ *
+ * A caller that is not a browser sends none of these, and is let in as before:
+ * another process on this machine is not what this guards against.
+ *
+ * A request a proxy passed on is never let in this way. A reverse proxy on the
+ * same host — nginx, Caddy — makes every request arrive from this machine at a
+ * name the server knows, so where it comes from says nothing any more. One
+ * that says so (`Forwarded`, `X-Forwarded-For`, `X-Real-IP`) is refused; one
+ * that says nothing cannot be told apart, which is why a loopback bind is a
+ * boundary only while nothing forwards to it.
+ *
+ * The same rule, row for row, is in hkp-rt (`lib/include/origins.h`) and
+ * hkp-python (`hkp/origins.py`).
+ */
+
+/**
+ * The origins a server was told may call it, the way `ALLOWED_ORIGINS` gives
+ * them:
+ *
+ * - `"default"` — nothing was said: the origins Readymade's own apps run from,
+ *   and any page served from this machine;
+ * - a list — exactly those;
+ * - `"*"` — any origin, for a request that carries a credential. A request
+ *   that carries none is never let in on the strength of `*`: for it, `*`
+ *   reads as nothing was said.
+ */
+export type AllowedOrigins = "default" | "*" | string[];
+
+/** Where the Readymade apps load their pages from: desktop, iOS, Android. */
+const APP_ORIGINS = [
+  "saucer://embedded",
+  "hkp://app",
+  "https://appassets.androidplatform.net",
+];
+
+/** Reads `ALLOWED_ORIGINS`. */
+export function parseAllowedOrigins(value: string | undefined): AllowedOrigins {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return "default";
+  }
+  if (trimmed === "*") {
+    return "*";
+  }
+  return trimmed
+    .split(",")
+    .map((origin) => origin.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+/**
+ * Four dot-separated numbers and nothing else. Strict, because the names this
+ * is asked about come from a request: `127.0.0.1.example.com` is a name
+ * somebody else resolves, not an address.
+ */
+function isIPv4Literal(host: string): boolean {
+  const parts = host.split(".");
+  return (
+    parts.length === 4 &&
+    parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+  );
+}
+
+function isIPv6Literal(host: string): boolean {
+  return /^\[[0-9a-f:.]*:[0-9a-f:.]*\]$/.test(host);
+}
+
+/** Splits `host[:port]` — a `Host` header, or what follows an origin's scheme. */
+function splitHostPort(value: string): { host: string } | null {
+  const match = /^(\[[^\]]*\]|[^:]+)(?::(\d+))?$/.exec(value);
+  return match ? { host: match[1].toLowerCase() } : null;
+}
+
+function isLoopbackName(host: string): boolean {
+  return (
+    host === "localhost" ||
+    host === "[::1]" ||
+    (isIPv4Literal(host) && host.startsWith("127."))
+  );
+}
+
+/** True for the origin of a page served from this machine, on any port. */
+export function isLoopbackOrigin(origin: string): boolean {
+  const match = /^https?:\/\/(.*)$/.exec(origin.toLowerCase());
+  if (!match) {
+    return false;
+  }
+  const parsed = splitHostPort(match[1]);
+  return parsed !== null && isLoopbackName(parsed.host);
+}
+
+/**
+ * True when a `Host` header names the server by something a page cannot have
+ * arranged: an address, `localhost`, or a name the server was told is its own.
+ *
+ * A page that resolves its own name to this machine (DNS rebinding) is
+ * same-origin with the server as far as the browser can tell, and sends no
+ * `Origin` to refuse — but the name it used is still in `Host`. A request
+ * without the header was not sent by a browser.
+ */
+export function isKnownHost(
+  hostHeader: string | undefined,
+  ownNames: string[],
+): boolean {
+  const value = hostHeader?.trim();
+  if (!value) {
+    return true;
+  }
+  const parsed = splitHostPort(value);
+  if (!parsed) {
+    return false;
+  }
+  const { host } = parsed;
+  if (host === "localhost" || isIPv4Literal(host) || isIPv6Literal(host)) {
+    return true;
+  }
+  return ownNames.some((name) => name !== "" && name.toLowerCase() === host);
+}
+
+/**
+ * Whether a page at `origin` may call the server with nothing but where it is
+ * calling from.
+ */
+export function allowsOriginWithoutCredential(
+  origin: string | undefined,
+  allowed: AllowedOrigins,
+): boolean {
+  const value = origin?.trim().toLowerCase();
+  if (!value) {
+    return false;
+  }
+  if (Array.isArray(allowed)) {
+    return allowed.includes(value);
+  }
+  return APP_ORIGINS.includes(value) || isLoopbackOrigin(value);
+}
+
+/**
+ * Whether a page at `origin` may read what the server answers, and call it
+ * with a credential.
+ */
+export function allowsOrigin(
+  origin: string | undefined,
+  allowed: AllowedOrigins,
+): boolean {
+  return allowed === "*" || allowsOriginWithoutCredential(origin, allowed);
+}
+
+/** What a request says about where it came from. */
+export type RequestSource = {
+  origin?: string;
+  secFetchSite?: string;
+  host?: string;
+  /** A proxy says it passed the request on; see `isForwarded`. */
+  forwarded?: boolean;
+};
+
+/** Whether a request carries a header a proxy adds when it passes one on. */
+export function isForwarded(
+  headers: Record<string, string | string[] | undefined>,
+): boolean {
+  return ["forwarded", "x-forwarded-for", "x-real-ip"].some((name) => {
+    const value = headers[name];
+    return (Array.isArray(value) ? value.join(",") : (value ?? "")).trim() !== "";
+  });
+}
+
+/**
+ * Whether a request that carries no credential may be let in on the strength
+ * of where it comes from. See the top of this file.
+ */
+export function admitsWithoutCredential(
+  source: RequestSource,
+  allowed: AllowedOrigins,
+  ownNames: string[],
+): boolean {
+  if (source.forwarded) {
+    return false;
+  }
+  if (source.origin?.trim()) {
+    if (!allowsOriginWithoutCredential(source.origin, allowed)) {
+      return false;
+    }
+  } else if (source.secFetchSite?.trim().toLowerCase() === "cross-site") {
+    // A browser leaves `Origin` off a plain GET it makes for another site's
+    // page — an image, a script — and says so here instead.
+    return false;
+  }
+  return isKnownHost(source.host, ownNames);
+}

package/bundle/hkp-node/src/reset.ts

@@ -0,0 +1,187 @@
+/**
+ * Forgetting everything one instance kept, for a fresh start.
+ *
+ * What a server restores on starting is easy to forget is there: a deployed
+ * board, a ticket to a coordinator, a table with last month's schema. When it
+ * is the cause of something, it is the last place anybody looks. Resetting
+ * moves the instance's folder aside and lets the next start begin empty.
+ *
+ * Moved, not deleted. The stale file is often exactly what is worth looking at
+ * once the problem is gone, so it is kept where it can be found:
+ *
+ *     ~/.hkp/node-<instance>.reset-2026-10-17T09-12/
+ *
+ * The name says how old it is and that nothing depends on it; deleting it is
+ * whoever reset's to do.
+ *
+ * The mount secret is carried over unless asked otherwise: it is what keeps a
+ * public endpoint's address the same, and a reset for debugging should not
+ * break a webhook somebody configured elsewhere.
+ */
+import fs from "fs";
+import path from "path";
+
+import {
+  Instance,
+  InstanceInUseError,
+  acquireInstanceLock,
+} from "./instance";
+
+const LOCK = "instance.lock";
+const MOUNT_SECRET = "mount-secret";
+
+export type ResetOptions = {
+  /** Move the folder; without it, only say what would be moved. */
+  apply?: boolean;
+  /** Leave the mount secret behind as well, which changes every mount address. */
+  includeMountSecret?: boolean;
+  /** When the reset happens; what the moved folder is named after. */
+  now?: Date;
+};
+
+export type ResetOutcome = {
+  /** Nothing there: the instance has never run, or was reset already. */
+  empty: boolean;
+  /** What is in the folder: each top-level entry and how many files it holds. */
+  entries: Array<{ name: string; files: number }>;
+  /** Where the folder goes, or went. */
+  movedTo: string;
+  /** Whether the mount secret is carried over into the fresh folder. */
+  keepsMountSecret: boolean;
+  applied: boolean;
+};
+
+function pad(value: number): string {
+  return String(value).padStart(2, "0");
+}
+
+/** `2026-10-17T09-12`, in local time: when a person reset it, as they'd say it. */
+export function resetStamp(now: Date): string {
+  return (
+    `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}` +
+    `T${pad(now.getHours())}-${pad(now.getMinutes())}`
+  );
+}
+
+/** Where the folder goes: a name not yet taken, should two resets share a minute. */
+function destination(instance: Instance, now: Date): string {
+  const base = `${instance.dir}.reset-${resetStamp(now)}`;
+  let candidate = base;
+  for (let n = 2; fs.existsSync(candidate); n++) {
+    candidate = `${base}-${n}`;
+  }
+  return candidate;
+}
+
+function countFiles(location: string): number {
+  const stat = fs.statSync(location);
+  if (!stat.isDirectory()) {
+    return 1;
+  }
+  return fs
+    .readdirSync(location)
+    .reduce((sum, entry) => sum + countFiles(path.join(location, entry)), 0);
+}
+
+/**
+ * Resets `instance`, or with `apply` unset, says what resetting it would do.
+ *
+ * Refuses — with the lock's own message — while a server runs as the
+ * instance: it holds the same state in memory and would write it back. And
+ * holds the lock itself while it works, so no server starts halfway through.
+ */
+export function resetInstance(
+  instance: Instance,
+  options: ResetOptions = {},
+): ResetOutcome {
+  const now = options.now ?? new Date();
+  const keepsMountSecret = !options.includeMountSecret;
+  const movedTo = destination(instance, now);
+
+  const names = fs.existsSync(instance.dir)
+    ? fs.readdirSync(instance.dir).filter((name) => name !== LOCK)
+    : [];
+  const entries = names.sort().map((name) => ({
+    name,
+    files: countFiles(path.join(instance.dir, name)),
+  }));
+  const outcome: ResetOutcome = {
+    empty: entries.length === 0,
+    entries,
+    movedTo,
+    keepsMountSecret,
+    applied: false,
+  };
+  if (outcome.empty) {
+    return outcome;
+  }
+
+  // Taken in a dry run too: being told what would be moved from under a
+  // running server is being told something that would not happen.
+  let release: () => void;
+  try {
+    release = acquireInstanceLock(instance);
+  } catch (error) {
+    if (error instanceof InstanceInUseError) {
+      const where = error.port ? ` on port ${error.port}` : "";
+      throw new InstanceInUseError(
+        `hkp-node instance "${instance.name}" is running (pid ${error.pid}` +
+          `${where}). Stop it before resetting it: it holds the same state ` +
+          "and would write it back.",
+        error.pid,
+        error.port,
+      );
+    }
+    throw error;
+  }
+  if (!options.apply) {
+    release();
+    return outcome;
+  }
+
+  fs.renameSync(instance.dir, movedTo);
+  // The lock went along with the folder; it was this process's and is done.
+  fs.rmSync(path.join(movedTo, LOCK), { force: true });
+
+  const secret = path.join(movedTo, MOUNT_SECRET);
+  if (keepsMountSecret && fs.existsSync(secret)) {
+    fs.mkdirSync(instance.dir, { recursive: true, mode: 0o700 });
+    fs.copyFileSync(secret, path.join(instance.dir, MOUNT_SECRET));
+    fs.chmodSync(path.join(instance.dir, MOUNT_SECRET), 0o600);
+  }
+  return { ...outcome, applied: true };
+}
+
+/** What a reset run from the command line prints, from what it did. */
+export function describeReset(
+  instance: Instance,
+  outcome: ResetOutcome,
+): string {
+  if (outcome.empty) {
+    return `Nothing to reset: ${instance.dir} holds nothing.`;
+  }
+  const lines = outcome.entries.map(
+    ({ name, files }) =>
+      `  ${name}${name === MOUNT_SECRET && outcome.keepsMountSecret ? " (copied back)" : ""}` +
+      `  — ${files} file${files === 1 ? "" : "s"}`,
+  );
+  const secret = outcome.keepsMountSecret
+    ? "The mount secret is copied back, so public endpoint addresses stay the same."
+    : "The mount secret goes too: every public endpoint address will change.";
+  if (!outcome.applied) {
+    return [
+      `Resetting instance "${instance.name}" would move ${instance.dir}`,
+      ...lines,
+      `to ${outcome.movedTo}.`,
+      secret,
+      "Nothing has been changed. Run again with --yes to reset.",
+    ].join("\n");
+  }
+  return [
+    `Reset instance "${instance.name}": moved ${instance.dir}`,
+    ...lines,
+    `to ${outcome.movedTo}.`,
+    secret,
+    "Nothing depends on the moved folder; delete it once it is of no more use.",
+  ].join("\n");
+}