@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/runtime/docker/home-proxy-server/index.ts

@@ -0,0 +1,177 @@
+// Worker-side `home-proxy.sock` broker. Binds a unix socket; a granted app
+// connects, sends one request line, and gets back one response line, relayed
+// to Home as an `apiAccess` call on the worker's uplink — the app container
+// holds no credential and reaches Home through nothing else.
+//
+// The broker owns the socket and the caller's identity: one socket per granted
+// app, and the `forward` the worker injects is bound to that app's id, so a
+// request's identity is the socket it arrived on and cannot be spelled by the
+// caller. Which surface of Home the sub-path lands on, and the fence that
+// keeps it there, are Home's — the worker builds no URL. The schema's literal
+// `..`/`//` reject (protocol.ts) stays as cheap input hygiene at the door.
+
+import { dirname } from "@std/path";
+import {
+  homeProxyRequestSchema,
+  type HomeProxyRequest,
+  type HomeProxyResponse,
+} from "./protocol.ts";
+
+// Caps the raw request line so a hostile caller can't exhaust memory before
+// the schema runs.
+const MAX_REQUEST_BYTES = 64 * 1024;
+// A caller must send its (small) request line within this window; bounds a
+// slow-loris that connects and stalls to pin a connection/fd.
+const REQUEST_READ_TIMEOUT_MS = 30 * 1000;
+// Per-request budget for the relay to Home. Aborts on expiry so a hung Home
+// can't pin the conn/fd forever.
+const FORWARD_TIMEOUT_MS = 30 * 1000;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+interface StartOpts {
+  /** Host path to bind this app's proxy socket at. Required — the worker
+   * passes the per-app `home-proxy/<appId>/home-proxy.sock` path (the socket
+   * sits alone in its own per-app dir; the server mkdirs the dir before
+   * binding). */
+  socketPath: string;
+  /**
+   * Relays one validated request to Home. The worker binds this to the
+   * `apiAccess` method with this socket's app id, so the identity travels with
+   * the closure rather than with anything the caller sent.
+   */
+  forward: (req: HomeProxyRequest) => Promise<HomeProxyResponse>;
+}
+
+interface ServerHandle {
+  /** Stop the server: close the listener, drop active conns, remove the socket file. */
+  stop(): Promise<void>;
+}
+
+export async function startHomeProxyServer(opts: StartOpts): Promise<ServerHandle> {
+  const socketPath = opts.socketPath;
+
+  // The socket lives alone in its own per-app directory: the app mounts the
+  // dir, not the socket file (a file bind-mount of a unix socket doesn't wire
+  // across containers on macOS Docker), and one socket per dir keeps an app
+  // from mounting a dir holding a sibling's socket.
+  await Deno.mkdir(dirname(socketPath), { recursive: true });
+  await Deno.remove(socketPath).catch(() => {});
+  const listener = Deno.listen({ transport: "unix", path: socketPath });
+  const conns = new Set<Deno.Conn>();
+
+  void acceptLoop(listener, conns, opts.forward);
+
+  return {
+    async stop() {
+      try {
+        listener.close();
+      } catch {}
+      for (const c of conns) {
+        try {
+          c.close();
+        } catch {}
+      }
+      conns.clear();
+      await Deno.remove(socketPath).catch(() => {});
+    },
+  };
+}
+
+type Forward = StartOpts["forward"];
+
+async function acceptLoop(
+  listener: Deno.Listener,
+  conns: Set<Deno.Conn>,
+  forward: Forward,
+): Promise<void> {
+  try {
+    for await (const conn of listener) {
+      conns.add(conn);
+      handleConnection(conn as Deno.UnixConn, forward).finally(() => {
+        conns.delete(conn);
+        try {
+          conn.close();
+        } catch {}
+      });
+    }
+  } catch {
+    // Listener was closed via stop().
+  }
+}
+
+// One connection == one request. Every caller/forward failure is turned
+// into a response line; nothing throws across the accept loop.
+async function handleConnection(conn: Deno.UnixConn, forward: Forward): Promise<void> {
+  const writer = conn.writable.getWriter();
+  let res: HomeProxyResponse;
+  try {
+    const raw = await withTimeout(
+      readRequest(conn),
+      REQUEST_READ_TIMEOUT_MS,
+      "home proxy request read timed out",
+    );
+    let req: HomeProxyRequest;
+    try {
+      req = homeProxyRequestSchema.parse(JSON.parse(raw));
+    } catch (err) {
+      // Bad shape or unsafe path: reject with 400, never forward.
+      res = { status: 400, body: { error: (err as Error).message ?? String(err) } };
+      await writeLine(writer, res).catch(() => {});
+      return;
+    }
+    // The uplink is down, or Home refused: either way the app gets a 502, the
+    // same answer it got when this hop was a fetch.
+    res = await withTimeout(forward(req), FORWARD_TIMEOUT_MS, "home proxy forward timed out");
+  } catch (err) {
+    res = { status: 502, body: { error: (err as Error).message ?? String(err) } };
+  }
+  await writeLine(writer, res).catch(() => {});
+  try {
+    writer.releaseLock();
+  } catch {}
+  try {
+    conn.close();
+  } catch {}
+}
+
+// Read one `\n`-terminated request line, bounded. Mirrors the spawn server.
+async function readRequest(conn: Deno.UnixConn): Promise<string> {
+  const buf = new Uint8Array(1);
+  const collected: number[] = [];
+  while (collected.length < MAX_REQUEST_BYTES) {
+    const n = await conn.read(buf);
+    if (n === null) break;
+    if (n === 0) continue;
+    if (buf[0] === 0x0a) break;
+    collected.push(buf[0]!);
+  }
+  if (collected.length >= MAX_REQUEST_BYTES) throw new Error("home proxy request too large");
+  const raw = decoder.decode(new Uint8Array(collected)).trim();
+  if (!raw) throw new Error("empty home proxy request");
+  return raw;
+}
+
+async function writeLine(
+  writer: WritableStreamDefaultWriter<Uint8Array>,
+  obj: HomeProxyResponse,
+): Promise<void> {
+  await writer.write(encoder.encode(JSON.stringify(obj) + "\n"));
+}
+
+// Race `p` against a wall-clock budget. The loser keeps running in the
+// background; the read's pending op unblocks when the conn closes.
+async function withTimeout<T>(p: Promise<T>, ms: number, message: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      p,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), ms);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/runtime/docker/home-proxy-server/protocol.ts

@@ -0,0 +1,53 @@
+// The `home-proxy.sock` wire contract. One newline-delimited JSON request
+// in, one newline-delimited JSON response out, mirroring `spawn.sock`.
+//
+// The app supplies only a *sub-path*: which surface of Home it lands on, and
+// the fence that keeps it there, are Home's — the worker relays the request as
+// an `apiAccess` call and builds no URL. This schema is cheap input hygiene at
+// the door: malformed shapes and literal `..`/`//`, not encoded traversal.
+
+import { z } from "zod";
+
+const MAX_PATH = 2048;
+
+// Path-segment + query charset only: letters, digits, `-._~`, `/`, and the
+// query chars `?=&%`. The absence of `:` and `\` means a sub-path can't
+// carry a scheme (`://`), an authority, or a windows separator; control
+// chars and spaces are excluded by the same allowlist.
+const SAFE_SUBPATH = /^\/[A-Za-z0-9._~/?=&%-]*$/;
+
+// Cheap pre-filter, NOT the security boundary (see the file header): catches
+// malformed shape + obvious literal traversal at the door. Encoded traversal
+// (`%2e%2e`) intentionally passes here and is caught by Home, which is the
+// side that resolves the path against a real URL.
+function isSafeSubPath(p: string): boolean {
+  if (!SAFE_SUBPATH.test(p)) return false; // leading "/" + charset
+  if (p.includes("..")) return false; // literal path traversal
+  if (p.includes("//")) return false; // empty segment / protocol-relative
+  return true;
+}
+
+/**
+ * One control-plane call: `method` + `path` + an optional JSON `body`, relayed
+ * to Home verbatim under the app id the socket belongs to.
+ */
+export const homeProxyRequestSchema = z
+  .object({
+    method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+    path: z.string().min(1).max(MAX_PATH).refine(isSafeSubPath, { message: "unsafe path" }),
+    body: z.unknown().optional(),
+  })
+  .strict();
+
+export type HomeProxyRequest = z.infer<typeof homeProxyRequestSchema>;
+export type HomeProxyMethod = HomeProxyRequest["method"];
+
+/** The single line the broker writes back: Home's status + parsed body. */
+export const homeProxyResponseSchema = z
+  .object({
+    status: z.number().int(),
+    body: z.unknown(),
+  })
+  .strict();
+
+export type HomeProxyResponse = z.infer<typeof homeProxyResponseSchema>;