@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/schema/inputs.ts

@@ -0,0 +1,26 @@
+// input.* form-field factories.
+//
+// Inputs declare a schema for the user's runtime value (the Home UI uses
+// the schema to validate what the user types). The factory takes no
+// config-time value — chain methods configure title, prefill, etc.
+
+import { z } from "zod";
+import { baseInput, cloneAnd, numberInput } from "../factory.ts";
+
+export const text = baseInput("input.text", z.string());
+
+export const secret = baseInput("input.secret", z.string());
+
+// numberInput carries the `.int()/.min()/.max()` chain (see factory.ts).
+export const number = numberInput("input.number", z.number());
+
+export const boolean = baseInput("input.boolean", z.boolean());
+
+// Enum is parameterized — `r.input.enum(["a", "b"])` returns a fully-bound
+// record, not a 0-arg factory like text/secret, because the values are part
+// of the kind binding. `values` is also attached to the record so the sandbox
+// walker can surface them to the Home UI without poking at Zod internals.
+export function enum_<const T extends readonly [string, ...string[]]>(values: T) {
+  const record = baseInput("input.enum", z.enum(values))();
+  return cloneAnd(record, { values }) as typeof record & { readonly values: T };
+}

package/src/schema/nodes.ts

@@ -0,0 +1,75 @@
+// Sections and tabs — UI structural nodes that wrap inputs (and nested
+// sections) into groupings. They are generic functions rather than Builders
+// because their "value" is a children record whose types must narrow per
+// call site (`section({port: number()})` preserves `port: NumberInput`),
+// and the Builder binds I at schema-bind time. Chain-method helpers come
+// from factory.ts.
+
+import { cloneAnd, defineMethod, type CompleteInput, type CompletePermission } from "../factory.ts";
+
+// ----- Section -------------------------------------------------------------
+
+export type SectionChild = CompletePermission | CompleteInput | CompleteSection;
+
+export interface SectionRecord<C extends Record<string, SectionChild>> {
+  readonly kind: "node.section";
+  readonly children: C;
+  readonly meta: {
+    readonly isOptional: boolean;
+    readonly title?: string;
+    readonly description?: string;
+  };
+  title(this: this, text: string): this;
+  describe(this: this, text: string): this;
+  optional(this: this): this & { readonly meta: { readonly isOptional: true } };
+}
+
+export type CompleteSection = SectionRecord<Record<string, SectionChild>>;
+
+export function section<C extends Record<string, SectionChild>>(children: C): SectionRecord<C> {
+  const record = {
+    kind: "node.section" as const,
+    children,
+    meta: { isOptional: false },
+  } as unknown as SectionRecord<C>;
+  defineMethod(record, "title", function (this: SectionRecord<C>, text: string) {
+    return cloneAnd(this, { meta: { ...this.meta, title: text } });
+  });
+  defineMethod(record, "describe", function (this: SectionRecord<C>, text: string) {
+    return cloneAnd(this, { meta: { ...this.meta, description: text } });
+  });
+  defineMethod(record, "optional", function (this: SectionRecord<C>) {
+    return cloneAnd(this, { meta: { ...this.meta, isOptional: true } });
+  });
+  return record;
+}
+
+// ----- Tab -----------------------------------------------------------------
+
+export type TabChild = CompletePermission | CompleteInput | CompleteSection;
+
+export interface TabRecord<C extends Record<string, TabChild>> {
+  readonly kind: "node.tab";
+  readonly children: C;
+  readonly meta: {
+    readonly title?: string;
+    readonly description?: string;
+  };
+  title(this: this, text: string): this;
+  describe(this: this, text: string): this;
+}
+
+export function tab<C extends Record<string, TabChild>>(children: C): TabRecord<C> {
+  const record = {
+    kind: "node.tab" as const,
+    children,
+    meta: {},
+  } as unknown as TabRecord<C>;
+  defineMethod(record, "title", function (this: TabRecord<C>, text: string) {
+    return cloneAnd(this, { meta: { ...this.meta, title: text } });
+  });
+  defineMethod(record, "describe", function (this: TabRecord<C>, text: string) {
+    return cloneAnd(this, { meta: { ...this.meta, description: text } });
+  });
+  return record;
+}

package/src/schema/peer.ts

@@ -0,0 +1,400 @@
+// peers.* permission factories + per-kind Home-side mechanics.
+//
+// Each factory is built via `makePeerable`, which calls `basePermission`
+// AND tags the factory with the kind's hooks (extract / resolve /
+// extractNetworks / etc.) as non-enumerable symbol properties. The peer
+// registry is derived later via `derivePeerRegistry(peers)` — there is
+// no mutable module-scoped table. Adding a peer kind is one declaration.
+
+import { z } from "zod";
+import type { Network } from "../identifiers.ts";
+import type { HomeService } from "../resolve.ts";
+import { basePermission } from "../factory.ts";
+import { makePeerable, type AllowedProvider } from "../peer-registry.ts";
+import type { BuildAppEntry } from "./build-apps.ts";
+import type { DomainMode } from "./public-domain.ts";
+
+export type { AllowedProvider } from "../peer-registry.ts";
+
+const peerable = makePeerable(basePermission);
+
+// ----- Domain types -------------------------------------------------------
+
+/**
+ * The router shape a proxy app consumes. Deliberately NOT a structural alias
+ * of `HomeService["router"]`: the resolved side carries
+ * `r.home.publicDomain()`'s whole record (hosts + the operator's mode), and a
+ * proxy wants the two flattened - one list of hostnames to route, one mode to
+ * apply. `extract` below does that flattening, so narrowing the resolved shape
+ * can't silently change what Caddy is handed.
+ *
+ * `publicDomain` keeps the `string | string[]` union rather than narrowing to
+ * an array: a single host is the overwhelmingly common case, and the union is
+ * what a proxy's own tests can write by hand. The key is **absent** (not `[]`)
+ * when the operator granted no hosts, so "no public route" is structural
+ * rather than a truthiness check on an empty array.
+ */
+export type RoutedRouter = Omit<NonNullable<HomeService["router"]>, "publicDomain"> & {
+  publicDomain?: string | string[];
+  domainMode: DomainMode;
+};
+
+export interface RoutedService {
+  serviceId: string;
+  router: RoutedRouter;
+}
+
+export interface RoutedAppEntry {
+  appId: string;
+  network: Network;
+  services: RoutedService[];
+  /**
+   * Header-brokering names the app declared via `getTrustedHeaders` (absent
+   * when it didn't). The proxy injects these on the app's authenticated
+   * route (lifted from the ForwardAuth response) and strips them from
+   * every other path so identity can't be spoofed.
+   */
+  trustedHeaderKeys?: string[];
+}
+
+export interface HostPortEntry {
+  port: number;
+}
+
+export type BackupStrategy =
+  | { kind: "file-copy" }
+  | { kind: "sqlite"; file: string }
+  | { kind: "pg-dump"; url: string; version: number; network: Network }
+  | { kind: "valkey-save"; url: string; network: Network }
+  | { kind: "mysql-dump"; url: string; version: number; network: Network };
+
+export type NetworkStrategy = Extract<BackupStrategy, { network: Network }>;
+export type VolumeStrategy = Exclude<BackupStrategy, { network: Network }>;
+
+/**
+ * Branded host-absolute path sourced from a peer (e.g. resolved
+ * operator-placed Silo of a producer). Carries through `BackupTarget` so it
+ * flows into `volumes.hostPath` alongside `` `./${string}` `` without
+ * widening the literal-path type.
+ */
+export type PeerHostPath = string & { readonly __peerHostPath: unique symbol };
+
+export interface BackupTarget {
+  appId: string;
+  serviceKey: string;
+  hostPath: PeerHostPath;
+  strategy: BackupStrategy;
+}
+
+export function isNetworkStrategy(s: BackupStrategy): s is NetworkStrategy {
+  return "network" in s;
+}
+
+export function isVolumeStrategy(s: BackupStrategy): s is VolumeStrategy {
+  return !("network" in s);
+}
+
+// ----- Helpers ------------------------------------------------------------
+
+function appNetwork(appId: string): Network {
+  return `realm_${appId}` as Network;
+}
+
+/**
+ * Walk a JSON structure and rewrite every `{kind:"derived",
+ * appId:"__self__"}` ref marker to `{kind:"shared", providerAppId,
+ * serviceKey}`. Backup volumes' extract uses this: the provider's
+ * `getServiceDefinition` emits `derived(__self__)` for its own URL, and
+ * `__self__` resolves against whichever app the walker is running for.
+ * The backup app is a different app, so without the rewrite it would
+ * hash with its own appId instead of the provider's and derive the wrong
+ * password. The rewrite also puts the marker under the grant check, so
+ * only an app holding the matching peer grant can resolve it.
+ */
+function rewriteSelfDerivedToShared(
+  value: unknown,
+  providerAppId: string,
+  serviceKey: string,
+): unknown {
+  if (value == null || typeof value !== "object") return value;
+  if (Array.isArray(value)) {
+    return value.map((v) => rewriteSelfDerivedToShared(v, providerAppId, serviceKey));
+  }
+  if ("__realmRef" in value) {
+    const inner = (value as { __realmRef: unknown }).__realmRef;
+    return { __realmRef: rewriteMarker(inner, providerAppId, serviceKey) };
+  }
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    out[k] = rewriteSelfDerivedToShared(v, providerAppId, serviceKey);
+  }
+  return out;
+}
+
+function rewriteMarker(marker: unknown, providerAppId: string, serviceKey: string): unknown {
+  if (marker == null || typeof marker !== "object") return marker;
+  const m = marker as { kind?: string; appId?: string; name?: string; parts?: unknown[] };
+  if (m.kind === "derived" && m.appId === "__self__" && typeof m.name === "string") {
+    return { kind: "shared", providerAppId, serviceKey, name: m.name };
+  }
+  if (m.kind === "concat" && Array.isArray(m.parts)) {
+    return {
+      kind: "concat",
+      parts: m.parts.map((p) =>
+        typeof p === "string" ? p : rewriteMarker(p, providerAppId, serviceKey),
+      ),
+    };
+  }
+  return marker;
+}
+
+// ----- Factories ----------------------------------------------------------
+
+/**
+ * Read every app on this worker that exposes a routed service.
+ *
+ * Home aggregates routing info from every peer that declares a
+ * `router` and passes it in. The grant also lets the app join each
+ * routed app's network so traffic can actually reach them.
+ *
+ * Only single apps can declare a `router` (system apps are routeless by
+ * construction — `checkSystemAppRoutes`), so a system app never appears
+ * in this aggregation as a producer.
+ *
+ * Only a system app (`createSystemApp`) may declare this. It aggregates
+ * across every app on the worker, which is fleet-infrastructure work.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/peers/routed-apps/
+ */
+export const routedApps = peerable(
+  "peers.routedApps",
+  z.literal(true).default(true),
+  {
+    extract(appId, state): RoutedAppEntry[] {
+      const services: RoutedService[] = [];
+      for (const [serviceId, svc] of Object.entries(state.services)) {
+        if (svc.router == null) continue;
+        // Destructured rather than spread-then-overwrite so the flattened
+        // shape falls out of the code: `rest` cannot carry the record
+        // through, and an added router field arrives in `rest` for free.
+        const { publicDomain, ...rest } = svc.router;
+        const hosts = publicDomain?.hosts ?? [];
+        services.push({
+          serviceId,
+          router: {
+            ...rest,
+            domainMode: publicDomain?.domainMode ?? "redirect",
+            // Key omitted entirely when the operator granted no hosts, so a
+            // downstream truthiness check can't see an empty array as "has a
+            // public domain".
+            ...(hosts.length > 0 ? { publicDomain: [...hosts] } : {}),
+          },
+        });
+      }
+      if (services.length === 0) return [];
+      const trustedHeaderKeys = state.trustedHeaders?.keys ?? [];
+      return [{ appId, network: appNetwork(appId), services, trustedHeaderKeys }];
+    },
+    resolve(entries) {
+      // Sorted, because the world arrives in `contributions` Map insertion
+      // order and the fixpoint loop mutates that: a re-evaluated app is
+      // deleted and re-set, moving its entries to the end, so two renders
+      // of the same realm would emit different route order. `appId` is
+      // unique per entry, so this is a total order needing no tiebreak.
+      return [...entries].sort((a, b) => (a.appId < b.appId ? -1 : a.appId > b.appId ? 1 : 0));
+    },
+    extractNetworks(entry) {
+      return entry.network;
+    },
+    producerPredicate(svc) {
+      return svc.router != null;
+    },
+  },
+  {
+    name: "Routed apps",
+    phrase: "join routed app networks",
+    helpText:
+      "This app reads the list of all routed apps on this Worker and joins their networks to route traffic.",
+    icon: "ShareNetworkIcon",
+    danger: true,
+    // System-only: an aggregated view over every app on the worker.
+    // Widening later is additive where narrowing is not.
+    appKinds: "system",
+  },
+);
+
+/**
+ * Read every approved host port across apps on this worker.
+ *
+ * Home aggregates every approved `host.port()` and passes the port
+ * numbers in. Reactive: when port approvals change anywhere on the
+ * worker, this app re-evaluates and redeploys if the list shifts.
+ *
+ * Only a system app (`createSystemApp`) may declare this. It aggregates
+ * across every app on the worker, which is fleet-infrastructure work.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/peers/host-ports/
+ */
+export const hostPorts = peerable(
+  "peers.hostPorts",
+  z.literal(true).default(true),
+  {
+    extract(_appId, state): HostPortEntry[] {
+      const out: HostPortEntry[] = [];
+      for (const svc of Object.values(state.services)) {
+        for (const hp of svc.hostPorts ?? []) out.push({ port: hp.hostPort });
+      }
+      return out;
+    },
+    resolve(entries) {
+      return entries;
+    },
+  },
+  {
+    name: "Host ports",
+    phrase: "read host port allocations",
+    helpText: "This app reads the list of all approved host ports across apps on this Worker.",
+    icon: "ShareNetworkIcon",
+    // System-only: same aggregated shape as routedApps.
+    appKinds: "system",
+  },
+);
+
+/**
+ * Read every backup target across apps on this worker.
+ *
+ * Home aggregates volume metadata from every app with a backup
+ * strategy and passes in a list of targets - app ID, service key, host
+ * path, and the strategy itself. Network-based strategies (pg-dump,
+ * valkey-save, mysql-dump) carry a connection URL and network handle.
+ * Reactive: re-evaluates when apps are installed or removed.
+ *
+ * Only a system app (`createSystemApp`) may declare this. It aggregates
+ * across every app on the worker, which is fleet-infrastructure work.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/peers/backup-volumes/
+ */
+export const backupVolumes = peerable(
+  "peers.backupVolumes",
+  z.literal(true).default(true),
+  {
+    extract(appId, state): BackupTarget[] {
+      const out: BackupTarget[] = [];
+      for (const [serviceKey, svc] of Object.entries(state.services)) {
+        for (const vol of svc.volumes ?? []) {
+          if (!vol.backup) continue;
+          const scopedPath = vol.hostPath.startsWith("./")
+            ? `./apps/${appId}/${vol.hostPath.slice(2)}`
+            : vol.hostPath;
+          const isNetwork = "url" in vol.backup;
+          const rewritten = rewriteSelfDerivedToShared(vol.backup, appId, serviceKey) as Record<
+            string,
+            unknown
+          >;
+          const strategy = isNetwork
+            ? ({ ...rewritten, network: appNetwork(appId) } as BackupStrategy)
+            : (rewritten as BackupStrategy);
+          out.push({
+            appId,
+            serviceKey,
+            hostPath: scopedPath as PeerHostPath,
+            strategy,
+          });
+        }
+      }
+      return out;
+    },
+    resolve(entries) {
+      return entries;
+    },
+    extractNetworks(entry) {
+      return isNetworkStrategy(entry.strategy) ? entry.strategy.network : undefined;
+    },
+    extractPeerVolumes(entry) {
+      return isNetworkStrategy(entry.strategy) ? undefined : entry.hostPath;
+    },
+    extractAllowedProvider(entry): AllowedProvider {
+      return { appId: entry.appId, serviceKey: entry.serviceKey };
+    },
+    producerPredicate(svc) {
+      return svc.volumes?.some((v) => !!v.backup) ?? false;
+    },
+  },
+  {
+    name: "Backup volumes",
+    phrase: "mount peer volumes for backup",
+    helpText:
+      "This app reads the list of all volumes with backup strategies and mounts them for snapshotting.",
+    icon: "ShareNetworkIcon",
+    danger: true,
+    // System-only: same aggregated shape as routedApps.
+    appKinds: "system",
+  },
+);
+
+/**
+ * Read the build recipe of every build-from-source service in the realm.
+ *
+ * Home resolves each `build:` service's recipe (dockerfile / context /
+ * buildArgs, with `build: true` normalized to `{}`) and passes the list in,
+ * keyed by `(appId, service)`. Forge materializes it as a watched file and
+ * looks the recipe up when a push triggers a build, so the image is built with
+ * the author's recipe instead of the root-Dockerfile default. Reactive:
+ * re-evaluates when a build app is installed or removed. No networks — Forge
+ * clones source and builds in a disposable box; it never joins the targets.
+ *
+ * Realm-wide, unlike every other peer permission: the list covers every Worker
+ * in the Realm, not just the one the builder runs on. A Realm has a single
+ * builder, so a per-Worker list would mean only the box it sits on could host
+ * build-from-source apps at all. Safe because an entry is only ever read — it
+ * carries no network to join, no host path to mount and no startup ordering,
+ * so one from another Worker is the same inert data as one from your own.
+ *
+ * Only a single app (`createApp`) may declare this. Its consumer is the
+ * builder, and a realm has one builder.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/peers/build-apps/
+ */
+export const buildApps = peerable(
+  "peers.buildApps",
+  z.literal(true).default(true),
+  // `extract` + `resolve` and NOTHING else, deliberately. Home unions this
+  // kind's entries across workers (`isBuildAppEntry` in peer-world.ts is the
+  // filter), which is only sound while an entry is inert data anywhere in the
+  // realm. Each of the four hooks omitted here would turn one into something
+  // that exists on exactly one box, leaving a consumer on another worker with a
+  // dangling reference:
+  //   - extractNetworks: a docker network on that box to join
+  //   - extractPeerVolumes: a host path on that box to mount
+  //   - extractAllowedProvider: a `shared` ref you may dereference
+  //   - producerPredicate: a depends_on edge, which also fails the worker's
+  //     dependsOn validation because a pinless build target is off the wire
+  // Adding any of the four gives up realm scope — peer-world.test.ts fails.
+  {
+    extract(appId, state): BuildAppEntry[] {
+      const out: BuildAppEntry[] = [];
+      for (const [service, svc] of Object.entries(state.services)) {
+        if (svc.build != null && svc.image == null) {
+          out.push({ appId, service, recipe: svc.build });
+        }
+      }
+      return out;
+    },
+    resolve(entries) {
+      return entries;
+    },
+  },
+  {
+    name: "Build apps",
+    phrase: "read the recipes of build apps",
+    helpText:
+      "This app reads the build recipe of every build-from-source service across every app in your Realm, on any Worker.",
+    icon: "ShareNetworkIcon",
+    danger: true,
+    // Single-only: the one consumer is forge, and the builder is a
+    // singleton — enforced on `home.apiAccess` by builderScopeIssue,
+    // not here. Aggregated like the three above; the restriction is
+    // about who reads it, not what it holds.
+    appKinds: "single",
+  },
+);

package/src/schema/public-domain.ts

@@ -0,0 +1,116 @@
+// The public-domain value type, its brand, and the hostname schema both
+// sides of the boundary parse against.
+//
+// A leaf module holding only `zod` on purpose: `service-definition.ts`,
+// `resolve.ts`, `schema/peer.ts` and `schema/home.ts` all need these, and
+// putting them in `schema/home.ts` would form an import cycle with
+// `resolve.ts`. `normalizeHost()` stays private: everything that needs it gets
+// it by parsing through a schema that normalizes on the way in - the
+// `domain_claim` key through `publicDomainValueSchema`, the install form's
+// domain editor through `publicDomainHostSchema`.
+//
+// QuickJS-safe: only `z` + pure constants at module load.
+
+import { z } from "zod";
+
+/**
+ * A hostname the operator brought and granted to one app.
+ *
+ * Branded so `router.publicDomain` can only be fed the resolved value of a
+ * `r.home.publicDomain()` grant - a bare `"example.com"` doesn't typecheck.
+ * That is what makes the permission the sole door onto a public route.
+ * Erased at runtime, so the real gate is `iterateUses` + `checkAppGrants`
+ * (see `schema/home.ts`); the brand is DX.
+ */
+export type PublicDomain = string & { readonly __publicDomain: unique symbol };
+
+/**
+ * What to do when the operator granted more than one host. `"redirect"`
+ * (the default) serves the first and 301s the rest to it; `"all"` serves
+ * the app at every granted host. Operator state on the grant, not an
+ * author decision - which is why it travels inside the value rather than
+ * sitting beside it on the router.
+ */
+export type DomainMode = "redirect" | "all";
+
+/**
+ * What `r.home.publicDomain()` resolves to. Ordered, with `hosts[0]`
+ * canonical - there is no separate `primary` field, because storing the
+ * canonical host twice is how the two drift. `hosts: []` when the operator
+ * enabled the permission but supplied no domain, which must emit no route.
+ */
+export interface PublicDomainValue {
+  readonly hosts: readonly PublicDomain[];
+  readonly domainMode: DomainMode;
+}
+
+// One DNS label: 1-63 characters, alphanumeric, interior hyphens only.
+// Assembled from a string so the two-label minimum below stays readable.
+const LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
+const HOSTNAME = new RegExp(`^${LABEL}(?:\\.${LABEL})+$`);
+
+// Lowercase + trailing dot stripped. Both matter beyond tidiness: the
+// baseDomain reservation in `checkPublicDomains` is a suffix comparison, so
+// `Photos.EXAMPLE.com` or `photos.example.com.` would slip past it otherwise,
+// and running every claim through this is what makes `Photos.example.com` and
+// `photos.example.com` one `domain_claim` row.
+function normalizeHost(host: string): string {
+  return host.trim().replace(/\.$/, "").toLowerCase();
+}
+
+/**
+ * One granted hostname. Normalized first, then constrained to the DNS
+ * charset - this is the gate the Caddy config builder inherits, and the
+ * reason a host can carry no quote, backtick, brace or whitespace into a
+ * route matcher.
+ *
+ * Exported for the install form's domain editor, which parses each typed host
+ * against this exact schema rather than a second hostname regex: the operator
+ * reads the server's own message, and the row that lands is already in the
+ * normalized form `domain_claim`'s primary key compares on.
+ */
+export const publicDomainHostSchema = z
+  .string()
+  .transform(normalizeHost)
+  .refine((h) => h.length <= 253 && HOSTNAME.test(h), {
+    message:
+      "must be a hostname of at least two labels using letters, digits and hyphens (e.g. photos.example.com)",
+  });
+
+/**
+ * First occurrence wins, order preserved - so `hosts[0]` stays canonical.
+ *
+ * Run after normalization, which is what makes `Photos.example.com` and
+ * `photos.example.com` one entry rather than two.
+ */
+export function dedupeHosts(hosts: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const host of hosts) {
+    if (seen.has(host)) continue;
+    seen.add(host);
+    out.push(host);
+  }
+  return out;
+}
+
+/**
+ * The stored/wire shape of the value: plain strings, before branding.
+ * Parsed in two places - out of the sandbox (`resolve.ts`'s router schema)
+ * and at grant write (`sanitizeGrants`, via the kind's `grantSchema`) - so
+ * neither an author's packed bundle nor an operator's form post can put an
+ * unconstrained string on a route.
+ *
+ * The dedupe is here, not only in the form, because `syncDomainClaims`
+ * deliberately tolerates the same host twice under one leaf (the table is a
+ * set) - so a raw PATCH could otherwise store `["a.com", "a.com"]`, and
+ * `pushRoutes` would emit a 301 from the primary to itself. Dead config rather
+ * than a loop, since the proxy route is pushed first and is terminal, but it
+ * has no reason to exist.
+ */
+export const publicDomainValueSchema = z.object({
+  hosts: z.array(publicDomainHostSchema).transform(dedupeHosts),
+  domainMode: z.enum(["redirect", "all"]),
+});
+
+export type PublicDomainGrantData = z.infer<typeof publicDomainValueSchema>;

package/src/schema/remote.ts

@@ -0,0 +1,74 @@
+// remote.* permission factories.
+//
+// `fetchUrl` carries a live Zod schema for response validation, attached
+// non-enumerably so JSON.stringify drops it on the QuickJS boundary while
+// it stays reachable inside the sandbox. The type-level gate
+// (CompleteSchemablePermission) makes `.schema()` mandatory — without it a
+// fetchUrl won't satisfy `Leaf` and fails to typecheck in `configSchema`.
+
+import { z } from "zod";
+import { basePermission, schemablePermission } from "../factory.ts";
+import { makeRemotable } from "../remote-registry.ts";
+
+const remotable = makeRemotable(basePermission);
+const remotableSchemable = makeRemotable(schemablePermission);
+
+/**
+ * Branded string returned by `remote.artifact` — authors land it in
+ * `ServiceDefinition.files` to fill a file with the downloaded artifact's
+ * contents. Branded to keep artifact values from leaking into unrelated
+ * string slots without an explicit cast.
+ */
+export type Artifact = string & { readonly __brand: "Artifact" };
+
+/**
+ * Fetch and validate external data at eval time.
+ *
+ * Home makes the HTTP request, validates the response against the
+ * Zod schema you provide via `.schema(z)`, and passes the parsed data
+ * into `getDesiredState`. The app never opens a socket itself.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/remote/fetch-url/
+ */
+// `url` is plain z.string() rather than z.url(): the schema runs inside
+// QuickJS at module-load time, where Zod's URL regex doesn't behave the same
+// as on the host. Home validates at fetch time via resolveAndValidateUrl
+// (SSRF + scheme + DNS pinning).
+export const fetchUrl = remotableSchemable(
+  "remote.fetchUrl",
+  z.object({
+    url: z.string(),
+    maxSizeMb: z.number().positive().optional(),
+  }),
+  {
+    name: "Fetch URL",
+    phrase: "fetch a remote URL",
+    helpText:
+      "Home fetches this URL on behalf of the app and validates the response. The app itself never makes network requests.",
+    icon: "CloudArrowDownIcon",
+    appKinds: "both",
+  },
+);
+
+/**
+ * Download a content-addressed file at eval time.
+ *
+ * Home fetches the file, caches it by SHA-256 digest, and exposes it
+ * as a path the app can mount via `files`. The digest is required for
+ * integrity - Home re-hashes after download and refuses to deploy on
+ * a mismatch.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/remote/artifact/
+ */
+export const artifact = remotable(
+  "remote.artifact",
+  z.object({ url: z.string(), digest: z.string() }),
+  {
+    name: "Download artifact",
+    phrase: "download a remote artifact",
+    helpText:
+      "Home downloads this file, verifies its SHA-256 hash, and caches it. The app gets the verified file at deploy time.",
+    icon: "CloudArrowDownIcon",
+    appKinds: "both",
+  },
+);