@readymadeit/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,369 @@
+import { allowsOrigin, type AllowedOrigins } from "./origins";
+import { Request, Response, NextFunction } from "express";
+import jwt from "jsonwebtoken";
+import jwksClient from "jwks-rsa";
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Request {
+      authenticatedUser?: AuthenticatedUser;
+    }
+  }
+}
+
+/**
+ * Who a verified token speaks for.
+ *
+ * `email` is present only when the token carries one **and** says it is
+ * verified, and is normalised the way the lists it is compared with are. An
+ * address somebody merely typed while signing up is dropped rather than
+ * carried: everything that reads it — the server's allowlist, a board's member
+ * list, a run's caller — treats it as proof of who is asking.
+ */
+export type AuthenticatedUser = { sub: string; email?: string };
+
+/** An email as the lists it is compared with keep it. */
+export function normalizeEmail(email: string): string {
+  return email.trim().toLowerCase();
+}
+
+/**
+ * Owner key used when authentication is disabled. Every request collapses into
+ * this single tenant, which is exactly the pre-multi-tenancy behaviour.
+ */
+export const ANONYMOUS_SUB = "anonymous";
+
+/**
+ * The tenant a request belongs to. Runtimes are namespaced by this key, so a
+ * runtime id is only ever resolved within the caller's own namespace.
+ */
+export function ownerKeyOf(user: AuthenticatedUser | undefined): string {
+  return user?.sub ?? ANONYMOUS_SUB;
+}
+
+export type AuthMiddleware = (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) => void | Promise<void>;
+
+/**
+ * How requests are authenticated.
+ *
+ * - `jwt`  — verify an Auth0 bearer token against the JWKS for `domain`/`audience`.
+ *   When `allowedEmails` is set, owning anything here — a runtime, a board —
+ *   additionally takes a **verified** `email` claim that is on the list. It
+ *   gates who may own, not who may be identified: a deployed board's member
+ *   list admits people the allowlist does not name, to that board only.
+ *
+ *   `audience` may list several accepted values. The frontend sends its id_token,
+ *   whose `aud` is the Auth0 *client id* of whichever application signed the user
+ *   in — and the web and native apps must be separate Auth0 applications (only a
+ *   SPA-type one can do the browser flows, only a Native-type one the RFC 8252
+ *   flow). One runtime serves users from both, so it accepts both client ids.
+ * - `none` — accept everything (no identity). Only ever resolved for a local
+ *   development checkout that opts in via ALLOW_NO_AUTH; the published npm
+ *   package never runs in this mode (see resolveServerAuthConfig in index.ts).
+ */
+export type AuthConfig =
+  | {
+      mode: "jwt";
+      domain: string;
+      audience: string | string[];
+      allowedEmails?: string[];
+      /**
+       * Where the issuer's signing keys are published. Unset is Auth0's
+       * `https://<domain>/.well-known/jwks.json`; tests point it at keys they
+       * hold. The issuer a token must name stays `https://<domain>/` either way.
+       * Verification is the real one, only the keys are the harness's. The
+       * server sets it only from `HKP_TEST_JWKS_URI`, which it takes only from
+       * a checkout and only on loopback (`testJwksUri` in index.ts).
+       */
+      jwksUri?: string;
+    }
+  | { mode: "none" };
+
+/**
+ * Resolves an opaque (non-JWT) bearer token to a principal, or null if unknown.
+ * Used for coordinator **session tokens**: short random strings the runtime
+ * itself mints (gated by a user JWT) and hands to the coordinator, so the
+ * coordinator can make long-lived machine calls on that user's behalf without a
+ * user JWT that would expire. The token resolves back to the user it was minted
+ * for, so there is no unscoped "service" superuser.
+ */
+export type OpaqueTokenResolver = (
+  token: string,
+) => AuthenticatedUser | null;
+
+export type AuthenticatorOptions = {
+  resolveOpaqueToken?: OpaqueTokenResolver;
+};
+
+/**
+ * Resolved auth surface shared by HTTP and WebSocket entry points so both apply
+ * the exact same checks.
+ */
+export type Authenticator = {
+  /**
+   * Express middleware for HTTP routes: `authorizeOwner` on the bearer token.
+   * Sets req.authenticatedUser on success.
+   */
+  middleware: AuthMiddleware;
+  /**
+   * Who a raw token speaks for, and nothing about what they may do: signature,
+   * issuer, audience and `sub`, with the email only when it is verified. For
+   * the paths that decide access by something narrower than the server's
+   * allowlist — a deployed board's member list.
+   */
+  identifyToken(
+    token: string | undefined | null,
+  ): Promise<AuthenticatedUser | null>;
+  /**
+   * `identifyToken`, then the server's allowlist: whether this person may own
+   * things here — runtimes, boards. What every route uses unless it says
+   * otherwise. The token is a raw string, from a WebSocket `?access_token=`
+   * query param or an Authorization bearer value.
+   */
+  authorizeOwner(
+    token: string | undefined | null,
+  ): Promise<AuthenticatedUser | null>;
+};
+
+/**
+ * Email-allowlist gate applied after signature verification. Fail closed: when
+ * a list is configured, a token without an `email` claim — or with an
+ * unverified one — is rejected, because on tenants that allow self-signup an
+ * attacker could otherwise register an allowlisted address without owning it.
+ */
+export function isEmailAllowed(
+  claims: { [claim: string]: unknown },
+  allowedEmails: string[] | undefined,
+): boolean {
+  if (!allowedEmails) {
+    return true;
+  }
+  const email = ownClaim(claims, "email");
+  if (typeof email !== "string" || ownClaim(claims, "email_verified") !== true) {
+    return false;
+  }
+  return allowedEmails.includes(normalizeEmail(email));
+}
+
+/**
+ * A claim the token itself carries. What the claims object inherits is not
+ * something the token says, so a value written onto `Object.prototype` by
+ * anything in the process cannot become somebody's identity.
+ */
+function ownClaim(claims: { [claim: string]: unknown }, name: string): unknown {
+  return Object.hasOwn(claims, name) ? claims[name] : undefined;
+}
+
+/**
+ * The allowlist asked of somebody already identified. An identity carries an
+ * email only when it was verified, so this is `isEmailAllowed` without the
+ * claims.
+ */
+export function mayOwn(
+  user: AuthenticatedUser,
+  allowedEmails: string[] | undefined,
+): boolean {
+  if (!allowedEmails) {
+    return true;
+  }
+  return !!user.email && allowedEmails.includes(user.email);
+}
+
+/** What a token's claims say about who it speaks for, or null without a `sub`. */
+export function identityFromClaims(claims: {
+  [claim: string]: unknown;
+}): AuthenticatedUser | null {
+  const sub = ownClaim(claims, "sub");
+  if (typeof sub !== "string" || !sub) {
+    return null;
+  }
+  // Dropped, not refused: a person whose address is unverified can still sign
+  // in wherever no list is asked, and is simply nobody's listed member.
+  const email = ownClaim(claims, "email");
+  const verified = ownClaim(claims, "email_verified") === true;
+  const address =
+    typeof email === "string" && verified ? normalizeEmail(email) : "";
+  return { sub, ...(address ? { email: address } : {}) };
+}
+
+function createJwtVerifier(
+  domain: string,
+  audience: string | string[],
+  jwksUri = `https://${domain}/.well-known/jwks.json`,
+): (token: string) => Promise<AuthenticatedUser | null> {
+  // An empty `audience` makes jwt.verify skip the check altogether, which would
+  // accept a token minted for any application in the tenant. Refusing to build a
+  // verifier that cannot check is the fail-closed reading, and it also gives the
+  // non-empty list jsonwebtoken's own typing asks for.
+  const audiences = (Array.isArray(audience) ? audience : [audience]).filter(
+    Boolean,
+  );
+  if (!audiences.length) {
+    throw new Error(
+      "JWT authentication needs at least one accepted audience (AUTH0_AUDIENCE)",
+    );
+  }
+  const expected = audiences as [string, ...string[]];
+
+  const client = jwksClient({
+    jwksUri,
+    cache: true,
+    rateLimit: true,
+  });
+
+  function getSigningKey(
+    header: jwt.JwtHeader,
+    callback: jwt.SigningKeyCallback,
+  ) {
+    client.getSigningKey(header.kid, (err, key) => {
+      if (err) {
+        callback(err);
+        return;
+      }
+      callback(null, key?.getPublicKey());
+    });
+  }
+
+  return (token: string) =>
+    new Promise<AuthenticatedUser | null>((resolve) => {
+      // The same checks in every runtime (hkp-python's auth.py, hkp-rt's
+      // http/auth.cpp, the website's auth.php): RS256 only, the issuer the
+      // keys came from, one of the accepted audiences, and an expiry that must
+      // be there — jsonwebtoken checks one only when it is present — within a
+      // minute of clock skew. The subject is asked by identityFromClaims.
+      jwt.verify(
+        token,
+        getSigningKey,
+        {
+          audience: expected,
+          issuer: `https://${domain}/`,
+          algorithms: ["RS256"],
+          clockTolerance: 60,
+        },
+        (err, decoded) => {
+          if (
+            err ||
+            !decoded ||
+            typeof decoded === "string" ||
+            typeof ownClaim(decoded, "exp") !== "number"
+          ) {
+            resolve(null);
+            return;
+          }
+          resolve(identityFromClaims(decoded));
+        },
+      );
+    });
+}
+
+export function createAuthenticator(
+  config: AuthConfig,
+  options: AuthenticatorOptions = {},
+): Authenticator {
+  if (config.mode === "none") {
+    return {
+      // Identity is irrelevant in no-auth mode, but tenant resolution still
+      // needs a principal, so set the same stable one both entry points use.
+      // Everything then lands in a single "anonymous" namespace.
+      middleware: (req, _res, next) => {
+        req.authenticatedUser = { sub: ANONYMOUS_SUB };
+        next();
+      },
+      identifyToken: async () => ({ sub: ANONYMOUS_SUB }),
+      authorizeOwner: async () => ({ sub: ANONYMOUS_SUB }),
+    };
+  }
+
+  const verify = createJwtVerifier(config.domain, config.audience, config.jwksUri);
+
+  const identifyToken = async (
+    token: string | undefined | null,
+  ): Promise<AuthenticatedUser | null> => {
+    if (!token) {
+      return null;
+    }
+    // Session tokens are opaque and resolve locally without a network round-trip,
+    // so check them before falling back to JWT verification.
+    const opaque = options.resolveOpaqueToken?.(token);
+    if (opaque) {
+      return opaque;
+    }
+    return verify(token);
+  };
+
+  const authorizeOwner = async (
+    token: string | undefined | null,
+  ): Promise<AuthenticatedUser | null> => {
+    if (!token) {
+      return null;
+    }
+    // A session token was minted for somebody who had passed the allowlist,
+    // and carries no email to ask it of again.
+    const opaque = options.resolveOpaqueToken?.(token);
+    if (opaque) {
+      return opaque;
+    }
+    const user = await verify(token);
+    return user && mayOwn(user, config.allowedEmails) ? user : null;
+  };
+
+  return {
+    middleware: (req, res, next) => {
+      const header = req.headers.authorization;
+      if (!header?.startsWith("Bearer ")) {
+        res.sendStatus(401);
+        return;
+      }
+      void authorizeOwner(header.slice(7)).then((user) => {
+        if (!user) {
+          res.sendStatus(401);
+          return;
+        }
+        req.authenticatedUser = user;
+        next();
+      });
+    },
+    identifyToken,
+    authorizeOwner,
+  };
+}
+
+export type { AllowedOrigins } from "./origins";
+
+/**
+ * True when the bind address is reachable only from the local machine. A
+ * loopback bind keeps other machines out — nothing off-machine can connect —
+ * which is why running without authentication is permitted there. It does not
+ * keep out a page in a browser on this machine; origins.ts does.
+ */
+export function isLoopbackHost(host: string): boolean {
+  const h = host.trim().toLowerCase();
+  return (
+    h === "localhost" || h === "::1" || h === "[::1]" || h.startsWith("127.")
+  );
+}
+
+/**
+ * Cross-Site WebSocket Hijacking protection, for an upgrade that carries a
+ * credential. Browsers always send an Origin header on the WS handshake, so a
+ * mismatched one is a cross-site attempt and is rejected. Non-browser clients
+ * (e.g. the coordinator) send no Origin; they are allowed through here and
+ * gated by the token check instead.
+ *
+ * An upgrade that carries no credential is asked more of; see
+ * `admitsWithoutCredential` in origins.ts.
+ */
+export function isOriginAllowed(
+  origin: string | undefined,
+  allowed: AllowedOrigins,
+): boolean {
+  if (origin === undefined) {
+    return true;
+  }
+  return allowsOrigin(origin, allowed);
+}

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

@@ -0,0 +1,281 @@
+/**
+ * What a call report says of the value a service was called with, or produced.
+ *
+ * Every call is bracketed by a pair of reports (`call-process`,
+ * `call-process-finished`), and each carries the value — what the flow
+ * inspector shows of the call. That value travels wherever the reports do: to
+ * every client watching the runtime and, on a deployed board, to its
+ * coordinator, whose frame limit drops a message above 64 MiB and closes the
+ * connection a little above that. A value that never leaves its runtime would
+ * still leave it as a report, once for every service it passes through.
+ *
+ * So a report carries a value only up to `CALL_REPORT_LIMIT`. Above it, a
+ * description takes its place — what it is, how large, and how it begins —
+ * which the inspector shows and will not run again. The same limit, and the
+ * same description, in every runtime: `call_report.py` in hkp-python,
+ * `call_report.h` in hkp-rt, and this file in hkp-node (`src/callReport.ts`)
+ * and hkp-frontend (`src/runtime/callReport.ts`), kept identical.
+ *
+ * Measuring stops once the limit is passed, so a value of a hundred megabytes
+ * costs no more to judge than one of five. A size counted only that far is said
+ * to be not `exact`.
+ *
+ * **And only while the board is captured.** What passes between the services
+ * of a run is private; only what a board outputs is public. So a report
+ * carries its value only in Capture mode — switched on by someone building the
+ * board, never saved — and otherwise says only that the call happened and,
+ * when it ended, whether it passed nothing on (`stopped`). See
+ * `outgoingPayload`, and `plans/TODO-CAPTURE-MODE.md`.
+ */
+
+/** The most a report carries of one value: 5 MiB. */
+export const CALL_REPORT_LIMIT = 5 * 1024 * 1024;
+
+/** How much of a value too large to report its description begins with. */
+export const PREVIEW_LENGTH = 1024;
+
+/** What stands in a report for a value too large to carry. */
+export type TooLarge = {
+  __hkpTooLarge: {
+    type: "string" | "json" | "binary";
+    /** At least this many bytes; all of them when `exact`. */
+    bytes: number;
+    exact: boolean;
+    /** How it begins, as text; none for bytes. */
+    preview?: string;
+  };
+};
+
+/** Whether a reported value is the description of one too large to carry. */
+export function isTooLarge(value: unknown): value is TooLarge {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.prototype.hasOwnProperty.call(value, "__hkpTooLarge")
+  );
+}
+
+/**
+ * A notification's payload as it may leave for anyone listening: a call
+ * report carrying its value only while `capture` is on, and then no more of it
+ * than `reportedValue` allows; every other payload as it is.
+ */
+export function outgoingPayload(payload: unknown, capture: boolean): unknown {
+  if (!payload || typeof payload !== "object") {
+    return payload;
+  }
+  const internal = (payload as { __internal?: unknown }).__internal;
+  if (!internal || typeof internal !== "object") {
+    return payload;
+  }
+  const { data, ...report } = internal as Record<string, unknown>;
+  if (report.state !== "call-process" && report.state !== "call-process-finished") {
+    return payload;
+  }
+  const carried = capture
+    ? "data" in internal
+      ? { ...report, data: reportedValue(data) }
+      : report
+    : report.state === "call-process-finished" &&
+        (data === null || data === undefined)
+      ? { ...report, stopped: true }
+      : report;
+  return { ...payload, __internal: carried };
+}
+
+/** `value` as a report may carry it: itself, or its description. */
+export function reportedValue(
+  value: unknown,
+  limit: number = CALL_REPORT_LIMIT,
+): unknown {
+  if (typeof value === "string") {
+    const bytes = utf8LengthUpTo(value, limit);
+    // A text longer than the limit in characters is not counted in bytes.
+    return bytes > limit
+      ? tooLarge("string", bytes, value.length <= limit, head(value))
+      : value;
+  }
+  if (isBinary(value)) {
+    const bytes = value.byteLength;
+    return bytes > limit ? tooLarge("binary", bytes, true) : value;
+  }
+  if (!Array.isArray(value) && !isPlainObject(value)) {
+    return value;
+  }
+  const bytes = sizeUpTo(value, limit);
+  return bytes > limit ? tooLarge("json", bytes, false, preview(value)) : value;
+}
+
+function tooLarge(
+  type: TooLarge["__hkpTooLarge"]["type"],
+  bytes: number,
+  exact: boolean,
+  preview?: string,
+): TooLarge {
+  return {
+    __hkpTooLarge: {
+      type,
+      bytes,
+      exact,
+      ...(preview !== undefined ? { preview } : {}),
+    },
+  };
+}
+
+function isBinary(value: unknown): value is ArrayBufferView | ArrayBuffer {
+  return ArrayBuffer.isView(value) || value instanceof ArrayBuffer;
+}
+
+/**
+ * Whether `value` is data written as an object literal, rather than an
+ * instance of something. Only those are looked inside: an instance may hold a
+ * whole graph of references — back to its app, in a cycle — none of which is
+ * the value a service passed on.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/** Counted, and shown, as this much and no more: see `isPlainObject`. */
+const OPAQUE_SIZE = 16;
+
+/**
+ * The UTF-8 length of `text`, counted no further than `budget`: a text with
+ * more characters than that is past it already, whatever they encode to, and
+ * is answered with its character count.
+ */
+function utf8LengthUpTo(text: string, budget: number): number {
+  if (text.length > budget) {
+    return text.length;
+  }
+  let bytes = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code < 0x80) {
+      bytes += 1;
+    } else if (code < 0x800) {
+      bytes += 2;
+    } else if (code >= 0xd800 && code <= 0xdbff) {
+      // A surrogate pair: one character of four bytes.
+      bytes += 4;
+      i++;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+}
+
+/**
+ * What `value` takes as compact JSON, near enough, counted until it passes
+ * `budget`. A container's own brackets and commas are counted before what is
+ * in it, so a list of a million items is past a small budget without one of
+ * them being visited.
+ */
+function sizeUpTo(value: unknown, budget: number): number {
+  let total = 0;
+  const pending: unknown[] = [value];
+  while (pending.length > 0 && total <= budget) {
+    const next = pending.pop();
+    if (typeof next === "string") {
+      total += utf8LengthUpTo(next, budget - total) + 2;
+    } else if (typeof next === "number" || typeof next === "bigint") {
+      total += String(next).length;
+    } else if (typeof next === "boolean") {
+      total += next ? 4 : 5;
+    } else if (next === null || next === undefined) {
+      total += 4;
+    } else if (isBinary(next)) {
+      total += next.byteLength;
+    } else if (Array.isArray(next)) {
+      total += 2 + Math.max(0, next.length - 1);
+      if (total > budget) {
+        break;
+      }
+      for (const item of next) {
+        pending.push(item);
+      }
+    } else if (isPlainObject(next)) {
+      total += 2;
+      for (const key in next) {
+        if (!Object.prototype.hasOwnProperty.call(next, key)) {
+          continue;
+        }
+        total += utf8LengthUpTo(key, budget - total) + 4;
+        if (total > budget) {
+          break;
+        }
+        pending.push(next[key]);
+      }
+    } else {
+      total += OPAQUE_SIZE;
+    }
+  }
+  return total;
+}
+
+/** The beginning of `text`, never ending on half a surrogate pair. */
+function head(text: string, length: number = PREVIEW_LENGTH): string {
+  if (text.length <= length) {
+    return text;
+  }
+  const last = text.charCodeAt(length - 1);
+  return text.slice(0, last >= 0xd800 && last <= 0xdbff ? length - 1 : length);
+}
+
+/**
+ * How `value` begins, as compact JSON of at most `PREVIEW_LENGTH` characters
+ * and an ellipsis — written only that far, never the whole of it.
+ */
+function preview(value: unknown): string {
+  let out = "";
+  // False once the preview is full: nothing more is written, not even the
+  // brackets that would close what was begun.
+  const write = (item: unknown): boolean => {
+    if (out.length >= PREVIEW_LENGTH) {
+      return false;
+    }
+    if (typeof item === "string") {
+      out += JSON.stringify(head(item, PREVIEW_LENGTH - out.length));
+    } else if (isBinary(item)) {
+      out += `"<${item.byteLength} bytes>"`;
+    } else if (Array.isArray(item)) {
+      out += "[";
+      for (let i = 0; i < item.length; i++) {
+        if (i > 0) {
+          out += ",";
+        }
+        if (!write(item[i])) {
+          return false;
+        }
+      }
+      out += "]";
+    } else if (isPlainObject(item)) {
+      out += "{";
+      let first = true;
+      for (const key in item) {
+        if (!Object.prototype.hasOwnProperty.call(item, key)) {
+          continue;
+        }
+        out += `${first ? "" : ","}${JSON.stringify(key)}:`;
+        first = false;
+        if (!write(item[key])) {
+          return false;
+        }
+      }
+      out += "}";
+    } else if (item !== null && typeof item === "object") {
+      out += `"<${item.constructor?.name ?? "object"}>"`;
+    } else {
+      out += JSON.stringify(item) ?? "null";
+    }
+    return out.length < PREVIEW_LENGTH;
+  };
+  const complete = write(value);
+  return complete ? out : `${head(out)}…`;
+}