@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/schema/host.ts

@@ -0,0 +1,792 @@
+// host.* permission factories + per-kind Home-side mechanics.
+//
+// Each factory is built via `hostable(...)` (the local binding of
+// `makeHostable(basePermission)`), which calls basePermission AND tags
+// the kind's hooks (iterateUses / toValue / grantSchema) so the host
+// registry derived in grants.ts can dispatch through them. The hooks
+// are colocated with the factory: adding a host kind is one declaration.
+
+import { z } from "zod";
+import type { Network } from "../identifiers.ts";
+import { basePermission } from "../factory.ts";
+import { makeHostable } from "../host-registry.ts";
+import { RealmCompileError, SiloRequiresError } from "../errors.ts";
+import type { ResolveArgs } from "../resolve-context.ts";
+import { REALM_LOGS_MOUNT } from "../worker-protocol/logs-socket-path.ts";
+import { REALM_STATS_MOUNT } from "../worker-protocol/stats-socket-path.ts";
+import { SPAWN_PLACEHOLDER, spawnMounts, type SpawnValue } from "../worker-protocol/spawn-paths.ts";
+import { MANAGEMENT_NET, siloNetwork } from "../worker-protocol/networks.ts";
+import { speculativeSilo } from "../speculative-silo.ts";
+
+const hostable = makeHostable(basePermission);
+
+/**
+ * Resolved shape of a `host.management()` grant. The network is fixed
+ * (the SDK-side constant); the rest this kind's `resolve` hook reads off the
+ * eval context — `home_state` identity plus the running worker. Empty strings
+ * stand in for "unconfigured" so authors can guard with
+ * `if (config.management.baseDomain)`.
+ */
+export interface ManagementValue {
+  readonly network: Network;
+  readonly baseDomain: string;
+  readonly homeSlug: string;
+  readonly workerId: string;
+  // acme-dns credentials Home provisions from Realm DNS, or null when no
+  // DNS provider is configured (fresh install / BYO-domain offline mode).
+  // Injected at eval time, never stored in the app config.
+  readonly acmeDns: {
+    readonly serverUrl: string;
+    readonly username: string;
+    readonly apiKey: string;
+    // ACME directory URL. Empty = the proxy's default (Let's Encrypt prod).
+    // Set to a staging endpoint, or to a test CA (Pebble) in the e2e.
+    readonly ca: string;
+    // PEM root to trust for the ACME endpoint, for a non-publicly-trusted
+    // test CA (Pebble). Empty for real LE / staging (publicly trusted API).
+    readonly caRootPem: string;
+  } | null;
+}
+
+const MANAGEMENT_PLACEHOLDER: ManagementValue = {
+  network: MANAGEMENT_NET,
+  baseDomain: "",
+  homeSlug: "",
+  workerId: "",
+  acmeDns: null,
+};
+
+/**
+ * Roots an operator can never point a Silo's volume under. An operator-set
+ * path lands verbatim in a bind-mount source on the worker, so dangerous
+ * roots are veto'd at write time - a Silo backed by `/etc` or
+ * `/var/run/docker.sock` never reaches the DB. Lives here (not in
+ * security.ts) to avoid the cycle schema/host.ts <-> security.ts <->
+ * grants.ts; security.ts re-exports for Home UI consumers.
+ */
+export const HOST_DIRECTORY_BLOCKLIST = [
+  "/",
+  "/proc",
+  "/sys",
+  "/dev",
+  "/run",
+  "/var/run",
+  "/var/lib/docker",
+  "/etc",
+  "/root",
+  "/home",
+  "/opt/realm",
+  "/boot",
+] as const;
+
+/**
+ * The one spelling of a host-absolute path, or `null` when the string can't be
+ * one: `//mnt///media/` and `/mnt/./media` both collapse to `/mnt/media`, and
+ * anything relative or carrying a `..` segment is refused outright rather than
+ * resolved (a path that climbs is a path whose target depends on where it was
+ * written, which is not something an admin-set string gets to do).
+ *
+ * Returning the canonical string is the point: two paths that name the same
+ * directory have to compare equal before anything can be stored or checked for
+ * overlap against what's already stored.
+ */
+export function normalizeHostPath(raw: string): string | null {
+  if (!raw.startsWith("/")) return null;
+  const segments: string[] = [];
+  for (const segment of raw.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") return null;
+    segments.push(segment);
+  }
+  return `/${segments.join("/")}`;
+}
+
+/**
+ * Whether two normalized paths name the same tree - equal, or either inside the
+ * other. Compared on separator boundaries, so `/mnt/nas/media` and
+ * `/mnt/nas/media-old` are unrelated rather than nested.
+ *
+ * Both arguments must already be through `normalizeHostPath`; a trailing slash
+ * or a doubled separator would read as a different tree.
+ */
+export function pathsOverlap(a: string, b: string): boolean {
+  if (a === b) return true;
+  const contains = (parent: string, child: string) =>
+    child.startsWith(parent === "/" ? "/" : `${parent}/`);
+  return contains(a, b) || contains(b, a);
+}
+
+export function isValidHostDirectoryPath(raw: unknown): raw is string {
+  if (typeof raw !== "string") return false;
+  const normalized = normalizeHostPath(raw);
+  if (normalized === null) return false;
+  for (const blocked of HOST_DIRECTORY_BLOCKLIST) {
+    if (normalized === blocked) return false;
+    // Not `pathsOverlap`: containment here is one-directional. Everything is
+    // under `/`, so the root entry blocks itself and nothing else.
+    if (blocked === "/") continue;
+    if (normalized.startsWith(blocked + "/")) return false;
+  }
+  return true;
+}
+
+/**
+ * Pass through the host's GPU to the container.
+ *
+ * Gives the container access to the graphics card via Docker device
+ * requests. Used for hardware-accelerated workloads like video transcoding.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/host/gpu/
+ */
+export const gpu = hostable(
+  "host.gpu",
+  z.literal(true).default(true),
+  {
+    iterateUses: (svc) => (svc.gpu === true ? [true] : []),
+    toValue: () => true as const,
+  },
+  {
+    name: "GPU passthrough",
+    phrase: "GPU passthrough (/dev/dri)",
+    helpText: "This app gets access to your graphics card.",
+    icon: "GraphicsCardIcon",
+    appKinds: "both",
+  },
+);
+
+/**
+ * Publish a port on the host machine.
+ *
+ * The app declares the port it wants; the admin can approve it as-is or
+ * change the port number on the consent screen.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/host/port/
+ */
+export const port = hostable(
+  "host.port",
+  z.number().int().min(1).max(65535),
+  {
+    iterateUses: (svc) => (svc.hostPorts ?? []).map((hp) => hp.hostPort),
+    toValue: (data: number) => ({ port: data }),
+    // Admin-grant input arrives as a raw string from the form (we don't
+    // coerce in the UI so an empty input stays empty). Coerce here, then
+    // re-validate the int range.
+    grantSchema: z.coerce.number().int().min(1).max(65535),
+  },
+  {
+    name: "Port",
+    phrase: "bind a host port",
+    helpText:
+      "This port will be reachable from the internet. You can change the port number before approving.",
+    icon: "PlugIcon",
+    appKinds: "both",
+  },
+);
+
+/**
+ * Branded host-absolute path owned by a Silo. Mirrors `PeerHostPath` /
+ * `WorkerHostPath`: lets the Silo's operator-chosen directory flow into
+ * `volumes.hostPath` without widening the literal-path type to arbitrary
+ * `string`.
+ */
+export type SiloHostPath = string & { readonly __siloHostPath: unique symbol };
+
+/**
+ * Services a member requires from its Silo: service name -> the port it
+ * answers on. The richer form of the `network` affordance - `network: true`
+ * is membership alone, a require-map is membership plus resolution.
+ */
+export type SiloRequires = Readonly<Record<string, number>>;
+
+/**
+ * How a member uses the Silo's shared directory. Declared, never guessed:
+ * writability is the biggest thing a Silo hands out, so it's the app's stated
+ * intent and the operator's consent, not a property of the path string.
+ */
+export type SiloVolumeMode = "read" | "readwrite";
+
+/** The three affordances a member can ask a Silo for. */
+export interface SiloGrants {
+  readonly network?: true | SiloRequires;
+  readonly volume?: SiloVolumeMode;
+  readonly apiKey?: true;
+}
+
+/**
+ * `SiloGrants` with at least one affordance set. Joining a Silo without
+ * asking it for anything means nothing, so `r.host.silo({})` is a compile
+ * error rather than a no-op grant the operator has to reason about.
+ */
+export type SiloGrantsInput = {
+  [K in keyof SiloGrants]-?: Required<Pick<SiloGrants, K>> & Partial<SiloGrants>;
+}[keyof SiloGrants];
+
+/**
+ * The Silo's shared directory as a complete volume entry - it goes straight
+ * into `volumes` and is mounted verbatim, so every member sees the same bytes
+ * at the same `containerPath` and can exchange absolute paths at runtime.
+ */
+export interface SiloVolume {
+  readonly hostPath: SiloHostPath;
+  readonly containerPath: string;
+  /**
+   * The Silo's group. The worker adds `group_add: [gid]` to any service that
+   * mounts a gid-carrying volume, so filesystem membership lands exactly where
+   * the mount lands - no cooperation needed from the image.
+   */
+  readonly gid: number;
+  /** `true` for `volume: "read"`, `false` for `volume: "readwrite"`. */
+  readonly readOnly: boolean;
+  /**
+   * Always `false`: a member's mount is never how a Silo gets backed up.
+   * Whether the shared bytes are backed up is the operator's answer on the
+   * Silo record, and it reaches the backup app from there - so no member
+   * speaks for the commons, and two members mounting the same tree can't
+   * enroll it twice. Stamped rather than left absent so a volume with no
+   * declared strategy stays a signal about volumes an author actually wrote.
+   */
+  readonly backup: false;
+}
+
+type ServicesFrom<N extends SiloRequires> = {
+  readonly [K in keyof N]: { readonly host: string; readonly port: number };
+};
+
+/**
+ * What `config.silo` resolves to, narrowed to the affordances that were
+ * actually asked for - reading `config.silo.apiKey` without declaring
+ * `apiKey: true` is a compile error, not an undefined at runtime.
+ *
+ * `services` only appears for a require-map, and contains exactly the names
+ * that were required: it answers "where is the thing I said I need", not
+ * "who else is in this Silo", so there is no roster to iterate and no
+ * possibly-undefined lookup to guard.
+ */
+export type SiloValue<G extends SiloGrants> = (G extends { network: infer N }
+  ? N extends SiloRequires
+    ? { readonly network: Network; readonly services: ServicesFrom<N> }
+    : { readonly network: Network }
+  : unknown) &
+  (G extends { volume: SiloVolumeMode } ? { readonly volume: SiloVolume } : unknown) &
+  (G extends { apiKey: true } ? { readonly apiKey: string } : unknown);
+
+/**
+ * The widest resolved shape - every affordance optional. This is what the
+ * runtime deals in (`resolveSilo` builds it per-declaration from the Silo
+ * record on the eval context);
+ * the per-declaration narrowing to `SiloValue<G>` is type-level only, applied
+ * by `ValueOf` in grants.ts off the author's declared flags.
+ */
+export type SiloResolved = {
+  readonly network?: Network;
+  readonly services?: Readonly<Record<string, { readonly host: string; readonly port: number }>>;
+  readonly volume?: SiloVolume;
+  readonly apiKey?: string;
+};
+
+/**
+ * One require-map entry the Silo can't satisfy: the name isn't published at
+ * all (`offeredPort` absent) or is published on a different port.
+ */
+export interface SiloRequireUnmet {
+  readonly name: string;
+  readonly port: number;
+  readonly offeredPort?: number;
+}
+
+/**
+ * The guided message for a require-map the Silo doesn't meet. Shared between
+ * Home eval and the SDK test harness so both surfaces emit byte-identical
+ * text (the harness asserts against it).
+ */
+export function siloRequiresUnmetMessage(
+  siloName: string,
+  unmet: readonly SiloRequireUnmet[],
+): string {
+  const parts = unmet.map((u) =>
+    u.offeredPort === undefined
+      ? `doesn't offer "${u.name}" on port ${u.port}`
+      : `offers "${u.name}" on ${u.offeredPort}, not ${u.port}`,
+  );
+  return `Silo "${siloName}" ${parts.join("; ")}`;
+}
+
+// Type-level only, so `ValueOf` can read the shape off `toValue` (mirrors
+// `host.management` / `home.apiAccess`). Every real value comes from
+// `resolveSilo`, built from the Silo record on the eval context.
+const SILO_PLACEHOLDER: SiloResolved = {};
+
+/**
+ * Resolve a `host.silo` declaration against the Silo the operator bound the
+ * app to.
+ *
+ * Two sides meet here: `declared` is the author's asked-for affordances,
+ * `grant` is the operator's chosen Silo id. Neither alone is enough - the
+ * author says what they want, the operator says from where.
+ *
+ * Throws rather than resolving a partial value: an app that can't get what it
+ * asked for must drop with a readable message, not push an `undefined` into a
+ * mount and fail somewhere further downstream.
+ *
+ * The throws are `validation` issues, not `eval` ones, because every failure
+ * here is the operator's to fix (wrong Silo, wrong worker, a require the Silo
+ * doesn't meet) and every message says only what they already know - their own
+ * permission path, their own Silo id, their own worker. `eval` issues get
+ * redacted to a generic string at the HTTP boundary precisely because they can
+ * carry internals; these carry none, so they reach the operator intact.
+ */
+function resolveSilo({ grant, declared, path, ctx }: ResolveArgs<unknown>): SiloResolved {
+  // Annotated rather than inferred: TypeScript only narrows past a
+  // `never`-returning call when the binding carries an explicit type.
+  const fail: (message: string) => never = (message) => {
+    throw new RealmCompileError({ kind: "validation", path: path.split("."), message });
+  };
+
+  if (typeof grant !== "string") {
+    // A speculative eval has no operator behind it, so "you didn't pick a
+    // Silo" answers a question nobody has been asked yet - and refusing there
+    // drops the app out of its own install preview.
+    //
+    // Both grant-writing routes run `sanitizeGrants`, whose `grantSchema` for
+    // this kind is a non-empty string, so a Silo grant with no id is a 400 long
+    // before it reaches here; the `fail` below is defence in depth.
+    if (ctx.speculative) return speculativeSilo(declared as SiloGrants);
+    fail("no Silo was picked for this permission");
+  }
+  const silo = ctx.silos.find((s) => s.id === grant);
+  if (!silo) fail(`Silo "${grant}" no longer exists`);
+  if (ctx.worker.internalId !== undefined && silo.workerId !== ctx.worker.internalId) {
+    // A Silo's bytes are a real directory on one box, so a member has to run
+    // on that box. Reachable by deploying a silo app to every worker.
+    fail(`Silo "${silo.name}" is on worker ${silo.workerSlug}, so this app must run there too`);
+  }
+
+  const asked = declared as SiloGrants;
+  const resolved: SiloResolved = {};
+  if (asked.network !== undefined) {
+    (resolved as { network: SiloResolved["network"] }).network = siloNetwork(silo.id);
+    if (asked.network !== true) {
+      // A require-map gates on the merged directory of the Silo's other
+      // members: every required name must be published on exactly the
+      // required port. Thrown as its own subclass so the pass structure can
+      // retry the drop when the directory later grows.
+      const offered = ctx.siloDirectory(silo.id);
+      const unmet: SiloRequireUnmet[] = [];
+      for (const [name, port] of Object.entries(asked.network)) {
+        const entry = offered.get(name);
+        if (entry === undefined) unmet.push({ name, port });
+        else if (entry.port !== port) unmet.push({ name, port, offeredPort: entry.port });
+      }
+      if (unmet.length > 0) {
+        throw new SiloRequiresError({
+          kind: "validation",
+          path: path.split("."),
+          message: siloRequiresUnmetMessage(silo.name, unmet),
+        });
+      }
+      const services: Record<string, { host: string; port: number }> = {};
+      for (const [name, port] of Object.entries(asked.network)) {
+        // The published name IS the host: the worker sets a matching
+        // network alias on the silo bridge at connect time.
+        services[name] = { host: name, port };
+      }
+      (resolved as { services: SiloResolved["services"] }).services = services;
+    }
+  }
+  if (asked.volume !== undefined) {
+    (resolved as { volume: SiloResolved["volume"] }).volume = {
+      hostPath: silo.hostPath as SiloHostPath,
+      containerPath: silo.containerPath,
+      gid: silo.gid,
+      // The author declared the mode and the operator approved it; a member
+      // that only asked to read gets a mount it cannot write through.
+      readOnly: asked.volume === "read",
+      backup: false,
+    };
+  }
+  if (asked.apiKey !== undefined) {
+    // Derived for every Silo up front, so present whenever the exists-check
+    // above passed.
+    (resolved as { apiKey: SiloResolved["apiKey"] }).apiKey = ctx.siloApiKeys.get(silo.id)!;
+  }
+  return resolved;
+}
+
+const siloRequiresSchema = z.record(z.string(), z.number().int().min(1).max(65535));
+
+const siloGrantsSchema = z
+  .object({
+    network: z.union([z.literal(true), siloRequiresSchema]).optional(),
+    volume: z.enum(["read", "readwrite"]).optional(),
+    apiKey: z.literal(true).optional(),
+  })
+  .refine((g) => g.network !== undefined || g.volume !== undefined || g.apiKey !== undefined, {
+    message: "silo() needs at least one of network, volume, apiKey",
+  });
+
+const siloFactory = hostable(
+  "host.silo",
+  siloGrantsSchema,
+  {
+    // The elevated use is the communal volume: a mount carrying a gid reads
+    // (or writes) another trust domain's bytes and joins its group. All three
+    // of hostPath, gid and writability have to match a Silo the operator bound
+    // this app to - a hand-written gid, a Silo path without the join, or a
+    // writable mount from an app that only asked to read, all fail the gate.
+    // Network membership and the apiKey have no per-service use; they fall out
+    // of the grant being in place.
+    iterateUses: function* (svc) {
+      for (const v of svc.volumes ?? []) {
+        if (v.gid !== undefined) {
+          yield { hostPath: v.hostPath, gid: v.gid, readOnly: v.readOnly === true };
+        }
+      }
+    },
+    // Type-level only. The grant carries a Silo id, which means nothing
+    // without the Silo record, so every real value comes from `resolve`
+    // below; this exists so `ValueOf` can read the resolved shape.
+    toValue: (): SiloResolved => SILO_PLACEHOLDER,
+    resolve: resolveSilo,
+    // The author declares which affordances they want; the grant carries
+    // which Silo the operator bound (its id).
+    grantSchema: z.string().min(1),
+  },
+  {
+    name: "Silo",
+    phrase: "join a Silo",
+    helpText:
+      "This app joins a Silo you pick - an operator-owned network, shared directory, and shared credential. Everything in a Silo can see everything else in it, so only put apps together that you mean to share.",
+    icon: "StackIcon",
+    // Single-only: a Silo is a directory on one box, so the grant means
+    // nothing spread across a fleet.
+    appKinds: "single",
+  },
+);
+
+/**
+ * A `silo()` record with the author's declared flags preserved on `data`.
+ *
+ * Every other permission's `data` is `z.output<schema>` - one fixed type per
+ * kind, which is all `FactoryFor` can express. Silo is the one kind whose
+ * resolved value depends on what was asked for, so the factory is re-typed
+ * generically and the chain methods are re-declared here. They have to be
+ * re-declared rather than inherited: `Omit` instantiates polymorphic `this`
+ * against the *source* type, so an inherited `.reason()` would silently hand
+ * back the wide record and undo the narrowing. Inside an interface, `this`
+ * survives.
+ */
+interface SiloRecord<G extends SiloGrantsInput> extends Omit<
+  ReturnType<typeof siloFactory>,
+  "data" | "reason" | "describe" | "optional"
+> {
+  readonly data: G;
+  reason(text: string): this & { readonly meta: { readonly reason: string } };
+  describe(text: string): this;
+  optional(): this & { readonly meta: { readonly isOptional: true } };
+}
+
+/**
+ * Join an operator-owned Silo: a shared network, a shared directory, and a
+ * shared credential that outlive every app in them.
+ *
+ * The operator creates the Silo and points apps at it, so a set of apps
+ * installed separately can share files and talk to each other without any of
+ * them owning the anchor. Ask for the affordances you need and nothing else -
+ * `config.silo` is typed to exactly what you declared.
+ *
+ * ```ts
+ * silo: r.host
+ *   .silo({ network: { sabnzbd: 8080 }, volume: "readwrite" })
+ *   .reason("Import finished downloads into your library"),
+ * ```
+ *
+ * A require-map (rather than `network: true`) both gates the install - the
+ * operator can't pick a Silo that doesn't offer those services - and resolves
+ * those names into `config.silo.services`.
+ *
+ * `volume` says what you do with the shared bytes: `"read"` mounts them
+ * read-only, `"readwrite"` lets you write. Ask for `"read"` when that's all
+ * you need - it's the difference the operator sees on the consent screen.
+ *
+ * For storage the app keeps to itself, don't reach for this: a relative
+ * `volumes` path persists with no permission and no operator decision.
+ *
+ * Only a single app (`createApp`) may declare this. A Silo is a directory on
+ * one box, so a member runs on that box - "every compatible worker" is the
+ * opposite claim.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/host/silo/
+ */
+export const silo = siloFactory as unknown as Omit<typeof siloFactory, never> &
+  (<G extends SiloGrantsInput>(grants: G) => SiloRecord<G>);
+
+/**
+ * Join the Home's management bridge network and read Home-side identity.
+ *
+ * Bundles the bridge network with the dashboard URL pieces every system-app
+ * proxy or sidecar tends to want at once - `network` (the management bridge),
+ * `baseDomain` and `homeSlug` (owned by Home's `home_state`, set by the
+ * installer or operator), and `workerId` (the running worker's short slug).
+ *
+ * The `network` half is the SDK-known constant; the rest come off the eval
+ * context. Empty strings stand in for "not yet configured" - guard with
+ * `if (config.management.baseDomain && config.management.homeSlug)` before
+ * deriving URLs.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/host/management/
+ */
+export const management = hostable(
+  "host.management",
+  z.literal(true).default(true),
+  {
+    // The "use" of management is implicit — joining the network and
+    // reading the URL pieces falls out of the grant being in place;
+    // nothing in the resolved service spec distinguishes a user from a
+    // non-user.
+    iterateUses: () => [],
+    // Type-level only. The network is the SDK-side constant, but every other
+    // field is Home's, so the real value comes from `resolve`.
+    toValue: (): ManagementValue => MANAGEMENT_PLACEHOLDER,
+    resolve: ({ ctx }): ManagementValue => ({
+      network: MANAGEMENT_NET,
+      baseDomain: ctx.home.baseDomain,
+      homeSlug: ctx.home.homeSlug,
+      workerId: ctx.worker.id,
+      // acme-dns username is the domain slug = the first label of baseDomain.
+      acmeDns: ctx.home.acmeDns
+        ? {
+            serverUrl: ctx.home.acmeDns.serverUrl,
+            username: ctx.home.baseDomain.split(".")[0] ?? "",
+            apiKey: ctx.home.acmeDns.apiKey,
+            ca: ctx.home.acmeDns.ca,
+            caRootPem: ctx.home.acmeDns.caRootPem,
+          }
+        : null,
+    }),
+  },
+  {
+    name: "Management bridge + Home identity",
+    phrase: "join the management bridge network and read Home identity",
+    helpText:
+      "This grants access to the management bridge network and the Home's dashboard URL pieces.",
+    icon: "ShareNetworkIcon",
+    danger: true,
+    appKinds: "both",
+  },
+);
+
+/**
+ * Install host-level iptables and ip6tables rules from the container.
+ *
+ * Unlocks the service-level `iptables: true` field. The renderer expands
+ * that into the primitives the firewall needs - the `NET_ADMIN` capability
+ * to mutate netfilter rules, plus host network mode so the rules apply to
+ * host traffic and Docker's `DOCKER-USER` chain.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/host/iptables/
+ */
+export const iptables = hostable(
+  "host.iptables",
+  z.literal(true).default(true),
+  {
+    iterateUses: (svc) => (svc.iptables === true ? [true] : []),
+    toValue: () => true as const,
+  },
+  {
+    name: "Host iptables",
+    phrase: "install host iptables and ip6tables rules",
+    helpText:
+      "This app installs firewall rules on the host. Required for the firewall app to lock down which ports are reachable.",
+    icon: "ShieldIcon",
+    danger: true,
+    appKinds: "both",
+  },
+);
+
+/**
+ * Allow outbound internet access from the container.
+ *
+ * Without this permission, app networks are created with Docker's
+ * `internal: true` flag - containers can talk to peers they have explicit
+ * permission for, but cannot reach the outside world.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/host/egress/
+ */
+export const egress = hostable(
+  "host.egress",
+  z.literal(true).default(true),
+  {
+    iterateUses: () => [],
+    toValue: () => true as const,
+  },
+  {
+    name: "Internet access",
+    phrase: "outbound internet access",
+    helpText:
+      "Without this, the app can only communicate with other apps on your server. Granting this allows it to make outbound connections to the internet.",
+    icon: "GlobeIcon",
+    appKinds: "both",
+  },
+);
+
+/**
+ * Receive a stream of every container's stdout and stderr from the worker
+ * via a unix socket on the host.
+ *
+ * Resolves to the mount for the worker's logs socket DIRECTORY — spread it
+ * into `volumes` (`volumes: [config.logs]`, or override `containerPath` to put
+ * it elsewhere). Inside the container, connect to the `logs.sock` inside the
+ * mounted dir with `connectToLogsSocket` / `streamLogs` from
+ * `@yourrealm/sdk/runtime/logs-client`. (The mount is the directory, not the
+ * socket file: a file bind-mount of a unix socket doesn't wire across
+ * containers on macOS Docker.)
+ *
+ * `readOnly: true` and not negotiable — the directory is shared by every app
+ * holding this grant, so a writable mount would let any of them unlink the
+ * socket and put their own listener in its place. Overriding it is a grant
+ * violation, not a preference.
+ *
+ * The grant exempts the resolved path from the absolute-mount gate, so a
+ * bare `host.logs()` is enough to wire the volume.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/host/logs/
+ */
+/**
+ * Probe-the-UX permission. No worker advertises this kind, so an app
+ * that declares it can only succeed once a (hypothetical) worker that
+ * supports it enrolls. Useful for exercising the
+ * "no worker can satisfy this required permission" path in the
+ * install panel without a real driver behind it.
+ */
+export const rocketLaunch = hostable(
+  "host.rocketLaunch",
+  z.literal(true).default(true),
+  {
+    iterateUses: () => [],
+    toValue: () => true as const,
+  },
+  {
+    name: "Rocket launch",
+    phrase: "launch a rocket",
+    helpText:
+      "Permission with no worker that can satisfy it. Used to exercise the unsupported-permission UX.",
+    icon: "RocketLaunchIcon",
+    appKinds: "both",
+  },
+);
+
+export const logs = hostable(
+  "host.logs",
+  z.literal(true).default(true),
+  {
+    // The "use" of host.logs is implicit — mounting the socket dir falls out
+    // of the grant being in place; the resolved hostPath is exempted from the
+    // absolute-mount check via `collectAllowed` in the Home eval graph. That
+    // exemption carries the read-only requirement with it, so an app that
+    // mounts the shared dir writable is rejected there.
+    iterateUses: () => [],
+    toValue: () => REALM_LOGS_MOUNT,
+  },
+  {
+    name: "Container logs",
+    phrase: "stream container logs from every app",
+    helpText:
+      "This app receives the stdout and stderr of every container running on this Worker. Useful for log forwarders and audit collectors.",
+    icon: "TerminalWindowIcon",
+    danger: true,
+    appKinds: "both",
+  },
+);
+
+/**
+ * Ask the worker for a point-in-time sample of the host and every container
+ * running on it, over a unix socket.
+ *
+ * The read-only counterpart to `host.logs`: same broker shape, same
+ * all-or-nothing scope, but request/response instead of a stream. Resolves to
+ * the mount for the worker's stats socket DIRECTORY — spread it into `volumes`
+ * (`volumes: [config.stats]`, or override `containerPath`). Inside the
+ * container, connect to the `stats.sock` inside the mounted dir with
+ * `sampleStats` from `@yourrealm/sdk/runtime/stats-client`. (The mount is the
+ * directory, not the socket file: a file bind-mount of a unix socket doesn't
+ * wire across containers on macOS Docker.) `readOnly: true` is fixed, for the
+ * same shared-directory reason as `host.logs`.
+ *
+ * The grant exempts the resolved path from the absolute-mount gate, so a
+ * bare `host.stats()` is enough to wire the volume.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/host/stats/
+ */
+export const stats = hostable(
+  "host.stats",
+  z.literal(true).default(true),
+  {
+    // The "use" of host.stats is implicit — mounting the socket dir falls out
+    // of the grant being in place; the resolved hostPath is exempted from the
+    // absolute-mount check via `collectAllowed` in the Home eval graph. That
+    // exemption carries the read-only requirement with it, so an app that
+    // mounts the shared dir writable is rejected there.
+    iterateUses: () => [],
+    toValue: () => REALM_STATS_MOUNT,
+  },
+  {
+    name: "Container stats",
+    phrase: "read resource usage for every app's containers",
+    helpText:
+      "This app can sample the resource usage of every container running on this Worker, plus the host's own load, memory, and disks. Read-only: it can see your fleet, but can't touch it.",
+    icon: "PulseIcon",
+    danger: true,
+    appKinds: "both",
+  },
+);
+
+/**
+ * Spawn disposable, fully-hardened containers on the worker - one box per
+ * job, torn down the moment it exits - without ever holding the Docker
+ * socket. The app picks what to run; the worker dictates how it runs
+ * (hardening, network, lifecycle). The canonical consumer is a builder
+ * running attacker-controlled `RUN` steps.
+ *
+ * Resolves to `{ socket, scratch, artifacts }`, three mounts Home fills per-app
+ * at eval (`/opt/realm/worker/spawn/sock/<appId>` + `data/<appId>/scratch` +
+ * `data/<appId>/artifacts`): the broker socket DIRECTORY to mount (connect to
+ * `spawn.sock` inside it), the scratch dir to stage a build context in (input),
+ * and the artifacts dir to read a build's output back from. Spread each into
+ * `volumes`. `socket` is `readOnly: true` and can't be overridden — connecting
+ * to the broker needs no write access to the directory holding it; `scratch`
+ * and `artifacts` are the app's own storage and stay writable. All three are
+ * built per-app by this kind's `resolve` hook (mirrors `home.apiAccess`).
+ * The grant exempts all three resolved paths from the absolute-mount gate,
+ * so a bare `host.spawn()` is enough to wire them. There is no network:
+ * the box attaches to the untrusted-zone DMZ broker-side, and no app service
+ * may sit on that DMZ.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/host/spawn/
+ */
+export const spawn = hostable(
+  "host.spawn",
+  z.literal(true).default(true),
+  {
+    // The "use" of host.spawn is implicit — mounting the socket/scratch/
+    // artifacts dirs falls out of the grant being in place; the resolved
+    // paths are exempted from the absolute-mount gate via `collectAllowed`
+    // in the Home eval graph.
+    iterateUses: () => [],
+    // Type-level only; every real value comes from `resolve`, since all three
+    // paths are per-app and the grant carries only presence.
+    toValue: (): SpawnValue => SPAWN_PLACEHOLDER,
+    // `socket` is the per-app DIRECTORY the app mounts (connect to
+    // `spawn.sock` inside); the wire carries the socket file inside it (the
+    // path the worker binds). scratch/artifacts are dir mounts.
+    resolve: ({ ctx }): SpawnValue => spawnMounts(ctx.appId),
+  },
+  {
+    name: "Spawn disposable containers",
+    phrase: "spawn disposable hardened containers on the worker",
+    helpText:
+      "This app can start one-shot, fully-hardened containers on your server (e.g. to run builds). The worker forces the hardening, network, and lifecycle; the app never gets the Docker socket.",
+    icon: "CubeIcon",
+    danger: true,
+    appKinds: "both",
+  },
+);