@uniflowed/router 0.0.0-alpha.12 → 0.0.0-alpha.14

package/internal/action-wire.js

@@ -0,0 +1,382 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: what a server action's arguments and its
+// result are allowed to be.
+//
+// A `"use server"` export is a public HTTP endpoint from the moment it exists.
+// The one decision that makes it a feature rather than a remote-code-execution
+// surface is what the bytes on the wire are permitted to become, and this
+// module is that decision, written once and applied on both sides of it.
+//
+// # The boundary
+//
+// **A server action's arguments are plain JSON data and nothing else.**
+//
+// One JSON object, `{"args": [...]}`, at most `MAX_ACTION_BODY_BYTES` of valid
+// UTF-8, holding at most `MAX_ACTION_ARGUMENTS` values, nested at most
+// `MAX_ACTION_DEPTH` deep, with at most `MAX_ACTION_VALUES` values in total.
+// Each of those values is `null`, a boolean, a finite number, a string, an
+// array of them, or a plain object whose keys are ordinary strings. The result
+// travels back under exactly the same grammar, plus `undefined` for an action
+// that returns nothing.
+//
+// Nothing in a payload can name a function, a module, a class, a prototype, a
+// React element, an id or a reference, and nothing in it is revived into an
+// object the sender chose. `decodeActionArguments` produces values a
+// `JSON.parse` already produced; what this adds is the refusal of everything
+// `JSON.parse` would have let through — which is the whole of what a decoder
+// has to get right.
+//
+// # What is deliberately absent, and why
+//
+// * **A reference format.** React's Flight payload can carry a reference to a
+//   client module, a promise, or an element, and a decoder that reconstructs
+//   those is a decoder that constructs attacker-chosen objects. uf has no such
+//   payload (ubugeeei-prod/uf#252) and this grammar is not the place to grow
+//   one quietly.
+// * **Class instances, `Map`, `Set`, `Date`, `RegExp`, typed arrays.** Each
+//   would need a tag in the payload saying which constructor to call, and a
+//   tag naming a constructor is the oracle every deserialisation CVE is made
+//   of. An action that wants a date takes an ISO string and parses it, where
+//   the parse is the application's and is checked.
+// * **`FormData` and `<form action={fn}>`.** Multipart parsing is its own
+//   attack surface with its own bounds, and a form post is a *simple* CORS
+//   request — it reaches a server with the visitor's cookies and no preflight.
+//   Both are worth having and neither is worth having by accident; see the
+//   security note in `./action-endpoint.js`.
+// * **Cycles and shared references.** A value that refers to itself is
+//   rejected rather than encoded, because the alternative is a marker in the
+//   payload that says "this is the object you saw earlier", which is a
+//   reference format by another name.
+//
+// # Why the same module runs on both sides
+//
+// The browser refuses to *send* what the server would refuse to receive, so a
+// value that cannot cross is a mistake at the call site with the argument's
+// position in the message, rather than a 400 with nothing in it. Two
+// implementations of one grammar is how the two come to disagree, and the
+// side that is lenient is always the server.
+//
+// Pure: no imports, no platform APIs beyond `JSON`, so the browser half of
+// `@uniflowed/router` can reach it without reaching anything server-only.
+
+/** The request header carrying the action id. */
+export const ACTION_HEADER: string = "uf-action";
+
+/**
+ * The only content type an action call may be sent with.
+ *
+ * Not decoration. `application/json` is not one of the three types a form can
+ * produce, so a cross-origin `<form>` — which is sent with the visitor's
+ * cookies and no preflight — cannot reach the decoder at all. It is the second
+ * of the three independent things standing between this endpoint and a CSRF,
+ * the others being the `Origin` check and `ACTION_HEADER` itself, which is a
+ * header no simple request may carry.
+ */
+export const ACTION_CONTENT_TYPE: string = "application/json";
+
+/** Largest request body the endpoint will read, in bytes. */
+export const MAX_ACTION_BODY_BYTES: number = 1024 * 1024;
+
+/** Most positional arguments an action may be called with. */
+export const MAX_ACTION_ARGUMENTS: number = 16;
+
+/** Deepest nesting a payload may have. */
+export const MAX_ACTION_DEPTH: number = 24;
+
+/** Most values, of any kind, one payload may hold. */
+export const MAX_ACTION_VALUES: number = 10000;
+
+/**
+ * Everything that may cross the wire.
+ *
+ * Recursive on purpose, and closed on purpose: this type is what
+ * `ServerActionBoundary` in `../action.js` holds every action's parameters and
+ * return value against, so an action that takes a `Map` is a `uf check` error
+ * rather than a request that arrives with an empty object in it.
+ */
+export type ActionValue =
+  | null
+  | boolean
+  | number
+  | string
+  | $ReadOnlyArray<ActionValue>
+  | { readonly [string]: ActionValue };
+
+/**
+ * A value that is outside the grammar, and where in the payload it was.
+ *
+ * Thrown on the browser side, where the path is the argument the caller
+ * passed. On the server side it is caught and becomes a `400` with none of
+ * this in it: the sender does not get told which part of what they sent was
+ * the part that was refused.
+ */
+export class ActionValueError extends Error {
+  /** Where in the payload the offending value sat, e.g. `argument 2.name`. */
+  path: string;
+
+  constructor(path: string, reason: string) {
+    super(`@uniflowed/router: ${path} ${reason}.`);
+    this.name = "ActionValueError";
+    this.path = path;
+  }
+}
+
+/**
+ * Keys that are never a property in this grammar.
+ *
+ * `JSON.parse` gives `__proto__` an *own* data property rather than changing
+ * the prototype, so a payload carrying one is not itself pollution — it
+ * becomes pollution in the first line of application code that spreads or
+ * merges it. Refused here, where there is one place to refuse it, rather than
+ * left for every action to remember. `uf_pm::detect` draws the same line for
+ * manifest JSON.
+ */
+const FORBIDDEN_KEYS: $ReadOnlyArray<string> = ["__proto__", "constructor", "prototype"];
+
+/**
+ * Whether an object is one this grammar carries.
+ *
+ * The prototype is compared, not `instanceof` and not a duck-type: a class
+ * instance, a `Map`, a `Date` and a React element all pass every structural
+ * test somebody might reach for, and each of them loses its meaning on the
+ * wire. `Object.create(null)` is accepted because it is what a careful caller
+ * builds and what this module's own decoder could produce.
+ */
+function isPlainObject(value: interface {}): boolean {
+  const prototype: mixed = Object.getPrototypeOf(value);
+  return prototype === PLAIN_PROTOTYPE || prototype === null;
+}
+
+/**
+ * The prototype every object literal has, captured rather than named.
+ *
+ * `Object.prototype` is not on Flow's `Object` statics, and the usual
+ * substitute — asking whether the prototype's own prototype is `null` — also
+ * accepts `Object.create(Object.create(null))`, which is a different set of
+ * values. One `{}` at module scope is the exact answer and costs nothing.
+ */
+const PLAIN_PROTOTYPE: mixed = Object.getPrototypeOf({});
+
+/** One entry of the explicit walk stack. */
+type Pending = {| readonly value: mixed, readonly path: string, readonly depth: number |};
+
+/**
+ * Refuse a value that cannot cross the wire, naming where it was.
+ *
+ * An explicit stack rather than recursion, for the reason the RSC graph walk
+ * gives: a payload arrives from the network, its nesting is the sender's
+ * choice, and a recursive walk over it is a stack overflow with an attacker's
+ * hand on the depth. Every bound is checked as the walk runs rather than
+ * afterwards, so a payload that busts one is refused before the rest of it is
+ * visited.
+ */
+export function checkActionValue(root: mixed, label: string): void {
+  const stack: Array<Pending> = [{ value: root, path: label, depth: 0 }];
+  const seen = new Set<mixed>();
+  let remaining = MAX_ACTION_VALUES;
+
+  while (stack.length > 0) {
+    const pending = stack.pop();
+    if (pending == null) {
+      break;
+    }
+    const { value, path, depth } = pending;
+
+    remaining -= 1;
+    if (remaining < 0) {
+      throw new ActionValueError(label, `holds more than ${String(MAX_ACTION_VALUES)} values`);
+    }
+    if (depth > MAX_ACTION_DEPTH) {
+      throw new ActionValueError(path, `is nested deeper than ${String(MAX_ACTION_DEPTH)}`);
+    }
+
+    if (value === null) {
+      continue;
+    }
+    const kind = typeof value;
+    if (kind === "boolean" || kind === "string") {
+      continue;
+    }
+    if (kind === "number") {
+      // `NaN` and the infinities have no JSON spelling; `JSON.stringify` writes
+      // `null` for each, so accepting one here would mean an action was called
+      // with a different number from the one the caller passed.
+      if (!Number.isFinite(value)) {
+        throw new ActionValueError(path, "is not a finite number");
+      }
+      continue;
+    }
+    if (kind !== "object") {
+      // `undefined`, a function, a symbol, a bigint. Named rather than
+      // lumped together, because "a function cannot cross" is the sentence
+      // that tells a caller they passed a callback to a server action.
+      throw new ActionValueError(path, `is a ${kind}, which cannot cross to a server action`);
+    }
+
+    const object: interface {} = value as $FlowFixMe;
+    if (seen.has(object)) {
+      throw new ActionValueError(path, "refers to a value that already appeared in the payload");
+    }
+    seen.add(object);
+
+    if (Array.isArray(object)) {
+      const items: $ReadOnlyArray<mixed> = object as $FlowFixMe;
+      for (let index = 0; index < items.length; index += 1) {
+        stack.push({ value: items[index], path: `${path}[${String(index)}]`, depth: depth + 1 });
+      }
+      continue;
+    }
+
+    if (!isPlainObject(object)) {
+      throw new ActionValueError(
+        path,
+        "is a class instance, a Map, a Set, a Date, a React element or another object with a " +
+          "prototype, and only arrays and plain objects cross to a server action",
+      );
+    }
+
+    // Symbol keys are silently dropped by `JSON.stringify`, so a payload built
+    // with one would arrive missing a property nobody could see was missing.
+    if (Object.getOwnPropertySymbols(object).length > 0) {
+      throw new ActionValueError(path, "has a symbol key, which has no spelling on the wire");
+    }
+
+    const record: { readonly [string]: mixed } = object as $FlowFixMe;
+    for (const key of Object.getOwnPropertyNames(object)) {
+      if (FORBIDDEN_KEYS.includes(key)) {
+        throw new ActionValueError(`${path}.${key}`, "is a key this grammar never carries");
+      }
+      stack.push({ value: record[key], path: `${path}.${key}`, depth: depth + 1 });
+    }
+  }
+}
+
+/**
+ * The request body for a call, or a named failure.
+ *
+ * The browser's half. Refusing here is what turns "the server answered 400"
+ * into "argument 2.createdAt is a class instance", at the call site, with a
+ * stack that reaches the component.
+ */
+export function encodeActionArguments(args: $ReadOnlyArray<mixed>): string {
+  if (args.length > MAX_ACTION_ARGUMENTS) {
+    throw new ActionValueError(
+      "the call",
+      `passes ${String(args.length)} arguments, and an action takes at most ` +
+        String(MAX_ACTION_ARGUMENTS),
+    );
+  }
+  for (let index = 0; index < args.length; index += 1) {
+    checkActionValue(args[index], `argument ${String(index + 1)}`);
+  }
+  return JSON.stringify({ args });
+}
+
+/**
+ * The arguments a request body holds, or a named failure.
+ *
+ * The server's half, and the one that faces the network. The shape is exact —
+ * one object, one key — because a payload with a key nobody reads is a payload
+ * whose sender believed something about it that is not true, and because the
+ * only way to keep this closed as it grows is to refuse anything that is not
+ * this today.
+ */
+export function decodeActionArguments(text: string): Array<ActionValue> {
+  let parsed: mixed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new ActionValueError("the body", "is not JSON");
+  }
+  if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new ActionValueError("the body", "is not a JSON object");
+  }
+  const keys: $ReadOnlyArray<string> = Object.getOwnPropertyNames(parsed);
+  if (keys.length !== 1 || keys[0] !== "args") {
+    throw new ActionValueError("the body", 'has keys other than "args"');
+  }
+  const args: mixed = parsed.args;
+  if (!Array.isArray(args)) {
+    throw new ActionValueError("the body", 'has an "args" that is not an array');
+  }
+  if (args.length > MAX_ACTION_ARGUMENTS) {
+    throw new ActionValueError(
+      "the body",
+      `passes more than ${String(MAX_ACTION_ARGUMENTS)} arguments`,
+    );
+  }
+  for (let index = 0; index < args.length; index += 1) {
+    checkActionValue(args[index], `argument ${String(index + 1)}`);
+  }
+  return args as $FlowFixMe;
+}
+
+/**
+ * The response body for a result, or a named failure.
+ *
+ * An action that returns nothing answers `{}` rather than `{"value":null}`:
+ * JSON has no `undefined`, and turning one into `null` would make an action
+ * declared `Promise<void>` resolve to something on the browser side.
+ */
+export function encodeActionResult(value: mixed): string {
+  if (value === undefined) {
+    return "{}";
+  }
+  checkActionValue(value, "the result");
+  return JSON.stringify({ value });
+}
+
+/**
+ * The result a response body holds, or a named failure.
+ *
+ * The same grammar in the other direction, and checked rather than trusted:
+ * the browser is talking to whatever answered, which on a compromised network
+ * is not the server. What it can be handed is therefore data and never an
+ * object of somebody's choosing, exactly as on the way out.
+ */
+export function decodeActionResult(text: string): ActionValue | void {
+  let parsed: mixed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new ActionValueError("the answer", "is not JSON");
+  }
+  if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new ActionValueError("the answer", "is not a JSON object");
+  }
+  const keys: $ReadOnlyArray<string> = Object.getOwnPropertyNames(parsed);
+  if (keys.length === 0) {
+    return undefined;
+  }
+  if (keys.length !== 1 || keys[0] !== "value") {
+    throw new ActionValueError("the answer", 'has keys other than "value"');
+  }
+  const value: mixed = parsed.value;
+  checkActionValue(value, "the result");
+  return value as $FlowFixMe;
+}
+
+/**
+ * Whether `text` is the canonical spelling of an action id.
+ *
+ * Sixty-four lowercase hexadecimal characters, which is what
+ * `uf_rsc::ActionId::to_hex` writes. Checked before the id reaches the table
+ * so an oversized or repeated header cannot make the endpoint do work, and
+ * hand-written rather than a regular expression because this reads a header a
+ * client chose (`docs/security.md`, rule 5).
+ */
+export function isActionId(text: string): boolean {
+  if (text.length !== 64) {
+    return false;
+  }
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+    const digit = code >= 0x30 && code <= 0x39;
+    const lower = code >= 0x61 && code <= 0x66;
+    if (!digit && !lower) {
+      return false;
+    }
+  }
+  return true;
+}

package/internal/diagnostics.js

@@ -0,0 +1,169 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the way a diagnostic the browser produced
+// reaches the terminal.
+//
+// Every other uf diagnostic — a type error, a lint finding, a failing test, a
+// page that rendered its error boundary — arrives in the terminal the
+// developer already has open. One produced *in the browser* had nowhere to go:
+// the page is the only process that knows about it, and `uf dev`'s diagnostics
+// come up the driver's event channel from the Node process. So the hydration
+// report added in ubugeeei-prod/uf#582 lived in a browser overlay and in the
+// console, which has to be noticed, in a window that may not be in front, by
+// somebody who does not know to look. See ubugeeei-prod/uf#583.
+//
+// This is the client half. The server half is `uf dev`, through
+// `@uniflowed/vite`'s `internal/diagnostics.js`, which turns what arrives into
+// the same rendering the terminal gives everything else: a severity, the page
+// it came from, and a code frame when there is a position to draw one around.
+//
+// # One channel, and why the poster is not shared
+//
+// `/__uf/diagnostic` and `/__uf/vitals` are one channel: two paths, one payload
+// shape, one `diagnostic` event out of the driver, one renderer. What is *not*
+// shared is the twenty lines that post to it. `@uniflowed/web/vitals` has its
+// own `vitalsBeacon`, and this is the router's.
+//
+// `@uniflowed/hmr` would have been the tidier home — it is already "the browser
+// half of `uf dev`" — and it cannot be one. `tools/ci/publishable.sh` refuses a
+// published package that depends on an unpublished one, because the tarball
+// would name a version the registry does not have; `@uniflowed/router` is on
+// npm and `@uniflowed/hmr` is a declaration package that is not. What the two
+// posters do share is the contract, and `tests/library/dev-channel.test.js`
+// asserts that every spelling of these paths agrees — a duplicated constant
+// with a test on it is honest, and one without is how a browser ends up
+// posting to a path nothing serves.
+//
+// # It is development only, and it is best effort
+//
+// `uf dev` serves this path and nothing else does: a built application has no
+// `/__uf/` anything, so a call in production posts to a path that answers 404
+// and the rejected promise is swallowed here. That is a fallback rather than a
+// design — the only caller is behind `import.meta.hot` in `../client.js`, so a
+// production bundle has no path to this module rather than merely no answer
+// from it.
+//
+// Nothing here opens a connection until it is called, importing it does nothing
+// at all, and what it sends goes to the page's own origin as a path rather than
+// a URL, so it cannot be pointed at somebody else's server. Nothing leaves the
+// machine.
+
+/**
+ * The path `uf dev` serves the diagnostic channel on.
+ *
+ * Under `/__uf/`, beside the update stream `@uniflowed/hmr` opens and the
+ * vitals endpoint `@uniflowed/web/vitals` posts to, for the reason that prefix
+ * exists: a directory in `app/` whose name begins with `_` is not a route, so
+ * no application can put anything here and nothing here can shadow a path a
+ * project wrote.
+ */
+export const DIAGNOSTIC_ENDPOINT: string = "/__uf/diagnostic";
+
+/**
+ * How loudly a diagnostic reads in the terminal.
+ *
+ * `error` for something that is wrong, `warn` for something that is worth
+ * knowing, `info` for something that is only a measurement. Three rather than
+ * two because the vitals report on the same channel needs the third: a page
+ * whose numbers are all good has still reported, and printing that as a warning
+ * would teach the reader to ignore the warnings.
+ */
+export type DiagnosticSeverity = "error" | "warn" | "info";
+
+/**
+ * One diagnostic, as the channel carries it.
+ *
+ * `message` is the headline and the only required field: one line, the thing
+ * that is wrong. `detail` is everything under it — the values that differed,
+ * the path through the tree, the advice — and is a list of lines rather than a
+ * blob so the terminal can indent them without guessing where they break.
+ *
+ * `url` is the page the browser was on, which the reporter fills in when the
+ * caller does not: a diagnostic that does not say which page produced it is a
+ * diagnostic somebody has to reproduce before they can act on it.
+ *
+ * `file`, `line` and `column` are for the rare browser-side report that knows a
+ * source position. When the file and the line are both there `uf dev` draws its
+ * ordinary code frame; when they are not it prints the headline and the detail,
+ * which is what a hydration mismatch — a fact about a DOM node rather than
+ * about a line — can honestly offer.
+ */
+export type BrowserDiagnostic = {
+  readonly severity: DiagnosticSeverity,
+  readonly message: string,
+  readonly detail?: $ReadOnlyArray<string>,
+  readonly url?: string,
+  readonly file?: string,
+  readonly line?: number,
+  readonly column?: number,
+};
+
+/** The part of the browser this module needs. */
+type ReportingWindow = {
+  readonly location?: { readonly href?: string, ... },
+  readonly fetch?: (input: string, init: { ... }) => Promise<mixed>,
+  ...
+};
+
+/** For a promise whose outcome is deliberately not looked at. */
+function noop(): void {}
+
+/**
+ * Send one diagnostic to `uf dev`, if there is a `uf dev` to send it to.
+ *
+ * Returns nothing and throws nothing. A diagnostic is a thing a person reads,
+ * not a thing an application branches on, and a reporter that could fail would
+ * make every caller wrap it — from a code path that is, by construction,
+ * already handling something that went wrong.
+ *
+ * `fetch` rather than `sendBeacon`, which is the opposite of the choice
+ * `vitalsBeacon` makes and for the opposite reason: a vital is measured as the
+ * page is put away and needs a transport that outlives it, while a diagnostic
+ * is produced by a page that is still running and had better arrive in the
+ * order it happened. `keepalive` covers the case where the page goes away
+ * immediately afterwards anyway.
+ *
+ * @param diagnostic what to report
+ * @param endpoint where to post it; [`DIAGNOSTIC_ENDPOINT`] by default
+ */
+export function reportDiagnostic(diagnostic: BrowserDiagnostic, endpoint?: string): void {
+  const win = reportingWindow();
+  if (win == null) {
+    return;
+  }
+  const post = win.fetch;
+  if (post == null) {
+    return;
+  }
+
+  const body = JSON.stringify({
+    ...diagnostic,
+    url: diagnostic.url ?? win.location?.href ?? "",
+  });
+  // A rejected promise nobody is holding becomes an unhandled rejection, which
+  // arrives in whatever error reporter the application installed — from a line
+  // about development tooling. Losing the report is the right outcome when
+  // there is nothing listening; reporting the loss as an application error is
+  // not.
+  post(endpoint ?? DIAGNOSTIC_ENDPOINT, {
+    method: "POST",
+    body,
+    keepalive: true,
+    headers: { "content-type": "application/json" },
+  }).then(noop, noop);
+}
+
+/**
+ * The window to report from, or `null` where there is no browser.
+ *
+ * The same reading `@uniflowed/web/vitals` makes, and for the same reason: in a
+ * browser `globalThis` *is* the window, but not where a document has been
+ * installed onto another host's global, which is every uf test process. Asking
+ * for the document first is what makes both cases work.
+ */
+function reportingWindow(): ReportingWindow | null {
+  if (typeof globalThis.document === "undefined") {
+    return null;
+  }
+  return globalThis.window ?? globalThis;
+}