@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/create-app.ts

@@ -0,0 +1,982 @@
+// createApp lifecycle: validate the schema, build a default config shape
+// from inputs' prefills + tab/section structure, deep-merge user config
+// over defaults, hand the merged tree to getDesiredState, then
+// resolveDesiredApp the result.
+
+import { z } from "zod";
+import {
+  resolveDesiredApp,
+  type TrustedHeaderSource,
+  type TrustedHeadersManifest,
+  type HomeApp,
+} from "./resolve.ts";
+import { deepMergeConfig } from "./deep-merge.ts";
+import { HEADER_NAME_RE, HEADER_VALUE_RE } from "./http-header.ts";
+import { checkPermissionAppKinds, checkSystemAppRoutes } from "./security.ts";
+import type { Service } from "./service.ts";
+import type { ServiceDefinition, SystemServiceDefinition } from "./service-definition.ts";
+import type { ConfigSchema, InferConfigSchema, Node } from "./types.ts";
+import { isInput, isSection, isTab } from "./types.ts";
+import type { ConfigFieldLeaf, ConfigFieldTree, SerializablePermission } from "./sandbox.ts";
+import type { Action, Loader, Page, UiConfig, Widget } from "./ui-surface.ts";
+import type {
+  ActionManifest,
+  LoaderManifest,
+  ManifestHeader,
+  SurfaceManifest,
+  UiManifest,
+  WidgetManifest,
+} from "./resolve.ts";
+import { identityRef, REF_SYMBOL, type Ref } from "./ref.ts";
+
+interface DesiredApp {
+  /**
+   * Map of service names to their definitions. Each key becomes the
+   * container's display name and the in-app DNS alias other services use
+   * to reach it. Service classes (e.g. `new Postgres(...)`) and plain
+   * `ServiceDefinition` objects can be mixed.
+   *
+   * Optional: a config-only app (no `services`) runs no container. An app
+   * may resolve to nothing and simply deploys nothing.
+   */
+  services?: Record<string, Service | ServiceDefinition>;
+  /**
+   * Set to `config.egress` from a `r.host.egress()` permission to allow
+   * outbound traffic from this app's containers. When absent or
+   * `undefined`, the per-app network is created with Docker's
+   * `internal: true` flag and containers can only reach peers they have
+   * explicit permissions for. Realm.ts authors thread this through
+   * themselves, the same way every other resolved permission flows
+   * from `config` into the desired state.
+   */
+  egress?: true;
+}
+
+/**
+ * The desired state a system app's `getDesiredState` returns: the same
+ * shape as {@link DesiredApp} but services are routeless
+ * ({@link SystemServiceDefinition}) — system apps have no routes, so a
+ * `router` key is a type error at authoring time. The resolved-state
+ * check (`checkSystemAppRoutes`) backs the type at runtime.
+ */
+interface SystemDesiredApp {
+  /** Same as {@link DesiredApp.services}, minus `router`. */
+  services?: Record<string, Service | SystemServiceDefinition>;
+  /** Same as {@link DesiredApp.egress}. */
+  egress?: true;
+}
+
+/**
+ * The authenticated Home user, as seen by `getTrustedHeaders`. This is the
+ * person logged into Home reaching the app - through its authenticated
+ * subdomain, or through one of its dashboard surfaces - never an app-local
+ * account.
+ *
+ * `username` / `email` are `Ref<string>`, not plain strings: at the point
+ * `getTrustedHeaders` runs there is no real user (it is sampled at deploy
+ * time to extract the header mapping), and the value is filled in per
+ * request on whichever door the request came through. Pass them straight
+ * through as a header value or compose with `interpolate`. `role` is a real
+ * literal so authors can branch on it.
+ */
+export interface User {
+  username: Ref<string>;
+  email: Ref<string>;
+  role: "admin" | "member";
+}
+
+/**
+ * Per-install preview context, passed to `getDesiredState` as `preview`.
+ *
+ * `null` for a normal (persistent) install; a `{ previewKey }` object when
+ * Home stamps this app as an ephemeral `role: preview` child of a template
+ * (one per PR). The `previewKey` is opaque to the app (a PR number on GitHub,
+ * an MR id on GitLab, …) and DNS-label-safe, so it's safe to fold straight
+ * into a hostname or an id. The idiom is to branch a per-preview identity off
+ * it - a base URL, a bucket prefix, a database name:
+ *
+ * ```ts
+ * getDesiredState: ({ config, preview }) => ({
+ *   services: {
+ *     web: {
+ *       image: "...",
+ *       env: {
+ *         SITE_URL: preview
+ *           ? `https://pr-${preview.previewKey}.example.com`
+ *           : config.siteUrl,
+ *       },
+ *     },
+ *   },
+ * })
+ * ```
+ *
+ * Not a per-preview *public domain*: `r.home.publicDomain()` is an operator
+ * grant and a child inherits its template's grants verbatim, so every child
+ * would claim the same host. Home clears the resolved value on any preview
+ * child rather than trusting the source not to wire it, so previews ride the
+ * gated auto subdomain.
+ */
+export interface PreviewContext {
+  previewKey: string;
+}
+
+/**
+ * One operator-facing value surfaced by `info` on the app's summary page. A
+ * **bare value** - a string, a `Ref<string>`, or `null` (a service URL Home
+ * drops) - or a **rich object** that adds a label, description, and mask/copy
+ * flags.
+ */
+type InfoValue =
+  | string
+  | null
+  | Ref<string>
+  | {
+      value: string | null | Ref<string>;
+      /** Display label, distinct from the dict key. Falls back to the key. */
+      label?: string;
+      /** One line of context rendered as muted subtext under the value. */
+      description?: string;
+      /** Mask with a reveal control; not shown in plaintext by default. */
+      sensitive?: boolean;
+      /** Show a copy button (default: true). */
+      copyable?: boolean;
+    };
+
+/**
+ * `info`'s signature: a `services` URL map in, a dict of {@link InfoValue}s
+ * out (`undefined` keys omitted). See platform/docs realm-ts/info.mdx.
+ */
+type InfoFn = (args: {
+  services: Record<string, string | null>;
+}) => Record<string, InfoValue | undefined>;
+
+// Everything common to both factories. `info`, `getTrustedHeaders` and
+// `verifyAnonymousRequest` are layered on by `SingleAppOptions` — all three
+// hang off an app's routes, and system apps have none. The desired state type
+// is a parameter so `createSystemApp` can narrow services to the routeless
+// `SystemServiceDefinition`.
+interface BaseAppOptions<TSchema extends ConfigSchema, TState extends DesiredApp> {
+  /**
+   * Stable, human-readable identifier shown in the dashboard. Free-form
+   * text - the per-install app id (used in container/network names) is
+   * generated separately and isn't derived from this.
+   */
+  name: string;
+  /**
+   * One-sentence description shown next to the app name in the dashboard
+   * and on the consent screen.
+   */
+  description?: string;
+  /**
+   * Typed tree of permissions, inputs, sections, and tabs the admin
+   * configures on the consent screen. Either every top-level entry is an
+   * `r.tab(...)` or none of them are - mixing throws at `createApp` time.
+   */
+  configSchema?: TSchema;
+  /**
+   * Pages and widgets contributed to the Home dashboard. Render fns are
+   * extracted by realm-sdk and bundled for the iframe runtime; loader
+   * schemas become a JSON manifest Home uses to validate proxy calls
+   * and route to the named service.
+   */
+  ui?: UiConfig;
+  /**
+   * Pure function that turns the resolved config into the app's desired
+   * services. Called by Home on every reconcile. Read fields off
+   * `config` (typed from `configSchema`) and return a `services` map;
+   * the SDK handles permission checks, ref resolution, and compose
+   * rendering downstream.
+   */
+  getDesiredState: (args: {
+    /**
+     * The resolved config tree. Inputs land as their primitive value;
+     * permissions land as their resolved shape (e.g. `host.port` ->
+     * `{ path }`, `host.port` -> `{ port }`); peer permissions land as
+     * the aggregated peer data; remote permissions land as parsed
+     * fetched data.
+     *
+     * Per-worker context (worker id + Home's `home_state` identity) lands
+     * under `host.management()` when granted - read `config.<path>.workerId`
+     * etc. rather than expecting a separate `worker` arg.
+     */
+    config: InferConfigSchema<TSchema>;
+    /**
+     * `null` on a normal install; a `{ previewKey }` object when Home stamps
+     * this app as an ephemeral preview child of a template. Branch on it to
+     * vary per-preview state (typically a public domain). See
+     * {@link PreviewContext}.
+     */
+    preview: PreviewContext | null;
+  }) => TState;
+}
+
+/**
+ * Options for `createApp` (a single app): runs on one selected worker. The
+ * install panel shows a single-pick; UI loaders forward to that one worker
+ * and `merge` is not allowed. Only single apps carry `info` and the two
+ * route-bound auth hooks.
+ */
+interface SingleAppOptions<TSchema extends ConfigSchema = ConfigSchema> extends BaseAppOptions<
+  TSchema,
+  DesiredApp
+> {
+  /**
+   * Header brokering: turn the authenticated Home user into the request
+   * headers this app trusts for sign-in (e.g. Miniflux's
+   * `AUTH_PROXY_HEADER`). Returns a flat `header -> value` map; Home
+   * computes it per request at the ForwardAuth hop and Caddy injects the
+   * result on the app's authenticated subdomain. The same header names are
+   * stripped from every other path (the public route, the client's own
+   * copy) so identity can't be spoofed.
+   *
+   * Header *names* must be static: Home samples this function once per role
+   * at eval time and unions the keys. A header *value* is a bare `user`
+   * field, a constant, or an `interpolate` template mixing the two
+   * (`` i`Bearer ${user.username}` ``). A transformed expression
+   * (`user.username.toUpperCase()`) won't round-trip and is rejected.
+   *
+   * Declaring this is the opt-in; installing an app that declares it is the
+   * operator's consent to forward identity to it.
+   */
+  getTrustedHeaders?: (user: User) => Record<string, string | Ref<string>>;
+  /**
+   * Anonymous gate: admit session-less machine callers (a webhook, a
+   * `docker pull`) that carry their own credential instead of a Home
+   * session. Home runs this at the ForwardAuth hop for every request to
+   * this app that arrives without a usable Home session.
+   *
+   * Return `true` to admit the request as the built-in `anonymous`
+   * principal, a `Response` to relay to the caller verbatim (e.g. a 401
+   * auth challenge), or `false` to deny. The hook can only ever govern
+   * its own app's routes.
+   *
+   * `request` carries the original call's method, URL, and headers - not
+   * its body (the verify hop never receives it). `stableSecret(name)`
+   * returns the live value of `r.stableSecret(name)` for this app, derived
+   * by Home; compare the incoming credential against it. The call is
+   * synchronous - no `await` - even though Home derives it asynchronously.
+   */
+  verifyAnonymousRequest?: (
+    request: Request,
+    stableSecret: (name: string) => string,
+  ) => boolean | Response;
+  /**
+   * Operator-facing setup values - a webhook URL, a generated secret, a
+   * derived string - surfaced on the app's summary page. See platform/docs
+   * realm-ts/info.mdx.
+   */
+  info?: InfoFn;
+}
+
+/**
+ * Options for `createSystemApp`: the app runs on every compatible worker —
+ * the operator has no per-worker choice; the install panel shows a static
+ * caption instead of a picker. UI loaders fan out to every reachable worker
+ * and `merge` is required on every loader.
+ *
+ * System apps have no routes, so the route-bound options are unavailable:
+ * `info` (a fanned-out service has one URL *per worker*, so there's no
+ * single URL for `services.<name>` to resolve to) and
+ * `verifyAnonymousRequest` (anonymous gates admit callers to an app's
+ * routes).
+ *
+ * `getTrustedHeaders` is banned for a different reason, and not a
+ * route-shaped one - brokered identity also reaches a container through a
+ * page or widget loader, which a system app very much has. The reason is
+ * consent: a system app is seeded by the platform with no operator install
+ * click, so disclosing who is signed in would be granted by the platform
+ * rather than by the operator. Revisit if a system app ever needs a viewer;
+ * none does today.
+ *
+ * The `never` tombstones hold for spread and variable-typed options, not
+ * just literals.
+ *
+ * See platform/docs realm-ts/workers.mdx.
+ */
+interface SystemAppOptions<TSchema extends ConfigSchema = ConfigSchema> extends BaseAppOptions<
+  TSchema,
+  SystemDesiredApp
+> {
+  info?: never;
+  getTrustedHeaders?: never;
+  verifyAnonymousRequest?: never;
+}
+
+export interface AppDefinition<TSchema extends ConfigSchema = ConfigSchema> {
+  name: string;
+  description?: string;
+  kind: "single" | "system";
+  /**
+   * Raw anonymous gate, retained on the definition so Home can call it
+   * inside the sandbox at the verify hop (unlike `getTrustedHeaders`,
+   * which is sampled to a static manifest, the gate is live logic over
+   * the request and must execute).
+   */
+  verifyAnonymousRequest?: (
+    request: Request,
+    stableSecret: (name: string) => string,
+  ) => boolean | Response;
+  configSchema?: TSchema;
+  /**
+   * Author-provided ui block, retained so the iframe bundle can reach
+   * each surface's `render` fn. Loader runtime values stay here too —
+   * only the JSON manifest is stripped down for `evaluate`'s output.
+   */
+  ui?: UiConfig;
+  /** Raw `info` fn, retained so Home can run it in the sandbox on the
+   * summary-page path. */
+  info?: InfoFn;
+  /**
+   * Attach file-based surfaces (pages/*, widgets/*) after construction. Called
+   * only by the merge's generated glue — it imports the surface files and
+   * wires them in before the app is bundled, so a file-based app needs no `ui:`
+   * block and the merge runs with esbuild alone (no TypeScript compiler,
+   * which is why it can run in Home). Throws if an inline `ui:` is already set.
+   */
+  attachSurfaces: (ui: UiConfig) => void;
+  evaluate: (args: {
+    config: InferConfigSchema<TSchema>;
+    appId?: string;
+    preview?: PreviewContext | null;
+  }) => HomeApp;
+}
+
+// Plain JS identifier shape — keys appear in dotted paths
+// ("general.webhooks"), filesystem cache names, and getDesiredState as
+// `config.general.webhooks`.
+const IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+function assertValidKeys(schema: Record<string, Node>, prefix = ""): void {
+  for (const [key, node] of Object.entries(schema)) {
+    if (!IDENT_RE.test(key)) {
+      const where = prefix ? `at "${prefix}.${key}"` : `at "${key}"`;
+      throw new Error(
+        `configSchema key must match /^[a-zA-Z_][a-zA-Z0-9_]*$/ ${where} - ` +
+          `use identifier-shaped names (letters, digits, underscore)`,
+      );
+    }
+    if (isTab(node) || isSection(node)) {
+      assertValidKeys(node.children as Record<string, Node>, prefix ? `${prefix}.${key}` : key);
+    }
+  }
+}
+
+function assertSchemaHomogeneous(schema: Record<string, Node>): void {
+  const keys = Object.keys(schema);
+  if (keys.length === 0) return;
+  const tabs = keys.filter((k) => isTab(schema[k]!));
+  if (tabs.length > 0 && tabs.length !== keys.length) {
+    const first = tabs[0]!;
+    const other = keys.find((k) => !isTab(schema[k]!))!;
+    throw new Error(
+      `configSchema must be either all r.tab(...) or none - "${first}" is a tab, "${other}" is not`,
+    );
+  }
+}
+
+/**
+ * Flatten the authoring tree to dotted-path → permission node, the same
+ * shape (and the same paths) `extractSchema` produces inside QuickJS. A
+ * permission node is whatever isn't a tab, a section or an input, which
+ * is how the sandbox walk classifies them too.
+ *
+ * Exists so the factories can run `checkPermissionAppKinds` against the
+ * live schema, before any bundling or eval. Home runs the same check on
+ * the extracted `permsFlat`.
+ */
+function collectPermissionNodes(
+  schema: Record<string, Node>,
+  out: Record<string, SerializablePermission> = {},
+  prefix = "",
+): Record<string, SerializablePermission> {
+  for (const [key, node] of Object.entries(schema)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (isTab(node) || isSection(node)) {
+      collectPermissionNodes(node.children as Record<string, Node>, out, path);
+    } else if (!isInput(node)) {
+      // A permission record is already `{kind, data, meta}` plus chain methods;
+      // the sandbox serializer drops the methods and reads the same three fields.
+      out[path] = node as unknown as SerializablePermission;
+    }
+  }
+  return out;
+}
+
+const OMIT = Symbol("omit");
+
+function buildConfigShape(schema: Record<string, Node>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, node] of Object.entries(schema)) {
+    const built = buildNodeShape(node);
+    if (built !== OMIT) out[key] = built;
+  }
+  return out;
+}
+
+function buildNodeShape(node: Node): unknown {
+  if (isTab(node)) {
+    const sub: Record<string, unknown> = {};
+    for (const [k, child] of Object.entries(node.children)) {
+      const built = buildNodeShape(child as Node);
+      if (built !== OMIT) sub[k] = built;
+    }
+    return sub;
+  }
+
+  if (isSection(node)) {
+    if (node.meta.isOptional) return OMIT;
+    const sub: Record<string, unknown> = {};
+    for (const [k, child] of Object.entries(node.children)) {
+      const built = buildNodeShape(child as Node);
+      if (built !== OMIT) sub[k] = built;
+    }
+    return sub;
+  }
+
+  if (isInput(node)) {
+    const value = (node.meta as { prefill?: unknown }).prefill;
+    if (value !== undefined) return value;
+    return OMIT;
+  }
+
+  // Permission leaf: admin must grant; defaults don't apply.
+  return OMIT;
+}
+
+// ----- getTrustedHeaders sampling -------------------------------------------
+//
+// Header *names* must be static so Caddy can list them for copy_headers
+// (inject) and delete (anti-spoof) without seeing a request. Sampling finds
+// them: call getTrustedHeaders once per role with identity refs for
+// username/email (and the real role, so role-branching works), then read each
+// returned value as a `{field}` reference, a `{literal}` string, or a
+// `{template}` of literal + field segments (an `interpolate` over identity,
+// e.g. `i`Bearer ${user.username}``). The verify hop substitutes the live
+// value; role itself rides along as a literal captured in each sample.
+
+const AUTH_ROLES = ["admin", "member"] as const;
+
+function sampleTrustedHeaders(
+  fn: (user: User) => Record<string, string | Ref<string>>,
+): TrustedHeadersManifest {
+  const keys = new Set<string>();
+  const byRole = {} as TrustedHeadersManifest["byRole"];
+  for (const role of AUTH_ROLES) {
+    const out = fn({ username: identityRef("username"), email: identityRef("email"), role });
+    const map: Record<string, TrustedHeaderSource> = {};
+    for (const [key, value] of Object.entries(out)) {
+      if (!HEADER_NAME_RE.test(key)) {
+        throw new Error(
+          `getTrustedHeaders["${key}"]: not a valid HTTP header name (letters, digits, ` +
+            "and !#$%&'*+-.^_`|~). Every call into the app carries these headers, and a " +
+            "malformed name is rejected outright",
+        );
+      }
+      // `X-Realm-*` is the platform's namespace: Home and the worker stamp into
+      // it and Caddy strips it off every client request, so a container is
+      // entitled to trust whatever arrives under it. An app declaring into it
+      // would break that reservation, and a name Home later stamps would
+      // silently take over the app's value.
+      if (key.toLowerCase().startsWith("x-realm-")) {
+        throw new Error(
+          `getTrustedHeaders["${key}"]: the X-Realm-* namespace is reserved for the ` +
+            "platform. Home and the worker stamp headers there and clients are stripped " +
+            "of them, so a container can trust them; pick a name outside it",
+        );
+      }
+      keys.add(key);
+      map[key] = toTrustedHeaderSource(key, value);
+    }
+    byRole[role] = map;
+  }
+  return { keys: [...keys], byRole };
+}
+
+// Literal text an author baked into a header value, checked against the same
+// rule the worker applies at request time. Literals only: a `{field}` is filled
+// per request from the live session, and its charset is bounded at account
+// creation, not here.
+function assertHeaderLiteral(key: string, text: string): void {
+  if (HEADER_VALUE_RE.test(text)) return;
+  throw new Error(
+    `getTrustedHeaders["${key}"]: value must be printable ASCII. A character outside ` +
+      "it is rejected on the way into the container, failing every call the app makes",
+  );
+}
+
+// A returned header value is a literal string, a single user field (a bare
+// identity ref), or an `interpolate` template mixing literal text with user
+// fields (e.g. `i`Bearer ${user.username}``). Other ref kinds (secret, derived,
+// deferred) and any field other than username/email are rejected.
+function toTrustedHeaderSource(key: string, value: string | Ref<string>): TrustedHeaderSource {
+  if (typeof value === "string") {
+    assertHeaderLiteral(key, value);
+    return { literal: value };
+  }
+  if (typeof value === "object" && value !== null && REF_SYMBOL in value) {
+    const json = (value as Ref<string>).toJSON();
+    if (typeof json === "string") {
+      assertHeaderLiteral(key, json);
+      return { literal: json };
+    }
+    const marker = (json as { __realmRef: { kind?: string; field?: string; parts?: unknown[] } })
+      .__realmRef;
+    if (marker.kind === "identity") return { field: identityField(key, marker.field) };
+    // `interpolate` flattens to a single concat of string + leaf segments;
+    // for identity headers every leaf must itself be an identity field.
+    if (marker.kind === "concat") {
+      return { template: (marker.parts ?? []).map((part) => headerSegment(key, part)) };
+    }
+  }
+  throw new Error(`getTrustedHeaders["${key}"]: value must be a user field or a literal string`);
+}
+
+// One segment of an interpolated header value: literal text passes through,
+// an identity leaf becomes a `{field}` the verify hop fills per request.
+function headerSegment(key: string, part: unknown): string | { field: "username" | "email" } {
+  if (typeof part === "string") {
+    assertHeaderLiteral(key, part);
+    return part;
+  }
+  const m = part as { kind?: string; field?: string };
+  if (m?.kind === "identity") return { field: identityField(key, m.field) };
+  throw new Error(
+    `getTrustedHeaders["${key}"]: only user fields (user.username / user.email) and literal text can compose a header value`,
+  );
+}
+
+function identityField(key: string, field: string | undefined): "username" | "email" {
+  if (field === "username" || field === "email") return field;
+  throw new Error(`getTrustedHeaders["${key}"]: unknown user field "${field}"`);
+}
+
+// ----- ui validation + manifest extraction -------------------------------
+
+function assertBaseSurface(surface: Page, where: string): void {
+  if (typeof surface.title !== "string" || surface.title.length === 0) {
+    throw new Error(`${where}.title must be a non-empty string`);
+  }
+  if (typeof surface.icon !== "string" || surface.icon.length === 0) {
+    throw new Error(`${where}.icon must be a non-empty string from the icon registry`);
+  }
+  if (typeof surface.render !== "function") {
+    throw new Error(`${where}.render must be a function`);
+  }
+  if (surface.loaders) {
+    for (const [lk, l] of Object.entries(surface.loaders)) {
+      if (!IDENT_RE.test(lk)) {
+        throw new Error(`${where}.loaders key "${lk}" must be an identifier`);
+      }
+      if (typeof l.service !== "string" || typeof l.port !== "number") {
+        throw new Error(`${where}.loaders.${lk} needs a string service and a number port`);
+      }
+      if (typeof l.request !== "function") {
+        throw new Error(`${where}.loaders.${lk}.request must be a (state, config) => request fn`);
+      }
+    }
+  }
+  if (surface.actions) {
+    for (const [ak, a] of Object.entries(surface.actions)) {
+      if (!IDENT_RE.test(ak)) {
+        throw new Error(`${where}.actions key "${ak}" must be an identifier`);
+      }
+      if (typeof a.service !== "string" || typeof a.port !== "number") {
+        throw new Error(`${where}.actions.${ak} needs a string service and a number port`);
+      }
+      if (typeof a.request !== "function") {
+        throw new Error(`${where}.actions.${ak}.request must be an (input, config) => request fn`);
+      }
+    }
+  }
+}
+
+function assertPageMap(pages: Record<string, Page>): void {
+  for (const [key, p] of Object.entries(pages)) {
+    if (!IDENT_RE.test(key)) {
+      throw new Error(
+        `ui.pages key must match /^[a-zA-Z_][a-zA-Z0-9_]*$/ at "${key}" - ` +
+          `use identifier-shaped names (letters, digits, underscore)`,
+      );
+    }
+    assertBaseSurface(p, `ui.pages.${key}`);
+  }
+}
+
+function assertWidgetMap(widgets: Record<string, Widget>): void {
+  for (const [key, w] of Object.entries(widgets)) {
+    if (!IDENT_RE.test(key)) {
+      throw new Error(
+        `ui.widgets key must match /^[a-zA-Z_][a-zA-Z0-9_]*$/ at "${key}" - ` +
+          `use identifier-shaped names (letters, digits, underscore)`,
+      );
+    }
+    assertBaseSurface(w, `ui.widgets.${key}`);
+    for (const dim of ["cols", "rows"] as const) {
+      const v = w[dim];
+      if (v === undefined) continue;
+      if (!Number.isInteger(v) || v < 1) {
+        throw new Error(`ui.widgets.${key}.${dim} must be an integer ≥ 1`);
+      }
+    }
+  }
+}
+
+function assertValidUi(ui: UiConfig): void {
+  if (ui.pages) assertPageMap(ui.pages);
+  if (ui.widgets) assertWidgetMap(ui.widgets);
+}
+
+// A system app fans out to every worker, so the iframe runtime needs a `merge`
+// reducer to combine per-worker loader responses. A single app only ever has one
+// response, where a `merge` would never run — reject it rather than let authors
+// think it is wired up. Actions take no `merge` either way: a system app's
+// resolve with the raw `{results: [...]}` envelope, a single app's with the
+// single upstream body.
+function assertMergeMatchesKind(ui: UiConfig, kind: "single" | "system"): void {
+  const visit = (where: string, surface: Page) => {
+    if (!surface.loaders) return;
+    for (const [name, l] of Object.entries(surface.loaders)) {
+      const hasMerge = typeof l.merge === "function";
+      if (kind === "system" && !hasMerge) {
+        throw new Error(
+          `${where}.loaders.${name}: createSystemApp requires merge(results) on every loader`,
+        );
+      }
+      if (kind === "single" && hasMerge) {
+        throw new Error(
+          `${where}.loaders.${name}: createApp forbids merge — only one worker responds`,
+        );
+      }
+    }
+  };
+  if (ui.pages) for (const [k, p] of Object.entries(ui.pages)) visit(`ui.pages.${k}`, p);
+  if (ui.widgets) for (const [k, w] of Object.entries(ui.widgets)) visit(`ui.widgets.${k}`, w);
+}
+
+function headerToManifest(value: string | { toJSON?: () => unknown }): ManifestHeader {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object" && REF_SYMBOL in value) {
+    const json = (value as { toJSON: () => unknown }).toJSON();
+    return json as ManifestHeader;
+  }
+  throw new Error("ui proxy headers must be strings or refs (e.g. r.stableSecret(...))");
+}
+
+function headersToManifest(
+  headers: Record<string, string | { toJSON?: () => unknown }> | undefined,
+): Record<string, ManifestHeader> | undefined {
+  if (!headers) return undefined;
+  const out: Record<string, ManifestHeader> = {};
+  for (const [k, v] of Object.entries(headers)) out[k] = headerToManifest(v);
+  return out;
+}
+
+// Zod v4's toJSONSchema throws on z.void() / z.undefined() because they
+// have no JSON representation. Loaders rarely use void but actions
+// frequently return nothing — coerce both to an empty object schema
+// (matches anything, which is the right semantic for "no return").
+function toJsonSchemaSafe(schema: unknown): unknown {
+  try {
+    return z.toJSONSchema(schema as Parameters<typeof z.toJSONSchema>[0]);
+  } catch (e) {
+    if (e instanceof Error && e.message.includes("cannot be represented in JSON Schema")) {
+      return {};
+    }
+    throw e;
+  }
+}
+
+// The loader's static shape. Which loaders prefill - and the request each uses
+// - is decided at shell-render time: Home runs each loader's
+// `request(seedState, config)` live in a warm VM with the placement's real
+// config. See `stitchLoaderRequests` in sandbox.ts.
+function loaderToManifest(loader: Loader): LoaderManifest {
+  const manifest: LoaderManifest = {
+    outputSchema: toJsonSchemaSafe(loader.outputSchema),
+    service: loader.service,
+    port: loader.port,
+    headers: headersToManifest(loader.headers),
+  };
+  if (loader.merge) manifest.merge = true;
+  if (manifest.headers === undefined) delete manifest.headers;
+  return manifest;
+}
+
+function actionToManifest(action: Action): ActionManifest {
+  const manifest: ActionManifest = {
+    inputSchema: toJsonSchemaSafe(action.inputSchema),
+    service: action.service,
+    port: action.port,
+    headers: headersToManifest(action.headers),
+  };
+  if (action.outputSchema) manifest.outputSchema = toJsonSchemaSafe(action.outputSchema);
+  if (manifest.headers === undefined) delete manifest.headers;
+  return manifest;
+}
+
+// Walk a ui surface's `configSchema` — a flat record of `r.input.*` leaves —
+// into the three wire forms Home needs: a `configFields` render descriptor for
+// the config screen, a `configSchema` JSON Schema for validating a submitted
+// config, and a `defaultConfig` seeded from each leaf's `.prefill()`.
+//
+// Rejects anything a surface config may not hold: a permission / tab / section
+// leaf, or an `r.input.secret()`. A widget config is a per-placement display
+// knob, not a credential store, and a secret can't ride the in-iframe
+// `request(state, config)` without leaking to the sandbox; credentials live in
+// the app's top-level configSchema and reach a loader via a header ref. The
+// type-level `SurfaceConfigSchema` rejects it at authoring time, so this covers
+// the packed/JS path.
+function describeSurfaceConfig(schema: Record<string, Node>): {
+  fields: ConfigFieldTree;
+  defaultConfig: Record<string, unknown>;
+  validation: z.ZodType;
+} {
+  const fields: ConfigFieldTree = {};
+  const shape: Record<string, z.ZodType> = {};
+  const defaultConfig: Record<string, unknown> = {};
+  for (const [key, node] of Object.entries(schema)) {
+    if (!isInput(node)) {
+      throw new Error(
+        `ui surface configSchema "${key}": only r.input.* leaves are allowed ` +
+          `(no permissions, tabs, or sections).`,
+      );
+    }
+    if (node.kind === "input.secret") {
+      throw new Error(
+        `ui surface configSchema "${key}": r.input.secret() isn't supported in a ` +
+          `surface config - a widget config holds display settings, not credentials. ` +
+          `Declare the secret in the app's top-level configSchema and pass its ref to a loader header.`,
+      );
+    }
+    const specific = node.kind.slice("input.".length) as ConfigFieldLeaf["type"];
+    const meta = (node.meta ?? {}) as Record<string, unknown>;
+    const leaf: ConfigFieldLeaf = { type: specific };
+    if (meta.title) leaf.label = meta.title as string;
+    if (meta.placeholder !== undefined) leaf.placeholder = meta.placeholder as string | number;
+    if (meta.prefill !== undefined) {
+      leaf.default = meta.prefill;
+      defaultConfig[key] = meta.prefill;
+    }
+    if (meta.description) leaf.description = meta.description as string;
+    if (meta.isOptional) leaf.optional = true;
+    if (specific === "enum" && "values" in node) {
+      leaf.values = [...(node as { values: readonly string[] }).values];
+    }
+    if (specific === "number") {
+      if (meta.int) leaf.step = 1;
+      if (meta.min !== undefined) leaf.min = meta.min as number;
+      if (meta.max !== undefined) leaf.max = meta.max as number;
+    }
+    fields[key] = leaf;
+    // A field that is `.optional()` or carries a `.prefill()` need not be
+    // submitted: the prefill rides `defaultConfig` as a base layer Home merges in
+    // before running loaders. Only builders like `.min()`/`.max()` tighten
+    // `node.schema`, while `.optional()`/`.prefill()` live purely in `meta`, so
+    // they are marked non-required here or `z.object` rejects a blank leaf.
+    shape[key] =
+      meta.isOptional || meta.prefill !== undefined ? node.schema.optional() : node.schema;
+  }
+  return { fields, defaultConfig, validation: z.object(shape) };
+}
+
+// Shared surface manifest bits (title / icon / state / loaders / actions).
+// Config is widget-only — `widgetToManifest` layers it on; pages carry none.
+function surfaceToManifest(s: Page): SurfaceManifest {
+  const manifest: SurfaceManifest = { title: s.title, icon: s.icon };
+  if (s.stateSchema) manifest.stateSchema = toJsonSchemaSafe(s.stateSchema);
+  if (s.loaders) {
+    manifest.loaders = {};
+    for (const [k, l] of Object.entries(s.loaders)) {
+      manifest.loaders[k] = loaderToManifest(l);
+    }
+  }
+  if (s.actions) {
+    manifest.actions = {};
+    for (const [k, a] of Object.entries(s.actions)) {
+      manifest.actions[k] = actionToManifest(a);
+    }
+  }
+  return manifest;
+}
+
+function widgetToManifest(w: Widget): WidgetManifest {
+  const manifest: WidgetManifest = {
+    ...surfaceToManifest(w),
+    cols: w.cols ?? 2,
+    rows: w.rows ?? 2,
+  };
+  if (w.configSchema) {
+    const { fields, defaultConfig, validation } = describeSurfaceConfig(
+      w.configSchema as Record<string, Node>,
+    );
+    manifest.configFields = fields;
+    manifest.configSchema = toJsonSchemaSafe(validation);
+    // Ship the prefill defaults to the iframe as the base layer; Home merges the
+    // placement's persisted config over it before running the surface's loaders
+    // (both in the prefill VM and, client-side, in the runtime).
+    manifest.defaultConfig = defaultConfig;
+  }
+  return manifest;
+}
+
+function buildUiManifest(ui: UiConfig): UiManifest {
+  const manifest: UiManifest = {};
+  if (ui.pages) {
+    manifest.pages = {};
+    for (const [k, p] of Object.entries(ui.pages)) {
+      // Only widgets are configurable — a page has no config screen, so a config
+      // it could never collect would leave its loaders/render with undefined
+      // values the author's types say are present. Fail loud (covers the
+      // packed/JS path that skips the type-level rejection on `page()`).
+      if ((p as { configSchema?: unknown }).configSchema) {
+        throw new Error(
+          `ui page "${k}": only widgets can be configured — ` +
+            `move the configSchema to a widget or drop it.`,
+        );
+      }
+      manifest.pages[k] = surfaceToManifest(p);
+    }
+  }
+  if (ui.widgets) {
+    manifest.widgets = {};
+    for (const [k, w] of Object.entries(ui.widgets)) {
+      manifest.widgets[k] = widgetToManifest(w);
+    }
+  }
+  return manifest;
+}
+
+// Shared factory body. `createApp` / `createSystemApp` are thin typed
+// wrappers that pin `kind`; everything else — schema validation, ui
+// manifest building, the evaluate closure — is identical.
+function buildApp<TSchema extends ConfigSchema>(
+  kind: "single" | "system",
+  options: SingleAppOptions<TSchema>,
+): AppDefinition<TSchema> {
+  const schema = options.configSchema as Record<string, Node> | undefined;
+  if (schema) {
+    assertValidKeys(schema);
+    assertSchemaHomogeneous(schema);
+    // Not all permissions are legal on both factories. Home's graph verification
+    // runs the same check authoritatively; this one is so the author sees it from
+    // `realm-sdk validate` or the test harness rather than through Home's
+    // redacted "app evaluation failed".
+    const scopeViolations = checkPermissionAppKinds(kind, collectPermissionNodes(schema));
+    if (scopeViolations.length > 0) {
+      const factory = kind === "system" ? "createSystemApp" : "createApp";
+      throw new Error(`${factory}: ${scopeViolations.map((v) => v.description).join("; ")}`);
+    }
+  }
+  if (options.info && kind === "system") {
+    throw new Error(
+      `createSystemApp: \`info\` is not supported — a fanned-out service has no ` +
+        `single URL for services.<name> to resolve to`,
+    );
+  }
+  if (options.ui) {
+    assertValidUi(options.ui);
+    assertMergeMatchesKind(options.ui, kind);
+  }
+  // `ui` + `uiManifest` are mutable so file-based surfaces can attach after
+  // construction (see attachSurfaces); inline-ui apps never call it.
+  let uiManifest = options.ui ? buildUiManifest(options.ui) : undefined;
+  const app: AppDefinition<TSchema> = {
+    name: options.name,
+    description: options.description,
+    kind,
+    verifyAnonymousRequest: options.verifyAnonymousRequest,
+    configSchema: options.configSchema,
+    ui: options.ui,
+    info: options.info,
+    attachSurfaces(ui: UiConfig) {
+      if (app.ui) {
+        throw new Error(
+          "createApp: `ui` is already set — remove the inline `ui:` block to use " +
+            "file-based surfaces (pages/*, widgets/*), or delete the surface files.",
+        );
+      }
+      assertValidUi(ui);
+      assertMergeMatchesKind(ui, kind);
+      app.ui = ui;
+      uiManifest = buildUiManifest(ui);
+    },
+    evaluate({ config, appId, preview }) {
+      const shaped = schema
+        ? (deepMergeConfig(
+            buildConfigShape(schema),
+            (config ?? {}) as Record<string, unknown>,
+          ) as InferConfigSchema<TSchema>)
+        : config;
+      const state = options.getDesiredState({ config: shaped, preview: preview ?? null });
+      const withExtras = {
+        ...state,
+        ...(options.getTrustedHeaders
+          ? { trustedHeaders: sampleTrustedHeaders(options.getTrustedHeaders) }
+          : {}),
+        ...(options.verifyAnonymousRequest ? { hasAnonymousGate: true } : {}),
+        ...(uiManifest ? { ui: uiManifest } : {}),
+      };
+      const resolved = resolveDesiredApp({ ...withExtras, kind }, { appId });
+      // The types already make routes unrepresentable on a system app; this
+      // catches what they can't — a Service class instance smuggling a router
+      // (flattened at resolve time) and raw trustedHeaders / hasAnonymousGate
+      // keys returned straight from getDesiredState. Home's graph verification
+      // runs the same check authoritatively.
+      if (kind === "system") {
+        const violations = checkSystemAppRoutes(resolved);
+        if (violations.length > 0) {
+          throw new Error(violations.map((v) => v.description).join("; "));
+        }
+      }
+      return resolved;
+    },
+  };
+  return app;
+}
+
+/**
+ * Define a realm.ts app that runs on one operator-selected worker.
+ *
+ * Returns an `AppDefinition` Home can compile. The author surface is
+ * `name`, `description`, `configSchema`, `ui`, and `getDesiredState`;
+ * everything downstream (validation, permission checks, ref resolution,
+ * compose rendering, iframe bundling) is the SDK's job.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/
+ */
+export function createApp<TSchema extends ConfigSchema>(
+  options: SingleAppOptions<TSchema>,
+): AppDefinition<TSchema> {
+  return buildApp("single", options);
+}
+
+/**
+ * Define a realm.ts system app: fleet-wide infrastructure that runs on
+ * every compatible worker (the seeded backup / firewall / logger / stats apps
+ * are system apps). The operator gets no per-worker choice, UI
+ * loaders fan out to every reachable worker (`merge` required on each),
+ * and the route-bound options — `info`, `getTrustedHeaders`,
+ * `verifyAnonymousRequest`, `router` on a service — are not available:
+ * system apps have no routes.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/workers/
+ */
+export function createSystemApp<TSchema extends ConfigSchema>(
+  options: SystemAppOptions<TSchema>,
+): AppDefinition<TSchema> {
+  // Runtime backstops for the packed/JS path, which skips the type-level
+  // `never` tombstones (precedent: the `info` throw in buildApp).
+  if ((options as { getTrustedHeaders?: unknown }).getTrustedHeaders) {
+    throw new Error(
+      "createSystemApp: `getTrustedHeaders` is not supported — header brokering " +
+        "happens on an authenticated subdomain, and a system app has no routes",
+    );
+  }
+  if ((options as { verifyAnonymousRequest?: unknown }).verifyAnonymousRequest) {
+    throw new Error(
+      "createSystemApp: `verifyAnonymousRequest` is not supported — anonymous " +
+        "gates admit callers to an app's routes, and a system app has none",
+    );
+  }
+  return buildApp("system", options);
+}