@query-farm/vgi-rpc 0.6.4 → 0.7.1

package/src/http/token.ts

@@ -1,112 +1,210 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
-import { createHmac, timingSafeEqual } from "node:crypto";
+import { openBytes, SealError, sealBytes } from "../crypto.js";
 
-const TOKEN_VERSION = 2;
-const HMAC_LEN = 32;
-// 1 (version) + 8 (created_at) + 4*3 (three length prefixes) + 32 (hmac)
-const MIN_TOKEN_LEN = 1 + 8 + 12 + HMAC_LEN;
+const _UTF8 = new TextEncoder();
+
+const TOKEN_VERSION = 4;
+
+const AAD_PREFIX = _UTF8.encode("vgi_rpc.state.v4\0");
+
+/**
+ * Build the AEAD associated data that binds a state token to its issuing
+ * principal. Anonymous and authenticated tokens produce distinct AAD
+ * strings, so an anonymous token cannot be opened by a named identity
+ * (and vice versa).
+ */
+export function computeAad(principal: string | null | undefined): Uint8Array {
+  if (!principal) {
+    const tail = _UTF8.encode("\0anonymous");
+    return concatBytes(AAD_PREFIX, tail);
+  }
+  const pBytes = _UTF8.encode(principal);
+  const tail = new Uint8Array(1 + pBytes.length);
+  tail[0] = 0x01;
+  tail.set(pBytes, 1);
+  return concatBytes(AAD_PREFIX, tail);
+}
+
+// Base64 helpers — `btoa`/`atob` exist on Node 16+, Bun, and workerd; we work
+// in chunks to stay below the per-call argument limit (Latin-1 only, so we
+// move byte-by-byte through `String.fromCharCode`).
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  let s = "";
+  for (let i = 0; i < bytes.length; i += 0x8000) {
+    s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  }
+  return btoa(s);
+}
+
+export function base64ToBytes(b64: string): Uint8Array {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+// Little-endian writers/readers — Buffer was the previous abstraction; we now
+// touch DataView for portability across Node, Bun, and workerd.
+
+function writeU32LE(view: DataView, offset: number, value: number): void {
+  view.setUint32(offset, value, /* littleEndian */ true);
+}
+
+function writeU64LE(view: DataView, offset: number, value: bigint): void {
+  view.setBigUint64(offset, value, /* littleEndian */ true);
+}
+
+function readU32LE(view: DataView, offset: number): number {
+  return view.getUint32(offset, /* littleEndian */ true);
+}
+
+function readU64LE(view: DataView, offset: number): bigint {
+  return view.getBigUint64(offset, /* littleEndian */ true);
+}
+
+function concatBytes(...parts: Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const p of parts) total += p.length;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const p of parts) {
+    out.set(p, offset);
+    offset += p.length;
+  }
+  return out;
+}
 
 /**
- * Pack a state token matching the Python v2 wire format.
+ * Seal a state token with XChaCha20-Poly1305 AEAD (v4 wire format).
+ *
+ * Layout (base64-encoded):
+ *
+ * ```
+ *   [1B  version=4]
+ *   [24B XChaCha20-Poly1305 nonce (random)]
+ *   [..  ciphertext + 16B Poly1305 tag]
+ *        plaintext:
+ *          [8B  created_at uint64 LE]
+ *          [4B  state_len uint32 LE]   [state_len bytes]
+ *          [4B  schema_len uint32 LE]  [schema_len bytes]
+ *          [4B  input_schema_len LE]   [input_schema_len bytes]
+ * ```
  *
- * Layout:
- *   [1B version=2]
- *   [8B created_at uint64 LE (seconds since epoch)]
- *   [4B state_len uint32 LE] [state_len bytes]
- *   [4B schema_len uint32 LE] [schema_len bytes]
- *   [4B input_schema_len uint32 LE] [input_schema_len bytes]
- *   [32B HMAC-SHA256(signing_key, all above bytes)]
+ * `created_at` lives inside the ciphertext so TTL enforcement runs after
+ * authenticity. The version byte is informational (a self-describing
+ * format marker); a tampered version byte still fails decryption because
+ * we use the matching algorithm for that version. `principal` is bound
+ * via AEAD associated data so a token minted for one identity fails
+ * decryption when presented by another.
  */
 export function packStateToken(
   stateBytes: Uint8Array,
   schemaBytes: Uint8Array,
   inputSchemaBytes: Uint8Array,
-  signingKey: Uint8Array,
+  tokenKey: Uint8Array,
+  principal: string | null | undefined,
   createdAt?: number,
 ): string {
+  if (tokenKey.length !== 32) {
+    throw new Error("XChaCha20-Poly1305 token key must be 32 bytes");
+  }
   const now = createdAt ?? Math.floor(Date.now() / 1000);
 
-  const payloadLen = 1 + 8 + 4 + stateBytes.length + 4 + schemaBytes.length + 4 + inputSchemaBytes.length;
-  const buf = Buffer.alloc(payloadLen);
+  const plaintextLen = 8 + 4 + stateBytes.length + 4 + schemaBytes.length + 4 + inputSchemaBytes.length;
+  const plaintext = new Uint8Array(plaintextLen);
+  const view = new DataView(plaintext.buffer);
   let offset = 0;
 
-  // version
-  buf.writeUInt8(TOKEN_VERSION, offset);
-  offset += 1;
-
-  // created_at as uint64 LE
-  buf.writeBigUInt64LE(BigInt(now), offset);
+  writeU64LE(view, offset, BigInt(now));
   offset += 8;
 
-  // state
-  buf.writeUInt32LE(stateBytes.length, offset);
+  writeU32LE(view, offset, stateBytes.length);
   offset += 4;
-  buf.set(stateBytes, offset);
+  plaintext.set(stateBytes, offset);
   offset += stateBytes.length;
 
-  // output schema
-  buf.writeUInt32LE(schemaBytes.length, offset);
+  writeU32LE(view, offset, schemaBytes.length);
   offset += 4;
-  buf.set(schemaBytes, offset);
+  plaintext.set(schemaBytes, offset);
   offset += schemaBytes.length;
 
-  // input schema
-  buf.writeUInt32LE(inputSchemaBytes.length, offset);
+  writeU32LE(view, offset, inputSchemaBytes.length);
   offset += 4;
-  buf.set(inputSchemaBytes, offset);
-  offset += inputSchemaBytes.length;
+  plaintext.set(inputSchemaBytes, offset);
 
-  // HMAC
-  const mac = createHmac("sha256", signingKey).update(buf).digest();
-  const token = Buffer.concat([buf, mac]);
-
-  return token.toString("base64");
+  const wire = sealBytes(plaintext, tokenKey, { aad: computeAad(principal), version: TOKEN_VERSION });
+  return bytesToBase64(wire);
 }
 
+/** Decrypted payload of a state token, as returned by {@link unpackStateToken}. */
 export interface UnpackedToken {
+  /** Serialized stream-state bytes carried by the token. */
   stateBytes: Uint8Array;
+  /** Serialized output-schema IPC bytes. */
   schemaBytes: Uint8Array;
+  /** Serialized input-schema IPC bytes (exchange streams). */
   inputSchemaBytes: Uint8Array;
+  /** Unix epoch seconds at which the token was minted (used for TTL checks). */
   createdAt: number;
 }
 
 /**
- * Unpack and verify a state token.
- * Throws on tampered, expired, or malformed tokens.
+ * Open and verify a state token. Decryption (which checks the Poly1305
+ * tag) authenticates the payload; any tampering, wrong key, or AAD
+ * mismatch (e.g. cross-principal replay) surfaces as a uniform
+ * "signature verification failed" error so callers cannot distinguish
+ * failure modes via timing or message content.
+ *
+ * Throws on tampered, expired, malformed, or unknown-version tokens.
  */
-export function unpackStateToken(tokenBase64: string, signingKey: Uint8Array, tokenTtl: number): UnpackedToken {
-  const token = Buffer.from(tokenBase64, "base64");
-
-  if (token.length < MIN_TOKEN_LEN) {
-    throw new Error("State token too short");
+export function unpackStateToken(
+  tokenBase64: string,
+  tokenKey: Uint8Array,
+  tokenTtl: number,
+  principal: string | null | undefined,
+): UnpackedToken {
+  let raw: Uint8Array;
+  try {
+    raw = base64ToBytes(tokenBase64);
+  } catch {
+    throw new Error("Malformed state token");
   }
-
-  // Split payload and mac
-  const payload = token.subarray(0, token.length - HMAC_LEN);
-  const receivedMac = token.subarray(token.length - HMAC_LEN);
-
-  // Verify HMAC first (before inspecting any fields)
-  const expectedMac = createHmac("sha256", signingKey).update(payload).digest();
-  if (!timingSafeEqual(receivedMac, expectedMac)) {
-    throw new Error("State token HMAC verification failed");
+  // Pre-check the envelope version separately so callers can distinguish
+  // "wrong format" from "tampered". Mirrors the pre-refactor error shape.
+  if (raw.length >= 1 && raw[0] !== TOKEN_VERSION) {
+    throw new Error(`Unsupported state token version: ${raw[0]}`);
+  }
+  let plaintext: Uint8Array;
+  try {
+    plaintext = openBytes(raw, tokenKey, { aad: computeAad(principal), version: TOKEN_VERSION });
+  } catch (err) {
+    if (err instanceof SealError) {
+      throw new Error("State token signature verification failed");
+    }
+    throw err;
+  }
+  if (plaintext.length < 8) {
+    throw new Error("State token truncated");
   }
 
+  // Copy each bytes section into a freshly-allocated Uint8Array with
+  // byteOffset=0. arrow-js's schema deserializer wraps the result as Int32Array
+  // and throws 'RangeError: Byte offset is not aligned' if the slice happens
+  // to start at a non-4-aligned offset. Copying normalizes the alignment.
+  const view = new DataView(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength);
   let offset = 0;
+  const copyAligned = (start: number, len: number) => {
+    const out = new Uint8Array(len);
+    out.set(plaintext.subarray(start, start + len));
+    return out;
+  };
 
-  // Version
-  const version = payload.readUInt8(offset);
-  offset += 1;
-  if (version !== TOKEN_VERSION) {
-    throw new Error(`Unsupported state token version: ${version}`);
-  }
-
-  // created_at
-  const createdAt = Number(payload.readBigUInt64LE(offset));
+  const createdAt = Number(readU64LE(view, offset));
   offset += 8;
 
-  // TTL check
   if (tokenTtl > 0) {
     const now = Math.floor(Date.now() / 1000);
     if (now - createdAt > tokenTtl) {
@@ -114,31 +212,28 @@ export function unpackStateToken(tokenBase64: string, signingKey: Uint8Array, to
     }
   }
 
-  // state bytes
-  const stateLen = payload.readUInt32LE(offset);
+  const stateLen = readU32LE(view, offset);
   offset += 4;
-  if (offset + stateLen > payload.length) {
+  if (offset + stateLen > plaintext.length) {
     throw new Error("State token truncated (state)");
   }
-  const stateBytes = payload.slice(offset, offset + stateLen);
+  const stateBytes = copyAligned(offset, stateLen);
   offset += stateLen;
 
-  // output schema bytes
-  const schemaLen = payload.readUInt32LE(offset);
+  const schemaLen = readU32LE(view, offset);
   offset += 4;
-  if (offset + schemaLen > payload.length) {
+  if (offset + schemaLen > plaintext.length) {
     throw new Error("State token truncated (schema)");
   }
-  const schemaBytes = payload.slice(offset, offset + schemaLen);
+  const schemaBytes = copyAligned(offset, schemaLen);
   offset += schemaLen;
 
-  // input schema bytes
-  const inputSchemaLen = payload.readUInt32LE(offset);
+  const inputSchemaLen = readU32LE(view, offset);
   offset += 4;
-  if (offset + inputSchemaLen > payload.length) {
+  if (offset + inputSchemaLen > plaintext.length) {
     throw new Error("State token truncated (input schema)");
   }
-  const inputSchemaBytes = payload.slice(offset, offset + inputSchemaLen);
+  const inputSchemaBytes = copyAligned(offset, inputSchemaLen);
 
   return { stateBytes, schemaBytes, inputSchemaBytes, createdAt };
 }

package/src/http/types.ts

@@ -1,16 +1,18 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
-import type { ExternalLocationConfig } from "../external.js";
-import type { DispatchHook } from "../types.js";
+import type { ExternalLocationConfig, UploadUrlProvider } from "../external.js";
+import type { DispatchHook, ServeStartHook } from "../types.js";
 import type { AuthenticateFn, OAuthResourceMetadata } from "./auth.js";
 
 /** Configuration options for createHttpHandler(). */
 export interface HttpHandlerOptions {
   /** URL path prefix for all endpoints. Default: "" (root). */
   prefix?: string;
-  /** HMAC-SHA256 signing key for state tokens. Random 32 bytes if omitted. */
-  signingKey?: Uint8Array;
+  /** XChaCha20-Poly1305 master key (32 bytes) used to seal stream state
+   *  tokens.  A random 32-byte key is generated if omitted (tokens won't
+   *  survive a restart or load-balance across workers). */
+  tokenKey?: Uint8Array;
   /** State token time-to-live in seconds. Default: 3600 (1 hour). 0 disables TTL checks. */
   tokenTtl?: number;
   /** CORS allowed origins. If set, CORS headers are added to all responses. */
@@ -19,8 +21,29 @@ export interface HttpHandlerOptions {
   corsMaxAge?: number | null;
   /** Maximum request body size in bytes. Advertised via VGI-Max-Request-Bytes header. */
   maxRequestBytes?: number;
-  /** Maximum bytes before a producer stream emits a continuation token. */
+  /** Cap on the post-decompression size of a `Content-Encoding: zstd`
+   *  request body, in bytes.  Defends against zstd decompression bombs:
+   *  a tiny compressed frame can declare a huge decompressed size and
+   *  blow up the server before {@link maxRequestBytes} ever sees the
+   *  payload.  When omitted, defaults to `maxRequestBytes * 16` if that
+   *  is set, otherwise unbounded. */
+  maxDecompressedRequestBytes?: number;
+  /** Maximum bytes before a producer stream emits a continuation token.
+   *
+   * @deprecated Use {@link maxResponseBytes} instead. The cap now governs all
+   *  HTTP method responses (unary, exchange, producer), not just producer streams.
+   */
   maxStreamResponseBytes?: number;
+  /** HTTP body cap. Hard for unary and stream-exchange (overshoot surfaces
+   *  as 200 + X-VGI-RPC-Error EXCEPTION batch). Soft for producer streams
+   *  (overshoot mints a continuation token). Externalised payloads do not
+   *  count toward this — they leave only tiny pointer batches on the wire.
+   *  Advertised via VGI-Max-Response-Bytes.  Undefined = unbounded. */
+  maxResponseBytes?: number;
+  /** Cap on bytes uploaded to external storage during one HTTP response.
+   *  Always hard — externalised uploads have no escape valve. Advertised via
+   *  VGI-Max-Externalized-Response-Bytes.  Undefined = unbounded. */
+  maxExternalizedResponseBytes?: number;
   /** Server ID included in response metadata. Random if omitted. */
   serverId?: string;
   /** Custom state serializer for stream state objects. Default: JSON with BigInt support. */
@@ -34,23 +57,64 @@ export interface HttpHandlerOptions {
   oauthResourceMetadata?: OAuthResourceMetadata;
   /** Optional dispatch hook for observability (tracing, metrics). */
   dispatchHook?: DispatchHook;
+  /** Optional lifecycle hook fired once on the first dispatched request.
+   *  Mirrors Python's on_serve_start; lazy-firing keeps it fork-safe for
+   *  pre-fork servers. */
+  onServeStart?: ServeStartHook;
   /** Enable HTML landing page at GET {prefix}/. Default: true. */
   enableLandingPage?: boolean;
   /** Enable HTML describe/API reference page at GET {prefix}/describe. Default: true. */
   enableDescribePage?: boolean;
   /** Enable HTML 404 page for unmatched GET routes. Default: true. */
   enableNotFoundPage?: boolean;
+  /** Enable JSON health endpoint at GET {prefix}/health. Default: true. */
+  enableHealthEndpoint?: boolean;
   /** Protocol name shown in HTML pages. Defaults to the Protocol's name. */
   protocolName?: string;
+  /** Operator-supplied protocol-contract version label, surfaced on every
+   *  access-log record so dashboards and alerts can key off contract
+   *  changes.  Mirrors the Python `RpcServer(..., protocol_version=...)`
+   *  argument. */
+  protocolVersion?: string;
   /** URL to service's source repository, shown in landing/describe pages. */
   repositoryUrl?: string;
   /** External storage config for externalizing large response batches. */
   externalLocation?: ExternalLocationConfig;
+  /** Provider for vending pre-signed upload URLs to clients via {prefix}/__upload_url__/init. */
+  uploadUrlProvider?: UploadUrlProvider;
+  /** Optional advertised maximum upload size, surfaced via VGI-Max-Upload-Bytes. */
+  maxUploadBytes?: number;
+  /** OAuth scope for PKCE authorization requests. Default: "openid email". */
+  oauthPkceScope?: string;
+  /** Allowed return-to origins for external frontend redirects. Default: Set(["https://cupola.query-farm.services"]). */
+  allowedReturnOrigins?: ReadonlySet<string>;
+
+  /** Enable opt-in sticky sessions on this HTTP handler. When enabled the
+   *  server advertises `VGI-Sticky-Enabled: true` (capability discovery),
+   *  honours `VGI-Session` / `VGI-Session-Accept` headers, and exposes a
+   *  `DELETE {prefix}/__session__` teardown endpoint. Default: false. */
+  enableSticky?: boolean;
+  /** Default session TTL in seconds when `ctx.openSession` is called without
+   *  an explicit `ttl` override. Default: 300. */
+  stickyDefaultTtl?: number;
+  /** Headers the server emits as `VGI-Echo-<name>: <value>` on the
+   *  session-opening response. A conformant client captures them and replays
+   *  them on every subsequent request in the session — used for
+   *  client-driven routing (e.g. `fly-force-instance-id` on Fly.io). */
+  stickyEchoHeaders?: Record<string, string>;
+  /** Internal — invoked once at handler creation with a {@link DrainHandle}
+   *  when sticky is enabled. Conformance fixtures use this to wire up the
+   *  test-only `/__test_drain__` admin endpoint without the library
+   *  exposing the registry directly. Production code should hold the
+   *  handle returned by a future `createHttpHandlerWithDrainHandle` helper. */
+  _onStickyHandle?: (handle: import("./sticky.js").DrainHandle) => void;
 }
 
 /** Serializer for stream state objects stored in state tokens. */
 export interface StateSerializer {
+  /** Encode a stream-state object into the bytes sealed inside a state token. */
   serialize(state: any): Uint8Array;
+  /** Decode the bytes recovered from a state token back into a state object. */
   deserialize(bytes: Uint8Array): any;
 }
 

package/src/index.ts

@@ -1,12 +1,14 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
+export { AccessLogHook, type AccessLogSink, FdSink } from "./access-log.js";
 export { AuthContext } from "./auth.js";
 export * from "./client/index.js";
 export {
   DESCRIBE_METHOD_NAME,
   DESCRIBE_VERSION,
   DESCRIBE_VERSION_KEY,
+  ERROR_KIND_KEY,
   LOG_EXTRA_KEY,
   LOG_LEVEL_KEY,
   LOG_MESSAGE_KEY,
@@ -14,11 +16,21 @@ export {
   REQUEST_ID_KEY,
   REQUEST_VERSION,
   REQUEST_VERSION_KEY,
+  RPC_ERROR_HEADER,
   RPC_METHOD_KEY,
   SERVER_ID_KEY,
   STATE_KEY,
 } from "./constants.js";
-export { RpcError, VersionError } from "./errors.js";
+export {
+  ERROR_KIND_METHOD_NOT_IMPLEMENTED,
+  ERROR_KIND_SERVER_DRAINING,
+  ERROR_KIND_SESSION_LOST,
+  MethodNotImplementedError,
+  RpcError,
+  ServerDrainingError,
+  SessionLostError,
+  VersionError,
+} from "./errors.js";
 export {
   type ExternalLocationConfig,
   type ExternalStorage,
@@ -54,6 +66,25 @@ export {
   type XfccElement,
   type XfccValidateFn,
 } from "./http/index.js";
+export {
+  acquireLock,
+  computeHash as launcherComputeHash,
+  defaultStateDir,
+  type FileLockHandle,
+  type GcResult,
+  gcStateDir,
+  type LaunchConfig,
+  launch,
+  probeSocket,
+  type ServeUnixHandle,
+  type ServeUnixOptions,
+  type SocketPaths,
+  type StatusRow,
+  serveUnix,
+  socketPaths,
+  statusRows,
+  tryAcquireLock,
+} from "./launcher/index.js";
 export { Protocol } from "./protocol.js";
 export {
   bool,
@@ -62,10 +93,16 @@ export {
   float32,
   inferParamTypes,
   int,
+  int8,
+  int16,
   int32,
   type SchemaLike,
   str,
   toSchema,
+  uint8,
+  uint16,
+  uint32,
+  uint64,
 } from "./schema.js";
 export { VgiRpcServer } from "./server.js";
 export {
@@ -83,5 +120,7 @@ export {
   OutputCollector,
   type ProducerFn,
   type ProducerInit,
+  type ServeStartHook,
+  TransportKind,
   type UnaryHandler,
 } from "./types.js";

package/src/launcher/hash.ts

@@ -0,0 +1,104 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Hash a worker tuple (argv + cwd + filtered env) into a deterministic
+ * 16-hex-character identifier.
+ *
+ * Cross-language contract — must match Python's `vgi_rpc.launcher.compute_hash`
+ * byte-for-byte so the same worker tuple resolves to the same socket path
+ * regardless of which language's launcher discovered it first.  The
+ * canonical form is:
+ *
+ * ```python
+ * canonical = {
+ *     "cmd": list(worker_argv),
+ *     "cwd": cwd if cwd is not None else os.getcwd(),
+ *     "env": {k: v for k, v in sorted(os.environ.items()) if k.startswith("VGI_RPC_")},
+ * }
+ * payload = json.dumps(canonical, sort_keys=True, separators=(",", ":")).encode("utf-8")
+ * sha256(payload).hexdigest()[:16]
+ * ```
+ *
+ * `scripts/regenerate_launcher_parity_vectors.py` in vgi-rpc-python emits a
+ * golden vector table; the parity test in `test/launcher.hash.test.ts`
+ * asserts byte equality against it.
+ */
+
+const HASH_LEN = 16;
+
+/** Recursively stringify with sorted object keys and `,`/`:` separators —
+ *  the JS equivalent of `json.dumps(..., sort_keys=True, separators=(",",":"))`.
+ *  We can't reuse `JSON.stringify` because the V8 implementation preserves
+ *  insertion order rather than sorting. */
+function canonicalJson(value: unknown): string {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") {
+    // Python json emits integers without a trailing `.0` and floats with the
+    // shortest round-trippable form. JS `JSON.stringify` matches this for
+    // both integer-valued and finite floats; `Infinity`/`NaN` would diverge
+    // (Python raises) but they shouldn't occur in launcher payloads.
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const keys = Object.keys(value as Record<string, unknown>).sort();
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalJson((value as Record<string, unknown>)[k])}`);
+    return `{${parts.join(",")}}`;
+  }
+  throw new TypeError(`canonicalJson: unsupported type ${typeof value}`);
+}
+
+async function sha256Hex(data: Uint8Array): Promise<string> {
+  // Web Crypto digest accepts BufferSource; copy into a fresh ArrayBuffer
+  // to dodge SharedArrayBuffer constraints in some runtimes.
+  const buf = new ArrayBuffer(data.byteLength);
+  new Uint8Array(buf).set(data);
+  const digest = await crypto.subtle.digest("SHA-256", buf);
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Compute the 16-hex-char tuple hash for a worker.
+ *
+ * @param workerArgv The worker command and its arguments.
+ * @param cwd        Working directory; defaults to `process.cwd()`.
+ * @param env        Process environment; defaults to `process.env`.  Only
+ *                   keys starting with `VGI_RPC_` participate in the hash —
+ *                   workers that differ only in unrelated env (PATH,
+ *                   HOME, …) intentionally share a worker.
+ */
+export async function computeHash(
+  workerArgv: readonly string[],
+  cwd?: string,
+  env?: Record<string, string | undefined>,
+): Promise<string> {
+  const cwdValue = cwd !== undefined ? cwd : process.cwd();
+  const sourceEnv = env ?? (process.env as Record<string, string | undefined>);
+
+  const filteredEnv: Record<string, string> = {};
+  for (const key of Object.keys(sourceEnv)) {
+    if (key.startsWith("VGI_RPC_")) {
+      const v = sourceEnv[key];
+      if (v !== undefined) filteredEnv[key] = v;
+    }
+  }
+
+  const canonical = {
+    cmd: [...workerArgv],
+    cwd: cwdValue,
+    env: filteredEnv,
+  };
+  const payload = new TextEncoder().encode(canonicalJson(canonical));
+  const hex = await sha256Hex(payload);
+  return hex.slice(0, HASH_LEN);
+}
+
+/** Exposed for parity-test fixtures that need to inspect the canonical form. */
+export const _internal = { canonicalJson };

package/src/launcher/index.ts

@@ -0,0 +1,35 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * AF_UNIX worker launcher — TypeScript port of `vgi_rpc.launcher`.
+ *
+ * Two halves:
+ *
+ * - **Coordination** ({@link launch}, {@link computeHash}, {@link gcStateDir},
+ *   {@link statusRows}): spawn-or-reuse a long-running worker process for a
+ *   given command tuple, returning the AF_UNIX socket path the caller
+ *   should connect to.  Hash and on-disk layout match the Python
+ *   implementation byte-for-byte so workers in any language under the
+ *   same tuple resolve to the same socket.
+ *
+ * - **Worker runner** ({@link serveUnix}): bind a Unix socket and serve a
+ *   {@link Protocol} via per-connection IPC streams.  Implements the
+ *   `--unix PATH` / `--idle-timeout SEC` / `UNIX:<path>` contract so
+ *   launchers (Python or TS) can spawn TS workers transparently.
+ */
+
+export { computeHash } from "./hash.js";
+export { type LaunchConfig, launch } from "./launch.js";
+export { acquireLock, type FileLockHandle, tryAcquireLock } from "./lock.js";
+export { type ServeUnixHandle, type ServeUnixOptions, serveUnix } from "./serve-unix.js";
+export {
+  defaultStateDir,
+  type GcResult,
+  gcStateDir,
+  probeSocket,
+  type SocketPaths,
+  type StatusRow,
+  socketPaths,
+  statusRows,
+} from "./state.js";