@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/home-api.ts

@@ -0,0 +1,172 @@
+// Shared request/response contract for the control-plane calls a granted app
+// makes over its `home-proxy.sock` broker. The schemas live here once and are
+// imported by both sides — the realm.ts app (client, via the worker's
+// `callHome`) and the Home route that serves the path — so the wire shape can't
+// drift. The app supplies the sub-path; Home serves it under `/api-access`:
+//   - `setImage` (POST /set-image): re-pin a `build:` app's service to a new
+//     digest.
+//   - preview install/uninstall (POST/DELETE /template/:t/preview[/:k]): stamp
+//     or tear down a template's `role: preview` child, keyed (templateId,
+//     previewKey), both parts riding the path. Install creates the child
+//     pinless; setImage pins it.
+//   - `registry` upsert (PUT /registry): upsert a pull credential for the
+//     caller or a child it created. `host` stays in the body because it may
+//     carry a `:port`, which the broker's path sanitizer forbids in a segment.
+
+import { z } from "zod";
+
+/** App-facing sub-path for setImage. Home serves it under `/api-access`. */
+export const SET_IMAGE_PATH = "/set-image";
+
+// A lowercase OCI repository path: slash-separated components, each alnum with
+// single `.` / `_` / `-` separators. No scheme, no `..`, no leading/trailing
+// slash, no empty segment. Mirrors the registry's REPO_PATTERN so the
+// host-anchored ref Home builds (`<body.host>/<repo>@<digest>`) always parses.
+const OCI_REPO =
+  /^[a-z0-9]+(?:(?:\.|_|__|-+)[a-z0-9]+)*(?:\/[a-z0-9]+(?:(?:\.|_|__|-+)[a-z0-9]+)*)*$/;
+
+// A pinned digest: `sha256:` + 64 lowercase hex. Tags / floating refs are
+// rejected — the only thing setImage can pin is a content-addressed digest.
+const SHA256_DIGEST = /^sha256:[0-9a-f]{64}$/;
+
+// A registry host: hostname with optional `:port` (e.g. `zot:5000`,
+// `1.2.3.15:5000`, `ghcr.io`). Shared by `setImage` and the registry upsert so
+// the host a caller supplies in either body parses the same way. No scheme, no
+// path — the port is why `host` can't be a path segment (the broker's
+// SAFE_SUBPATH excludes `:`).
+const REGISTRY_HOST = /^[a-zA-Z0-9.-]+(:[0-9]+)?$/;
+
+/**
+ * Body of a `setImage` call. `appId` + `service` name the target build app's
+ * service; `host` + `repo` + `digest` build the pull ref. `host` is the
+ * caller's own registry host — supplied here, but Home validates it belongs to
+ * the caller's own gated subdomain space, so the constructed ref can only ever
+ * point at the caller's own registry.
+ */
+export const setImageBodySchema = z
+  .object({
+    appId: z.string().min(1),
+    service: z.string().min(1),
+    host: z.string().regex(REGISTRY_HOST, "host must be a registry hostname with optional :port"),
+    repo: z.string().min(1).regex(OCI_REPO, "repo must be a lowercase OCI path"),
+    digest: z.string().regex(SHA256_DIGEST, "digest must be sha256:<64 hex>"),
+  })
+  .strict();
+
+export type SetImageBody = z.infer<typeof setImageBodySchema>;
+
+/** Success shape: echoes back the target the pin landed on. */
+export const setImageResponseSchema = z
+  .object({
+    ok: z.literal(true),
+    appId: z.string(),
+    service: z.string(),
+    digest: z.string(),
+  })
+  .strict();
+
+export type SetImageResponse = z.infer<typeof setImageResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// Preview install / uninstall (scope: builder)
+// ---------------------------------------------------------------------------
+
+// A preview key is a single DNS label: 1-63 chars, lowercase alnum + internal
+// hyphens, no edge hyphen. NOT `nameSchema` — that requires a leading letter,
+// which rejects a numeric PR key like "42". Safe to fold into a subdomain.
+const PREVIEW_KEY = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+/** A preview key (DNS label): the per-PR half of a `(templateId, previewKey)`. */
+export const previewKeySchema = z
+  .string()
+  .regex(PREVIEW_KEY, "previewKey must be a DNS label (lowercase alnum + internal hyphens, ≤63)");
+
+// Path builders, not flat consts: both key parts ride the path. `templateId`
+// is appId-shaped and `previewKey` is a DNS label — both colon-free — so they
+// drop in as segments. This lets a caller rebuild the URL from `(template,
+// key)` with no stored appId (Forge's PR-close GC relies on that).
+
+/** POST target — the preview collection under a template. */
+export function previewCollectionPath(templateId: string): string {
+  return `/template/${templateId}/preview`;
+}
+
+/** DELETE target — one preview under a template. */
+export function previewItemPath(templateId: string, previewKey: string): string {
+  return `/template/${templateId}/preview/${previewKey}`;
+}
+
+/**
+ * Body of a preview install (`POST /template/:templateId/preview`). The
+ * template is in the path; the only payload is the `previewKey`. No repo /
+ * digest — the child is created pinless and `setImage` pins it.
+ */
+export const previewInstallBodySchema = z.object({ previewKey: previewKeySchema }).strict();
+
+export type PreviewInstallBody = z.infer<typeof previewInstallBodySchema>;
+
+/**
+ * Success shape of a preview install. `appId` is the child row's id; `created`
+ * is `false` on the idempotent hit (a row already existed for this
+ * `(templateId, previewKey)`), `true` when a new child was stamped.
+ */
+export const previewInstallResponseSchema = z
+  .object({
+    ok: z.literal(true),
+    appId: z.string(),
+    created: z.boolean(),
+  })
+  .strict();
+
+export type PreviewInstallResponse = z.infer<typeof previewInstallResponseSchema>;
+
+/**
+ * Success shape of a preview uninstall (`DELETE
+ * /template/:templateId/preview/:previewKey`, no body). `removed` is the child
+ * row's id.
+ */
+export const previewUninstallResponseSchema = z
+  .object({ ok: z.literal(true), removed: z.string() })
+  .strict();
+
+export type PreviewUninstallResponse = z.infer<typeof previewUninstallResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// Registry credential upsert (scope: builder)
+// ---------------------------------------------------------------------------
+
+/** PUT target for the registry-credential upsert. */
+export const REGISTRY_PATH = "/registry";
+
+/**
+ * Body of a registry upsert (`PUT /registry`). `appId` is required — a global
+ * (NULL-app) credential is deliberately unrepresentable here; this surface only
+ * writes self-or-lineage scoped creds. `host` carries the registry host (may
+ * include `:port`); `username` / `password` are the Basic credential.
+ */
+export const registryUpsertBodySchema = z
+  .object({
+    appId: z.string().min(1),
+    host: z.string().regex(REGISTRY_HOST, "host must be a registry hostname with optional :port"),
+    username: z.string().min(1),
+    password: z.string().min(1),
+  })
+  .strict();
+
+export type RegistryUpsertBody = z.infer<typeof registryUpsertBodySchema>;
+
+/**
+ * Success shape of a registry upsert. `id` is the credential row id; `host` is
+ * the normalized host it was stored under; `created` is `false` when an
+ * existing row was updated.
+ */
+export const registryUpsertResponseSchema = z
+  .object({
+    ok: z.literal(true),
+    id: z.string(),
+    host: z.string(),
+    created: z.boolean(),
+  })
+  .strict();
+
+export type RegistryUpsertResponse = z.infer<typeof registryUpsertResponseSchema>;

package/src/home-cookie.ts

@@ -0,0 +1,10 @@
+/**
+ * Prefix of Home's own better-auth cookies (`realm-home.session_token`, …).
+ *
+ * Home sets it (`platform/home/src/server/auth.ts`) and the caddy app's
+ * cookie filter matches it, so the filter guards exactly Home's session and
+ * never an app's cookies — better-auth's default `better-auth.*` names
+ * included. Keep it free of regex metacharacters: caddy interpolates it into
+ * RE2 patterns.
+ */
+export const HOME_COOKIE_PREFIX = "realm-home";

package/src/home-registry.ts

@@ -0,0 +1,120 @@
+// Per-kind Home-side mechanics for `home.*` permissions — the keyless
+// control-plane namespace.
+//
+// `home` is a first-class namespace, not `host.homeApi` sugar: like
+// `peers`/`remote` it is Home-resolved and never worker-advertised, so it stays
+// out of the host worker-capability gate. But like `host` it carries data (the
+// granted scopes) and resolves to a runtime value (the per-app proxy socket),
+// so it gets its own small registry mirroring `host-registry.ts`. Each factory
+// carries its kind + hooks + meta as non-enumerable symbol properties (set by
+// makeHomeable), and `deriveHomeRegistry(home)` builds the runtime map from a
+// namespace import.
+//
+// `iterateUses` is always `() => []`: home kinds emit no elevated uses, since
+// the grant alone authorizes the socket mount and Home's eval graph exempts it.
+// It stays for symmetry with HostHooks.
+
+import type { z } from "zod";
+import type { HomeService } from "./resolve.ts";
+import type { ResolveArgs } from "./resolve-context.ts";
+import type { Builder } from "./shared.ts";
+import {
+  tagPermissionMeta,
+  type PermissionMeta,
+  type PermissionMetaTagged,
+} from "./permission-meta.ts";
+
+// Loose constraint used inside this module to bound K on `Homeable` /
+// `makeHomeable`. The closed `HomePermissionKind` lives in permissions.ts —
+// kept separate so this module doesn't import schema/home.ts (a type-level
+// cycle through factory.ts → shared.ts → permissions.ts → schema/home.ts).
+type HomeKindShape = `home.${string}`;
+
+export interface HomeHooks<TUse = unknown, TValue = unknown> {
+  iterateUses(svc: HomeService): Iterable<TUse>;
+  toValue(data: TUse): TValue;
+  /**
+   * Resolve against Home's eval-time world instead of the grant alone.
+   * Mirrors `HostHooks.resolve` — see resolve-context.ts. `home.apiAccess`
+   * uses it for the per-app proxy socket, which depends on the app, not the
+   * grant.
+   */
+  resolve?(args: ResolveArgs<TUse>): TValue;
+  /**
+   * Validator for admin-supplied grant data, used by `sanitizeGrants`.
+   * Falls back to the factory schema when omitted — appropriate for kinds
+   * where the admin grants exactly what the factory accepts (the scope
+   * array for `home.apiAccess`).
+   */
+  grantSchema?: z.ZodType;
+}
+
+const HOME_KIND = Symbol("realm.home.kind");
+const HOME_HOOKS = Symbol("realm.home.hooks");
+
+export interface Homeable<K extends HomeKindShape = HomeKindShape, V = unknown> {
+  readonly [HOME_KIND]: K;
+  readonly [HOME_HOOKS]: HomeHooks<unknown, V>;
+}
+
+function isHomeable(value: unknown): value is Homeable {
+  return (
+    (typeof value === "function" || (typeof value === "object" && value !== null)) &&
+    HOME_KIND in (value as object) &&
+    HOME_HOOKS in (value as object)
+  );
+}
+
+function tagHomeable<T extends object, K extends HomeKindShape, V>(
+  target: T,
+  kind: K,
+  hooks: HomeHooks<unknown, V>,
+  meta: PermissionMeta,
+): T & Homeable<K, V> & PermissionMetaTagged<K> {
+  Object.defineProperty(target, HOME_KIND, { value: kind, enumerable: false });
+  Object.defineProperty(target, HOME_HOOKS, { value: hooks, enumerable: false });
+  return tagPermissionMeta(target, kind, meta) as T & Homeable<K, V> & PermissionMetaTagged<K>;
+}
+
+/**
+ * Bind an inner Builder (`basePermission`) and return a factory-builder that
+ * produces tagged home-permission factories. Pure — no side effects on any
+ * registry. Mirrors `makeHostable`.
+ *
+ *   const homeable = makeHomeable(basePermission);
+ *   export const apiAccess = homeable("home.apiAccess", z.array(...), { ... }, meta);
+ *
+ * If `hooks.grantSchema` is omitted, the factory schema validates
+ * admin-supplied grant data.
+ */
+export function makeHomeable<BaseR extends object, KindUnion extends HomeKindShape>(
+  inner: Builder<BaseR, "perm", KindUnion>,
+) {
+  return <S extends z.ZodType, TUse, TValue, K extends KindUnion>(
+    kind: K,
+    schema: S,
+    hooks: HomeHooks<TUse, TValue>,
+    meta: PermissionMeta,
+  ) => {
+    const factory = inner(kind, schema);
+    const enriched: HomeHooks<TUse, TValue> = {
+      ...hooks,
+      grantSchema: hooks.grantSchema ?? schema,
+    };
+    return tagHomeable(factory, kind, enriched as HomeHooks<unknown, TValue>, meta);
+  };
+}
+
+/**
+ * Walk a namespace import (`import * as home from "./schema/home.ts"`) and
+ * build a kind→hooks map from every Homeable export.
+ */
+export function deriveHomeRegistry(
+  mod: Record<string, unknown>,
+): ReadonlyMap<HomeKindShape, HomeHooks> {
+  const reg = new Map<HomeKindShape, HomeHooks>();
+  for (const value of Object.values(mod)) {
+    if (isHomeable(value)) reg.set(value[HOME_KIND], value[HOME_HOOKS]);
+  }
+  return reg;
+}

package/src/home.ts

@@ -0,0 +1,187 @@
+// Home-side primitives. Server eval and dashboard islands import from
+// here. Kept off `@yourrealm/sdk`'s default entry so realm.ts bundles
+// don't pull these through barrel re-exports. Also kept off `/compile`
+// so islands can use the lightweight types/primitives without dragging
+// esbuild + quickjs into the browser bundle.
+
+// Error type re-export — Home catches it from bundle/sandbox.
+export { RealmCompileError, SiloRequiresError, formatIssue } from "./errors.ts";
+export type { CompileIssue } from "./errors.ts";
+
+// The eval-time world a permission resolver reads from. Home builds one per
+// app in graph.ts; the SDK test harness builds the same shape from fixtures.
+export type {
+  ResolveArgs,
+  ResolveContext,
+  ResolveSilo,
+  SiloPublication,
+} from "./resolve-context.ts";
+
+// Resolver inputs/outputs Home walks at recompute + image-pin time.
+export type { HomeApp, HomeService } from "./resolve.ts";
+
+// Header-brokering manifest sampled from `getTrustedHeaders` - Home reads it
+// off resolved state to compute per-request identity headers on every
+// Home-authenticated hop into the app (the ForwardAuth verify hop and the
+// UI surface loader/action hop), through the shared resolver below.
+export type { TrustedHeaderSource, TrustedHeadersManifest } from "./resolve.ts";
+export { resolveTrustedHeaders, stampHeaders } from "./trusted-headers.ts";
+export type { TrustedHeaderViewer } from "./trusted-headers.ts";
+
+// `host.management()` resolved shape — its resolver reads the identity off
+// the eval context (`home_state` + the running worker).
+export type { ManagementValue } from "./schema/host.ts";
+
+// `host.spawn()` resolved shape — its resolver builds the per-app paths at
+// eval, and `collectAllowed` reads them to exempt the socket/scratch/artifacts
+// paths from the absolute-mount gate.
+export type { SpawnValue } from "./worker-protocol/spawn-paths.ts";
+
+// `host.silo()` — the author's declared affordances (`SiloGrants`, the
+// descriptor's `data`) and the resolved shape its resolver builds from the Silo
+// record (`SiloResolved`, whose `volume` the app mounts verbatim).
+// `siloRequiresUnmetMessage` is the shared guided text for a require-map the
+// Silo can't satisfy — Home eval and the SDK harness emit it byte-identically.
+export { siloRequiresUnmetMessage } from "./schema/host.ts";
+export type {
+  SiloGrants,
+  SiloHostPath,
+  SiloRequireUnmet,
+  SiloResolved,
+  SiloVolume,
+} from "./schema/host.ts";
+
+// Generic config helper Home uses to merge config + resolved permission
+// values before handing them to the sandbox.
+export { deepMergeConfig } from "./deep-merge.ts";
+
+// SerializablePermission — shape coming out of the sandbox. Home UI
+// indexes by it; server eval threads it through the gate.
+export type { SerializablePermission } from "./sandbox.ts";
+
+// Grant + use shapes. Home enforces via the path-aware checkAppGrants in
+// security.ts, which builds on collectUses + hostHooks.
+export {
+  toValue,
+  resolveValue,
+  collectUses,
+  collectHomeApiScopes,
+  hostHooks,
+  homeHooks,
+  isHostGrant,
+  isHomeGrant,
+} from "./grants.ts";
+export type {
+  HomeGrant,
+  Grant,
+  GrantOf,
+  Grants,
+  GrantsOf,
+  HostGrant,
+  PeerGrant,
+  RemoteGrant,
+  Use,
+  ValueOf,
+} from "./grants.ts";
+
+// Permission kinds (closed sets, derived from schema/* factories).
+export type {
+  HomePermissionKind,
+  HostPermissionKind,
+  WorkerCapability,
+  PeerPermissionKind,
+  RemotePermissionKind,
+} from "./permissions.ts";
+
+// Host + home registry hooks (per-kind iterateUses / toValue / grantSchema).
+export type { HostHooks } from "./host-registry.ts";
+export type { HomeHooks } from "./home-registry.ts";
+
+// `home.apiAccess()` resolved shape — its resolver builds `socket` from the
+// app's per-app proxy path at eval time.
+export type { HomeApiAccessValue } from "./schema/home.ts";
+
+// Peer-world helpers + types (per-kind extract/resolve hooks, world
+// state aggregation, allow-list extraction for ref resolution).
+export {
+  extractPeerEntries,
+  resolvePeerValue,
+  isPeerGranted,
+  isBuildAppEntry,
+  peerHooks,
+  peerEntries,
+} from "./peer-world.ts";
+export type { BuildAppWorldEntry, WorldEntry, WorldState } from "./peer-world.ts";
+export type { AllowedProvider, PeerHooks } from "./peer-registry.ts";
+
+// Peer entry types — also on the author barrel because realm.ts can
+// reference them in `getDesiredState`, but Home eval walks them too so
+// they live here as well.
+export type {
+  BackupStrategy,
+  BackupTarget,
+  HostPortEntry,
+  NetworkStrategy,
+  PeerHostPath,
+  RoutedAppEntry,
+  VolumeStrategy,
+} from "./schema/peer.ts";
+
+// Identifier schemas + Network brand — Home eval references them when
+// building world state, validating image refs, etc.
+export { nameSchema, domainSchema, networkSchema, hostKey } from "./identifiers.ts";
+export type { Network } from "./identifiers.ts";
+
+// The public-domain grant value. Home parses stored grants through this to
+// recover the hosts an app claims, which is also how each `domain_claim` key
+// inherits the schema's hostname normalization instead of repeating it.
+export { publicDomainValueSchema } from "./schema/public-domain.ts";
+export type { PublicDomainGrantData } from "./schema/public-domain.ts";
+
+// Security primitives — write-time sanitize + runtime path-aware gate.
+export {
+  HOST_DIRECTORY_BLOCKLIST,
+  isValidHostDirectoryPath,
+  normalizeHostPath,
+  pathsOverlap,
+  grantsSchema,
+  sanitizeGrants,
+  checkAppGrants,
+  checkPermissionAppKinds,
+  checkPublicDomains,
+  isUnderBaseDomain,
+  checkSystemAppRoutes,
+  siloMountKey,
+} from "./security.ts";
+export type {
+  GrantViolation,
+  EvalErrorViolation,
+  WorkerCapabilityViolation,
+  AppKindViolation,
+  RoutingViolation,
+  Violation,
+  GrantIssue,
+  SanitizeResult,
+} from "./security.ts";
+
+// Per-kind presentation metadata + closed-set kind list.
+export {
+  PERMISSION_META,
+  PERMISSION_KINDS,
+  HOST_PERMISSION_KINDS,
+  WORKER_CAPABILITIES,
+} from "./permissions.ts";
+export type { PermissionMeta } from "./permissions.ts";
+export type { PermissionKind } from "./permissions.ts";
+
+// Required-vs-optional host-kind partition. Home eval uses it to drop
+// workers that don't advertise an app's required kinds; the install
+// panel uses it to gray out optional kinds no worker can satisfy.
+export { partitionHostKinds, stateRequiresVolumes } from "./required-host-kinds.ts";
+export type { PartitionedHostKinds } from "./required-host-kinds.ts";
+
+// Pure grant-building helper shared between the server install path
+// and the dashboard islands. Kept off the deeper barrels so client
+// islands can use it without dragging drizzle / db / sandbox into the
+// browser bundle.
+export { descriptorsToGrants } from "./grants-builder.ts";

package/src/host-registry.ts

@@ -0,0 +1,143 @@
+// Per-kind Home-side mechanics for host permissions.
+//
+// Each host factory carries its kind + hooks + meta as non-enumerable symbol
+// properties (set by makeHostable / tagHostable), and the runtime registry is
+// derived from a namespace import (`deriveHostRegistry(host)`) — same pattern
+// as peer-registry.ts. The hooks bundle what grants.ts and Home need per kind:
+// `iterateUses` walks a resolved service and yields each elevated thing it does
+// of this kind (a port bind, a directory mount), `toValue` projects a grant's
+// data into the value the SDK hands to `getDesiredState`, and the optional
+// `resolve` / `grantSchema` are documented on HostHooks below. Per-kind
+// presentation strings travel as a separate `meta` argument and land via
+// tagPermissionMeta, picked up by derivePermissionMeta in permissions.ts.
+//
+// `ValueOf<G>` in grants.ts is the type-level dual of toValue, derived by
+// walking `typeof host` and reading `Hostable<K, V>` off each export's tag —
+// V is the inferred return type of `toValue`, threaded through makeHostable.
+
+import type { z } from "zod";
+import type { HomeService } from "./resolve.ts";
+import type { ResolveArgs } from "./resolve-context.ts";
+import type { Builder } from "./shared.ts";
+import {
+  tagPermissionMeta,
+  type PermissionMeta,
+  type PermissionMetaTagged,
+} from "./permission-meta.ts";
+
+// Loose constraint used inside this module to bound K on `Hostable` /
+// `makeHostable`. The closed `HostPermissionKind` lives in permissions.ts —
+// kept separate so this module doesn't import schema/host.ts, which would form
+// a type-level cycle through factory.ts → shared.ts → permissions.ts →
+// schema/host.ts.
+type HostKindShape = `host.${string}`;
+
+export interface HostHooks<TUse = unknown, TValue = unknown> {
+  iterateUses(svc: HomeService): Iterable<TUse>;
+  toValue(data: TUse): TValue;
+  /**
+   * Resolve against Home's eval-time world instead of the grant alone.
+   *
+   * `toValue` handles the kinds where the grant already holds the answer.
+   * Declare `resolve` for the kinds where it doesn't - a Silo id means
+   * nothing without the Silo record, so `host.silo` reads it off
+   * `args.ctx`. When present it replaces `toValue` on the resolution path;
+   * `toValue` stays as the type-level source for `ValueOf`.
+   *
+   * Synchronous by construction: the context carries data, never a lookup
+   * that could await. See resolve-context.ts.
+   */
+  resolve?(args: ResolveArgs<TUse>): TValue;
+  /**
+   * Validator for admin-supplied grant data, used by `sanitizeGrants` /
+   * `grantsSchema`. Falls back to the factory schema when omitted —
+   * appropriate for kinds where the admin grants exactly what the
+   * factory accepts (port, capability, etc.). Override per-kind when
+   * grant data has a different shape than the factory's author input
+   * (e.g. `host.silo`: factory takes the asked flags but grants carry
+   * absolute paths plus a blocklist).
+   */
+  grantSchema?: z.ZodType;
+}
+
+const HOST_KIND = Symbol("realm.host.kind");
+const HOST_HOOKS = Symbol("realm.host.hooks");
+
+export interface Hostable<K extends HostKindShape = HostKindShape, V = unknown> {
+  readonly [HOST_KIND]: K;
+  readonly [HOST_HOOKS]: HostHooks<unknown, V>;
+}
+
+function isHostable(value: unknown): value is Hostable {
+  return (
+    (typeof value === "function" || (typeof value === "object" && value !== null)) &&
+    HOST_KIND in (value as object) &&
+    HOST_HOOKS in (value as object)
+  );
+}
+
+/**
+ * Attach kind + hooks + meta to an arbitrary value (mirrors tagPeerable
+ * for the rare wrapper case). Almost every host kind goes through
+ * makeHostable directly, but the helper is here for symmetry.
+ */
+function tagHostable<T extends object, K extends HostKindShape, V>(
+  target: T,
+  kind: K,
+  hooks: HostHooks<unknown, V>,
+  meta: PermissionMeta,
+): T & Hostable<K, V> & PermissionMetaTagged<K> {
+  Object.defineProperty(target, HOST_KIND, { value: kind, enumerable: false });
+  Object.defineProperty(target, HOST_HOOKS, { value: hooks, enumerable: false });
+  return tagPermissionMeta(target, kind, meta) as T & Hostable<K, V> & PermissionMetaTagged<K>;
+}
+
+/**
+ * Bind an inner Builder (typically `basePermission`) and return a
+ * factory-builder that produces tagged host-permission factories. Pure —
+ * no side effects on any registry. The runtime registry is derived from
+ * a namespace import via `deriveHostRegistry`.
+ *
+ * Composes with the factory mixins: `makeHostable(basePermission)` reads
+ * the same shape as `makeOptional(makeReasonable(makePermRecord))`.
+ *
+ *   const hostable = makeHostable(basePermission);
+ *   export const port = hostable("host.port", z.number()..., {
+ *     iterateUses, toValue,
+ *   });
+ *
+ * If `hooks.grantSchema` is omitted, the factory schema is used to
+ * validate admin-supplied grant data — appropriate for kinds where
+ * authors and admins supply the same shape.
+ */
+export function makeHostable<BaseR extends object, KindUnion extends HostKindShape>(
+  inner: Builder<BaseR, "perm", KindUnion>,
+) {
+  return <S extends z.ZodType, TUse, TValue, K extends KindUnion>(
+    kind: K,
+    schema: S,
+    hooks: HostHooks<TUse, TValue>,
+    meta: PermissionMeta,
+  ) => {
+    const factory = inner(kind, schema);
+    const enriched: HostHooks<TUse, TValue> = {
+      ...hooks,
+      grantSchema: hooks.grantSchema ?? schema,
+    };
+    return tagHostable(factory, kind, enriched as HostHooks<unknown, TValue>, meta);
+  };
+}
+
+/**
+ * Walk a namespace import (e.g. `import * as host from "./schema/host.ts"`)
+ * and build a kind→hooks map from every Hostable export.
+ */
+export function deriveHostRegistry(
+  mod: Record<string, unknown>,
+): ReadonlyMap<HostKindShape, HostHooks> {
+  const reg = new Map<HostKindShape, HostHooks>();
+  for (const value of Object.values(mod)) {
+    if (isHostable(value)) reg.set(value[HOST_KIND], value[HOST_HOOKS]);
+  }
+  return reg;
+}

package/src/http-header.ts

@@ -0,0 +1,20 @@
+// What HTTP allows in a header name and value, as one definition.
+//
+// Two places need it and must not drift. The worker's `/ui-proxy` enforces it
+// at request time and rejects the WHOLE call on a violation, so a single bad
+// character takes down every loader and action into an app. `getTrustedHeaders`
+// sampling enforces the same rule at compile time, so such an app fails to
+// install with a message naming the header instead of going dark in the field.
+//
+// Pure regex literals, no imports: this module is reachable from the author
+// barrel and therefore loads inside QuickJS.
+
+/** RFC 7230 `token`: what may appear in a header field name. */
+export const HEADER_NAME_RE = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/;
+
+/**
+ * Printable ASCII, the safe subset of a header field value. Excludes CR and LF
+ * (response splitting) and everything above 0x7e, which has no interoperable
+ * encoding in a header.
+ */
+export const HEADER_VALUE_RE = /^[\x20-\x7e]*$/;