@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/generator/resolve-refs.ts

@@ -0,0 +1,207 @@
+import { RealmCompileError } from "../errors.ts";
+import type { LeafRefMarker, RefMarker } from "../ref.ts";
+import type { AllowedProvider } from "../peer-registry.ts";
+import { deriveAppPassword } from "../keys.ts";
+
+export interface ResolutionContext {
+  consumerAppId: string;
+  /**
+   * HMAC key used to derive per-app passwords. Null when the caller (a
+   * test fixture, typically) doesn't plan to exercise derived/shared
+   * markers — the walker throws if it meets one anyway.
+   */
+  derivationSeed: CryptoKey | null;
+  secrets: Record<string, string>;
+  /** `providerAppId` -> set of `serviceKey`s the consumer holds grants for. */
+  allowedProviders: Map<string, Set<string>>;
+  derivedCache: Map<string, string>;
+  /**
+   * Batched second-shot for `apply()` callbacks. The walker hands over
+   * every deferred marker it meets (with its `input` already resolved)
+   * in one call, gets back the returned strings in the same order, and
+   * splices them into the tree. Unset when the caller doesn't plan to
+   * exercise deferred markers — the walker throws if it meets one
+   * anyway.
+   */
+  runDeferred?: (items: Array<{ id: number; input: unknown }>) => Promise<string[]>;
+}
+
+/**
+ * Build the per-consumer allow-map from the set of granted providers.
+ * Each `(providerAppId, serviceKey)` pair becomes an entry the walker
+ * will accept when it meets a `shared` marker.
+ */
+export function buildAllowMap(entries: AllowedProvider[]): Map<string, Set<string>> {
+  const map = new Map<string, Set<string>>();
+  for (const e of entries) {
+    let set = map.get(e.appId);
+    if (!set) {
+      set = new Set<string>();
+      map.set(e.appId, set);
+    }
+    set.add(e.serviceKey);
+  }
+  return map;
+}
+
+function isMarker(value: unknown): value is { __realmRef: RefMarker } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    "__realmRef" in value &&
+    typeof (value as { __realmRef: unknown }).__realmRef === "object" &&
+    (value as { __realmRef: unknown }).__realmRef !== null
+  );
+}
+
+async function resolveDerived(
+  appId: string,
+  name: string,
+  ctx: ResolutionContext,
+): Promise<string> {
+  const cacheKey = `derived:${appId}:${name}`;
+  const cached = ctx.derivedCache.get(cacheKey);
+  if (cached) return cached;
+  if (!ctx.derivationSeed) {
+    throw new RealmCompileError({ kind: "eval", message: "derivationSeed is not configured" });
+  }
+  const hash = await deriveAppPassword(ctx.derivationSeed, appId, name);
+  ctx.derivedCache.set(cacheKey, hash);
+  return hash;
+}
+
+/**
+ * Resolve a sync leaf marker (derived/shared/secret) to its string
+ * value. Concat is handled in `walk`; deferred goes through the
+ * placeholder mechanism in `resolveRefs`.
+ */
+async function resolveLeaf(marker: LeafRefMarker, ctx: ResolutionContext): Promise<string> {
+  if (marker.kind === "derived") {
+    // `derived` markers only ever carry `__self__` when emitted by the SDK —
+    // the resolver rewrites them to the consumer's own app id. A foreign
+    // `appId` can only come from a hand-crafted payload in a malicious
+    // realm.ts, which would otherwise let the walker hash a victim app's
+    // derived secret with no grant check — the cross-app leak `shared` closes.
+    if (marker.appId !== "__self__") {
+      throw new RealmCompileError({
+        kind: "eval",
+        message: "derived ref carried a foreign appId",
+      });
+    }
+    return resolveDerived(ctx.consumerAppId, marker.name, ctx);
+  }
+
+  if (marker.kind === "shared") {
+    const { providerAppId, serviceKey, name } = marker;
+    const allowed = ctx.allowedProviders.get(providerAppId);
+    if (!allowed || !allowed.has(serviceKey)) {
+      const missing = `${providerAppId}.${serviceKey}`;
+      throw new RealmCompileError({ kind: "permission", missing });
+    }
+    // Hash with the provider's identity so both sides agree on the value.
+    return resolveDerived(providerAppId, name, ctx);
+  }
+
+  // secret
+  const value = ctx.secrets[marker.path];
+  if (value == null) {
+    throw new RealmCompileError({
+      kind: "validation",
+      path: marker.path.split("."),
+      message: "unknown secret",
+    });
+  }
+  return value;
+}
+
+interface DeferredPlaceholder {
+  readonly __deferredPlaceholder__: true;
+  readonly index: number;
+}
+
+function isPlaceholder(value: unknown): value is DeferredPlaceholder {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __deferredPlaceholder__?: boolean }).__deferredPlaceholder__ === true
+  );
+}
+
+/**
+ * Walk `node` recursively and replace every `{__realmRef: ...}` marker
+ * with its resolved value. Plain values pass through unchanged.
+ *
+ * Markers that can't be resolved — unknown kind, missing secret, or a
+ * `shared` ref that the consumer has no grant for — throw.
+ *
+ * Deferred markers force a second pass: the walker first resolves every
+ * other marker plus the `input` of each deferred marker (leaving
+ * placeholders in the tree), then invokes `ctx.runDeferred` once with
+ * the collected items, then splices the returned strings back in. The
+ * wire schema forbids deferred markers inside concat parts and inside
+ * other deferred inputs, so the walker's contract is one flat pass +
+ * one batch.
+ */
+export async function resolveRefs<T>(node: T, ctx: ResolutionContext): Promise<T> {
+  const items: Array<{ id: number; input: unknown }> = [];
+
+  async function walk(n: unknown): Promise<unknown> {
+    if (n == null) return n;
+    if (typeof n !== "object") return n;
+    if (isMarker(n)) {
+      const marker = n.__realmRef;
+      if (marker.kind === "deferred") {
+        if (!ctx.runDeferred) {
+          throw new RealmCompileError({ kind: "eval", message: "runDeferred is not configured" });
+        }
+        const resolvedInput = await walk(marker.input);
+        const index = items.length;
+        items.push({ id: marker.id, input: resolvedInput });
+        return { __deferredPlaceholder__: true, index } satisfies DeferredPlaceholder;
+      }
+      if (marker.kind === "concat") {
+        const parts: string[] = [];
+        for (const p of marker.parts) {
+          parts.push(typeof p === "string" ? p : await resolveLeaf(p, ctx));
+        }
+        return parts.join("");
+      }
+      return resolveLeaf(marker, ctx);
+    }
+    if (Array.isArray(n)) {
+      const out: unknown[] = [];
+      for (const item of n) out.push(await walk(item));
+      return out;
+    }
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(n as Record<string, unknown>)) {
+      out[k] = await walk(v);
+    }
+    return out;
+  }
+
+  const walked = await walk(node);
+
+  if (items.length === 0) return walked as T;
+
+  // Any failure inside runDeferred (user fn throwing, non-string return,
+  // sandbox crash) bubbles as RealmCompileError from runInSandbox, which
+  // already logged the underlying cause. Don't catch-and-relog here —
+  // that just adds a second line with an empty message.
+  const results = await ctx.runDeferred!(items);
+
+  function replace(n: unknown): unknown {
+    if (n == null) return n;
+    if (typeof n !== "object") return n;
+    if (isPlaceholder(n)) return results[n.index];
+    if (Array.isArray(n)) return n.map(replace);
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(n as Record<string, unknown>)) {
+      out[k] = replace(v);
+    }
+    return out;
+  }
+
+  return replace(walked) as T;
+}

package/src/grants-builder.ts

@@ -0,0 +1,100 @@
+// Pure grant-building helpers shared between the server install path
+// (apps-logic.ts) and the dashboard islands (InstallAppPanel,
+// EditAppPanel). Kept standalone so importing it from a client island
+// doesn't pull drizzle / db / sandbox into the browser bundle.
+
+import type { Grants } from "./home.ts";
+import type { SerializablePermission } from "./sandbox.ts";
+
+interface GrantSelection {
+  /**
+   * Dotted paths of permissions whose toggle is ON. Everything else is
+   * denied.
+   */
+  enabled: Set<string>;
+  /**
+   * Per-path admin override, keyed by dotted permission path. Sparse:
+   * an entry only appears when the admin actively edited the value.
+   * `descriptorsToGrants` falls back to the descriptor's `perm.data`
+   * when an entry is missing, so the form never has to prefill — the
+   * default *is* the descriptor.
+   *
+   * Entries for presence-only kinds (host.gpu/egress/management,
+   * peers.*, remote.*) are ignored: those grants are flag-shaped.
+   */
+  grantValues: Record<string, unknown>;
+}
+
+/**
+ * Build a Grants object from the typed permission descriptors plus the
+ * admin's toggle state. Drops anything not in `selection.enabled`. For
+ * data-carrying host kinds, uses `grantValues[path] ?? perm.data` —
+ * untouched fields fall back to the descriptor's proposed value;
+ * `??` only triggers on null/undefined, so an admin-cleared empty
+ * string passes through verbatim and gets rejected by sanitizeGrants.
+ *
+ * Presence-only host kinds (host.gpu, host.egress, host.management —
+ * descriptor `perm.data === true`) and the peers kinds emit `data: true`.
+ * remote.* lands as flag-only `{ kind }`.
+ *
+ * `host.silo` and `home.publicDomain` are the exceptions to the fallback:
+ * their descriptor and their grant carry different shapes, so they emit the
+ * operator's value alone.
+ */
+export function descriptorsToGrants(
+  permsFlat: Record<string, SerializablePermission>,
+  selection: GrantSelection,
+): Grants {
+  const out: Grants = {};
+  for (const [path, perm] of Object.entries(permsFlat)) {
+    if (!selection.enabled.has(path)) continue;
+    const kind = perm.kind;
+
+    // peers.* / remote.* are presence-only at grant time: the descriptor says
+    // *what* to consume (remote.fetchUrl.url) but the runtime resolver pulls
+    // real values from world state / fetch, so the grant blob is just a flag.
+    if (kind.startsWith("peers.") || kind.startsWith("remote.")) {
+      out[path] = { kind } as Grants[string];
+      continue;
+    }
+
+    if (kind.startsWith("host.")) {
+      // Presence-only host kinds (host.gpu, host.egress, host.management)
+      // resolve their `.default(true)` schema to `perm.data === true`.
+      if (perm.data === true) {
+        out[path] = { kind, data: true };
+        continue;
+      }
+      // host.silo's descriptor data and grant data are different shapes: the
+      // descriptor carries the author's affordance flags (`{volume:
+      // "readwrite"}`), the grant the operator's chosen Silo id. There is no
+      // sensible default Silo, so an unpicked one emits `undefined` and
+      // sanitizeGrants rejects it.
+      if (kind === "host.silo") {
+        out[path] = { kind, data: selection.grantValues[path] };
+        continue;
+      }
+      // Data-carrying: prefer admin override, fall back to descriptor.
+      out[path] = { kind, data: selection.grantValues[path] ?? perm.data };
+      continue;
+    }
+
+    if (kind.startsWith("home.")) {
+      // home.publicDomain is the home-family twin of host.silo: the descriptor
+      // carries nothing but the author's intent (`true`), the grant the
+      // operator's hostnames. Falling back to `perm.data` would send
+      // `data: true` for an enabled-but-untouched toggle, which sanitizeGrants
+      // rejects and the install 400s on. `undefined` lands on the grantSchema's
+      // `{ hosts: [] }` default: permission granted, no domain yet, no route.
+      if (kind === "home.publicDomain") {
+        out[path] = { kind, data: selection.grantValues[path] };
+        continue;
+      }
+      // Every other home kind carries data (the granted scopes) with no
+      // presence-only form: admin override first, descriptor scopes second.
+      out[path] = { kind, data: selection.grantValues[path] ?? perm.data };
+      continue;
+    }
+  }
+  return out;
+}

package/src/grants.ts

@@ -0,0 +1,260 @@
+// Grants: stripped permission records (kind + data, no meta) plus the
+// primitives the Home-side gate builds on. A "use" has the same shape as a
+// grant: `collectUses` emits one per elevated thing a resolved service does
+// (mounts, port binds, network joins), and `checkAppGrants` in security.ts
+// matches those against the admin's grants keyed by permission descriptor
+// path — a use with no matching grant drops the app. `GrantsOf` carries the
+// same contract at the type level, so `grants.X.data` flows from the schema's
+// I. Per-kind host mechanics (iterateUses / toValue / grantSchema) are tagged
+// onto each factory in schema/host.ts via `makeHostable`; this file walks that
+// namespace import and dispatches through the resulting registry.
+
+import type { HomeService } from "./resolve.ts";
+import * as host from "./schema/host.ts";
+import * as peers from "./schema/peer.ts";
+import * as home from "./schema/home.ts";
+import type { Artifact } from "./schema/remote.ts";
+import type { SiloGrants, SiloValue } from "./schema/host.ts";
+import type { ResolveContext } from "./resolve-context.ts";
+import { deriveHostRegistry, type Hostable, type HostHooks } from "./host-registry.ts";
+import { deriveHomeRegistry, type Homeable, type HomeHooks } from "./home-registry.ts";
+import type { Peerable } from "./peer-registry.ts";
+import type {
+  HomePermissionKind,
+  HostPermissionKind,
+  PeerPermissionKind,
+  PermissionKind,
+  RemotePermissionKind,
+} from "./permissions.ts";
+
+// ----- Grant / Use shapes --------------------------------------------------
+//
+// Two authorization mechanisms ride this one type. Host grants approve a
+// specific value (the port number, the directory path), matched against each
+// service's elevated uses by JSON-equal comparison. Peer/remote grants are
+// presence-only: the grant existing at all unlocks the resolver, and
+// authorization flows through resolved values into `allowedNetworks` /
+// `allowedAbsoluteHostPaths`. Only `HostGrant` carries `data`.
+
+export type { RemotePermissionKind };
+
+export type HostGrant = { readonly kind: HostPermissionKind; readonly data: unknown };
+export type PeerGrant = { readonly kind: PeerPermissionKind };
+export type RemoteGrant = { readonly kind: RemotePermissionKind };
+// Home grants carry `data` (the granted scopes) like host grants — the third
+// authorization shape on this union. Resolved values flow into
+// `allowedAbsoluteHostPaths` (the per-app socket), not through the grant blob.
+export type HomeGrant = { readonly kind: HomePermissionKind; readonly data: unknown };
+export type Grant = HostGrant | PeerGrant | RemoteGrant | HomeGrant;
+
+export type GrantOf<P> = P extends { readonly kind: infer K }
+  ? K extends HostPermissionKind | HomePermissionKind
+    ? P extends { readonly data: infer D }
+      ? { readonly kind: K; readonly data: D }
+      : never
+    : K extends PeerPermissionKind | RemotePermissionKind
+      ? { readonly kind: K }
+      : never
+  : never;
+
+export type GrantsOf<S> = {
+  readonly [K in keyof S]: GrantOf<S[K]>;
+};
+
+export type Use = { readonly kind: PermissionKind; readonly data: unknown };
+
+/** Admin-supplied grants keyed by dotted permission path. */
+export type Grants = Record<string, Grant>;
+
+// ----- Host registry (derived from schema/host.ts) ------------------------
+
+const HOST_REGISTRY = deriveHostRegistry(host as Record<string, unknown>);
+
+export function hostHooks(kind: string): HostHooks | undefined {
+  return HOST_REGISTRY.get(kind as `host.${string}`);
+}
+
+// ----- Home registry (derived from schema/home.ts) ------------------------
+
+const HOME_REGISTRY = deriveHomeRegistry(home as Record<string, unknown>);
+
+export function homeHooks(kind: string): HomeHooks | undefined {
+  return HOME_REGISTRY.get(kind as `home.${string}`);
+}
+
+// ----- toGrant: strip meta from a permission record ----------------------
+//
+// host.* and home.* grants carry `data` (the value the admin approved, the
+// granted scopes). For peer/remote kinds the descriptor's data is metadata the
+// consumer needs (e.g. fetchUrl.url) but not part of the grant blob — those
+// grants are presence-only, so the returned shape has no `data` field.
+
+export function toGrant<P extends { readonly kind: string; readonly data: unknown }>(
+  p: P,
+): GrantOf<P> {
+  if (p.kind.startsWith("host.") || p.kind.startsWith("home.")) {
+    return { kind: p.kind, data: p.data } as GrantOf<P>;
+  }
+  return { kind: p.kind } as GrantOf<P>;
+}
+
+/**
+ * Union the granted `home.apiAccess` scopes across an app's grants blob,
+ * deduped. An app can declare `apiAccess` at more than one descriptor path
+ * (e.g. one per capability it needs); Home resolves the app's *effective*
+ * scope set by collecting them all. Returns `[]` when the app has no
+ * `home.apiAccess` grant. Home reads this to authorize an app's call against
+ * what it was granted (the keyless app identity carries no scopes itself).
+ */
+export function collectHomeApiScopes(grants: Grants): string[] {
+  const scopes = new Set<string>();
+  for (const g of Object.values(grants)) {
+    if (isHomeGrant(g) && g.kind === "home.apiAccess") {
+      for (const scope of g.data as string[]) scopes.add(scope);
+    }
+  }
+  return [...scopes];
+}
+
+// ----- grant matching primitives (used by security.ts checkAppGrants) -----
+
+/**
+ * JSON-equal comparison of grant.data and use.data. Home-side path-aware
+ * gate (security.ts checkAppGrants) reuses this — same comparator, no
+ * duplication.
+ */
+export function dataMatches(grantData: unknown, useData: unknown): boolean {
+  return JSON.stringify(grantData) === JSON.stringify(useData);
+}
+
+export function isHostGrant(g: Grant): g is HostGrant {
+  return g.kind.startsWith("host.");
+}
+
+export function isHomeGrant(g: Grant): g is HomeGrant {
+  return g.kind.startsWith("home.");
+}
+
+// ----- toValue: grant → runtime value -------------------------------------
+//
+// Each kind's runtime shape is declared via its makeHostable / makePeerable
+// hook in schema/{host,peer}.ts; toValue dispatches through the host registry
+// at runtime. peers.* / remote.* return undefined — peers resolve via
+// WorldState in peer-world.ts, remote is fetched at runtime.
+//
+// `ValueOf<G>` walks the same namespace imports: each export is tagged
+// `Hostable<K, V>` / `Peerable<K, V>` where V is the inferred return type of
+// `toValue` (host) or `resolve` (peer). Adding a kind is one declaration in
+// schema/{host,peer}.ts; remote falls through to `unknown`.
+
+type HostValueLookup = {
+  [N in keyof typeof host as (typeof host)[N] extends Hostable<infer K, unknown>
+    ? K
+    : never]: (typeof host)[N] extends Hostable<HostPermissionKind, infer V> ? V : never;
+};
+
+type PeerValueLookup = {
+  [N in keyof typeof peers as (typeof peers)[N] extends Peerable<infer K, unknown>
+    ? K
+    : never]: (typeof peers)[N] extends Peerable<PeerPermissionKind, infer V> ? Readonly<V> : never;
+};
+
+type HomeValueLookup = {
+  [N in keyof typeof home as (typeof home)[N] extends Homeable<infer K, unknown>
+    ? K
+    : never]: (typeof home)[N] extends Homeable<HomePermissionKind, infer V> ? V : never;
+};
+
+// `host.silo` is the one kind whose value depends on the grant's *data*, not
+// just its kind: the affordances an author declared decide which fields
+// `config.silo` has. The kind-keyed lookup above can't express that (no
+// higher-kinded types to hang `SiloValue<_>` on), so it gets one branch ahead
+// of the generic path. It fires only with the flags in hand — a stored grant,
+// whose data is the operator's chosen Silo id, lands on the wide
+// `SiloResolved`.
+export type ValueOf<G extends Grant> = G extends {
+  kind: "host.silo";
+  data: infer D extends SiloGrants;
+}
+  ? SiloValue<D>
+  : G["kind"] extends keyof HostValueLookup
+    ? HostValueLookup[G["kind"]]
+    : G["kind"] extends keyof HomeValueLookup
+      ? HomeValueLookup[G["kind"]]
+      : G["kind"] extends keyof PeerValueLookup
+        ? PeerValueLookup[G["kind"]]
+        : G["kind"] extends "remote.artifact"
+          ? Artifact
+          : unknown;
+
+export function toValue<G extends Grant>(grant: G): ValueOf<G> {
+  if (isHomeGrant(grant)) {
+    const hooks = HOME_REGISTRY.get(grant.kind);
+    if (!hooks) return undefined as ValueOf<G>;
+    return hooks.toValue(grant.data) as ValueOf<G>;
+  }
+  if (!isHostGrant(grant)) return undefined as ValueOf<G>;
+  const hooks = HOST_REGISTRY.get(grant.kind);
+  if (!hooks) return undefined as ValueOf<G>;
+  return hooks.toValue(grant.data) as ValueOf<G>;
+}
+
+/**
+ * Resolve a grant against Home's eval-time world.
+ *
+ * Same job as `toValue`, with the context added for the kinds whose grant
+ * doesn't hold the answer on its own - a `host.silo` grant is a Silo id, which
+ * needs the Silo record to mean anything. A kind that declares a `resolve` hook
+ * gets it; every other kind falls through to `toValue`, which is most of them.
+ *
+ * This is the single dispatch point: Home's `resolvePermissions` and the SDK
+ * test harness both come through here, so an app's own tests and Home run the
+ * same resolver rather than two copies that drift.
+ */
+export function resolveValue<G extends Grant>(
+  grant: G,
+  args: { declared: unknown; path: string; ctx: ResolveContext },
+): ValueOf<G> {
+  // Two branches rather than one lookup because the registries are keyed by
+  // their own kind shapes; the predicates are what narrow `grant.data`.
+  if (isHostGrant(grant)) return viaHooks(HOST_REGISTRY.get(grant.kind), grant.data, args);
+  if (isHomeGrant(grant)) return viaHooks(HOME_REGISTRY.get(grant.kind), grant.data, args);
+  return toValue(grant);
+}
+
+/** `resolve` when the kind declares one, `toValue` otherwise. */
+function viaHooks<V>(
+  hooks: HostHooks | HomeHooks | undefined,
+  data: unknown,
+  args: { declared: unknown; path: string; ctx: ResolveContext },
+): V {
+  if (!hooks) return undefined as V;
+  return (hooks.resolve ? hooks.resolve({ grant: data, ...args }) : hooks.toValue(data)) as V;
+}
+
+// ----- collectUses: service spec → uses[] ---------------------------------
+//
+// Walks a resolved service through every host and home kind's iterateUses hook
+// and emits one Use per elevated thing it does; Home feeds the result into
+// checkAppGrants (security.ts). Adding a kind is a single declaration in
+// schema/{host,home}.ts. Most home kinds yield nothing — the grant alone
+// authorizes them — except `home.publicDomain`, whose per-service hostnames
+// have to be matched against what the operator granted.
+
+export function collectUses(svc: HomeService): Use[] {
+  const uses: Use[] = [];
+  for (const [kind, hooks] of HOST_REGISTRY) {
+    for (const data of hooks.iterateUses(svc)) {
+      // HOST_REGISTRY's keys are typed as the open `host.${string}` shape;
+      // at runtime they're whatever the schema/host.ts factories declared,
+      // which are exactly HostPermissionKind. Narrow at the boundary.
+      uses.push({ kind: kind as HostPermissionKind, data });
+    }
+  }
+  for (const [kind, hooks] of HOME_REGISTRY) {
+    for (const data of hooks.iterateUses(svc)) {
+      uses.push({ kind: kind as HomePermissionKind, data });
+    }
+  }
+  return uses;
+}