@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/ref.ts

@@ -0,0 +1,271 @@
+/**
+ * Brand symbols for the two ref categories. Distinct symbols (rather
+ * than a shared one) make `Ref<T>` and `Deferred<T>` non-assignable to
+ * each other at the type level — `interpolate` accepts the first but
+ * not the second, so the broken composition `interpolate\`${apply(...)}\``
+ * fails to typecheck instead of producing a malformed marker tree.
+ */
+export const REF_SYMBOL = Symbol.for("realm.ref");
+const DEFERRED_SYMBOL = Symbol.for("realm.deferred");
+
+/**
+ * Sync leaf markers — single-step lookups the walker resolves with no
+ * user-code round-trip. Home maps marker → string against a grant-
+ * scoped allow-map.
+ */
+export type LeafRefMarker =
+  | { kind: "derived"; appId: string; name: string }
+  | { kind: "shared"; providerAppId: string; serviceKey: string; name: string }
+  | { kind: "secret"; path: string };
+
+/**
+ * Wire-shape markers `Ref<T>` carries. Either a single leaf or a flat
+ * concat of leaves. Two structural invariants the wire schema enforces:
+ *
+ *   1. concat parts contain only leaves — no nested concat (interpolate
+ *      flattens at build time) and no deferred sub-parts (interpolate
+ *      rejects `Deferred<T>` at the type level).
+ *   2. `Deferred<T>` is a separate brand entirely — never appears here.
+ *
+ * Together these mean the walker's concat handling is plain sync
+ * recursion over leaves, not a two-pass placeholder dance.
+ */
+export type SyncRefMarker = LeafRefMarker | { kind: "concat"; parts: (string | LeafRefMarker)[] };
+
+/**
+ * Wire shape for `apply()`. Distinct from `SyncRefMarker` because the
+ * walker has to register a placeholder and round-trip through a second
+ * sandbox eval to invoke the user fn.
+ */
+export type DeferredRefMarker = { kind: "deferred"; id: number; input: unknown };
+
+export type RefMarker = SyncRefMarker | DeferredRefMarker;
+
+/**
+ * Sync ref — secrets, derived/shared passwords, concat templates. The
+ * walker resolves them in one pass with no user-code round-trip. Always
+ * the type accepted by `interpolate`.
+ */
+export interface Ref<T> {
+  readonly [REF_SYMBOL]: true;
+  toJSON(): { __realmRef: SyncRefMarker } | T;
+  toString(): never;
+}
+
+/**
+ * Deferred ref — produced only by `apply()`. Resolution requires a
+ * second sandbox call to invoke the user fn, so deferred refs cannot
+ * compose into `interpolate` (a deferred sub-part inside a concat would
+ * force the walker to mix synchronous and second-pass resolution mid-
+ * concat, which the wire schema forbids). Wrap affix logic inside the
+ * deferred fn instead.
+ */
+export interface Deferred<T> {
+  readonly [DEFERRED_SYMBOL]: true;
+  // Phantom `| T` parallels `Ref<T>` so `Deferred<string>` and
+  // `Deferred<number>` brand distinctly at the type level. Always the
+  // marker shape at runtime — the user fn's return value is spliced in
+  // by the walker, never produced by toJSON.
+  toJSON(): { __realmRef: DeferredRefMarker } | T;
+  toString(): never;
+}
+
+/**
+ * Anything that becomes a `T` at deploy time — sync ref or deferred.
+ * Use this for field types that accept either (env values, file
+ * contents, etc.). `interpolate` is the exception: it accepts `Ref<T>`
+ * only, since deferred values can't sit inside a concat template.
+ */
+export type Resolvable<T> = Ref<T> | Deferred<T>;
+
+function isRef(value: unknown): value is Ref<string> {
+  return typeof value === "object" && value !== null && REF_SYMBOL in value;
+}
+
+/**
+ * True if `value` holds a ref anywhere in its tree, in either form: a
+ * branded `Ref` (from author helpers like `r.stableSecret` / `interpolate`)
+ * or a bare `{__realmRef}` marker (what a config secret value already is by
+ * the time `getDesiredState` runs — symbols don't survive the sandbox's
+ * JSON boundary). The serializers (toJson/toYaml/toIni/toXml) use this to
+ * choose the eager path (no refs → plain string) over the deferred path
+ * (refs → resolve via apply(), then serialize).
+ */
+export function containsRef(value: unknown): boolean {
+  if (isRef(value) || isRefMarker(value)) return true;
+  if (Array.isArray(value)) return value.some(containsRef);
+  if (typeof value === "object" && value !== null) {
+    for (const v of Object.values(value as Record<string, unknown>)) {
+      if (containsRef(v)) return true;
+    }
+  }
+  return false;
+}
+
+export function isRefMarker(value: unknown): value is { __realmRef: RefMarker } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__realmRef" in value &&
+    typeof (value as { __realmRef: unknown }).__realmRef === "object"
+  );
+}
+
+function throwOnToString(): never {
+  throw new Error(
+    "Refs cannot be stringified directly. Use interpolate`...` for templates " +
+      "or pass the ref through as an env/command/volume value.",
+  );
+}
+
+/**
+ * Marker for a `User` field read inside `getTrustedHeaders`. Unlike every
+ * other ref it never reaches the worker wire or the resolve-refs walker:
+ * `createApp`'s sampler reads it at deploy time to build the static
+ * header→field map, and the ForwardAuth verify hop substitutes the real
+ * value per request. Kept out of `SyncRefMarker` for exactly that reason —
+ * the wire schema and walker never have to know about it.
+ */
+type IdentityRefMarker = { kind: "identity"; field: "username" | "email" };
+
+/**
+ * Build the `Ref<string>` handed to `getTrustedHeaders` for `user.username` /
+ * `user.email`. At deploy time there is no real user, so the value is a
+ * deferred marker the verify hop fills in per request — the same "string
+ * not known until later" idiom as `db.url`. Composes through `interpolate`
+ * like any other ref (the sampler resolves the resulting concat).
+ */
+export function identityRef(field: IdentityRefMarker["field"]): Ref<string> {
+  // The identity marker is deliberately outside `SyncRefMarker` (it never
+  // reaches the wire), so toJSON doesn't structurally match `Ref<string>` -
+  // cast through `unknown`. Runtime shape is identical to every other ref.
+  return {
+    [REF_SYMBOL]: true,
+    toJSON: () => ({ __realmRef: { kind: "identity", field } }),
+    toString: throwOnToString,
+  } as unknown as Ref<string>;
+}
+
+/**
+ * Build a sync ref that serializes as `{__realmRef: marker}`.
+ */
+export function ref(marker: SyncRefMarker): Ref<string> {
+  return {
+    [REF_SYMBOL]: true,
+    toJSON: () => ({ __realmRef: marker }),
+    toString: throwOnToString,
+  };
+}
+
+/**
+ * Build a sync ref whose toJSON resolves to a plain string at
+ * serialization time. Used for values that don't need Home-side
+ * resolution (e.g. the service's DNS name — a literal known once
+ * `_setServiceKey` runs, which happens before `getServiceDefinition`).
+ */
+export function stringRef(resolve: () => string): Ref<string> {
+  return {
+    [REF_SYMBOL]: true,
+    toJSON: resolve,
+    toString: throwOnToString,
+  };
+}
+
+/**
+ * Build a deferred ref. Internal — `apply()` in apply.ts is the public
+ * entry point; this helper centralizes the brand + toJSON shape.
+ */
+export function deferredRef(marker: DeferredRefMarker): Deferred<string> {
+  return {
+    [DEFERRED_SYMBOL]: true,
+    toJSON: () => ({ __realmRef: marker }),
+    toString: throwOnToString,
+  };
+}
+
+/**
+ * Tagged template literal that handles refs.
+ *
+ * Literal parts and plain values fold in at serialization time. Sync
+ * refs keep their marker; string-producing refs fold to strings. The
+ * result is always a single concat marker with parts in source order
+ * (adjacent strings are not pre-joined — the walker collapses them).
+ *
+ * `Deferred<string>` is rejected at the type level: a deferred sub-part
+ * inside a concat would need to mix sync + second-pass resolution mid-
+ * template, and the wire schema forbids it. Move affix logic inside the
+ * apply callback: `apply(input, s => \`prefix-${s}\`)` instead of
+ * `interpolate\`prefix-${apply(input, s => s)}\``.
+ *
+ * Usage:
+ *   interpolate`postgres://${db.user}:${db.password}@${db.host}:${db.port}/${db.database}`
+ */
+function interpolate(
+  strings: TemplateStringsArray,
+  ...values: (string | Ref<string> | number)[]
+): Ref<string> {
+  return {
+    [REF_SYMBOL]: true,
+    toJSON() {
+      const parts: (string | LeafRefMarker)[] = [];
+      let allStrings = true;
+      for (let i = 0; i < strings.length; i++) {
+        const literal = strings[i]!;
+        if (literal.length > 0) parts.push(literal);
+        if (i < values.length) {
+          const val = values[i];
+          // Three runtime shapes: a `Ref<string>`, whose marker comes off
+          // `.toJSON()`; a plain `{__realmRef: ...}` object — what a Ref
+          // looks like after crossing the host→sandbox JSON boundary, which
+          // realm.ts authors hit interpolating an `r.input.secret(...)`
+          // field; or anything else, which coerces to a string.
+          let marker: SyncRefMarker | null = null;
+          if (isRef(val)) {
+            const resolved = val.toJSON();
+            if (typeof resolved === "object" && resolved !== null && "__realmRef" in resolved) {
+              marker = (resolved as { __realmRef: SyncRefMarker }).__realmRef;
+            } else {
+              parts.push(String(resolved));
+            }
+          } else if (isRefMarker(val)) {
+            // Runtime guard: a deferred marker can only land here via a
+            // hand-crafted `as unknown as string` cast (the type rejects
+            // proper `Deferred<string>`). Reject it loudly so the wire
+            // schema isn't the only line of defense.
+            const m = val.__realmRef;
+            if (m.kind === "deferred") {
+              throw new Error(
+                "interpolate cannot accept a deferred ref; move affix logic into apply()",
+              );
+            }
+            marker = m;
+          } else {
+            parts.push(String(val));
+          }
+          if (marker) {
+            // Flatten nested concats so the walker sees a single level.
+            // `interpolate` is the only path that produces a concat, so an
+            // already-concat sub-marker came from another one upstream.
+            if (marker.kind === "concat") {
+              for (const p of marker.parts) {
+                parts.push(p);
+                if (typeof p !== "string") allStrings = false;
+              }
+            } else {
+              parts.push(marker);
+              allStrings = false;
+            }
+          }
+        }
+      }
+      // When every part is already a plain string the template has no
+      // deferred resolution to do — collapse it to a literal so it can
+      // land in strict string-typed fields (e.g. volume hostPath).
+      if (allStrings) return (parts as string[]).join("");
+      return { __realmRef: { kind: "concat", parts } };
+    },
+    toString: throwOnToString,
+  };
+}
+
+export { interpolate };

package/src/remote-registry.ts

@@ -0,0 +1,33 @@
+// Per-kind tagging for remote.* permissions.
+//
+// Remote kinds carry no Home-side dispatch hooks (no iterateUses /
+// extract) — Home handles fetchUrl + artifact through dedicated endpoints
+// rather than by walking a registry. The factory tags only kind + meta,
+// enough for derivePermissionMeta and permissions.ts's type-level kind
+// deriver to pick them up.
+
+import type { z } from "zod";
+import type { Builder } from "./shared.ts";
+import {
+  tagPermissionMeta,
+  type PermissionMeta,
+  type PermissionMetaTagged,
+} from "./permission-meta.ts";
+
+// Loose constraint used inside this module. The closed
+// `RemotePermissionKind` is derived in permissions.ts.
+type RemoteKindShape = `remote.${string}`;
+
+/**
+ * Bind an inner Builder (basePermission or schemablePermission) and
+ * return a factory-builder that produces tagged remote-permission
+ * factories. Mirrors makeHostable / makePeerable.
+ */
+export function makeRemotable<BaseR extends object, KindUnion extends RemoteKindShape>(
+  inner: Builder<BaseR, "perm", KindUnion>,
+) {
+  return <S extends z.ZodType, K extends KindUnion>(kind: K, schema: S, meta: PermissionMeta) => {
+    const factory = inner(kind, schema);
+    return tagPermissionMeta(factory, kind, meta) as typeof factory & PermissionMetaTagged<K>;
+  };
+}

package/src/required-host-kinds.ts

@@ -0,0 +1,110 @@
+// Partition the host permission kinds an app declares into "required"
+// vs "optional" sets. Required ⇒ the permission is at the root (or
+// nested inside non-optional tabs/sections only) AND doesn't carry
+// `.optional()` on its leaf meta. Anything else is optional.
+//
+// Two consumers: Home's validation gates (apps-logic / apps-recompute)
+// drop workers whose advertised capabilities don't cover an app's required
+// kinds, and the install panel grays out optional permissions whose kind no
+// worker can satisfy. It lives in the SDK so server eval and dashboard
+// islands consume the same rule.
+
+import type { ConfigFieldTree, SerializablePermission } from "./sandbox.ts";
+import type { HostPermissionKind } from "./permissions.ts";
+import type { HomeApp } from "./resolve.ts";
+
+function isHostKind(kind: string): kind is HostPermissionKind {
+  return kind.startsWith("host.");
+}
+
+/**
+ * Dotted paths of permission leaves that live inside an
+ * optional-section (or optional-tab) subtree. Schema-only — runtime
+ * `values` aren't consulted here, declaration-time optionality is what
+ * decides whether a permission counts as required for capability
+ * gating.
+ */
+function pathsUnderOptionalAncestor(schema: ConfigFieldTree): Set<string> {
+  const optionalPrefixes: string[] = [];
+  function walk(fields: ConfigFieldTree, prefix: string) {
+    for (const [name, field] of Object.entries(fields)) {
+      const path = prefix ? `${prefix}.${name}` : name;
+      if (field.type === "section" || field.type === "tab") {
+        if (field.optional) {
+          optionalPrefixes.push(path);
+          // Don't recurse: every descendant is already covered by
+          // this prefix.
+          continue;
+        }
+        walk(field.fields, path);
+      }
+    }
+  }
+  walk(schema, "");
+  return new Set(optionalPrefixes);
+}
+
+function hasOptionalAncestor(path: string, optionalPrefixes: Set<string>): boolean {
+  for (const prefix of optionalPrefixes) {
+    if (path === prefix || path.startsWith(prefix + ".")) return true;
+  }
+  return false;
+}
+
+export interface PartitionedHostKinds {
+  required: HostPermissionKind[];
+  optional: HostPermissionKind[];
+}
+
+/**
+ * Given a permsFlat map plus the configFields tree, split the host
+ * kinds the app declares into required vs optional. A kind is required
+ * iff at least one declaration of that kind is *both* leaf-required
+ * (`meta.isOptional !== true`) AND has no optional ancestor section/tab
+ * along its dotted path. Otherwise the kind is optional.
+ *
+ * Both arrays are deduped and stable-sorted so the gate's missing-kinds
+ * messages render in a predictable order.
+ */
+export function partitionHostKinds(
+  permissionsFlat: Record<string, SerializablePermission>,
+  configFields: ConfigFieldTree,
+): PartitionedHostKinds {
+  const optionalPrefixes = pathsUnderOptionalAncestor(configFields);
+  const required = new Set<HostPermissionKind>();
+  const optional = new Set<HostPermissionKind>();
+  for (const [path, perm] of Object.entries(permissionsFlat)) {
+    if (!isHostKind(perm.kind)) continue;
+    const leafOptional = (perm.meta as { isOptional?: boolean }).isOptional === true;
+    const ancestorOptional = hasOptionalAncestor(path, optionalPrefixes);
+    if (!leafOptional && !ancestorOptional) {
+      required.add(perm.kind);
+    } else {
+      optional.add(perm.kind);
+    }
+  }
+  // A kind that's required at one path and optional at another is
+  // required overall — required wins.
+  for (const k of required) optional.delete(k);
+  return {
+    required: [...required].sort(),
+    optional: [...optional].sort(),
+  };
+}
+
+/**
+ * State-based capability check: any service mounting a volume (relative
+ * or absolute) needs the worker to advertise the `host.volumes`
+ * capability — whether the worker can hold persistent files at all. A
+ * worker without it represents an ephemeral runtime (think sandbox VM,
+ * k8s emptyDir-only) and can't run any app that persists state.
+ *
+ * Returns true iff at least one service in the resolved state has a
+ * non-empty `volumes` array.
+ */
+export function stateRequiresVolumes(state: HomeApp): boolean {
+  for (const svc of Object.values(state.services)) {
+    if (svc.volumes && svc.volumes.length > 0) return true;
+  }
+  return false;
+}

package/src/resolve-context.ts

@@ -0,0 +1,111 @@
+// The world a permission resolver reads from.
+//
+// A resolver turns "the author declared this, the operator granted that"
+// into the value the app reads out of `config`. For most kinds the grant
+// already holds the answer and `toValue` is the whole resolver; the rest
+// need facts only Home knows at eval time: which Silos exist, where the
+// worker is, what the other members of a Silo publish.
+//
+// Everything here is plain data or a pure lookup closed over plain data,
+// never a callback into Home - the resolvers live in the SDK, which cannot
+// import Home. The caller resolves every database read, fetch and key
+// derivation up front, which is what keeps resolvers synchronous.
+//
+// Home builds one per app in `evalApps`; the SDK test harness builds the
+// same shape from fixtures, so both run the same resolvers.
+
+/**
+ * A Silo as a resolver reads it. Deliberately structural: Home's own row
+ * (`server/silos.ts`) is assignable without the SDK knowing the row type,
+ * and the fields a resolver has no business reading (`saltId`,
+ * `setupAckAt`) stay off it.
+ */
+export interface ResolveSilo {
+  readonly id: string;
+  readonly name: string;
+  /** The worker row id the Silo is pinned to - what placement is checked against. */
+  readonly workerId: string;
+  /** That worker's slug, so a refusal can name the box the operator knows. */
+  readonly workerSlug: string;
+  readonly hostPath: string;
+  readonly containerPath: string;
+  readonly gid: number;
+}
+
+/** One service name published into a Silo by another member. */
+export interface SiloPublication {
+  readonly port: number;
+  readonly appId: string;
+}
+
+/**
+ * The Home identity `host.management` resolves from. Structural, like
+ * `ResolveSilo`: Home's own `HomeSettings` (read from installer env) is
+ * assignable without the SDK importing it.
+ */
+export interface ResolveHomeSettings {
+  readonly baseDomain: string;
+  readonly homeSlug: string;
+  readonly acmeDns: {
+    readonly serverUrl: string;
+    readonly apiKey: string;
+    readonly ca: string;
+    readonly caRootPem: string;
+  } | null;
+}
+
+export interface ResolveContext {
+  /** The app being evaluated. */
+  readonly appId: string;
+  /**
+   * The worker this evaluation targets. `id` is the slug an author reads as
+   * `worker.id`; `internalId` is the row id, absent when there is no concrete
+   * worker (previews, sweeps, loader cold starts), which is why placement
+   * checks guard on it rather than assuming it.
+   */
+  readonly worker: { readonly id: string; readonly internalId?: string };
+  /**
+   * Home's own identity, from installer env. `host.management` resolves the
+   * dashboard URL pieces and the acme-dns credentials out of this.
+   */
+  readonly home: ResolveHomeSettings;
+  /** Every Silo the operator has defined. Read once per eval, not per app. */
+  readonly silos: readonly ResolveSilo[];
+  /**
+   * One Silo's merged service directory, with the evaluating app's own
+   * publications excluded. A function rather than a map because it is derived
+   * per app from state that grows as the app's peers evaluate.
+   */
+  readonly siloDirectory: (siloId: string) => ReadonlyMap<string, SiloPublication>;
+  /**
+   * Per-Silo API keys, derived up front (HKDF off REALM_SECRET) so a resolver
+   * that needs one stays synchronous.
+   */
+  readonly siloApiKeys: ReadonlyMap<string, string>;
+  /**
+   * Resolution mode, not a fact about the world like the rest of this context:
+   * the caller is asking what an app WOULD ship, with every permission granted
+   * sight-unseen and nothing actually chosen. Home's install preview is the
+   * only caller.
+   *
+   * The one resolver that reads it is `host.silo`; see `speculative-silo.ts`
+   * for why it is the only permission that needs a mode at all. Setting it
+   * anywhere an app can deploy would put a fabricated directory on the wire,
+   * so `evalApps` refuses it unless the eval is also `ephemeral`.
+   */
+  readonly speculative?: boolean;
+}
+
+/**
+ * What a `resolve` hook receives. `grant` is the operator's side (the same
+ * data `toValue` gets), `declared` is the author's side off the descriptor.
+ * Neither alone is enough for the kinds that need a resolver: the author
+ * says what they want, the operator says from where.
+ */
+export interface ResolveArgs<TGrant = unknown> {
+  readonly grant: TGrant;
+  readonly declared: unknown;
+  /** Dotted config path of this permission. Error messages name it. */
+  readonly path: string;
+  readonly ctx: ResolveContext;
+}