@cortexkit/subc-client 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# @cortexkit/subc-client
+
+TypeScript client for the [subc](../../README.md) daemon. It speaks the same
+loopback-TCP transport as the Rust consumers (`subc-core`'s `subc-probe`),
+wire-compatible **byte-for-byte** with `subc-transport` (the HMAC-SHA256
+handshake) and `subc-protocol` (the 17-byte envelope and channel-0 control RPCs).
+
+Use it when a TypeScript/JavaScript process needs to reach a subc-routed module
+(e.g. a provider module exposing a tool surface or a management surface).
+
+## Install
+
+It ships as source (no build step) and runs on Bun or Node ≥ 18 — the only
+imports are `node:net`, `node:crypto`, and `node:fs`.
+
+```jsonc
+// from the subconscious monorepo
+"dependencies": { "@cortexkit/subc-client": "workspace:*" }
+```
+
+## Usage
+
+A consumer authenticates, optionally lists the catalog, opens a route to a
+target module, then issues requests on the returned route channel. There is no
+client `HELLO` — `HELLO` is module-registration only.
+
+```ts
+import { SubcClient } from "@cortexkit/subc-client";
+
+// The daemon publishes its connection file at $XDG_RUNTIME_DIR/subc-connection.json.
+const client = await SubcClient.connect({ connectionFile });
+
+// Optional: discover what is registered.
+const modules = await client.catalogList();
+
+// Open a route to a management-surface module and call it.
+const routeChannel = await client.routeOpen(
+  { kind: "management_surface", module_id: "ai-provider-quota" },
+  { project_root: process.cwd(), harness: "my-harness", session: "session-1" },
+);
+
+// request() resolves to the module's full Response body (the parsed JSON),
+// NOT an unwrapped field. A module decides its own response envelope; this one
+// wraps its array under `result`, so read `body.result`.
+const body = await client.request(routeChannel, { method: "usage.get", params: {} });
+const usage = body.result; // ProviderUsage[] for the ai-provider-quota module
+
+client.close();
+```
+
+`connect()` runs the full handshake before resolving: `ClientHello` →
+verify the server's proof **and** the daemon id from the connection file →
+`ClientAuth`. A wrong key, an impostor daemon, or a tampered connection file
+fails loud with an `AuthError` rather than connecting insecurely.
+
+### Routing notes
+
+- **Correlation, not order.** Every request carries a correlation id; replies are
+  matched by `(channel, corr)`, never by arrival order. subc may interleave a
+  control reply ahead of another exchange's response on the same connection.
+- **Priority.** Channel-0 control RPCs and data-plane requests are sent
+  `Interactive`. `request()` accepts `{ priority, timeoutMs, onProgress }`;
+  `onProgress` receives interim `Push`/`StreamData` frame bodies before the
+  terminal reply.
+- **Errors.** A module that returns a `FrameType::Error` frame surfaces as a
+  thrown `SubcError` carrying the canonical `{ code, message }`.
+- **Connection-file security.** On unix the file must be owner-only (`0600`); a
+  group/world-readable file is rejected, because the key has effectively leaked.
+
+## Testing
+
+```sh
+bun test          # 23 unit + 2 live-handshake
+```
+
+The live-handshake tests boot the real `subc-core` binary
+(`target/debug/subc-core`) and complete the handshake against it — the
+byte-identity authority for this client. They skip automatically when the binary
+is not built; run `cargo build -p subc-core` first (the CI lane does this).
+
+## Layout
+
+| File | Responsibility |
+| --- | --- |
+| `src/envelope.ts` | 17-byte header codec, frame types, flags, priority |
+| `src/connection-file.ts` | read + validate the daemon connection file (owner-only gate) |
+| `src/socket.ts` | buffered TCP socket with deadline-bounded `readExact` |
+| `src/auth.ts` | HMAC-SHA256 handshake (`computeProof`, constant-time verify) |
+| `src/client.ts` | `SubcClient`: handshake, channel-0 RPCs, `request()` corr-mux |

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@cortexkit/subc-client",
+  "version": "0.1.0",
+  "description": "TypeScript client for the subc daemon. Wire-compatible (byte-for-byte) with the Rust subc-transport handshake and subc-protocol envelope.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^22.0.0",
+    "bun-types": "^1.3.14",
+    "typescript": "^5.6.0"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,120 @@
+// Port of subc-transport's auth.rs client handshake. The proof construction,
+// domain strings, message framing, and verification order must match the Rust
+// byte-for-byte: a single byte of drift fails authentication outright.
+//
+// Handshake (client side):
+//   1. send ClientHello { client_nonce, role }
+//   2. receive ServerProof { daemon_id, server_nonce, daemon_ver, server_proof }
+//   3. verify server_proof == HMAC(key, "subc-server-v1" ‖ cn ‖ sn ‖ did)  (constant-time)
+//      and daemon_id == the id from the connection file
+//   4. send ClientAuth { client_auth = HMAC(key, "subc-client-v1" ‖ cn ‖ sn ‖ did) }
+//
+// Each message on the wire is a 4-byte little-endian length prefix followed by
+// the JSON body. Byte arrays (nonces, proofs, ids) serialize as JSON arrays of
+// numbers, matching serde's default for [u8; N].
+
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+import type { ConnectionInfo } from "./connection-file.js";
+import { SubcSocket } from "./socket.js";
+
+export const NONCE_LEN = 32;
+export const PROOF_LEN = 32;
+export const MAX_AUTH_MESSAGE_LEN = 4096;
+export const SERVER_PROOF_DOMAIN = "subc-server-v1";
+export const CLIENT_AUTH_DOMAIN = "subc-client-v1";
+export const DEFAULT_CLIENT_ROLE = "client";
+
+export class AuthError extends Error {}
+
+/** HMAC-SHA256 over domain ‖ client_nonce ‖ server_nonce ‖ daemon_id. */
+export function computeProof(
+  key: Uint8Array,
+  domain: string,
+  clientNonce: Uint8Array,
+  serverNonce: Uint8Array,
+  daemonId: Uint8Array,
+): Uint8Array {
+  const mac = createHmac("sha256", Buffer.from(key));
+  mac.update(Buffer.from(domain, "utf8"));
+  mac.update(Buffer.from(clientNonce));
+  mac.update(Buffer.from(serverNonce));
+  mac.update(Buffer.from(daemonId));
+  return new Uint8Array(mac.digest());
+}
+
+function constantTimeEq(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+
+async function writeMessage(
+  sock: SubcSocket,
+  value: unknown,
+  deadlineMs: number,
+): Promise<void> {
+  const json = Buffer.from(JSON.stringify(value), "utf8");
+  if (json.length > MAX_AUTH_MESSAGE_LEN) {
+    throw new AuthError(`auth message too large: ${json.length} > ${MAX_AUTH_MESSAGE_LEN}`);
+  }
+  const lenPrefix = new Uint8Array(4);
+  new DataView(lenPrefix.buffer).setUint32(0, json.length, true);
+  await sock.write(lenPrefix, deadlineMs);
+  await sock.write(json, deadlineMs);
+}
+
+async function readMessage<T>(sock: SubcSocket, deadlineMs: number): Promise<T> {
+  const lenBytes = await sock.readExact(4, deadlineMs);
+  const len = new DataView(lenBytes.buffer, lenBytes.byteOffset, 4).getUint32(0, true);
+  if (len > MAX_AUTH_MESSAGE_LEN) {
+    throw new AuthError(`auth message too large: ${len} > ${MAX_AUTH_MESSAGE_LEN}`);
+  }
+  const body = len === 0 ? new Uint8Array(0) : await sock.readExact(len, deadlineMs);
+  try {
+    return JSON.parse(Buffer.from(body).toString("utf8")) as T;
+  } catch (err) {
+    throw new AuthError(`auth message JSON decode failed: ${String(err)}`);
+  }
+}
+
+interface ServerProofMessage {
+  daemon_id: number[];
+  server_nonce: number[];
+  daemon_ver: string;
+  server_proof: number[];
+}
+
+/**
+ * Run the client handshake over an already-connected socket. Resolves on
+ * success; throws AuthError on any proof/identity mismatch or framing fault.
+ * The whole exchange is bounded by `deadlineMs` (epoch ms).
+ */
+export async function authenticateClient(
+  sock: SubcSocket,
+  conn: ConnectionInfo,
+  deadlineMs: number,
+): Promise<void> {
+  const clientNonce = new Uint8Array(randomBytes(NONCE_LEN));
+
+  await writeMessage(
+    sock,
+    { client_nonce: Array.from(clientNonce), role: DEFAULT_CLIENT_ROLE },
+    deadlineMs,
+  );
+
+  const proof = await readMessage<ServerProofMessage>(sock, deadlineMs);
+  const serverNonce = Uint8Array.from(proof.server_nonce);
+  const daemonId = Uint8Array.from(proof.daemon_id);
+  const serverProof = Uint8Array.from(proof.server_proof);
+
+  const expected = computeProof(conn.key, SERVER_PROOF_DOMAIN, clientNonce, serverNonce, daemonId);
+  if (!constantTimeEq(expected, serverProof)) {
+    throw new AuthError("server proof mismatch — wrong key or impostor daemon");
+  }
+  if (!constantTimeEq(daemonId, conn.daemonId)) {
+    throw new AuthError("daemon id mismatch — connection file points at a different daemon");
+  }
+
+  const clientAuth = computeProof(conn.key, CLIENT_AUTH_DOMAIN, clientNonce, serverNonce, daemonId);
+  await writeMessage(sock, { client_auth: Array.from(clientAuth) }, deadlineMs);
+}