@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/worker-protocol/spawn-paths.ts

@@ -0,0 +1,165 @@
+// Wire constants for `host.spawn()` — the worker's disposable-container
+// broker, keyed per granted app. Mirrors `home-proxy-paths.ts`: one socket
+// per app, so the worker attaches the caller's identity from *which* socket a
+// request arrived on, never from the wire. The resolved
+// `{socket, scratch, artifacts}` is built per-app by `host.spawn`'s resolver at
+// eval, not a fixed constant — so the SDK only ships the placeholder + the path
+// builders.
+//
+// Pure constants + string-join builders, no runtime imports (the
+// `WorkerHostPath` import is type-only and erases), so schema/host.ts can pull
+// `SPAWN_PLACEHOLDER` under QuickJS and any realm.ts consumer can read the
+// resolved shape without dragging Deno deps.
+
+import type { WorkerHostPath } from "./logs-socket-path.ts";
+import type { WorkerMount } from "./worker-mount.ts";
+
+/**
+ * Host directory the worker keeps every spawn app's socket + per-app tree
+ * under. Lives beneath `/opt/realm/worker/` — the one directory the worker
+ * container already shares with the host — so the inode the worker binds is
+ * the same one a granted app bind-mounts through the host docker daemon
+ * (mirrors `REALM_HOME_PROXY_DIR`).
+ *
+ * Two fixed sub-roots hang off this: `sock/` holds one per-app socket dir each
+ * (`sock/<appId>/spawn.sock`), and `data/` holds the *heavy* per-app build
+ * storage (scratch / artifacts / the broker-private back room). Keeping the
+ * sockets under their own `sock/` segment — a sibling of `data/` — means a
+ * per-app socket dir can never collide with the `data/<appId>` tree, even for
+ * an app literally named `data`. The `data/` segment is also the relocation
+ * seam: an operator who wants build storage on another drive mounts it at
+ * `${REALM_SPAWN_DIR}/data` (a fixed path, not a config knob), which keeps
+ * scratch / artifacts / private on the *same* filesystem — load-bearing,
+ * because the back-room seal renames between them and a rename must not cross a
+ * device boundary.
+ */
+export const REALM_SPAWN_DIR = "/opt/realm/worker/spawn";
+
+/**
+ * Host directory holding one app's spawn broker socket
+ * (`/opt/realm/worker/spawn/sock/<appId>`). The socket sits alone inside it, so
+ * this is the path the app bind-mounts (a file bind-mount of a unix socket
+ * doesn't wire across containers on macOS Docker; the app mounts the dir and
+ * connects to the socket inside it). `host.spawn`'s resolver builds its
+ * `{ socket }` from this per-app dir at eval, and `collectAllowed` exempts it
+ * from the absolute-mount gate.
+ */
+export function spawnSocketDir(appId: string): WorkerHostPath {
+  return `${REALM_SPAWN_DIR}/sock/${appId}` as WorkerHostPath;
+}
+
+/**
+ * Host path of one app's spawn broker socket, inside {@link spawnSocketDir}
+ * (`/opt/realm/worker/spawn/sock/<appId>/spawn.sock`). The worker binds this in
+ * `reconcileSpawnSockets` and carries it on the wire; the app connects to it
+ * inside the mounted per-app socket dir to start one disposable box per job.
+ */
+export function spawnSocketPath(appId: string): string {
+  return `${spawnSocketDir(appId)}/spawn.sock`;
+}
+
+/**
+ * Host path of one app's scratch dir
+ * (`/opt/realm/worker/spawn/data/<appId>/scratch`). The app stages a build
+ * context under a relative key here; the broker renames that one subdir into
+ * its per-box back room (see {@link spawnPrivatePath}) and mounts it into the
+ * box read-only. Per-app, so one spawn app can't read another's in-flight
+ * context. Under `data/` so it shares a filesystem with artifacts +
+ * private (the seal's rename must not cross a device boundary).
+ */
+export function spawnScratchPath(appId: string): WorkerHostPath {
+  return `${REALM_SPAWN_DIR}/data/${appId}/scratch` as WorkerHostPath;
+}
+
+/**
+ * Host path of one app's artifacts dir
+ * (`/opt/realm/worker/spawn/data/<appId>/artifacts`). On a successful build
+ * the broker renames the box's output here under a per-box subdir; the app
+ * reads the result back out of it (e.g. `output-<boxId>/image.tar`). A sibling
+ * of the scratch dir so input (the cloned source the app stages) and output
+ * (the built image) live in separate per-app mounts. Under `data/` so it
+ * shares a filesystem with scratch + private (the success rename must not
+ * cross a device boundary).
+ */
+export function spawnArtifactsPath(appId: string): WorkerHostPath {
+  return `${REALM_SPAWN_DIR}/data/${appId}/artifacts` as WorkerHostPath;
+}
+
+/**
+ * Host path of one app's broker-private "back room"
+ * (`/opt/realm/worker/spawn/data/<appId>/private`). The broker moves both bind
+ * sources (the validated context, and the box's output dir) into a per-box
+ * subdir here for the duration of a build — a dir the calling app has NO mount
+ * into. That's the seal: the broker re-validates the *moved* inode and
+ * runs the box against a path the caller can't reach, so the caller can't swap
+ * the validated dir for a symlink between validate and Docker mount.
+ *
+ * Broker-only: unlike socket / scratch / artifacts this is NOT part of
+ * {@link SpawnValue}, never travels the wire, and is never exempted from the
+ * absolute-mount gate — no app ever mounts it. It's a sibling of scratch +
+ * artifacts under `data/<appId>/` so the seal's renames stay same-filesystem,
+ * and so the worker's reconcile reclaims it with the rest of the app's `data/`
+ * subtree once the app is off the wire.
+ */
+export function spawnPrivatePath(appId: string): WorkerHostPath {
+  return `${REALM_SPAWN_DIR}/data/${appId}/private` as WorkerHostPath;
+}
+
+/**
+ * Resolved shape of a `host.spawn()` grant. All three fields are per-app paths
+ * built at eval (no fixed constant); `SPAWN_PLACEHOLDER` is type-level only,
+ * there so `ValueOf` can read this shape off `toValue` (mirrors
+ * `HomeApiAccessValue` / `HOME_API_PLACEHOLDER`). `socket` is the per-app
+ * DIRECTORY holding the broker socket — the app mounts it and connects to
+ * `<mount>/spawn.sock` inside (a file bind-mount of a unix socket doesn't wire
+ * across containers on macOS Docker). `scratch` is where the app stages a build
+ * context (input); `artifacts` is where it reads a build's output back. There
+ * is no network field: the box attaches to the untrusted-zone DMZ broker-side
+ * (see spawn-server/spec.ts), and that DMZ has no internal members — an app
+ * never puts a service on it, so it has nothing to wire.
+ */
+export interface SpawnValue {
+  readonly socket: WorkerMount;
+  readonly scratch: WorkerMount;
+  readonly artifacts: WorkerMount;
+}
+
+/**
+ * Build the resolved `host.spawn` value for one app. `socket` is read-only -
+ * the app connects to the broker, it never writes to the socket's directory.
+ * `scratch` and `artifacts` are the app's own working storage on both sides of
+ * a build (stage a context in, read an image back out), so they stay writable.
+ */
+export function spawnMounts(appId: string): SpawnValue {
+  return {
+    socket: {
+      hostPath: spawnSocketDir(appId),
+      containerPath: "/run/realm/spawn-sock",
+      readOnly: true,
+    },
+    scratch: {
+      hostPath: spawnScratchPath(appId),
+      containerPath: "/run/realm/spawn",
+      readOnly: false,
+    },
+    artifacts: {
+      hostPath: spawnArtifactsPath(appId),
+      containerPath: "/run/realm/artifacts",
+      readOnly: false,
+    },
+  };
+}
+
+/**
+ * Type-level stand-in for `host.spawn()`'s resolved value, so `ValueOf` can
+ * read the shape. Empty paths stand in for "never resolved"; the container paths and the
+ * writability are already final, since those don't depend on the app.
+ */
+const UNFILLED = spawnMounts("");
+const blank = (m: WorkerMount): WorkerMount => ({ ...m, hostPath: "" as WorkerHostPath });
+
+export const SPAWN_PLACEHOLDER: SpawnValue = {
+  socket: blank(UNFILLED.socket),
+  scratch: blank(UNFILLED.scratch),
+  artifacts: blank(UNFILLED.artifacts),
+};

package/src/worker-protocol/stats-socket-path.ts

@@ -0,0 +1,40 @@
+import type { WorkerHostPath } from "./logs-socket-path.ts";
+import type { WorkerMount } from "./worker-mount.ts";
+
+/**
+ * Host directory the worker keeps the shared stats socket inside. This is the
+ * path an app mounts (the DIRECTORY, not the socket file): a file bind-mount
+ * of a unix socket does NOT wire to the live listener across containers on
+ * macOS Docker (connect succeeds, no bytes flow), so every broker socket lives
+ * alone in its own directory and the app mounts that directory. The value
+ * `r.host.stats()` resolves to (and the path the resolver exempts from the
+ * absolute-mount gate).
+ *
+ * Lives under `/opt/realm/worker/` for the same reason as
+ * {@link REALM_LOGS_DIR}: it's the one directory the worker container already
+ * shares with the host, so the socket the worker binds is the same inode an
+ * app container can bind-mount through the host docker daemon. It also puts
+ * the path under the `/opt/realm` entry of `HOST_DIRECTORY_BLOCKLIST`, so an
+ * operator can't route a Silo around the `host.stats`
+ * gate.
+ */
+export const REALM_STATS_DIR = "/opt/realm/worker/stats" as WorkerHostPath;
+
+/**
+ * Host path of the stats socket, inside {@link REALM_STATS_DIR}. The worker's
+ * stats-server binds this; a consumer mounts {@link REALM_STATS_DIR} and
+ * connects to the socket at the corresponding path inside the mounted
+ * directory.
+ */
+export const REALM_STATS_SOCKET = `${REALM_STATS_DIR}/stats.sock`;
+
+/**
+ * What `r.host.stats()` resolves to: the mount, not the bare path. Read-only
+ * for the same reason as {@link REALM_LOGS_MOUNT} - {@link REALM_STATS_DIR} is
+ * shared by every app holding the grant.
+ */
+export const REALM_STATS_MOUNT: WorkerMount = {
+  hostPath: REALM_STATS_DIR,
+  containerPath: "/run/realm/stats",
+  readOnly: true,
+};

package/src/worker-protocol/update-files.ts

@@ -0,0 +1,77 @@
+// The two files an updater-driven compose project carries beside its `.env`:
+// `.update`, the pending request and the updater's retry token, and
+// `.update.error`, what the last failed attempt said. The worker reads them
+// for its own box's `worker` and `ingress` projects and Home reads its own
+// `etc/home`, so the one reader lives here rather than twice.
+//
+// A read, never a write: the worker writes `.update` (self-update.ts) and the
+// updater writes `.update.error` (apply.rs). This module only says what is on
+// disk right now.
+
+/**
+ * Longest `error` this reader hands back, and so the longest an
+ * `update.status` carries: the tail of `.update.error`. It lives beside the
+ * reader rather than in the uplink catalogue so this module, on the
+ * author-safe barrel, imports nothing from `uplink/`.
+ */
+export const UPDATE_ERROR_MAX_CHARS = 2048;
+
+/** The two files an updater-driven project carries beside its `.env`. */
+export interface UpdateFiles {
+  /** `.update` exists (the pending request / retry token). */
+  pending: boolean;
+  /**
+   * Trimmed `.update.error` content, or null when absent or empty. Capped at
+   * `UPDATE_ERROR_MAX_CHARS` from the end, because the last lines of a compose
+   * failure are the ones that say why.
+   */
+  error: string | null;
+}
+
+/**
+ * Anything bigger is junk, not a message: the updater bounds what it writes
+ * well under this, so a file over it was put there by something else.
+ */
+const MAX_ERROR_FILE_BYTES = 16 * 1024;
+
+/**
+ * Read `<dir>/.update` and `<dir>/.update.error`.
+ *
+ * `Deno.*` is touched inside the body only: this module is reachable from the
+ * author-safe `worker-protocol` barrel, which an author's realm.ts may import
+ * into QuickJS, where `Deno` does not exist (`quickjs-safe.test.ts`).
+ *
+ * Never throws for a missing file or dir - that is `{ pending: false, error:
+ * null }`, the shape of a project with nothing going on. The worker's
+ * `.tmp-*` siblings from a tmp-then-rename in flight are not these files and
+ * are never read.
+ */
+export async function readUpdateFiles(dir: string): Promise<UpdateFiles> {
+  const [pending, error] = await Promise.all([
+    isFile(`${dir}/.update`),
+    readError(`${dir}/.update.error`),
+  ]);
+  return { pending, error };
+}
+
+async function isFile(path: string): Promise<boolean> {
+  try {
+    return (await Deno.stat(path)).isFile;
+  } catch {
+    return false;
+  }
+}
+
+async function readError(path: string): Promise<string | null> {
+  let text: string;
+  try {
+    const stat = await Deno.stat(path);
+    if (!stat.isFile || stat.size > MAX_ERROR_FILE_BYTES) return null;
+    text = await Deno.readTextFile(path);
+  } catch {
+    return null;
+  }
+  const trimmed = text.trim();
+  if (trimmed === "") return null;
+  return trimmed.length > UPDATE_ERROR_MAX_CHARS ? trimmed.slice(-UPDATE_ERROR_MAX_CHARS) : trimmed;
+}

package/src/worker-protocol/uplink/constants.ts

@@ -0,0 +1,86 @@
+// The numbers this layer owns, from `todo/ideas/uplink.md` § Constants.
+// That table is the authority; change it there, not here.
+
+/** `[len u16][streamId u32][type u8]`. */
+export const FRAME_HEADER_BYTES = 7;
+
+/** What `len` can express. `encodeFrame` refuses more; the wire rule is below. */
+export const MAX_FRAME_LEN = 65535;
+
+/** OPEN headers and DATA fragments are both capped here, in both directions. */
+export const MAX_PAYLOAD_BYTES = 16 * 1024;
+
+export const DEFAULT_LIMITS = {
+  fragmentSize: 16 * 1024,
+  initialWindow: 256 * 1024,
+  maxStreams: 64,
+  maxInFlight: 8 * 1024 * 1024,
+} as const;
+
+/** PING/PONG ride stream 0 and carry 8 opaque bytes. */
+export const CONTROL_STREAM_ID = 0;
+export const PING_PAYLOAD_BYTES = 8;
+
+/** WINDOW carries one u32 credit increment. */
+export const WINDOW_PAYLOAD_BYTES = 4;
+
+/** The RPC response head is `[u16 headLen][head JSON]`, so the head fits a u16. */
+export const MAX_RPC_HEAD_BYTES = 65535;
+
+/** RESET reasons are diagnostics, not payloads; long ones are cut here. */
+export const MAX_RESET_REASON_CHARS = 512;
+
+// --- the session below the mux ---------------------------------------
+
+/**
+ * The Noise prologue, `realm-uplink/1`. It versions the bytes below the RPC -
+ * the handshake, the frames, the mux - and a peer on another number fails the
+ * handshake. The catalogue above those bytes is versioned separately, by
+ * `PROTOCOL_VERSION` in `protocol.ts`, which two peers compare in `hello` and
+ * can act on.
+ *
+ * Those are different failures on purpose. A `PROTOCOL_VERSION` mismatch still
+ * gives both sides a session, so Home can tell the box to update over it. A
+ * prologue mismatch gives them nothing: there is no session to carry the
+ * instruction, and moving that box takes the updater's `.update` file by hand.
+ * So this number changes only when the transport itself does.
+ *
+ * Spelled byte by byte rather than through `encodeUtf8` so it can be a
+ * module-load constant: this file is reachable from an author bundle, where
+ * `TextEncoder` does not exist.
+ */
+export const UPLINK_PROLOGUE: Uint8Array = Uint8Array.from("realm-uplink/1", (c) =>
+  c.charCodeAt(0),
+);
+
+/** A Noise message is at most 65535 bytes including its 16-byte tag. */
+export const NOISE_MAX_PAYLOAD = 65519;
+
+/** Socket open and all three handshake messages, together. */
+export const HANDSHAKE_TIMEOUT_MS = 5000;
+
+/** `WebSocket.send` buffers unboundedly; the session stops filling past this. */
+export const SOCKET_HIGH_WATER = 256 * 1024;
+
+/**
+ * Undecrypted messages queued ahead of the mux. A WHATWG socket cannot pause
+ * its reads, so a peer that outruns decryption is closed rather than buffered.
+ */
+export const SOCKET_INBOUND_CAP = 16 * 1024 * 1024;
+
+// --- liveness ---------------------------------------------------------
+// The session runs none of these. The worker's client loop owns the ping
+// cadence, the pong deadline and the reconnect; Home's session registry owns
+// the idle deadline. They are here so both sides read one number.
+
+export const PING_INTERVAL_MS = 25_000;
+export const PONG_TIMEOUT_MS = 10_000;
+export const IDLE_TIMEOUT_MS = 35_000;
+
+/** Rekey by reconnecting, so no session holds one key forever. */
+export const REKEY_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const REKEY_JITTER_MS = 2 * 60 * 60 * 1000;
+
+/** Reconnect backoff: doubling from the base to the cap, full jitter. */
+export const BACKOFF_BASE_MS = 1000;
+export const BACKOFF_CAP_MS = 30_000;

package/src/worker-protocol/uplink/errors.ts

@@ -0,0 +1,61 @@
+// Everything the mux and the RPC layer reject with. One base so a caller
+// can tell an uplink failure from an application one in a single check.
+
+export class UplinkError extends Error {}
+
+/** The peer violated the framing. The mux closes the session on one of these. */
+export class UplinkProtocolError extends UplinkError {
+  constructor(message: string) {
+    super(message);
+    this.name = "UplinkProtocolError";
+  }
+}
+
+/** The session is gone; every open and pending stream fails with this. */
+export class SessionClosed extends UplinkError {
+  readonly reason: string;
+
+  constructor(reason: string) {
+    super(`uplink session closed: ${reason}`);
+    this.name = "SessionClosed";
+    this.reason = reason;
+  }
+}
+
+/** One stream was aborted, in either direction. Carries the peer's reason. */
+export class StreamReset extends UplinkError {
+  readonly reason: string;
+
+  constructor(reason: string) {
+    super(reason === "" ? "stream reset" : `stream reset: ${reason}`);
+    this.name = "StreamReset";
+    this.reason = reason;
+  }
+}
+
+/**
+ * The responder's static key is not the one the worker pinned. Raised after
+ * handshake message 2 and before message 3, so the worker's own static never
+ * goes out. Not retryable, and it is the worker's loop — not this layer —
+ * that must refuse to retry (`todo/ideas/uplink.md` § What it guarantees).
+ */
+export class HomeKeyMismatch extends UplinkError {
+  /** Hex, for a log line the operator can compare against the paste. */
+  readonly expected: string;
+  readonly actual: string;
+
+  constructor(expected: Uint8Array, actual: Uint8Array) {
+    const want = hex(expected);
+    const got = hex(actual);
+    super(`Home answered with static key ${got}, not the pinned ${want}`);
+    this.name = "HomeKeyMismatch";
+    this.expected = want;
+    this.actual = got;
+  }
+}
+
+// Not `Uint8Array.prototype.toHex`: this module is reachable from an author
+// bundle, and QuickJS has no such method.
+function hex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/src/worker-protocol/uplink/frame.ts

@@ -0,0 +1,114 @@
+// The uplink frame codec: `[len u16][streamId u32][type u8][payload]`,
+// big-endian, `len` counting payload only. The byte stream underneath may
+// split or coalesce arbitrarily, so `FrameParser` is fed raw chunks and
+// emits whole frames, keeping any partial tail for the next chunk.
+
+import { FRAME_HEADER_BYTES, MAX_FRAME_LEN, MAX_PAYLOAD_BYTES } from "./constants.ts";
+import { UplinkProtocolError } from "./errors.ts";
+
+export const FrameType = {
+  OPEN: 1,
+  DATA: 2,
+  END: 3,
+  RESET: 4,
+  WINDOW: 5,
+  PING: 6,
+  PONG: 7,
+} as const;
+
+export type FrameType = (typeof FrameType)[keyof typeof FrameType];
+
+const FRAME_TYPE_NAMES: Record<number, string> = Object.fromEntries(
+  Object.entries(FrameType).map(([name, id]) => [id, name]),
+);
+
+export function frameTypeName(type: number): string {
+  return FRAME_TYPE_NAMES[type] ?? `type ${type}`;
+}
+
+export interface Frame {
+  type: FrameType;
+  streamId: number;
+  payload: Uint8Array;
+}
+
+export const EMPTY_PAYLOAD = new Uint8Array(0);
+
+export function encodeFrame(type: FrameType, streamId: number, payload: Uint8Array): Uint8Array {
+  if (payload.length > MAX_FRAME_LEN) {
+    throw new RangeError(`frame payload ${payload.length} exceeds ${MAX_FRAME_LEN} bytes`);
+  }
+  const out = new Uint8Array(FRAME_HEADER_BYTES + payload.length);
+  const view = new DataView(out.buffer);
+  view.setUint16(0, payload.length);
+  view.setUint32(2, streamId);
+  view.setUint8(6, type);
+  out.set(payload, FRAME_HEADER_BYTES);
+  return out;
+}
+
+export class FrameParser {
+  #pending = EMPTY_PAYLOAD;
+
+  /** Throws `UplinkProtocolError` on anything the framing forbids. */
+  push(chunk: Uint8Array): Frame[] {
+    const buf = this.#pending.length === 0 ? chunk : concatBytes(this.#pending, chunk);
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    const frames: Frame[] = [];
+    let offset = 0;
+    while (buf.length - offset >= FRAME_HEADER_BYTES) {
+      const len = view.getUint16(offset);
+      const total = FRAME_HEADER_BYTES + len;
+      if (buf.length - offset < total) break;
+      const type = view.getUint8(offset + 6);
+      if (FRAME_TYPE_NAMES[type] === undefined) {
+        throw new UplinkProtocolError(`unknown frame type ${type}`);
+      }
+      // The `len` field can express 64 KiB, the protocol allows 16.
+      if (len > MAX_PAYLOAD_BYTES) {
+        throw new UplinkProtocolError(`frame payload ${len} exceeds ${MAX_PAYLOAD_BYTES} bytes`);
+      }
+      frames.push({
+        type: type as FrameType,
+        streamId: view.getUint32(offset + 2),
+        // Copied: the payload outlives `chunk` once it lands in a stream queue.
+        payload: buf.slice(offset + FRAME_HEADER_BYTES, offset + total),
+      });
+      offset += total;
+    }
+    this.#pending = offset === buf.length ? EMPTY_PAYLOAD : buf.slice(offset);
+    return frames;
+  }
+}
+
+export function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a);
+  out.set(b, a.length);
+  return out;
+}
+
+export function encodeU32(value: number): Uint8Array {
+  const out = new Uint8Array(4);
+  new DataView(out.buffer).setUint32(0, value);
+  return out;
+}
+
+export function decodeU32(bytes: Uint8Array): number {
+  return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0);
+}
+
+// Lazy so no Web global is touched at module load: this file is reachable
+// from the SDK graph that gets inlined into QuickJS author bundles.
+let encoder: TextEncoder | undefined;
+let decoder: TextDecoder | undefined;
+
+export function encodeUtf8(text: string): Uint8Array {
+  encoder ??= new TextEncoder();
+  return encoder.encode(text);
+}
+
+export function decodeUtf8(bytes: Uint8Array): string {
+  decoder ??= new TextDecoder();
+  return decoder.decode(bytes);
+}

package/src/worker-protocol/uplink/identity.ts

@@ -0,0 +1,40 @@
+// The one text encoding of an uplink static public key, shared by everything
+// that writes or reads one: the `worker.public_key` column, `uplink.pub` on
+// Home's box, `home.pub` in the worker dir, and the enrollment token
+// `{homePublicKey}.{otp}`. Unpadded base64url, 43 chars for 32 bytes.
+
+import { KEY_LENGTH } from "@yourrealm/noise";
+
+const ENCODED_LENGTH = 43;
+
+export function encodePublicKey(key: Uint8Array): string {
+  if (key.length !== KEY_LENGTH) {
+    throw new RangeError(`public key must be ${KEY_LENGTH} bytes, got ${key.length}`);
+  }
+  return key.toBase64({ alphabet: "base64url", omitPadding: true });
+}
+
+/** Returns null for anything that is not exactly one encoded key. */
+export function decodePublicKey(text: string): Uint8Array | null {
+  if (text.length !== ENCODED_LENGTH || !/^[A-Za-z0-9_-]+$/.test(text)) return null;
+  try {
+    const key = Uint8Array.fromBase64(text, { alphabet: "base64url" });
+    return key.length === KEY_LENGTH ? key : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Splits `{homePublicKey}.{otp}`; a bare OTP has no key half. */
+export function parseEnrollmentToken(
+  token: string,
+): { homePublicKey: Uint8Array | null; otp: string } | null {
+  const trimmed = token.trim();
+  if (trimmed === "") return null;
+  const dot = trimmed.indexOf(".");
+  if (dot === -1) return { homePublicKey: null, otp: trimmed };
+  const homePublicKey = decodePublicKey(trimmed.slice(0, dot));
+  const otp = trimmed.slice(dot + 1);
+  if (homePublicKey === null || otp === "") return null;
+  return { homePublicKey, otp };
+}

package/src/worker-protocol/uplink/index.ts

@@ -0,0 +1,63 @@
+// @yourrealm/sdk/worker-protocol/uplink — one uplink session and everything
+// that rides it: the Noise handshake over a WebSocket, the mux, the RPC
+// framing and the method catalogue.
+//
+// The layers below the session know nothing about Noise, WebSockets, Home or
+// workers: `Mux` and `Rpc` run over any `ByteDuplex` and own no timers.
+// `connectUplink` / `acceptUplink` are what join them to a socket.
+
+export { Mux } from "./mux.ts";
+export type { ByteDuplex, Limits, MuxSide, Stream } from "./mux.ts";
+export { jsonResponse, readJson, Rpc } from "./rpc.ts";
+export type { RpcHandler, RpcRequest, RpcResponse } from "./rpc.ts";
+export { acceptUplink, connectUplink } from "./session.ts";
+export type { SessionOptions, UplinkSession } from "./session.ts";
+export { decodePublicKey, encodePublicKey, parseEnrollmentToken } from "./identity.ts";
+export { PROTOCOL_VERSION } from "./protocol.ts";
+export {
+  APPLY_MESSAGE_MAX_CHARS,
+  appApplyResultSchema,
+  callJson,
+  callUiProxy,
+  ETAG_HEADER,
+  jsonHandler,
+  MethodError,
+  methods,
+  pullState,
+  UPDATE_ERROR_MAX_CHARS,
+  UPDATE_PROJECTS,
+  updateStatusSchema,
+} from "./methods.ts";
+export type {
+  AppApplyResult,
+  JsonMethod,
+  MethodName,
+  Params,
+  Result,
+  StatePull,
+  UiProxyResult,
+  UpdateProject,
+  UpdateStatus,
+} from "./methods.ts";
+export {
+  HomeKeyMismatch,
+  SessionClosed,
+  StreamReset,
+  UplinkError,
+  UplinkProtocolError,
+} from "./errors.ts";
+// The framing itself stays inside: callers get streams, not frames.
+export {
+  BACKOFF_BASE_MS,
+  BACKOFF_CAP_MS,
+  DEFAULT_LIMITS,
+  HANDSHAKE_TIMEOUT_MS,
+  IDLE_TIMEOUT_MS,
+  MAX_PAYLOAD_BYTES,
+  PING_INTERVAL_MS,
+  PONG_TIMEOUT_MS,
+  REKEY_INTERVAL_MS,
+  REKEY_JITTER_MS,
+  SOCKET_HIGH_WATER,
+  UPLINK_PROLOGUE,
+} from "./constants.ts";