@robota-sdk/agent-transport-link 0.0.0-stage → 3.1.2

package/src/__tests__/squatter.test.ts

@@ -0,0 +1,147 @@
+/**
+ * A program that took over the control socket and answers like a runtime. It may run a real runtime
+ * of its own, certified by its own keyring or by nobody, or forge an answer by hand. Every byte the
+ * client sends it is recorded: the client is refused before it sends anything but the request line
+ * and its hello, so the squatter never sees a proof, a grant or a session frame.
+ */
+import { Buffer } from 'node:buffer';
+import { randomBytes } from 'node:crypto';
+import type { Socket } from 'node:net';
+
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+
+import {
+  LINK_CHALLENGE_MAX_BYTES,
+  LINK_HELLO_BYTES,
+  LinkRefusedError,
+  createLinkResponder,
+  createRuntimeIdentity,
+  startSpawnerExchange,
+  type IOwnerHandover,
+  type IRuntimeIdentity,
+} from '@robota-sdk/agent-keyring';
+
+import {
+  LINK_REQUEST_LINE,
+  OwnerLinkClosedError,
+  openOwnerLink,
+  openSpawnerLink,
+} from '../index.js';
+import { BINDING, connect, frame, keyrings, listen, type IListening } from './harness.js';
+
+let owner: IOwnerHandover;
+let stranger: IOwnerHandover;
+const servers: IListening[] = [];
+
+beforeAll(async () => {
+  ({ owner, stranger } = await keyrings());
+});
+afterAll(() => {
+  owner.dispose();
+  stranger.dispose();
+});
+afterEach(async () => {
+  for (const server of servers.splice(0)) await server.close();
+});
+
+/** A squatter that answers each hello with `answer(hello)` and records everything it receives. */
+async function squatter(answer: (hello: Uint8Array) => Uint8Array) {
+  const received: Buffer[] = [];
+  const server = await listen((socket: Socket) => {
+    let buffered = Buffer.alloc(0);
+    let answered = false;
+    socket.on('data', (chunk: Buffer) => {
+      received.push(chunk);
+      buffered = Buffer.concat([buffered, chunk]);
+      const helloStart = buffered.indexOf(0x0a) + 1;
+      if (!answered && helloStart > 0 && buffered.length >= helloStart + 4 + LINK_HELLO_BYTES) {
+        answered = true;
+        socket.write(
+          frame(answer(buffered.subarray(helloStart + 4, helloStart + 4 + LINK_HELLO_BYTES))),
+        );
+      }
+    });
+  });
+  servers.push(server);
+  return { port: server.port, received: () => Buffer.concat(received) };
+}
+
+/** What a client sends before it has checked the runtime: the request line and its hello, no more. */
+function expectOnlyHello(received: Buffer): void {
+  const line = Buffer.from(LINK_REQUEST_LINE);
+  expect(received.subarray(0, line.length).toString()).toBe(LINK_REQUEST_LINE);
+  expect(received.readUInt32BE(line.length)).toBe(LINK_HELLO_BYTES);
+  expect(received.length).toBe(line.length + 4 + LINK_HELLO_BYTES);
+}
+
+function certifiedBy(handover: IOwnerHandover): IRuntimeIdentity {
+  const identity = createRuntimeIdentity();
+  const exchange = startSpawnerExchange();
+  exchange.complete(identity.answerSpawnerExchange(exchange.message)).spawnerKey.wipe();
+  identity.installTrustRoot(handover.certify(identity.instancePublicKey, BINDING), BINDING);
+  return identity;
+}
+
+async function refusal(opening: Promise<unknown>): Promise<string> {
+  const error = await opening.then(
+    () => undefined,
+    (reason: unknown) => reason,
+  );
+  expect(error).toBeInstanceOf(LinkRefusedError);
+  return (error as LinkRefusedError).reason;
+}
+
+describe('a squatter on the control socket', () => {
+  it('running a runtime another keyring certified gets no proof from the owner', async () => {
+    const identity = certifiedBy(stranger);
+    const { port, received } = await squatter((hello) =>
+      createLinkResponder(identity, BINDING).challenge(hello),
+    );
+    expect(await refusal(openOwnerLink(await connect(port), owner))).toBe('certificate-mismatch');
+    expectOnlyHello(received());
+  });
+
+  it('forging an owner-mode answer gets no proof from the owner', async () => {
+    const forged = (): Uint8Array =>
+      Buffer.concat([
+        randomBytes(96),
+        Buffer.from([0, 4]),
+        Buffer.from('fake'),
+        Buffer.from([0, 4]),
+        Buffer.from('fake'),
+        Buffer.from([0, 64]),
+        randomBytes(64),
+        randomBytes(64),
+      ]);
+    const { port, received } = await squatter(forged);
+    expect(await refusal(openOwnerLink(await connect(port), owner))).toBe('certificate-mismatch');
+    expectOnlyHello(received());
+  });
+
+  it('running a runtime of its own gets nothing from the real spawner', async () => {
+    const real = createRuntimeIdentity();
+    const exchange = startSpawnerExchange();
+    const { spawnerKey, instancePublicKey } = exchange.complete(
+      real.answerSpawnerExchange(exchange.message),
+    );
+    const own = createRuntimeIdentity();
+    const ownExchange = startSpawnerExchange();
+    ownExchange.complete(own.answerSpawnerExchange(ownExchange.message));
+    const { port, received } = await squatter((hello) =>
+      createLinkResponder(own, BINDING).challenge(hello),
+    );
+    expect(await refusal(openSpawnerLink(await connect(port), spawnerKey, instancePublicKey))).toBe(
+      'instance-mismatch',
+    );
+    expectOnlyHello(received());
+  });
+
+  it('announcing a challenge over its bound is closed on, not read, and nothing more is sent', async () => {
+    const { port, received } = await squatter(() => randomBytes(LINK_CHALLENGE_MAX_BYTES + 1));
+    // A closed link, not a refusal: the client never read the challenge to judge it.
+    await expect(openOwnerLink(await connect(port), owner)).rejects.toBeInstanceOf(
+      OwnerLinkClosedError,
+    );
+    expectOnlyHello(received());
+  });
+});

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * `@robota-sdk/agent-transport-link` — the owner link carrier. It runs the `agent-keyring` owner
+ * link handshake and frame protection over a local byte stream (a supervised runtime's control
+ * socket or pipe), carries the unchanged session protocol of `agent-transport` in sealed frames,
+ * and owns the owner vocabulary: trust-root install, read grants, lock, the accept question and the
+ * runtime's existing control commands. Wire shapes stop here; a runtime answers through the
+ * domain-typed desk and session ports, and decides there what each standing may do.
+ */
+export { LINK_PROTOCOL, LINK_REQUEST_LINE, isLinkRequest } from './link-request.js';
+export { DEFAULT_HANDSHAKE_TIMEOUT_MS, serveRuntimeLink } from './serve-runtime-link.js';
+export type {
+  IAdmittedRuntimeLink,
+  IRuntimeLinkDeps,
+  IRuntimeLinkPorts,
+} from './serve-runtime-link.js';
+export { DEFAULT_OPEN_TIMEOUT_MS, openOwnerLink, openSpawnerLink } from './open-runtime-link.js';
+export type {
+  ILinkSessionChannel,
+  IOpenRuntimeLinkOptions,
+  IOwnerRuntimeLinkClient,
+  IRuntimeLinkClient,
+} from './open-runtime-link.js';
+export { OwnerLinkClosedError, OwnerRequestRefusedError } from './link-ports.js';
+export type {
+  ILinkSessionSink,
+  IOwnerControlRequest,
+  IOwnerLinkDesk,
+  IOwnerLinkSessions,
+  IRuntimeCustodyState,
+  TGrantOutcome,
+  TOwnerControlResult,
+  TOwnerControlValue,
+  TOwnerSessionQuestion,
+  TRequestedLockReason,
+} from './link-ports.js';

package/src/link-bounds.ts

@@ -0,0 +1,21 @@
+/**
+ * How large each kind of frame may be. A session frame carries one session-protocol message, and its
+ * bound is the protocol's own inbound limit counted in UTF-8 bytes, the way the local attach path
+ * counts it: a message within it is within the decoder's character limit too, so a sender never
+ * emits what the receiving decoder must refuse. Owner frames carry short requests and replies. Both
+ * ends bound what they send, and every frame they read before reading it, by these.
+ */
+import { LINK_FRAME_OVERHEAD_BYTES } from '@robota-sdk/agent-keyring';
+import { MAX_INBOUND_FRAME_BYTES } from '@robota-sdk/agent-transport';
+
+export const SESSION_FRAME_MAX_BYTES = MAX_INBOUND_FRAME_BYTES;
+export const OWNER_FRAME_MAX_BYTES = 1024 * 1024;
+/** The largest sealed frame either end accepts, of any kind. */
+export const SEALED_FRAME_MAX_BYTES =
+  Math.max(SESSION_FRAME_MAX_BYTES, OWNER_FRAME_MAX_BYTES) + LINK_FRAME_OVERHEAD_BYTES;
+/**
+ * Owner requests and read grants one link may have waiting at once. A client refuses its own request
+ * beyond it, so a well-behaved caller never loses its link; the runtime ends a link whose peer sends
+ * one more.
+ */
+export const MAX_REQUESTS_IN_FLIGHT = 64;

package/src/link-ports.ts

@@ -0,0 +1,118 @@
+/**
+ * What the owner link asks of a runtime, and tells its clients, in domain terms.
+ *
+ * The owner vocabulary's wire shapes stop inside this package. A runtime answers an admitted link
+ * through two ports: the desk, for custody (the trust root, the read grant, locking and the existing
+ * control commands), and the session decisions, for the one owner decision that is not a session
+ * protocol message (accepting a record not verified as the owner's). Both are given the link's
+ * standing when the link is admitted, and decide what that standing may do: this package carries
+ * requests, it does not grant them.
+ */
+import type { IReadKeys, ITrustRoot } from '@robota-sdk/agent-keyring';
+
+/** What a client may ask a runtime to lock for; idle and last-link-closed are the runtime's own. */
+export type TRequestedLockReason = 'explicit' | 'screen-lock' | 'suspend';
+
+/**
+ * How a read grant went. `mismatch`: the keyring file's sealing public key is not the granted one;
+ * the runtime seals to the granted key, and the owner is told to run `secure verify`.
+ */
+export type TGrantOutcome = 'verified' | 'mismatch';
+
+/** What every linked client is told, once admitted and whenever it changes. */
+export interface IRuntimeCustodyState {
+  readonly unlocked: boolean;
+  /** Whether owner links are possible: a spawner installed a trust root. */
+  readonly certified: boolean;
+}
+
+/**
+ * The runtime's answer to "may I open this session?". `accept` asks the owner, on a surface that
+ * shows the fixed `notice` and `question` and never the record, and `digest` binds the answer to
+ * the bytes the runtime read.
+ */
+export type TOwnerSessionQuestion =
+  | { readonly kind: 'open' }
+  | {
+      readonly kind: 'accept';
+      readonly digest: string;
+      readonly notice: string;
+      readonly question: string;
+    }
+  | { readonly kind: 'refused'; readonly message: string };
+
+/** One of the runtime's existing control commands, carried inside the link. */
+export interface IOwnerControlRequest {
+  readonly command: string;
+  readonly fields: Readonly<Record<string, string>>;
+}
+
+export type TOwnerControlValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly TOwnerControlValue[]
+  | { readonly [key: string]: TOwnerControlValue };
+
+/** What a control command answered. */
+export type TOwnerControlResult = { readonly [key: string]: TOwnerControlValue };
+
+/** The runtime's custody answers for one admitted link. */
+export interface IOwnerLinkDesk {
+  /** The state the link announces as soon as it is admitted. */
+  custody(): IRuntimeCustodyState;
+  installTrustRoot(root: ITrustRoot): void | Promise<void>;
+  /**
+   * Installs the granted read keys. The desk owns them once this returns; when it refuses, by
+   * throwing, the carrier locks them.
+   */
+  unlock(keys: IReadKeys): TGrantOutcome | Promise<TGrantOutcome>;
+  lock(reason: TRequestedLockReason): void | Promise<void>;
+  control(request: IOwnerControlRequest): TOwnerControlResult | Promise<TOwnerControlResult>;
+  /** The link ended, for whatever reason. Called once. */
+  closed(): void;
+}
+
+/** The runtime's session decisions for one admitted link. */
+export interface IOwnerLinkSessions {
+  question(sessionId: string): TOwnerSessionQuestion | Promise<TOwnerSessionQuestion>;
+  openAccepted(sessionId: string, acceptedDigest: string): void | Promise<void>;
+}
+
+/** Where the session protocol of an admitted link goes: one serialized client message at a time. */
+export interface ILinkSessionSink {
+  receive(data: string): void;
+}
+
+const REFUSAL_CODE = /^[a-z][a-z0-9-]{0,63}$/u;
+const MAX_REFUSAL_MESSAGE_LENGTH = 1024;
+
+/**
+ * A request the runtime refused, by decision: a desk throws it with a fixed code and fixed text, and
+ * the client rejects with it. Any other failure reaches the client as `failed`, never with its text.
+ */
+export class OwnerRequestRefusedError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    if (
+      !REFUSAL_CODE.test(code) ||
+      message.length === 0 ||
+      message.length > MAX_REFUSAL_MESSAGE_LENGTH
+    ) {
+      throw new RangeError('A refusal has a lower-case code and a message of 1-1024 characters.');
+    }
+    super(message);
+    this.name = 'OwnerRequestRefusedError';
+    this.code = code;
+  }
+}
+
+/** The link closed, or never opened: the other end does not say why. */
+export class OwnerLinkClosedError extends Error {
+  constructor() {
+    super('The owner link closed.');
+    this.name = 'OwnerLinkClosedError';
+  }
+}

package/src/link-request.ts

@@ -0,0 +1,20 @@
+/**
+ * The request line that opens an owner link, in the control endpoint's existing request shape so
+ * the endpoint routes it like any other command. It names no runtime and no start: the binding is
+ * proven inside the handshake, never taken from the request.
+ */
+export const LINK_PROTOCOL = 1;
+
+/** Exactly what a client writes first, newline included. */
+export const LINK_REQUEST_LINE = `${JSON.stringify({ command: 'link', protocol: LINK_PROTOCOL })}\n`;
+
+/** Whether a parsed request line is exactly the link request; anything more or less is not. */
+export function isLinkRequest(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return (
+    Object.keys(record).length === 2 &&
+    record['command'] === 'link' &&
+    record['protocol'] === LINK_PROTOCOL
+  );
+}

package/src/link-stream.ts

@@ -0,0 +1,136 @@
+/**
+ * The owner link on a byte stream: after the request line, length-prefixed binary frames.
+ *
+ * Each frame is a 4-byte big-endian length and that many bytes. Every frame is bounded by what may
+ * come next (a hello, a challenge, a proof, a sealed frame), and the bound is checked as soon as the
+ * length arrives, so a peer can never make an end buffer more than one frame it is allowed to send.
+ * Chunks are kept as they arrive and joined once per frame, so a large frame costs one copy.
+ */
+import { Buffer } from 'node:buffer';
+import type { Duplex } from 'node:stream';
+
+import { LINK_REQUEST_LINE } from './link-request.js';
+
+const LENGTH_PREFIX_BYTES = 4;
+
+/** One frame: its length, then its bytes. */
+export function encodeLinkFrame(payload: Uint8Array): Buffer {
+  const prefix = Buffer.alloc(LENGTH_PREFIX_BYTES);
+  prefix.writeUInt32BE(payload.length);
+  return Buffer.concat([prefix, payload]);
+}
+
+/** The request line and the first frame, written together so the endpoint can route both at once. */
+export function encodeLinkOpening(hello: Uint8Array): Buffer {
+  return Buffer.concat([Buffer.from(LINK_REQUEST_LINE, 'utf8'), encodeLinkFrame(hello)]);
+}
+
+/** Collects stream chunks and hands out whole frames within the bound the caller gives. */
+class LinkFrameReader {
+  #chunks: Buffer[] = [];
+  #length = 0;
+
+  push(chunk: Uint8Array): void {
+    if (chunk.length === 0) return;
+    this.#chunks.push(Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+    this.#length += chunk.length;
+  }
+
+  /** The next whole frame, or `undefined` until it has arrived; throws when one is announced over `maxBytes`. */
+  next(maxBytes: number): Buffer | undefined {
+    if (this.#length < LENGTH_PREFIX_BYTES) return undefined;
+    if (this.#chunks[0]!.length < LENGTH_PREFIX_BYTES) this.#join();
+    const length = this.#chunks[0]!.readUInt32BE(0);
+    if (length > maxBytes) throw new RangeError('A frame was announced over its bound.');
+    if (this.#length < LENGTH_PREFIX_BYTES + length) return undefined;
+    const all = this.#join();
+    const end = LENGTH_PREFIX_BYTES + length;
+    const payload = Buffer.from(all.subarray(LENGTH_PREFIX_BYTES, end));
+    const rest = all.subarray(end);
+    this.#chunks = rest.length > 0 ? [rest] : [];
+    this.#length = rest.length;
+    return payload;
+  }
+
+  #join(): Buffer {
+    const all =
+      this.#chunks.length === 1 ? this.#chunks[0]! : Buffer.concat(this.#chunks, this.#length);
+    this.#chunks = [all];
+    return all;
+  }
+}
+
+export interface IFrameReading {
+  /** The bytes after the request line that arrived with it. */
+  readonly rest?: Uint8Array;
+  /** The largest frame allowed next; asked before each frame. */
+  readonly maxBytes: () => number;
+  /**
+   * One whole frame. May end the stream; nothing more is read once it has. Returning `'yield'` stops
+   * the reading for the rest of this tick, so a caller woken by this frame runs before the next one.
+   */
+  readonly onFrame: (frame: Buffer) => void | 'yield';
+  /** The stream ended, errored, or sent a frame over its bound. Called once. */
+  readonly onEnd: () => void;
+}
+
+/**
+ * Reads frames off `stream` until it ends; a frame over its bound destroys the stream. A stream that
+ * is already destroyed or closed reads nothing and ends on the next tick.
+ */
+export function readLinkFrames(stream: Duplex, reading: IFrameReading): void {
+  const reader = new LinkFrameReader();
+  let ended = false;
+  const end = (): void => {
+    if (ended) return;
+    ended = true;
+    reading.onEnd();
+  };
+  let yielded = false;
+  const drain = (): void => {
+    if (yielded) return;
+    try {
+      for (
+        let frame = reader.next(reading.maxBytes());
+        frame !== undefined;
+        frame = reader.next(reading.maxBytes())
+      ) {
+        if (stream.destroyed) return;
+        const outcome = reading.onFrame(frame);
+        if (stream.destroyed) return;
+        if (outcome === 'yield') {
+          // Paused, so nothing more arrives (and the stream cannot end) until the frames kept so far
+          // have been read: the pause is one tick, and holds no more than one chunk.
+          yielded = true;
+          stream.pause();
+          setImmediate(() => {
+            yielded = false;
+            drain();
+            if (!yielded) stream.resume();
+          });
+          return;
+        }
+      }
+    } catch {
+      // A frame over its bound, or a handler that failed: either way this link is over.
+      stream.destroy();
+    }
+  };
+  stream.on('data', (chunk: Buffer | string) => {
+    // A stream decoding to text has already lost the frames' bytes.
+    if (typeof chunk === 'string') {
+      stream.destroy();
+      return;
+    }
+    reader.push(chunk);
+    drain();
+  });
+  stream.on('error', () => stream.destroy());
+  stream.once('close', end);
+  stream.once('end', () => stream.destroy());
+  if (reading.rest !== undefined) reader.push(reading.rest);
+  drain();
+  stream.resume();
+  // A stream that is over before it is read emits no `close` to wait for, and a link must still end.
+  if (stream.destroyed) process.nextTick(end);
+}