@constructive-db/machine-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @constructive-db/machine-protocol
+
+The wire protocol shared by the machine relay (`compute/services/machine-relay`)
+and the machine runner (`compute/lib/machine-runner`): the JSON frames a remote
+session is made of — `open`, `input`, `resize`, `close` from the client side;
+`output`, `exit`, `error` from the runner side; `attached` from the relay — and
+the codec that encodes them and refuses malformed ones.
+
+The relay never interprets terminal bytes: `input` flows client → runner and
+`output` flows runner → client as opaque UTF-8 strings. Everything else is
+session lifecycle. The package has no dependencies so the relay can carry it
+into the functions image without dragging the runner's native pty bindings
+along.

package/esm/index.js

@@ -0,0 +1,241 @@
+// The machine transport wire protocol: JSON text frames over a WebSocket. Two
+// socket roles speak it — a runner (the daemon on the user's machine) and a
+// client (whatever is driving a session) — with the relay in the middle routing
+// frames between them by session id.
+//
+// The relay never interprets terminal bytes: `input` flows client → runner,
+// `output` flows runner → client, both opaque UTF-8 strings. Everything else
+// is session lifecycle.
+//
+// Phase 2 adds the rest of a terminal — `resize`, `signal`, `detach`,
+// `reattach` — as frames on this same socket rather than a second transport.
+// Each is an *operation*, not a routing hint: the relay answers every one of
+// them by asking the tenant's SQL again, so a frame here is a request and never
+// a decision. That is what makes a reattach from a different client safe —
+// nothing about the attach that opened the session carries over.
+//
+// This package is vocabulary, never policy. Everything a socket puts on the wire
+// — its database, its machine id — is a *coordinate*: it says which row the
+// socket is asking about, and the relay answers by asking that database's SQL.
+// Nothing here grants anything and no frame carries an authorization decision,
+// so naming a coordinate buys nothing: a secret only matches a machine row in
+// the tenant that issued it, and RLS decides everything after that. Addressing a
+// database you have no credential for is simply a refusal.
+// Token hashing is deliberately NOT re-exported here: it needs node's `crypto`,
+// and this index is imported by the browser terminal. Node consumers reach it at
+// `@constructive-db/machine-protocol/token`.
+/**
+ * Header a runner identifies itself with at upgrade time.
+ *
+ * A coordinate, not a claim: the bearer credential is what authenticates, and
+ * the machine row it matches is what decides. A socket naming a machine it
+ * cannot present the secret for is refused.
+ */
+export const HEADER_MACHINE_ID = 'x-machine-id';
+/**
+ * Header naming the tenant database the runner is enrolled in — which database
+ * to ask, never permission to be there, exactly as a sync route's hostname
+ * chooses a database before anyone is authenticated.
+ */
+export const HEADER_MACHINE_DATABASE = 'x-machine-database';
+/** URL paths the relay serves. */
+export const RUNNER_CONNECT_PATH = '/v1/machines/connect';
+/**
+ * Where a client attaches, with its own credential as a bearer token. The
+ * database is in the path because a tenant credential is only meaningful to the
+ * tenant that issued it: the relay authenticates the token *there*.
+ */
+export const clientAttachPath = (databaseId, machineId) => `/v1/databases/${encodeURIComponent(databaseId)}/machines/${encodeURIComponent(machineId)}/attach`;
+/**
+ * Subprotocol a browser attaches with.
+ *
+ * A `WebSocket` in a page cannot set request headers, so the one thing the
+ * standard does let it send — the subprotocol list — carries the credential:
+ * `[ATTACH_SUBPROTOCOL, '<credential>']`. It is the same bearer token the
+ * `Authorization` header would carry, authenticated by the same tenant
+ * `authenticate()`, and it stays out of the URL (and therefore out of access
+ * logs and `Referer`) which a query parameter would not. The relay answers with
+ * {@link ATTACH_SUBPROTOCOL} alone, so the credential is never echoed back.
+ */
+export const ATTACH_SUBPROTOCOL = 'constructive.machine.v1';
+/** The subprotocol list a browser client attaches with. */
+export const attachSubprotocols = (credential) => [
+    ATTACH_SUBPROTOCOL,
+    credential
+];
+/**
+ * The credential out of a subprotocol list, or null when the list is not an
+ * attach list. Only the documented two-entry shape is accepted — anything else
+ * is a client that has not agreed this protocol.
+ */
+export function credentialFromSubprotocols(header) {
+    if (!header)
+        return null;
+    const values = header.split(',').map(value => value.trim());
+    if (values.length !== 2 || values[0] !== ATTACH_SUBPROTOCOL || !values[1])
+        return null;
+    return values[1];
+}
+/** Parse {@link clientAttachPath}, or null when the path is something else. */
+export function parseClientAttachPath(path) {
+    const match = /^\/v1\/databases\/([^/]+)\/machines\/([^/]+)\/attach$/.exec(path);
+    if (!match)
+        return null;
+    return {
+        databaseId: decodeURIComponent(match[1]),
+        machineId: decodeURIComponent(match[2])
+    };
+}
+/**
+ * Signals a client may ask for. `SIGINT` and `SIGQUIT` are the terminal's own
+ * interrupt characters, so on a pty they are delivered the way a keyboard
+ * delivers them — through the line discipline, to the *foreground* process
+ * group — which is what interrupts a running command without ending the
+ * session. The rest are delivered to the session leader and do end it.
+ */
+export const SIGNAL_NAMES = ['SIGINT', 'SIGQUIT', 'SIGTERM', 'SIGHUP', 'SIGKILL'];
+const FRAME_TYPES = new Set([
+    'open',
+    'input',
+    'resize',
+    'signal',
+    'detach',
+    'reattach',
+    'close',
+    'output',
+    'exit',
+    'error',
+    'scrollback',
+    'attached',
+    'detached',
+    'reattached',
+    'enrolled'
+]);
+/** Frame types that must carry a session id. */
+const SESSION_FRAME_TYPES = new Set([
+    'open',
+    'input',
+    'resize',
+    'signal',
+    'detach',
+    'reattach',
+    'close',
+    'output',
+    'exit',
+    'scrollback',
+    'detached',
+    'reattached'
+]);
+const SIGNALS = new Set(SIGNAL_NAMES);
+/**
+ * Terminal geometry a pty will accept. A resize is a client-supplied pair of
+ * numbers that ends up in `ioctl(TIOCSWINSZ)`, so it is validated here rather
+ * than trusted: zero, negative, fractional or absurd values are a protocol
+ * fault, not something to clamp silently.
+ */
+const MAX_DIMENSION = 1000;
+function validDimension(value) {
+    return (typeof value === 'number' &&
+        Number.isInteger(value) &&
+        value > 0 &&
+        value <= MAX_DIMENSION);
+}
+export function encodeFrame(frame) {
+    return JSON.stringify(frame);
+}
+/**
+ * Parse one wire message into a frame. Malformed input is a protocol fault on
+ * the sending socket, so this throws rather than returning a placeholder —
+ * the caller decides whether that closes the connection.
+ */
+export function decodeFrame(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`machine-protocol: frame is not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('machine-protocol: frame is not an object');
+    }
+    const frame = parsed;
+    const type = frame.type;
+    if (typeof type !== 'string' || !FRAME_TYPES.has(type)) {
+        throw new Error(`machine-protocol: unknown frame type '${String(type)}'`);
+    }
+    if (SESSION_FRAME_TYPES.has(type) && typeof frame.sessionId !== 'string') {
+        throw new Error(`machine-protocol: '${type}' frame is missing sessionId`);
+    }
+    switch (type) {
+        case 'open':
+            if (typeof frame.command !== 'string' || frame.command.length === 0) {
+                throw new Error("machine-protocol: 'open' frame is missing command");
+            }
+            if (frame.cols !== undefined || frame.rows !== undefined) {
+                if (!validDimension(frame.cols) || !validDimension(frame.rows)) {
+                    throw new Error(`machine-protocol: 'open' frame needs integer cols/rows in 1..${MAX_DIMENSION}`);
+                }
+            }
+            break;
+        case 'input':
+        case 'output':
+            if (typeof frame.data !== 'string') {
+                throw new Error(`machine-protocol: '${type}' frame is missing data`);
+            }
+            break;
+        case 'resize':
+            if (!validDimension(frame.cols) || !validDimension(frame.rows)) {
+                throw new Error(`machine-protocol: 'resize' frame needs integer cols/rows in 1..${MAX_DIMENSION}`);
+            }
+            break;
+        case 'reattach':
+            // Geometry is optional on a reattach (a client may want the size the
+            // session already has), but a supplied one is held to the same bounds.
+            if (frame.cols !== undefined || frame.rows !== undefined) {
+                if (!validDimension(frame.cols) || !validDimension(frame.rows)) {
+                    throw new Error(`machine-protocol: 'reattach' frame needs integer cols/rows in 1..${MAX_DIMENSION}`);
+                }
+            }
+            break;
+        case 'signal':
+            if (typeof frame.signal !== 'string' || !SIGNALS.has(frame.signal)) {
+                throw new Error(`machine-protocol: 'signal' frame has unknown signal '${String(frame.signal)}'`);
+            }
+            break;
+        case 'scrollback':
+            if (typeof frame.data !== 'string' || typeof frame.truncated !== 'boolean') {
+                throw new Error("machine-protocol: 'scrollback' frame is missing data/truncated");
+            }
+            break;
+        case 'reattached':
+            if (typeof frame.state !== 'string' || typeof frame.lastSeq !== 'string') {
+                throw new Error("machine-protocol: 'reattached' frame is missing state/lastSeq");
+            }
+            break;
+        case 'exit':
+            if (typeof frame.exitCode !== 'number') {
+                throw new Error("machine-protocol: 'exit' frame is missing exitCode");
+            }
+            break;
+        case 'error':
+            if (typeof frame.message !== 'string') {
+                throw new Error("machine-protocol: 'error' frame is missing message");
+            }
+            break;
+        case 'attached':
+            if (typeof frame.machineId !== 'string') {
+                throw new Error("machine-protocol: 'attached' frame is missing machineId");
+            }
+            break;
+        case 'enrolled':
+            if (typeof frame.machineId !== 'string' || typeof frame.principalId !== 'string') {
+                throw new Error("machine-protocol: 'enrolled' frame is missing machineId/principalId");
+            }
+            if (typeof frame.credential !== 'string' || typeof frame.expiresAt !== 'number') {
+                throw new Error("machine-protocol: 'enrolled' frame is missing credential/expiresAt");
+            }
+            break;
+    }
+    return frame;
+}

package/esm/token.js

@@ -0,0 +1,22 @@
+/**
+ * How an enrollment token is stored and compared.
+ *
+ * The `machine` row keeps a hash, never the token: the runner holds the only
+ * copy of the secret, and a database dump of the machines table hands out no
+ * shells. Enrollment hashes the token it generated with this function, and the
+ * relay hashes what a socket presented and compares the two — in constant time,
+ * so the comparison leaks nothing about how much of a prefix matched.
+ */
+import { createHash, timingSafeEqual } from 'crypto';
+/** The hash stored in `machine.token_hash` for an enrollment token. */
+export function hashMachineToken(token) {
+    return createHash('sha256').update(token, 'utf8').digest('hex');
+}
+/** Constant-time comparison of two token hashes. */
+export function machineTokenHashMatches(expected, presented) {
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(presented, 'utf8');
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}

package/index.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Header a runner identifies itself with at upgrade time.
+ *
+ * A coordinate, not a claim: the bearer credential is what authenticates, and
+ * the machine row it matches is what decides. A socket naming a machine it
+ * cannot present the secret for is refused.
+ */
+export declare const HEADER_MACHINE_ID = "x-machine-id";
+/**
+ * Header naming the tenant database the runner is enrolled in — which database
+ * to ask, never permission to be there, exactly as a sync route's hostname
+ * chooses a database before anyone is authenticated.
+ */
+export declare const HEADER_MACHINE_DATABASE = "x-machine-database";
+/** URL paths the relay serves. */
+export declare const RUNNER_CONNECT_PATH = "/v1/machines/connect";
+/**
+ * Where a client attaches, with its own credential as a bearer token. The
+ * database is in the path because a tenant credential is only meaningful to the
+ * tenant that issued it: the relay authenticates the token *there*.
+ */
+export declare const clientAttachPath: (databaseId: string, machineId: string) => string;
+/**
+ * Subprotocol a browser attaches with.
+ *
+ * A `WebSocket` in a page cannot set request headers, so the one thing the
+ * standard does let it send — the subprotocol list — carries the credential:
+ * `[ATTACH_SUBPROTOCOL, '<credential>']`. It is the same bearer token the
+ * `Authorization` header would carry, authenticated by the same tenant
+ * `authenticate()`, and it stays out of the URL (and therefore out of access
+ * logs and `Referer`) which a query parameter would not. The relay answers with
+ * {@link ATTACH_SUBPROTOCOL} alone, so the credential is never echoed back.
+ */
+export declare const ATTACH_SUBPROTOCOL = "constructive.machine.v1";
+/** The subprotocol list a browser client attaches with. */
+export declare const attachSubprotocols: (credential: string) => [string, string];
+/**
+ * The credential out of a subprotocol list, or null when the list is not an
+ * attach list. Only the documented two-entry shape is accepted — anything else
+ * is a client that has not agreed this protocol.
+ */
+export declare function credentialFromSubprotocols(header: string | undefined): string | null;
+/** Parse {@link clientAttachPath}, or null when the path is something else. */
+export declare function parseClientAttachPath(path: string): {
+    databaseId: string;
+    machineId: string;
+} | null;
+/** Client → runner: start a process in a new session. */
+export interface OpenFrame {
+    type: 'open';
+    sessionId: string;
+    command: string;
+    args?: string[];
+    cols?: number;
+    rows?: number;
+    /**
+     * Ask for a terminal rather than a pipe. An interactive session gets a pty,
+     * so its output is opaque terminal bytes (escape sequences and all) and its
+     * geometry is part of the session — which is what makes `vim` render and
+     * reflow. Command mode (phase 1) is the default and unchanged.
+     */
+    interactive?: boolean;
+}
+/** Client → runner: bytes for the session's stdin. */
+export interface InputFrame {
+    type: 'input';
+    sessionId: string;
+    data: string;
+}
+/** Client → runner: the terminal was resized. */
+export interface ResizeFrame {
+    type: 'resize';
+    sessionId: string;
+    cols: number;
+    rows: number;
+}
+/** Client → runner: tear the session down. */
+export interface CloseFrame {
+    type: 'close';
+    sessionId: string;
+}
+/**
+ * Signals a client may ask for. `SIGINT` and `SIGQUIT` are the terminal's own
+ * interrupt characters, so on a pty they are delivered the way a keyboard
+ * delivers them — through the line discipline, to the *foreground* process
+ * group — which is what interrupts a running command without ending the
+ * session. The rest are delivered to the session leader and do end it.
+ */
+export declare const SIGNAL_NAMES: readonly ["SIGINT", "SIGQUIT", "SIGTERM", "SIGHUP", "SIGKILL"];
+export type SignalName = (typeof SIGNAL_NAMES)[number];
+/** Client → runner: deliver a signal to the session. */
+export interface SignalFrame {
+    type: 'signal';
+    sessionId: string;
+    signal: SignalName;
+}
+/**
+ * Client → relay → runner: stop streaming, but leave the process running.
+ *
+ * The session stays alive on the machine and its record moves to `detached`,
+ * which is what a later {@link ReattachFrame} — from this client or another
+ * one — comes back to.
+ */
+export interface DetachFrame {
+    type: 'detach';
+    sessionId: string;
+}
+/**
+ * Client → relay → runner: take over a session that is already running.
+ *
+ * A reattach is a fresh authorization question, never a continuation of the
+ * attach that opened the session: the client may be a different one, and the
+ * tenant answers again. `cols`/`rows` are the new terminal's geometry, applied
+ * to the pty so the program repaints at the size it is being watched on.
+ */
+export interface ReattachFrame {
+    type: 'reattach';
+    sessionId: string;
+    cols?: number;
+    rows?: number;
+}
+/** Runner → client: bytes from the session's pty. */
+export interface OutputFrame {
+    type: 'output';
+    sessionId: string;
+    data: string;
+}
+/** Runner → client: the process ended. */
+export interface ExitFrame {
+    type: 'exit';
+    sessionId: string;
+    exitCode: number;
+    signal?: number;
+}
+/**
+ * Any → any: something failed. Carries a session id when the failure belongs
+ * to one session (a rejected command), none when it belongs to the connection
+ * (the runner dropped).
+ */
+export interface ErrorFrame {
+    type: 'error';
+    sessionId?: string;
+    message: string;
+}
+/**
+ * Runner → relay: the scrollback a detaching session leaves behind, capped by
+ * the runner. The relay records it as the session's one interactive output row
+ * (the ledger is the agreed home for terminal bytes) and does not keep it.
+ */
+export interface ScrollbackFrame {
+    type: 'scrollback';
+    sessionId: string;
+    data: string;
+    /** True when older bytes fell out of the runner's ring buffer. */
+    truncated: boolean;
+}
+/** Relay → client: the session is detached and still running. */
+export interface DetachedFrame {
+    type: 'detached';
+    sessionId: string;
+}
+/**
+ * Relay → client: a reattach was authorized, and here is the session as the
+ * ledger has it — the geometry it is running at and how much of its record was
+ * already written, so a client can read the transcript back from SQL.
+ */
+export interface ReattachedFrame {
+    type: 'reattached';
+    sessionId: string;
+    state: string;
+    cols: number | null;
+    rows: number | null;
+    /** `machine_session.last_seq`, a bigint, so it travels as a decimal string. */
+    lastSeq: string;
+    interactive: boolean;
+}
+/** Relay → client: the attach succeeded and the runner is online. */
+export interface AttachedFrame {
+    type: 'attached';
+    machineId: string;
+}
+/**
+ * Relay → runner: the enrollment token was exchanged.
+ *
+ * The runner learns two things it did not know: the principal the tenant says it
+ * acts as, and a short-lived credential to dial with next time. The credential
+ * is held in memory and never logged or written beside the enrollment file —
+ * `expiresAt` is when it stops verifying, after which the runner falls back to
+ * the enrollment token and is issued a fresh one.
+ */
+export interface EnrolledFrame {
+    type: 'enrolled';
+    machineId: string;
+    /** The principal the machine's own writes are attributed to. */
+    principalId: string;
+    /** Short-lived database credential. Never log this value. */
+    credential: string;
+    /** Epoch seconds at which {@link credential} stops verifying. */
+    expiresAt: number;
+}
+export type ClientToRunnerFrame = OpenFrame | InputFrame | ResizeFrame | SignalFrame | DetachFrame | ReattachFrame | CloseFrame;
+export type RunnerToClientFrame = OutputFrame | ExitFrame | ErrorFrame | ScrollbackFrame;
+export type Frame = ClientToRunnerFrame | RunnerToClientFrame | AttachedFrame | DetachedFrame | ReattachedFrame | EnrolledFrame;
+export declare function encodeFrame(frame: Frame): string;
+/**
+ * Parse one wire message into a frame. Malformed input is a protocol fault on
+ * the sending socket, so this throws rather than returning a placeholder —
+ * the caller decides whether that closes the connection.
+ */
+export declare function decodeFrame(raw: string): Frame;

package/index.js

@@ -0,0 +1,250 @@
+"use strict";
+// The machine transport wire protocol: JSON text frames over a WebSocket. Two
+// socket roles speak it — a runner (the daemon on the user's machine) and a
+// client (whatever is driving a session) — with the relay in the middle routing
+// frames between them by session id.
+//
+// The relay never interprets terminal bytes: `input` flows client → runner,
+// `output` flows runner → client, both opaque UTF-8 strings. Everything else
+// is session lifecycle.
+//
+// Phase 2 adds the rest of a terminal — `resize`, `signal`, `detach`,
+// `reattach` — as frames on this same socket rather than a second transport.
+// Each is an *operation*, not a routing hint: the relay answers every one of
+// them by asking the tenant's SQL again, so a frame here is a request and never
+// a decision. That is what makes a reattach from a different client safe —
+// nothing about the attach that opened the session carries over.
+//
+// This package is vocabulary, never policy. Everything a socket puts on the wire
+// — its database, its machine id — is a *coordinate*: it says which row the
+// socket is asking about, and the relay answers by asking that database's SQL.
+// Nothing here grants anything and no frame carries an authorization decision,
+// so naming a coordinate buys nothing: a secret only matches a machine row in
+// the tenant that issued it, and RLS decides everything after that. Addressing a
+// database you have no credential for is simply a refusal.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIGNAL_NAMES = exports.attachSubprotocols = exports.ATTACH_SUBPROTOCOL = exports.clientAttachPath = exports.RUNNER_CONNECT_PATH = exports.HEADER_MACHINE_DATABASE = exports.HEADER_MACHINE_ID = void 0;
+exports.credentialFromSubprotocols = credentialFromSubprotocols;
+exports.parseClientAttachPath = parseClientAttachPath;
+exports.encodeFrame = encodeFrame;
+exports.decodeFrame = decodeFrame;
+// Token hashing is deliberately NOT re-exported here: it needs node's `crypto`,
+// and this index is imported by the browser terminal. Node consumers reach it at
+// `@constructive-db/machine-protocol/token`.
+/**
+ * Header a runner identifies itself with at upgrade time.
+ *
+ * A coordinate, not a claim: the bearer credential is what authenticates, and
+ * the machine row it matches is what decides. A socket naming a machine it
+ * cannot present the secret for is refused.
+ */
+exports.HEADER_MACHINE_ID = 'x-machine-id';
+/**
+ * Header naming the tenant database the runner is enrolled in — which database
+ * to ask, never permission to be there, exactly as a sync route's hostname
+ * chooses a database before anyone is authenticated.
+ */
+exports.HEADER_MACHINE_DATABASE = 'x-machine-database';
+/** URL paths the relay serves. */
+exports.RUNNER_CONNECT_PATH = '/v1/machines/connect';
+/**
+ * Where a client attaches, with its own credential as a bearer token. The
+ * database is in the path because a tenant credential is only meaningful to the
+ * tenant that issued it: the relay authenticates the token *there*.
+ */
+const clientAttachPath = (databaseId, machineId) => `/v1/databases/${encodeURIComponent(databaseId)}/machines/${encodeURIComponent(machineId)}/attach`;
+exports.clientAttachPath = clientAttachPath;
+/**
+ * Subprotocol a browser attaches with.
+ *
+ * A `WebSocket` in a page cannot set request headers, so the one thing the
+ * standard does let it send — the subprotocol list — carries the credential:
+ * `[ATTACH_SUBPROTOCOL, '<credential>']`. It is the same bearer token the
+ * `Authorization` header would carry, authenticated by the same tenant
+ * `authenticate()`, and it stays out of the URL (and therefore out of access
+ * logs and `Referer`) which a query parameter would not. The relay answers with
+ * {@link ATTACH_SUBPROTOCOL} alone, so the credential is never echoed back.
+ */
+exports.ATTACH_SUBPROTOCOL = 'constructive.machine.v1';
+/** The subprotocol list a browser client attaches with. */
+const attachSubprotocols = (credential) => [
+    exports.ATTACH_SUBPROTOCOL,
+    credential
+];
+exports.attachSubprotocols = attachSubprotocols;
+/**
+ * The credential out of a subprotocol list, or null when the list is not an
+ * attach list. Only the documented two-entry shape is accepted — anything else
+ * is a client that has not agreed this protocol.
+ */
+function credentialFromSubprotocols(header) {
+    if (!header)
+        return null;
+    const values = header.split(',').map(value => value.trim());
+    if (values.length !== 2 || values[0] !== exports.ATTACH_SUBPROTOCOL || !values[1])
+        return null;
+    return values[1];
+}
+/** Parse {@link clientAttachPath}, or null when the path is something else. */
+function parseClientAttachPath(path) {
+    const match = /^\/v1\/databases\/([^/]+)\/machines\/([^/]+)\/attach$/.exec(path);
+    if (!match)
+        return null;
+    return {
+        databaseId: decodeURIComponent(match[1]),
+        machineId: decodeURIComponent(match[2])
+    };
+}
+/**
+ * Signals a client may ask for. `SIGINT` and `SIGQUIT` are the terminal's own
+ * interrupt characters, so on a pty they are delivered the way a keyboard
+ * delivers them — through the line discipline, to the *foreground* process
+ * group — which is what interrupts a running command without ending the
+ * session. The rest are delivered to the session leader and do end it.
+ */
+exports.SIGNAL_NAMES = ['SIGINT', 'SIGQUIT', 'SIGTERM', 'SIGHUP', 'SIGKILL'];
+const FRAME_TYPES = new Set([
+    'open',
+    'input',
+    'resize',
+    'signal',
+    'detach',
+    'reattach',
+    'close',
+    'output',
+    'exit',
+    'error',
+    'scrollback',
+    'attached',
+    'detached',
+    'reattached',
+    'enrolled'
+]);
+/** Frame types that must carry a session id. */
+const SESSION_FRAME_TYPES = new Set([
+    'open',
+    'input',
+    'resize',
+    'signal',
+    'detach',
+    'reattach',
+    'close',
+    'output',
+    'exit',
+    'scrollback',
+    'detached',
+    'reattached'
+]);
+const SIGNALS = new Set(exports.SIGNAL_NAMES);
+/**
+ * Terminal geometry a pty will accept. A resize is a client-supplied pair of
+ * numbers that ends up in `ioctl(TIOCSWINSZ)`, so it is validated here rather
+ * than trusted: zero, negative, fractional or absurd values are a protocol
+ * fault, not something to clamp silently.
+ */
+const MAX_DIMENSION = 1000;
+function validDimension(value) {
+    return (typeof value === 'number' &&
+        Number.isInteger(value) &&
+        value > 0 &&
+        value <= MAX_DIMENSION);
+}
+function encodeFrame(frame) {
+    return JSON.stringify(frame);
+}
+/**
+ * Parse one wire message into a frame. Malformed input is a protocol fault on
+ * the sending socket, so this throws rather than returning a placeholder —
+ * the caller decides whether that closes the connection.
+ */
+function decodeFrame(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`machine-protocol: frame is not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('machine-protocol: frame is not an object');
+    }
+    const frame = parsed;
+    const type = frame.type;
+    if (typeof type !== 'string' || !FRAME_TYPES.has(type)) {
+        throw new Error(`machine-protocol: unknown frame type '${String(type)}'`);
+    }
+    if (SESSION_FRAME_TYPES.has(type) && typeof frame.sessionId !== 'string') {
+        throw new Error(`machine-protocol: '${type}' frame is missing sessionId`);
+    }
+    switch (type) {
+        case 'open':
+            if (typeof frame.command !== 'string' || frame.command.length === 0) {
+                throw new Error("machine-protocol: 'open' frame is missing command");
+            }
+            if (frame.cols !== undefined || frame.rows !== undefined) {
+                if (!validDimension(frame.cols) || !validDimension(frame.rows)) {
+                    throw new Error(`machine-protocol: 'open' frame needs integer cols/rows in 1..${MAX_DIMENSION}`);
+                }
+            }
+            break;
+        case 'input':
+        case 'output':
+            if (typeof frame.data !== 'string') {
+                throw new Error(`machine-protocol: '${type}' frame is missing data`);
+            }
+            break;
+        case 'resize':
+            if (!validDimension(frame.cols) || !validDimension(frame.rows)) {
+                throw new Error(`machine-protocol: 'resize' frame needs integer cols/rows in 1..${MAX_DIMENSION}`);
+            }
+            break;
+        case 'reattach':
+            // Geometry is optional on a reattach (a client may want the size the
+            // session already has), but a supplied one is held to the same bounds.
+            if (frame.cols !== undefined || frame.rows !== undefined) {
+                if (!validDimension(frame.cols) || !validDimension(frame.rows)) {
+                    throw new Error(`machine-protocol: 'reattach' frame needs integer cols/rows in 1..${MAX_DIMENSION}`);
+                }
+            }
+            break;
+        case 'signal':
+            if (typeof frame.signal !== 'string' || !SIGNALS.has(frame.signal)) {
+                throw new Error(`machine-protocol: 'signal' frame has unknown signal '${String(frame.signal)}'`);
+            }
+            break;
+        case 'scrollback':
+            if (typeof frame.data !== 'string' || typeof frame.truncated !== 'boolean') {
+                throw new Error("machine-protocol: 'scrollback' frame is missing data/truncated");
+            }
+            break;
+        case 'reattached':
+            if (typeof frame.state !== 'string' || typeof frame.lastSeq !== 'string') {
+                throw new Error("machine-protocol: 'reattached' frame is missing state/lastSeq");
+            }
+            break;
+        case 'exit':
+            if (typeof frame.exitCode !== 'number') {
+                throw new Error("machine-protocol: 'exit' frame is missing exitCode");
+            }
+            break;
+        case 'error':
+            if (typeof frame.message !== 'string') {
+                throw new Error("machine-protocol: 'error' frame is missing message");
+            }
+            break;
+        case 'attached':
+            if (typeof frame.machineId !== 'string') {
+                throw new Error("machine-protocol: 'attached' frame is missing machineId");
+            }
+            break;
+        case 'enrolled':
+            if (typeof frame.machineId !== 'string' || typeof frame.principalId !== 'string') {
+                throw new Error("machine-protocol: 'enrolled' frame is missing machineId/principalId");
+            }
+            if (typeof frame.credential !== 'string' || typeof frame.expiresAt !== 'number') {
+                throw new Error("machine-protocol: 'enrolled' frame is missing credential/expiresAt");
+            }
+            break;
+    }
+    return frame;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@constructive-db/machine-protocol",
+  "version": "0.1.0",
+  "description": "Wire protocol shared by the machine relay and the machine runner: the JSON frames a session is made of, and the codec that refuses malformed ones.",
+  "author": "Constructive <developers@constructive.io>",
+  "license": "MIT",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.4",
+    "jest": "^29.7.0",
+    "makage": "^0.1.12",
+    "ts-jest": "^29.2.0",
+    "typescript": "^5.1.6"
+  },
+  "scripts": {
+    "build": "makage build && cp LICENSE dist/LICENSE",
+    "build:dev": "makage build --dev && cp LICENSE dist/LICENSE",
+    "clean": "makage clean",
+    "lint": "eslint . --fix",
+    "test": "jest"
+  }
+}

package/token.d.ts

@@ -0,0 +1,13 @@
+/**
+ * How an enrollment token is stored and compared.
+ *
+ * The `machine` row keeps a hash, never the token: the runner holds the only
+ * copy of the secret, and a database dump of the machines table hands out no
+ * shells. Enrollment hashes the token it generated with this function, and the
+ * relay hashes what a socket presented and compares the two — in constant time,
+ * so the comparison leaks nothing about how much of a prefix matched.
+ */
+/** The hash stored in `machine.token_hash` for an enrollment token. */
+export declare function hashMachineToken(token: string): string;
+/** Constant-time comparison of two token hashes. */
+export declare function machineTokenHashMatches(expected: string, presented: string): boolean;

package/token.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * How an enrollment token is stored and compared.
+ *
+ * The `machine` row keeps a hash, never the token: the runner holds the only
+ * copy of the secret, and a database dump of the machines table hands out no
+ * shells. Enrollment hashes the token it generated with this function, and the
+ * relay hashes what a socket presented and compares the two — in constant time,
+ * so the comparison leaks nothing about how much of a prefix matched.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashMachineToken = hashMachineToken;
+exports.machineTokenHashMatches = machineTokenHashMatches;
+const crypto_1 = require("crypto");
+/** The hash stored in `machine.token_hash` for an enrollment token. */
+function hashMachineToken(token) {
+    return (0, crypto_1.createHash)('sha256').update(token, 'utf8').digest('hex');
+}
+/** Constant-time comparison of two token hashes. */
+function machineTokenHashMatches(expected, presented) {
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(presented, 'utf8');
+    if (a.length !== b.length)
+        return false;
+    return (0, crypto_1.timingSafeEqual)(a, b);
+}