@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/schema/build-apps.ts

@@ -0,0 +1,38 @@
+// The shared contract for build-recipe data: Home resolves it (resolve.ts
+// validates each service's `build`, peer.ts's `peers.buildApps` emits
+// `BuildAppEntry[]`), Forge parses `/etc/forge/apps.json` against
+// `buildAppsSchema`. A dependency-free leaf (only `zod`) so the Forge bundle
+// pulls just this, not the peer/factory machinery, and so it stays off the
+// author-facing root barrel — a Forge↔Home contract, not author surface.
+
+import { z } from "zod";
+
+/**
+ * Build-from-source recipe, mutually exclusive with `image` on a service.
+ * Recipe only — no repo/branch (the build service's binding lives in Forge).
+ * Structurally mirrors the `BuildRecipe` author interface in
+ * service-definition.ts; the resolver normalizes `build: true` to `{}` here.
+ */
+export const buildRecipeSchema = z
+  .object({
+    dockerfile: z.string().optional(),
+    buildArgs: z.record(z.string(), z.string()).optional(),
+    context: z.string().optional(),
+  })
+  .strict();
+
+/**
+ * One build target's resolved recipe, keyed by `(appId, service)`. Home's
+ * `peers.buildApps` peerable emits one entry per build-from-source service
+ * across apps; Forge looks the recipe up by `(appId, service)` when a push
+ * triggers a build.
+ */
+export const buildAppsSchema = z.array(
+  z.object({
+    appId: z.string(),
+    service: z.string(),
+    recipe: buildRecipeSchema,
+  }),
+);
+
+export type BuildAppEntry = z.infer<typeof buildAppsSchema>[number];

package/src/schema/home.ts

@@ -0,0 +1,217 @@
+// home.* permission factories + per-kind Home-side mechanics.
+//
+// Each factory is built via `homeable(...)` (the local binding of
+// `makeHomeable(basePermission)`), which calls basePermission AND tags the
+// kind's hooks (iterateUses / toValue / grantSchema) so the home registry
+// derived in grants.ts can dispatch through them. Adding a home kind is one
+// declaration here.
+//
+// QuickJS-safe: only `z` + pure constants at module load (the `WorkerHostPath`
+// import is type-only). This module loads inside QuickJS during realm.ts eval,
+// so it must touch no `Deno` or Web globals at load.
+
+import { z } from "zod";
+import type { WorkerHostPath } from "../worker-protocol/logs-socket-path.ts";
+import type { WorkerMount } from "../worker-protocol/worker-mount.ts";
+import { homeProxyMount } from "../worker-protocol/home-proxy-paths.ts";
+import { basePermission } from "../factory.ts";
+import { makeHomeable } from "../home-registry.ts";
+import {
+  publicDomainValueSchema,
+  type PublicDomain,
+  type PublicDomainGrantData,
+  type PublicDomainValue,
+} from "./public-domain.ts";
+
+const homeable = makeHomeable(basePermission);
+
+/**
+ * Closed set of control-plane capability scopes `home.apiAccess` can grant.
+ * Each names *what the app may do*, not a specific endpoint, so one scope can
+ * back several routes. An unknown scope is rejected at grant time (lands in
+ * `sanitizeGrants`'s `rejected` bucket).
+ *
+ *  - `builder` — the build-service control plane: re-pin a `build:` app to a
+ *    pushed digest (setImage), manage a template's preview children, and upsert
+ *    a pull credential. The three always travel together — a builder wants all
+ *    of them, nobody wants a subset — so they're one scope. Home enforces it
+ *    **singleton**: at most one app per Home may hold `builder`, so there is
+ *    exactly one builder and no sibling app can re-pin or shadow another app's
+ *    images. The per-endpoint fences (build-only, lineage, self-or-lineage)
+ *    still apply on top of the scope.
+ *  - `whoami` — read your own identity + deployment facts (appId, granted
+ *    scopes, worker slug, base domain). Low-privilege and **unlimited** (any
+ *    number of apps may hold it), so `home.apiAccess` stays a general primitive
+ *    rather than becoming builder-only once `builder` is singleton.
+ */
+const HOME_API_ACCESS_SCOPES = ["builder", "whoami"] as const;
+
+/**
+ * Resolved shape of a `home.apiAccess()` grant. Keyless by design — there is
+ * no token here, only the socket to talk to. `socket` is the mount for the
+ * per-app proxy DIRECTORY (connect to `home-proxy.sock` inside it — a file
+ * bind-mount of a unix socket doesn't wire across containers on macOS Docker),
+ * fixed at `readOnly: true` because relaying a request needs no write access to
+ * the directory. This kind's `resolve` hook builds it from the app's per-app
+ * proxy dir (`/opt/realm/worker/home-proxy/<appId>`) at eval time.
+ */
+export interface HomeApiAccessValue {
+  readonly socket: WorkerMount;
+}
+
+// Type-level placeholder: `apiAccess`'s resolver builds the real per-app value,
+// and this only exists so `ValueOf` can read the shape off `toValue`. Empty
+// hostPath stands in for "never resolved"; only the host path is per-app.
+const HOME_API_PLACEHOLDER: HomeApiAccessValue = {
+  socket: { ...homeProxyMount(""), hostPath: "" as WorkerHostPath },
+};
+
+/**
+ * Call your Home's control-plane API from this app, over the worker.
+ *
+ * The app container holds no uplink — only the Worker does — so it can't
+ * reach Home directly. `apiAccess` mounts a per-app worker socket dir
+ * (holding `home-proxy.sock`); the worker turns the request into one `apiAccess`
+ * call on its uplink, which Home dispatches to `/api-access/*`, and relays the
+ * response back.
+ *
+ * Keyless: the app holds no credential. Identity is the socket it arrived on
+ * (the worker asserts `X-Realm-App-Id`); authorization is the scopes you
+ * granted, enforced by Home. Resolves to `{ socket }` (the per-app socket
+ * DIRECTORY) — mount it as a volume and call `callHome`. The grant exempts the
+ * resolved dir from the absolute-mount gate, so a bare `apiAccess` is
+ * enough to wire it.
+ *
+ * Only a single app (`createApp`) may declare this. One app holding a Home
+ * control-plane socket on every box in the fleet is a much larger surface
+ * than one holding a single socket.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/home/api-access/
+ */
+export const apiAccess = homeable(
+  "home.apiAccess",
+  z.array(z.enum(HOME_API_ACCESS_SCOPES)).min(1),
+  {
+    // No elevated *use* to collect — mounting the socket falls out of the
+    // grant being in place; the resolved socket is exempted from the
+    // absolute-mount gate via `collectAllowed` in the Home eval graph.
+    iterateUses: () => [],
+    // Type-level only; every real value comes from `resolve`, since the
+    // socket is per-app and the grant carries only scopes.
+    toValue: (): HomeApiAccessValue => HOME_API_PLACEHOLDER,
+    // The value the app mounts is the per-app DIRECTORY; the wire carries the
+    // socket file inside it (the path the worker binds).
+    resolve: ({ ctx }): HomeApiAccessValue => ({ socket: homeProxyMount(ctx.appId) }),
+  },
+  {
+    name: "Home API access",
+    phrase: "call the Home control-plane API",
+    helpText:
+      "This app can call your Home's control-plane API (over the worker) to use the capabilities you grant — e.g. pinning the images it builds. It holds no key; the worker proves which app it is.",
+    icon: "GearIcon",
+    danger: true,
+    // Single-only: a fleet-wide app holding a Home API socket on every
+    // box is a materially larger surface than one holding a single
+    // socket, and `builder` (the only scope with reach) is a singleton.
+    appKinds: "single",
+  },
+);
+
+/**
+ * What an ungranted (or not-yet-filled) `publicDomain` resolves to. Not an
+ * error state: it is what an operator who installed now and will add the
+ * domain later has, and it emits no public route.
+ */
+const NO_PUBLIC_DOMAIN: PublicDomainValue = { hosts: [], domainMode: "redirect" };
+
+/**
+ * Serve this app on a hostname the operator owns.
+ *
+ * Every routed service already gets an authenticated subdomain under the
+ * Realm domain, so "reachable from the internet" is not what this adds. What
+ * it adds is a name the operator brings: a real URL, an origin the app owns
+ * (its own cookies, OIDC issuer, CORS and absolute links), its own
+ * certificate, and no per-request hop through Home's gate.
+ *
+ * The author declares the leaf and wires it; the *operator* supplies the
+ * hostname on the install screen, the same split as `host.silo`. So there is
+ * no domain string anywhere in a realm.ts:
+ *
+ * ```ts
+ * domain: r.home
+ *   .publicDomain()
+ *   .reason("Serve your photos on your own domain")
+ *   .optional(),
+ * // ...
+ * router: { containerPort: 2283, publicDomain: config.domain },
+ * ```
+ *
+ * A custom domain is necessarily **ungated**: Home cannot run its login on a
+ * domain it does not own (the `.{baseDomain}` session cookie can't reach it),
+ * so the app owns its own auth here. The gated auto subdomain keeps working
+ * alongside it.
+ *
+ * **Declare it `.optional()`.** There is no required variant in v1, and a
+ * required one breaks in two directions: a parked template is a row nobody can
+ * open an install screen for, and so is a pinless `build:` app. Nothing is
+ * broken without a custom domain anyway - the gated auto subdomain always
+ * exists, and an ungranted leaf resolves to `undefined`, which emits no public
+ * route.
+ *
+ * A preview child never serves one. It inherits its template's grants
+ * verbatim, so Home clears the resolved value for any `role: preview` app -
+ * without that, every child of one template would claim the same host.
+ *
+ * Only a single app (`createApp`) may declare this. A hostname resolves to
+ * one box, so a grant spread across a fleet would claim a name every worker
+ * would then fight over.
+ *
+ * @see https://yourrealm.eu/docs/realm-ts/home/public-domain/
+ */
+export const publicDomain = homeable(
+  "home.publicDomain",
+  // Empty author data. `z.literal(true)` rather than `z.void()` leaves the
+  // slot for `publicDomain({ wildcard: true })` without changing any call
+  // site: the author declares cardinality, the operator only ever chooses
+  // which domain.
+  z.literal(true).default(true),
+  {
+    // Unlike the rest of `home.*` this kind has a real per-service use: the
+    // hosts a router actually serves on. `checkAppGrants` matches them against
+    // the granted set, so a packed bundle can't hand the VM a router carrying
+    // a host the operator never approved. Routers with no hosts emit nothing —
+    // there is no elevated thing being done.
+    iterateUses: function* (svc) {
+      const value = svc.router?.publicDomain;
+      if (value && value.hosts.length > 0) yield value;
+    },
+    // The grant holds the whole answer (the operator's hosts + their redirect
+    // choice), so there is no `resolve` hook — branding is all that separates
+    // stored data from the resolved value.
+    //
+    // Total on purpose: the speculative-eval paths build grants straight off
+    // the descriptors with an empty `grantValues` map, and this kind has no
+    // `perm.data` to fall back to, so throwing on `undefined` would drop the
+    // image cards off the install screen of every app that declares it.
+    toValue: (data: PublicDomainGrantData | undefined): PublicDomainValue =>
+      data == null
+        ? NO_PUBLIC_DOMAIN
+        : { hosts: data.hosts as PublicDomain[], domainMode: data.domainMode },
+    // Descriptor data and grant data diverge, the `host.silo` shape: the
+    // author declares nothing but intent, the operator supplies the hosts.
+    // The default is what an enabled-but-untouched toggle stores, and it is
+    // the "no route" value rather than an error, because adding the domain
+    // later is a normal install-then-configure flow.
+    grantSchema: publicDomainValueSchema.default({ hosts: [], domainMode: "redirect" }),
+  },
+  {
+    name: "Public domain",
+    phrase: "serve this app on a domain you own",
+    helpText:
+      "This app is served on a hostname you supply, outside your Realm domain and without Home's login in front of it. Anyone who can reach the name reaches the app, so only grant it to an app whose own authentication you trust.",
+    icon: "GlobeIcon",
+    // Single-only: a hostname points at one box. Fanning the same name
+    // across every worker would have them all claim it.
+    appKinds: "single",
+  },
+);