@cortexkit/subc-client 0.1.0

package/src/connection-file.ts

@@ -0,0 +1,109 @@
+// Port of subc-transport's connection_file.rs reader. The connection file is
+// the daemon's published rendezvous record; its `key` is the shared transport
+// secret. We refuse to trust a key from a file other local users can read,
+// exactly as the Rust reader does, so a leaked (group/world-readable) key is a
+// loud failure rather than a silent downgrade.
+
+import { promises as fs } from "node:fs";
+
+export const SCHEMA_VERSION = 1;
+export const MIN_KEY_LEN = 32;
+export const DAEMON_ID_LEN = 16;
+
+export interface Endpoint {
+  host: string;
+  port: number;
+}
+
+export interface ConnectionInfo {
+  schema: number;
+  endpoints: Endpoint[];
+  /** Transport key bytes. Serialized on disk as a JSON array of numbers. */
+  key: Uint8Array;
+  /** 16-byte daemon identity. Serialized on disk as a JSON array of numbers. */
+  daemonId: Uint8Array;
+  pid: number;
+  daemonVer: string;
+}
+
+export class ConnectionFileError extends Error {}
+
+function toBytes(value: unknown, field: string): Uint8Array {
+  if (!Array.isArray(value) || value.some((n) => typeof n !== "number")) {
+    throw new ConnectionFileError(`connection file field '${field}' must be a JSON array of bytes`);
+  }
+  return Uint8Array.from(value as number[]);
+}
+
+function validate(info: ConnectionInfo): void {
+  if (info.schema !== SCHEMA_VERSION) {
+    throw new ConnectionFileError(
+      `unsupported connection file schema ${info.schema}; expected ${SCHEMA_VERSION}`,
+    );
+  }
+  if (info.endpoints.length === 0) {
+    throw new ConnectionFileError("connection file must include at least one endpoint");
+  }
+  if (info.key.length < MIN_KEY_LEN) {
+    throw new ConnectionFileError(
+      `connection file key is too short: ${info.key.length} bytes, need at least ${MIN_KEY_LEN}`,
+    );
+  }
+  if (info.daemonId.length !== DAEMON_ID_LEN) {
+    throw new ConnectionFileError(
+      `connection file daemon_id must be ${DAEMON_ID_LEN} bytes, got ${info.daemonId.length}`,
+    );
+  }
+}
+
+/**
+ * On unix, reject any group/other permission bit: the key is published
+ * owner-only (0600), so a wider mode means the secret has leaked. On Windows the
+ * file inherits the per-user profile directory ACL at create time and there are
+ * no portable mode bits to re-check, matching the Rust no-op.
+ */
+async function verifyOwnerOnly(path: string): Promise<void> {
+  if (process.platform === "win32") return;
+  const stat = await fs.stat(path);
+  const mode = stat.mode & 0o777;
+  if ((mode & 0o077) !== 0) {
+    throw new ConnectionFileError(
+      `connection file ${path} has insecure permissions 0o${mode.toString(8)}; expected owner-only 0600`,
+    );
+  }
+}
+
+/** Read, permission-check, and validate a connection file. */
+export async function readConnectionFile(path: string): Promise<ConnectionInfo> {
+  await verifyOwnerOnly(path);
+  const raw = await fs.readFile(path, "utf8");
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(raw) as Record<string, unknown>;
+  } catch (err) {
+    throw new ConnectionFileError(`connection file JSON read failed for ${path}: ${String(err)}`);
+  }
+
+  const endpointsRaw = parsed.endpoints;
+  if (!Array.isArray(endpointsRaw)) {
+    throw new ConnectionFileError("connection file 'endpoints' must be an array");
+  }
+  const endpoints: Endpoint[] = endpointsRaw.map((e) => {
+    const ep = e as Record<string, unknown>;
+    if (typeof ep.host !== "string" || typeof ep.port !== "number") {
+      throw new ConnectionFileError("connection file endpoint must be { host: string, port: number }");
+    }
+    return { host: ep.host, port: ep.port };
+  });
+
+  const info: ConnectionInfo = {
+    schema: parsed.schema as number,
+    endpoints,
+    key: toBytes(parsed.key, "key"),
+    daemonId: toBytes(parsed.daemon_id, "daemon_id"),
+    pid: parsed.pid as number,
+    daemonVer: (parsed.daemon_ver as string) ?? "",
+  };
+  validate(info);
+  return info;
+}

package/src/envelope.ts

@@ -0,0 +1,168 @@
+// Byte-for-byte port of subc-protocol's 17-byte envelope header.
+// Source of truth: crates/subc-protocol/src/lib.rs. Keep field offsets, the
+// little-endian encoding, and the frame-type/flag numbering in lock-step with
+// the Rust; a one-byte drift here desynchronizes every frame on the wire.
+
+export const PROTOCOL_VERSION = 1;
+export const HEADER_LEN = 17;
+export const FROZEN_PREFIX_LEN = 5;
+export const MAX_FRAME_BODY_LEN = 64 * 1024 * 1024;
+
+/** `type` byte at offset 5. */
+export enum FrameType {
+  Request = 0,
+  Response = 1,
+  Push = 2,
+  StreamData = 3,
+  StreamEnd = 4,
+  Error = 5,
+  Cancel = 6,
+  Ping = 7,
+  Pong = 8,
+  Hello = 9,
+  HelloAck = 10,
+  Goodbye = 11,
+}
+
+const FRAME_TYPE_MAX = FrameType.Goodbye;
+
+/** Cancel/Ping/Pong/Goodbye carry only a header (`len` must be 0). */
+export function isPureHeader(ty: FrameType): boolean {
+  return (
+    ty === FrameType.Cancel ||
+    ty === FrameType.Ping ||
+    ty === FrameType.Pong ||
+    ty === FrameType.Goodbye
+  );
+}
+
+/** Scheduling priority carried in flags bits 1-2. */
+export enum Priority {
+  Passive = 0,
+  Interactive = 1,
+  Background = 2,
+}
+
+const FLAG_BINARY = 0b0000_0001; // bit 0
+const FLAG_PRIORITY_MASK = 0b0000_0110; // bits 1-2
+const FLAG_PRIORITY_SHIFT = 1;
+const FLAG_LAST = 0b0000_1000; // bit 3
+const FLAG_RESERVED_MASK = 0b1111_0000; // bits 4-7 must be zero
+
+/** Build the flags byte from typed components (mirrors Flags::new). */
+export function buildFlags(binary: boolean, priority: Priority, last: boolean): number {
+  let b = 0;
+  if (binary) b |= FLAG_BINARY;
+  b |= priority << FLAG_PRIORITY_SHIFT;
+  if (last) b |= FLAG_LAST;
+  return b;
+}
+
+export interface EnvelopeHeader {
+  len: number;
+  ver: number;
+  ty: FrameType;
+  flags: number;
+  channel: number;
+  corr: bigint;
+}
+
+export interface Frame {
+  header: EnvelopeHeader;
+  body: Uint8Array;
+}
+
+/** Serialize a header to its fixed 17-byte little-endian form. */
+export function encodeHeader(h: EnvelopeHeader): Uint8Array {
+  const buf = new Uint8Array(HEADER_LEN);
+  const view = new DataView(buf.buffer);
+  view.setUint32(0, h.len, true);
+  buf[4] = h.ver;
+  buf[5] = h.ty;
+  buf[6] = h.flags;
+  view.setUint16(7, h.channel, true);
+  view.setBigUint64(9, h.corr, true);
+  return buf;
+}
+
+export class DecodeError extends Error {}
+
+/**
+ * Decode a header from the front of `bytes`, following the frozen-prefix
+ * discipline: need 5 bytes for len+ver, dispatch full header length on ver,
+ * then validate. Mirrors decode_header — never throws on a structurally short
+ * buffer beyond the typed DecodeError.
+ */
+export function decodeHeader(bytes: Uint8Array): EnvelopeHeader {
+  if (bytes.length < FROZEN_PREFIX_LEN) {
+    throw new DecodeError(`header shorter than frozen prefix: have ${bytes.length} bytes`);
+  }
+  const ver = bytes[4]!;
+  if (ver !== PROTOCOL_VERSION) {
+    throw new DecodeError(`unsupported envelope version ${ver}`);
+  }
+  if (bytes.length < HEADER_LEN) {
+    throw new DecodeError(`header too short for version: have ${bytes.length} bytes, need ${HEADER_LEN}`);
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const len = view.getUint32(0, true);
+  const tyByte = bytes[5]!;
+  if (tyByte > FRAME_TYPE_MAX) {
+    throw new DecodeError(`unknown frame type byte ${tyByte}`);
+  }
+  const ty = tyByte as FrameType;
+  const flags = bytes[6]!;
+  if ((flags & FLAG_RESERVED_MASK) !== 0) {
+    throw new DecodeError(`reserved flag bits set in flags 0b${flags.toString(2)}`);
+  }
+  if (((flags & FLAG_PRIORITY_MASK) >> FLAG_PRIORITY_SHIFT) === 0b11) {
+    throw new DecodeError(`reserved priority bits set in flags 0b${flags.toString(2)}`);
+  }
+  if (isPureHeader(ty) && len !== 0) {
+    throw new DecodeError(`pure-header frame ${FrameType[ty]} declared non-zero body length ${len}`);
+  }
+  const channel = view.getUint16(7, true);
+  const corr = view.getBigUint64(9, true);
+  return { len, ver, ty, flags, channel, corr };
+}
+
+/** Build a full current-version frame, enforcing the body-length cap and the pure-header rule. */
+export function buildFrame(
+  ty: FrameType,
+  flags: number,
+  channel: number,
+  corr: bigint,
+  body: Uint8Array,
+): Frame {
+  return buildFrameWithVersion(PROTOCOL_VERSION, ty, flags, channel, corr, body);
+}
+
+/** Build a full frame while preserving a peer-negotiated envelope version. */
+export function buildFrameWithVersion(
+  ver: number,
+  ty: FrameType,
+  flags: number,
+  channel: number,
+  corr: bigint,
+  body: Uint8Array,
+): Frame {
+  if (body.length > MAX_FRAME_BODY_LEN) {
+    throw new DecodeError(`frame body ${body.length} exceeds max ${MAX_FRAME_BODY_LEN}`);
+  }
+  if (isPureHeader(ty) && body.length !== 0) {
+    throw new DecodeError(`pure-header frame ${FrameType[ty]} cannot carry a body`);
+  }
+  return {
+    header: { len: body.length, ver, ty, flags, channel, corr },
+    body,
+  };
+}
+
+/** Encode a frame to wire bytes: 17-byte header followed by `len` body bytes. */
+export function encodeFrame(frame: Frame): Uint8Array {
+  const header = encodeHeader(frame.header);
+  const out = new Uint8Array(header.length + frame.body.length);
+  out.set(header, 0);
+  out.set(frame.body, header.length);
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+export {
+  SubcClient,
+  SubcError,
+  SubcCallError,
+  DEFAULT_RECONNECT_BACKOFF,
+  isConsumerReconnectTransient,
+  connectionFileExists,
+  type BindIdentity,
+  type RouteTarget,
+  type ManagedRouteKind,
+  type CatalogEntry,
+  type RequestOptions,
+  type ManagedCallOptions,
+  type ConnectOptions,
+  type ReconnectBackoff,
+  type SubcCallErrorKind,
+  type SubscribeOptions,
+  type Subscription,
+  type CloseRouteOptions,
+} from "./client.js";
+export {
+  readConnectionFile,
+  ConnectionFileError,
+  type ConnectionInfo,
+  type Endpoint,
+} from "./connection-file.js";
+export {
+  FrameType,
+  Priority,
+  PROTOCOL_VERSION,
+  HEADER_LEN,
+  buildFrame,
+  buildFrameWithVersion,
+  buildFlags,
+  encodeFrame,
+  decodeHeader,
+  encodeHeader,
+  DecodeError,
+  type Frame,
+  type EnvelopeHeader,
+} from "./envelope.js";
+export {
+  authenticateClient,
+  computeProof,
+  AuthError,
+  NONCE_LEN,
+  PROOF_LEN,
+  SERVER_PROOF_DOMAIN,
+  CLIENT_AUTH_DOMAIN,
+} from "./auth.js";
+export { SubcSocket, SocketClosedError, SocketTimeoutError } from "./socket.js";
+export {
+  SubcProvider,
+  SubcProviderError,
+  HELLO_CORR,
+  managementSurfaceManifest,
+  jsonProviderHandler,
+  type ProviderRequestContext,
+  type BindDecision,
+  type BindingsInput,
+  type CircuitBreakerInput,
+  type Concurrency,
+  type ConsumerRoleInput,
+  type ExecutionMode,
+  type IdentityBindingInput,
+  type IdentityScope,
+  type InternalTransport,
+  type LeaseScope,
+  type ManagementOperationInput,
+  type ManagementOperationKind,
+  type ManagementSurfaceManifestOptions,
+  type ManifestInput,
+  type ModelPolicyInput,
+  type ModuleHelloAckBody,
+  type ObservabilityKind,
+  type ObservabilitySurfaceInput,
+  type PipelineAppliesToInput,
+  type PipelineStageKind,
+  type ProviderConnectionState,
+  type ProviderHandler,
+  type ProviderRoleInput,
+  type RouteBindRequest,
+  type ScheduledTaskInput,
+  type StorageBindingInput,
+  type StorageKind,
+  type StorageScope,
+  type SubcProviderConnectOptions,
+  type TaskEligibilityInput,
+  type ToolInput,
+  type TrustTier,
+  type VaultGrantInput,
+} from "./provider.js";