@north-light/api 0.3.580 → 0.3.587

package/dist/daemon/machine-link/config.d.ts

@@ -0,0 +1,45 @@
+import { CrtrError } from '../../core/errors.js';
+/** The Northlight account, as the directory names it (`account` of the sign-in poll). */
+export interface NorthlightAccount {
+    id: string;
+    display: string;
+}
+/** `directoryUrl` is the directory the person signs in against (`crtr sys signin`).
+ *  `account` is the account the records moved into, kept only to name it when another account signs in; a Mac moved before it existed has none. */
+export interface MachineConfig {
+    apiUrl: string;
+    environmentId: string;
+    runId: string;
+    directoryUrl: string;
+    account?: NorthlightAccount;
+}
+export declare const machineConfigPath: () => string;
+export declare const machineCredentialPath: () => string;
+/** The machine config, or undefined when this install is not an imported machine. A present but malformed file throws. */
+export declare function readMachineConfig(): MachineConfig | undefined;
+export declare function writeMachineConfig(config: MachineConfig): void;
+export declare function readMachineCredential(): string;
+export declare function writeMachineCredential(secret: string): void;
+/** A move to Northlight in progress. `running`: the cloud run has not reached `done`, so a failure undoes the move. `committed`: the account holds the
+ *  records and only the switch-over (machine credential, `machine.json`, restart) is left. `activated`: the machine-role daemon is up, so the switch-over is
+ *  complete and commands run; the record stays only until `notified` — the asking node's message is stored in the account — is true, then it is deleted. */
+export interface MoveRecord {
+    runId: string;
+    apiUrl: string;
+    directoryUrl: string;
+    account: NorthlightAccount;
+    notify: string | null;
+    state: 'running' | 'committed' | 'activated';
+    notified: boolean;
+    /** The exporter's process, so a later `crtr sys signin` can tell a running move from one whose exporter was killed. */
+    pid: number;
+}
+export declare const moveRecordPath: () => string;
+/** The move record, or undefined when no move is running or unfinished. A present but malformed file throws. */
+export declare function readMoveRecord(): MoveRecord | undefined;
+export declare function writeMoveRecord(record: MoveRecord): void;
+export declare function deleteMoveRecord(): void;
+/** Whether a move's records are in the Northlight account but this computer has not switched over (the record says `committed`). */
+export declare const isMoveCommitted: () => boolean;
+/** The one `move_unfinished` error: every command, `crtr sys import resume` and a move whose switch-over failed answer it alike (exit code USAGE, as `not_signed_in`). */
+export declare const moveUnfinishedError: (reason?: string) => CrtrError;

package/dist/daemon/machine-link/config.js

@@ -0,0 +1,63 @@
+// src/daemon/machine-link/config.ts — what a Mac knows about its own machine environment after import (design-import I13):
+// `runtime/machine.json` ({apiUrl, environmentId, runId, directoryUrl, account}, written by the exporter's finish step) and the machine credential at
+// `runtime/secrets/machine-credential` (mode 0600). A Mac with no `machine.json` is a local control plane, not a machine.
+// Also the move record `runtime/import/move.json` (0600): where a move to Northlight that `crtr sys signin` started stands, from before the drain until the
+// computer has switched over (design-crtr-northlight-signin component 4).
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { runtimeRoot, secretsDir } from '../../core/layout.js';
+import { CrtrError } from '../../core/errors.js';
+import { atomicWriteJson } from '../../core/fs-utils.js';
+import { ExitCode } from '../../types.js';
+export const machineConfigPath = () => join(runtimeRoot(), 'machine.json');
+export const machineCredentialPath = () => join(secretsDir(), 'machine-credential');
+/** The machine config, or undefined when this install is not an imported machine. A present but malformed file throws. */
+export function readMachineConfig() {
+    const path = machineConfigPath();
+    if (!existsSync(path))
+        return undefined;
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (typeof raw.apiUrl !== 'string' || typeof raw.environmentId !== 'string' || typeof raw.runId !== 'string' || typeof raw.directoryUrl !== 'string')
+        throw new Error(`${path} must hold {apiUrl, environmentId, runId, directoryUrl}`);
+    const account = raw.account !== undefined && typeof raw.account?.id === 'string' && typeof raw.account.display === 'string' ? { id: raw.account.id, display: raw.account.display } : undefined;
+    return { apiUrl: raw.apiUrl, environmentId: raw.environmentId, runId: raw.runId, directoryUrl: raw.directoryUrl, ...(account === undefined ? {} : { account }) };
+}
+export function writeMachineConfig(config) {
+    mkdirSync(dirname(machineConfigPath()), { recursive: true });
+    writeFileSync(machineConfigPath(), `${JSON.stringify(config, null, 2)}\n`);
+}
+export function readMachineCredential() {
+    const path = machineCredentialPath();
+    if (!existsSync(path))
+        throw new Error(`no machine credential at ${path}`);
+    return readFileSync(path, 'utf8').trim();
+}
+export function writeMachineCredential(secret) {
+    const path = machineCredentialPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${secret}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+export const moveRecordPath = () => join(runtimeRoot(), 'import', 'move.json');
+/** The move record, or undefined when no move is running or unfinished. A present but malformed file throws. */
+export function readMoveRecord() {
+    const path = moveRecordPath();
+    if (!existsSync(path))
+        return undefined;
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (typeof raw.runId !== 'string' || typeof raw.apiUrl !== 'string' || typeof raw.directoryUrl !== 'string' || (raw.state !== 'running' && raw.state !== 'committed' && raw.state !== 'activated')
+        || typeof raw.account?.id !== 'string' || typeof raw.account.display !== 'string')
+        throw new Error(`${path} is not a move record`);
+    return { runId: raw.runId, apiUrl: raw.apiUrl, directoryUrl: raw.directoryUrl, account: { id: raw.account.id, display: raw.account.display },
+        notify: typeof raw.notify === 'string' ? raw.notify : null, state: raw.state, notified: raw.notified === true, pid: typeof raw.pid === 'number' ? raw.pid : 0 };
+}
+export function writeMoveRecord(record) {
+    atomicWriteJson(moveRecordPath(), record, { mode: 0o600 });
+}
+export function deleteMoveRecord() {
+    rmSync(moveRecordPath(), { force: true });
+}
+/** Whether a move's records are in the Northlight account but this computer has not switched over (the record says `committed`). */
+export const isMoveCommitted = () => readMoveRecord()?.state === 'committed';
+/** The one `move_unfinished` error: every command, `crtr sys import resume` and a move whose switch-over failed answer it alike (exit code USAGE, as `not_signed_in`). */
+export const moveUnfinishedError = (reason) => new CrtrError('move_unfinished', `crtr's records are already in your Northlight account, but this computer has not switched over${reason === undefined ? '.' : `: ${reason}`}`, ExitCode.USAGE, { next: 'Run `crtr sys signin` to finish.' });

package/dist/daemon/machine-link/credential.d.ts

@@ -0,0 +1,7 @@
+/** True when the environment has an unrevoked credential. */
+export declare function hasMachineCredential(environmentId: string): Promise<boolean>;
+/** Mint (or replace) the environment's credential and return the secret. */
+export declare function mintMachineCredential(environmentId: string): Promise<string>;
+export declare function revokeMachineCredential(environmentId: string): Promise<void>;
+/** True when `token` is the environment's current, unrevoked credential. */
+export declare function verifyMachineCredential(environmentId: string, token: string): Promise<boolean>;

package/dist/daemon/machine-link/credential.js

@@ -0,0 +1,24 @@
+// src/daemon/machine-link/credential.ts — the machine credential (design-import I13): the secret a Mac's crtrd presents on its link.
+// One row per machine environment in `machine_credentials` holding the sha256 hash; revoking sets `revoked_at`, minting again replaces the
+// hash (rotation). The plaintext is returned once and kept nowhere.
+import { createHash, randomBytes } from 'node:crypto';
+import { openDb } from '../../core/canvas/db.js';
+const hash = (token) => createHash('sha256').update(token).digest('hex');
+/** True when the environment has an unrevoked credential. */
+export async function hasMachineCredential(environmentId) {
+    return await (await openDb()).prepare('SELECT 1 AS ok FROM machine_credentials WHERE environment = ? AND revoked_at IS NULL').get(environmentId) !== undefined;
+}
+/** Mint (or replace) the environment's credential and return the secret. */
+export async function mintMachineCredential(environmentId) {
+    const token = `mc_${randomBytes(32).toString('base64url')}`;
+    await (await openDb()).prepare(`INSERT INTO machine_credentials (environment, token_hash, issued_at, revoked_at) VALUES (?, ?, ?, NULL)
+    ON CONFLICT (environment) DO UPDATE SET token_hash = EXCLUDED.token_hash, issued_at = EXCLUDED.issued_at, revoked_at = NULL`).run(environmentId, hash(token), new Date().toISOString());
+    return token;
+}
+export async function revokeMachineCredential(environmentId) {
+    await (await openDb()).prepare('UPDATE machine_credentials SET revoked_at = ? WHERE environment = ? AND revoked_at IS NULL').run(new Date().toISOString(), environmentId);
+}
+/** True when `token` is the environment's current, unrevoked credential. */
+export async function verifyMachineCredential(environmentId, token) {
+    return await (await openDb()).prepare('SELECT 1 AS ok FROM machine_credentials WHERE environment = ? AND token_hash = ? AND revoked_at IS NULL').get(environmentId, hash(token)) !== undefined;
+}

package/dist/daemon/machine-link/forward.d.ts

@@ -0,0 +1,16 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { BrokerViewLink } from '../../core/runtime/view-socket.js';
+import { type MachineLinkRefusal } from './holder.js';
+/** Unsent bytes on a viewer WebSocket above which the channel is closed (a viewer that cannot keep up is dropped, never buffered without bound). */
+export declare const VIEW_BUFFER_LIMIT_BYTES: number;
+/** A viewer channel to a node on a machine: over the link this process holds, or forwarded to the API process that does. */
+export declare function openMachineView(environmentId: string, nodeId: string): BrokerViewLink;
+/** One readiness check: the Mac connected the node's view.sock within `timeoutMs`. */
+export declare function probeMachineView(environmentId: string, nodeId: string, timeoutMs: number): Promise<boolean>;
+/** Wait for the node's broker on the Mac to accept a viewer, retrying while its view.sock refuses; false on the deadline or when the launch exits. */
+export declare function waitForMachineView(environmentId: string, nodeId: string, exited: Promise<unknown> | undefined, waitMs: number): Promise<boolean>;
+/** The environment id of a forwarded viewer upgrade path, or null for any other path. */
+export declare function machineViewEnvironment(req: IncomingMessage): string | null;
+/** The holder's side: authenticate the forwarding API process, open a channel on the link this process holds and pipe it. Returns a refusal for the caller to write, or null once upgraded. */
+export declare function handleMachineViewUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, environmentId: string): MachineLinkRefusal | null;

package/dist/daemon/machine-link/forward.js

@@ -0,0 +1,181 @@
+// src/daemon/machine-link/forward.ts — a viewer's channel to a Mac, from whichever API process the viewer reached (design-import I13).
+//
+// The link is held by one API process (`holder.ts`). A viewer that reaches another API process opens a cluster-internal WebSocket to the
+// holder at `machine_links.api_address`, on `/v1/machines/<environment>/view?node=<node>`, authenticated with an HMAC of the environment
+// id under the secrets key every API process shares. The frames on it are the link's own `view.ready` / `view.data` / `view.close` with
+// the channel left empty; the holder opens a `MachineViewLink` on the held link and pipes it.
+import { EventEmitter } from 'node:events';
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { WebSocket, WebSocketServer } from 'ws';
+import { openDb } from '../../core/canvas/db.js';
+import { loadSecretsKey } from '../../core/secrets/key.js';
+import { LINK_MAX_PAYLOAD_BYTES, parseFrame } from './frames.js';
+import { apiAddress, heldLinkOf, MachineViewLink, UNROUTABLE_PREFIX } from './holder.js';
+/** Unsent bytes on a viewer WebSocket above which the channel is closed (a viewer that cannot keep up is dropped, never buffered without bound). */
+export const VIEW_BUFFER_LIMIT_BYTES = 8 * 1024 * 1024;
+const CLOSE_SLOW_VIEWER = 1013;
+const FORWARD_PATH = /^\/v1\/machines\/([A-Za-z0-9_-]+)\/view$/;
+const wss = new WebSocketServer({ noServer: true, maxPayload: LINK_MAX_PAYLOAD_BYTES });
+const forwardToken = (environmentId) => createHmac('sha256', loadSecretsKey().key).update(`machine-view:${environmentId}`).digest('hex');
+/** A viewer channel to a node on a machine: over the link this process holds, or forwarded to the API process that does. */
+export function openMachineView(environmentId, nodeId) {
+    const held = heldLinkOf(environmentId);
+    return held !== null ? new MachineViewLink(held, nodeId) : new ForwardedViewLink(environmentId, nodeId);
+}
+/** The relay's end of a channel whose link another API process holds. Looks the holder up, connects, then relays frames both ways. */
+class ForwardedViewLink extends EventEmitter {
+    environmentId;
+    nodeId;
+    ws;
+    ended = false;
+    failed = false;
+    queued = [];
+    queuedBytes = 0;
+    constructor(environmentId, nodeId) {
+        super();
+        this.environmentId = environmentId;
+        this.nodeId = nodeId;
+        this.dial().catch((error) => this.finish(error instanceof Error ? error.message : String(error)));
+    }
+    get destroyed() { return this.ended; }
+    write(line) {
+        if (this.ended)
+            return false;
+        if (this.ws?.readyState !== WebSocket.OPEN) {
+            this.queuedBytes += line.length;
+            if (this.queuedBytes > VIEW_BUFFER_LIMIT_BYTES) {
+                this.finish('machine view: the holder did not accept the channel before its queue filled');
+                return false;
+            }
+            this.queued.push(line);
+            return true;
+        }
+        if (this.ws.bufferedAmount > VIEW_BUFFER_LIMIT_BYTES) {
+            this.finish('machine view: the holder is not draining the channel');
+            return false;
+        }
+        this.sendData(line);
+        return true;
+    }
+    destroy() {
+        if (!this.ended) {
+            if (this.ws?.readyState === WebSocket.OPEN)
+                this.ws.send(JSON.stringify({ type: 'view.close', channel: '' }));
+            this.finish(undefined);
+        }
+        return this;
+    }
+    sendData(bytes) { this.ws?.send(JSON.stringify({ type: 'view.data', channel: '', bytes: Buffer.from(bytes).toString('base64') })); }
+    async dial() {
+        const row = await (await openDb()).prepare('SELECT api_address, lease_expires_at FROM machine_links WHERE environment = ?').get(this.environmentId);
+        if (row === undefined || Date.parse(row.lease_expires_at) <= Date.now())
+            throw new Error(`machine_offline: machine ${this.environmentId} has no live link`);
+        if (row.api_address.startsWith(UNROUTABLE_PREFIX))
+            throw new Error(`machine_unreachable: the API process holding the link wrote ${row.api_address}; set CRTR_API_ADDRESS or listen on TCP`);
+        if (row.api_address === apiAddress())
+            throw new Error(`machine_offline: the link row names this API process (${row.api_address}) but it holds no link`);
+        if (this.ended)
+            return;
+        const url = new URL(`/v1/machines/${encodeURIComponent(this.environmentId)}/view`, row.api_address.includes('://') ? row.api_address : `ws://${row.api_address}`);
+        url.protocol = url.protocol === 'https:' ? 'wss:' : url.protocol === 'http:' ? 'ws:' : url.protocol;
+        url.searchParams.set('node', this.nodeId);
+        const ws = new WebSocket(url.toString(), { headers: { authorization: `Bearer ${forwardToken(this.environmentId)}` }, maxPayload: LINK_MAX_PAYLOAD_BYTES });
+        this.ws = ws;
+        ws.on('open', () => { for (const line of this.queued.splice(0))
+            this.sendData(line); });
+        ws.on('unexpected-response', (_req, res) => { res.resume(); this.finish(res.statusCode === 409 ? 'machine_offline: the holder no longer holds the link' : `machine view refused by ${row.api_address}: ${res.statusCode}`); });
+        ws.on('message', (data) => {
+            const frame = parseFrame(data);
+            if (frame === null)
+                return;
+            if (frame.type === 'view.ready')
+                this.emit('connect');
+            else if (frame.type === 'view.data')
+                this.emit('data', Buffer.from(frame.bytes, 'base64'));
+            else if (frame.type === 'view.close')
+                this.finish(frame.error);
+        });
+        ws.on('error', (error) => this.finish(error.message));
+        ws.on('close', () => this.finish('machine view forward closed'));
+    }
+    finish(error) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.ws?.close();
+        if (error !== undefined && !this.failed) {
+            this.failed = true;
+            this.emit('error', Object.assign(new Error(error), { code: 'ECONNRESET' }));
+        }
+        this.emit('close', this.failed);
+    }
+}
+/** One readiness check: the Mac connected the node's view.sock within `timeoutMs`. */
+export function probeMachineView(environmentId, nodeId, timeoutMs) {
+    return new Promise((resolve) => {
+        const view = openMachineView(environmentId, nodeId);
+        const timer = setTimeout(() => { resolve(false); view.destroy(); }, timeoutMs);
+        view.on('connect', () => { clearTimeout(timer); resolve(true); view.destroy(); });
+        view.on('error', () => { });
+        view.on('close', () => { clearTimeout(timer); resolve(false); });
+    });
+}
+/** Wait for the node's broker on the Mac to accept a viewer, retrying while its view.sock refuses; false on the deadline or when the launch exits. */
+export async function waitForMachineView(environmentId, nodeId, exited, waitMs) {
+    const deadline = Date.now() + waitMs;
+    let exitSeen = false;
+    void exited?.then(() => { exitSeen = true; });
+    while (Date.now() <= deadline && !exitSeen) {
+        if (await probeMachineView(environmentId, nodeId, Math.max(1, Math.min(2000, deadline - Date.now()))))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    return false;
+}
+/** The environment id of a forwarded viewer upgrade path, or null for any other path. */
+export function machineViewEnvironment(req) {
+    const match = FORWARD_PATH.exec(new URL(req.url ?? '/', 'http://runtime.local').pathname);
+    return match === null ? null : match[1];
+}
+/** The holder's side: authenticate the forwarding API process, open a channel on the link this process holds and pipe it. Returns a refusal for the caller to write, or null once upgraded. */
+export function handleMachineViewUpgrade(req, socket, head, environmentId) {
+    const header = req.headers['authorization'];
+    const token = /^Bearer (\S+)$/.exec(Array.isArray(header) ? header[0] ?? '' : header ?? '')?.[1] ?? '';
+    const expected = Buffer.from(forwardToken(environmentId));
+    const given = Buffer.from(token);
+    if (given.length !== expected.length || !timingSafeEqual(given, expected))
+        return { status: 401, text: 'Unauthorized', code: 'unauthorized', message: 'machine view forward credential refused' };
+    const node = new URL(req.url ?? '/', 'http://runtime.local').searchParams.get('node');
+    if (node === null || node === '')
+        return { status: 400, text: 'Bad Request', code: 'bad_request', message: 'node is required' };
+    const held = heldLinkOf(environmentId);
+    if (held === null)
+        return { status: 409, text: 'Conflict', code: 'machine_offline', message: 'this API process holds no link for the machine' };
+    wss.handleUpgrade(req, socket, head, (ws) => {
+        const view = new MachineViewLink(held, node);
+        const send = (frame) => { if (ws.readyState === WebSocket.OPEN)
+            ws.send(JSON.stringify(frame)); };
+        view.on('connect', () => send({ type: 'view.ready', channel: '' }));
+        view.on('data', (chunk) => {
+            // The Mac's pause bounds only its own WebSocket; a viewer that stops reading would otherwise grow this process's send buffer without limit.
+            if (ws.bufferedAmount > VIEW_BUFFER_LIMIT_BYTES) {
+                view.destroy();
+                ws.close(CLOSE_SLOW_VIEWER, 'viewer too slow');
+                return;
+            }
+            send({ type: 'view.data', channel: '', bytes: chunk.toString('base64') });
+        });
+        view.on('error', (error) => send({ type: 'view.close', channel: '', error: error.message }));
+        view.on('close', () => ws.close());
+        ws.on('message', (data) => {
+            const frame = parseFrame(data);
+            if (frame?.type === 'view.data')
+                view.write(Buffer.from(frame.bytes, 'base64'));
+            else if (frame?.type === 'view.close')
+                view.destroy();
+        });
+        ws.on('close', () => view.destroy());
+        ws.on('error', () => view.destroy());
+    });
+    return null;
+}

package/dist/daemon/machine-link/frames.d.ts

@@ -0,0 +1,49 @@
+import type { MachineOp } from '../../core/runtime/runner/machine/ops.js';
+export type MachineFrame = 
+/** holder → Mac: run `op`. */
+{
+    type: 'call';
+    call_id: string;
+    op: MachineOp;
+    args: unknown;
+}
+/** Mac → holder: the call's outcome. */
+ | {
+    type: 'result';
+    call_id: string;
+    ok: true;
+    value: unknown;
+} | {
+    type: 'result';
+    call_id: string;
+    ok: false;
+    error: string;
+}
+/** holder → Mac: open a viewer channel to `node`'s view.sock. */
+ | {
+    type: 'view.open';
+    channel: string;
+    node: string;
+}
+/** Mac → holder: the channel's view.sock accepted the connection. */
+ | {
+    type: 'view.ready';
+    channel: string;
+}
+/** Either way: base64 bytes of the view.sock stream. */
+ | {
+    type: 'view.data';
+    channel: string;
+    bytes: string;
+}
+/** Either way: the channel ended; `error` when it failed (the Mac could not reach the view.sock). */
+ | {
+    type: 'view.close';
+    channel: string;
+    error?: string;
+};
+export declare const LINK_MAX_PAYLOAD_BYTES: number;
+/** WebSocket close codes of the holder: a newer link took the environment's row; the credential is revoked (the Mac does not reconnect with it). */
+export declare const CLOSE_SUPERSEDED = 4001;
+export declare const CLOSE_REVOKED = 4003;
+export declare function parseFrame(data: Buffer | ArrayBuffer | Buffer[]): MachineFrame | null;

package/dist/daemon/machine-link/frames.js

@@ -0,0 +1,25 @@
+export const LINK_MAX_PAYLOAD_BYTES = 32 * 1024 * 1024;
+/** WebSocket close codes of the holder: a newer link took the environment's row; the credential is revoked (the Mac does not reconnect with it). */
+export const CLOSE_SUPERSEDED = 4001;
+export const CLOSE_REVOKED = 4003;
+export function parseFrame(data) {
+    const buf = Array.isArray(data) ? Buffer.concat(data) : Buffer.isBuffer(data) ? data : Buffer.from(new Uint8Array(data));
+    try {
+        const frame = JSON.parse(buf.toString('utf8'));
+        if (typeof frame !== 'object' || frame === null)
+            return null;
+        const strings = (...keys) => keys.every((key) => typeof frame[key] === 'string');
+        switch (frame['type']) {
+            case 'call': return strings('call_id', 'op') ? frame : null;
+            case 'result': return strings('call_id') && (frame['ok'] === true || (frame['ok'] === false && strings('error'))) ? frame : null;
+            case 'view.open': return strings('channel', 'node') ? frame : null;
+            case 'view.ready':
+            case 'view.close': return strings('channel') ? frame : null;
+            case 'view.data': return strings('channel', 'bytes') ? frame : null;
+            default: return null;
+        }
+    }
+    catch {
+        return null;
+    }
+}

package/dist/daemon/machine-link/holder.d.ts

@@ -0,0 +1,73 @@
+import { EventEmitter } from 'node:events';
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { WebSocket } from 'ws';
+import type { BrokerViewLink } from '../../core/runtime/view-socket.js';
+import { type MachineFrame } from './frames.js';
+export declare const LINK_LEASE_MS = 45000;
+export declare const LINK_RENEW_MS = 15000;
+export declare const LINK_PING_MS = 30000;
+/** Prefix of the address an API process writes when nothing tells it where other API processes can reach it; the viewer forward refuses it. */
+export declare const UNROUTABLE_PREFIX = "unroutable:";
+/** The TCP listener's bound `host:port`, used as this process's address when `CRTR_API_ADDRESS` is not set. */
+export declare const setApiAddress: (address: string) => void;
+/** The address other API processes find this one at, written to `machine_links.api_address`: `CRTR_API_ADDRESS`, else the listener's bound address, else an unroutable marker. */
+export declare const apiAddress: () => string;
+export declare class HeldLink extends EventEmitter {
+    readonly environmentId: string;
+    readonly generation: number;
+    readonly ws: WebSocket;
+    private readonly token;
+    private readonly timers;
+    private unsubscribe;
+    private claiming;
+    private closed;
+    private alive;
+    readonly channels: Map<string, MachineViewLink>;
+    constructor(environmentId: string, generation: number, ws: WebSocket, token: string);
+    start(): void;
+    private fault;
+    send(frame: MachineFrame): boolean;
+    /** Renew the row, my sent calls' leases and `last_seen_at`; a lost generation or a revoked credential closes the link. */
+    renew(): Promise<void>;
+    /** The credential this link authenticated with is still the environment's current one: rotation or revocation evicts the link. */
+    private credentialValid;
+    /** Claim this environment's pending calls (fenced by this link's generation) and forward them. */
+    claim(): Promise<void>;
+    /** `sent` is whether the call was written to the link: a call that was sent may have run, one that was not ran nowhere. */
+    private failCall;
+    /** This link's generation is still the one in the environment's `machine_links` row. */
+    private isCurrentGeneration;
+    /** Give a claimed, unsent call back to `pending`. */
+    private release;
+    /** Settle a call this link holds; a call another holder owns or one already settled is left as it is. A result settles only
+     *  while this link is the current generation (`requireCurrent`); a failure for a dropped link settles whatever the row now says. */
+    private settle;
+    private onMessage;
+    private teardown;
+}
+/** A viewer channel to one node's view.sock on the Mac, as the relay's broker-side link. */
+export declare class MachineViewLink extends EventEmitter implements BrokerViewLink {
+    private readonly link;
+    private ended;
+    private failed;
+    private readonly channel;
+    constructor(link: HeldLink, nodeId: string);
+    get destroyed(): boolean;
+    write(line: string | Buffer): boolean;
+    destroy(): this;
+    /** The channel is over: `error` names a failure (the relay records a fault), none is a clean end. */
+    finish(error: string | undefined): void;
+}
+/** The link this process holds for `environmentId`, or null (no link, or another API process holds it). */
+export declare const heldLinkOf: (environmentId: string) => HeldLink | null;
+/** The environment id of a machine-link upgrade path, or null for any other path. */
+export declare function machineLinkEnvironment(req: IncomingMessage): string | null;
+export interface MachineLinkRefusal {
+    status: number;
+    text: string;
+    code: string;
+    message: string;
+}
+/** Authenticate the machine credential and take over the environment's link. Returns a refusal for the caller to write, or null once upgraded. */
+export declare function handleMachineLinkUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, environmentId: string): Promise<MachineLinkRefusal | null>;