@pellux/goodvibes-daemon-sdk 1.6.0 → 1.7.0

package/dist/operator.js

@@ -28,8 +28,8 @@ const INVALID_ENCODING_RESPONSE = Response.json({ error: 'INVALID_PATH_ENCODING'
  *   authenticated session per handler implementation.
  * - STATE-CHANGING routes (service install/start/stop, route bindings,
  *   automation jobs, knowledge ingest) — always `withAdmin(context, req, ...)`.
- * - SCHEDULER/RUNTIME routes (getSchedulerCapacity, getRuntimeMetrics) —
- *   require admin per handler implementation.
+ * - SCHEDULER routes (getSchedulerCapacity) — require admin per handler
+ *   implementation.
  *
  * Dispatcher does not short-circuit unauthenticated requests; all auth
  * enforcement lives in the handler factories (system-routes.ts,
@@ -488,8 +488,10 @@ async function dispatchOperatorRoutesInner(req, handlers) {
         return handlers.deleteBootstrapFile(req);
     if (pathname === '/api/runtime/scheduler' && method === 'GET')
         return handlers.getSchedulerCapacity(req);
-    if (pathname === '/api/runtime/metrics' && method === 'GET')
-        return handlers.getRuntimeMetrics();
+    // GET /api/runtime/metrics is served by the gateway-REST parity table
+    // (gateway-rest-routes.ts → runtime.metrics.get), which dispatchDaemonApiRoutes
+    // tries ahead of this dispatcher. The raw handler that once lived here was
+    // removed to consolidate on the single gateway-verb mechanism.
     if (pathname === '/api/panels' && method === 'GET')
         return handlers.getPanels();
     if (pathname === '/api/panels/open' && method === 'POST')

package/dist/relay-registration.d.ts

@@ -0,0 +1,58 @@
+import { type RelayKeyPair, type RelayPairingPayload } from '@pellux/goodvibes-transport-core/relay';
+/** Structural client WebSocket the daemon uses to dial the relay. */
+export interface RelayClientWebSocket {
+    binaryType: string;
+    send(data: string | Uint8Array | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'open' | 'message' | 'close' | 'error', listener: (event: unknown) => void): void;
+}
+/** Header set on every relay-tunneled request so downstream can tell it apart. */
+export declare const RELAY_VIA_HEADER = "x-goodvibes-via-relay";
+/**
+ * Whether a request arrived over the relay (vs the trusted LAN). Surfaces and
+ * policy hooks use this to show connections as "via relay" and to apply
+ * relay-specific controls such as WebAuthn step-up on mutating calls.
+ */
+export declare function isRelayTunneledRequest(req: Request): boolean;
+/** Lifecycle status of the daemon's relay registration. */
+export type RelayRegistrationStatus = 'idle' | 'connecting' | 'registered' | 'reconnecting' | 'stopped';
+export interface RelayRegistrationLogger {
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+}
+/** Options for {@link createRelayDaemonRegistration}. */
+export interface RelayDaemonRegistrationOptions {
+    /** The relay URL to dial (wss://…). */
+    readonly relayUrl: string;
+    /** The unguessable rendezvous id this daemon registers under. */
+    readonly rid: string;
+    /** The daemon's persistent relay identity key pair. */
+    readonly identity: RelayKeyPair;
+    /** Base URL used to resolve tunneled request paths into local Requests. */
+    readonly localBaseUrl: string;
+    /** Replay a reconstructed request against the daemon; returns null if unrouted. */
+    readonly dispatch: (req: Request) => Promise<Response | null>;
+    /** WebSocket constructor override (defaults to globalThis.WebSocket). */
+    readonly webSocketImpl?: (url: string) => RelayClientWebSocket;
+    /** Reconnect backoff base delay in ms (default 500). */
+    readonly reconnectBaseDelayMs?: number;
+    /** Reconnect backoff cap in ms (default 30000). */
+    readonly reconnectMaxDelayMs?: number;
+    /** Max concurrent event-subscription streams per pipe (default 8). */
+    readonly maxStreamsPerPipe?: number;
+    /** Bounded per-stream send buffer, in chunks; overflow drops-with-notice (default 256). */
+    readonly streamBufferChunks?: number;
+    readonly logger?: RelayRegistrationLogger;
+    readonly onStatusChange?: (status: RelayRegistrationStatus) => void;
+}
+/** A running daemon-side relay registration. */
+export interface RelayDaemonRegistration {
+    start(): void;
+    stop(): void;
+    readonly status: RelayRegistrationStatus;
+    /** Mint a pairing payload a surface can scan to reach this daemon. */
+    mintPairing(label?: string): Promise<RelayPairingPayload>;
+}
+export declare function createRelayDaemonRegistration(options: RelayDaemonRegistrationOptions): RelayDaemonRegistration;
+//# sourceMappingURL=relay-registration.d.ts.map

package/dist/relay-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-registration.d.ts","sourceRoot":"","sources":["../src/relay-registration.ts"],"names":[],"mappings":"AAaA,OAAO,EAeL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACzB,MAAM,wCAAwC,CAAC;AAEhD,qEAAqE;AACrE,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,IAAI,CAAC;IACpD,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;CAC1G;AAED,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,2DAA2D;AAC3D,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,YAAY,GAAG,YAAY,GAAG,cAAc,GAAG,SAAS,CAAC;AAExG,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAChE;AAED,yDAAyD;AACzD,MAAM,WAAW,8BAA8B;IAC7C,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC9D,yEAAyE;IACzE,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,oBAAoB,CAAC;IAC/D,wDAAwD;IACxD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,mDAAmD;IACnD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,sEAAsE;IACtE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,2FAA2F;IAC3F,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC;IAC1C,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,uBAAuB,KAAK,IAAI,CAAC;CACrE;AAED,gDAAgD;AAChD,MAAM,WAAW,uBAAuB;IACtC,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;IACb,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,sEAAsE;IACtE,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC3D;AA8FD,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,8BAA8B,GAAG,uBAAuB,CA4Q9G"}

package/dist/relay-registration.js

@@ -0,0 +1,376 @@
+// relay-registration.ts
+//
+// The daemon half of the relay path. It dials the relay OUTBOUND (so the daemon
+// needs no inbound port or public IP), registers under its rendezvous id, and
+// terminates the end-to-end secure channel INSIDE this process. Tunneled HTTP
+// requests are decrypted here and replayed against the daemon's own route
+// dispatcher, exactly as if they had arrived on the local HTTP listener — the
+// relay only ever moved ciphertext.
+//
+// Reconnect uses the same capped exponential-backoff shape as the transport
+// stream reconnector (base 500ms, ×2, cap 30s). The channel keys are per-pipe
+// and ephemeral, so a reconnect simply re-registers and old pipes are dropped.
+import { RELAY_PROTOCOL_VERSION, RelaySecureChannel, createRelayPairingPayload, decodeControlFrame, decodeTunnelFrame, encodeControlFrame, encodeTunnelFrame, encodeUtf8, framePipePayload, relayIdentityPublicKeyBase64Url, respondToHandshake, toBase64Url, unframePipePayload, } from '@pellux/goodvibes-transport-core/relay';
+/** Header set on every relay-tunneled request so downstream can tell it apart. */
+export const RELAY_VIA_HEADER = 'x-goodvibes-via-relay';
+/**
+ * Whether a request arrived over the relay (vs the trusted LAN). Surfaces and
+ * policy hooks use this to show connections as "via relay" and to apply
+ * relay-specific controls such as WebAuthn step-up on mutating calls.
+ */
+export function isRelayTunneledRequest(req) {
+    return req.headers.get(RELAY_VIA_HEADER) === '1';
+}
+const SILENT = { info: () => { }, warn: () => { }, error: () => { } };
+function defaultWebSocket(url) {
+    const Ctor = globalThis.WebSocket;
+    if (!Ctor)
+        throw new Error('No WebSocket implementation available; provide options.webSocketImpl.');
+    return new Ctor(url);
+}
+function toBytes(data) {
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data.slice(0));
+    if (ArrayBuffer.isView(data))
+        return new Uint8Array(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+    return null;
+}
+const DEFAULT_MAX_STREAMS_PER_PIPE = 8;
+const DEFAULT_STREAM_BUFFER_CHUNKS = 256;
+/**
+ * The daemon-side pump for one event subscription: it seals event-source chunks
+ * into `stream-data` frames and writes them to the relay socket, applying a
+ * bounded buffer so a slow consumer can never make the daemon buffer without
+ * limit. When the buffer is full a chunk is DROPPED and counted, and the next
+ * successful flush emits a `stream-overflow` notice carrying the dropped count —
+ * an honest gap signal, never a silent one. Clean close is explicit in both
+ * directions (`stream-close`).
+ */
+class DaemonStreamPump {
+    streamId;
+    channel;
+    pipeIdBytes;
+    ws;
+    bufferCap;
+    onError;
+    queue = [];
+    dropped = 0;
+    seq = 0;
+    flushing = false;
+    closed = false;
+    constructor(streamId, channel, pipeIdBytes, ws, bufferCap, onError) {
+        this.streamId = streamId;
+        this.channel = channel;
+        this.pipeIdBytes = pipeIdBytes;
+        this.ws = ws;
+        this.bufferCap = bufferCap;
+        this.onError = onError;
+    }
+    enqueue(chunk) {
+        if (this.closed)
+            return;
+        if (this.queue.length >= this.bufferCap) {
+            this.dropped += 1;
+            return;
+        }
+        this.queue.push(chunk);
+        void this.flush();
+    }
+    async flush() {
+        if (this.flushing)
+            return;
+        this.flushing = true;
+        try {
+            while (this.queue.length > 0 && !this.closed) {
+                const chunk = this.queue.shift();
+                const frame = encodeTunnelFrame({ id: this.streamId, kind: 'stream-data', seq: this.seq++ }, chunk);
+                this.ws.send(framePipePayload(this.pipeIdBytes, await this.channel.seal(frame)));
+                if (this.dropped > 0 && !this.closed) {
+                    const dropped = this.dropped;
+                    this.dropped = 0;
+                    const notice = encodeTunnelFrame({ id: this.streamId, kind: 'stream-overflow', dropped }, new Uint8Array(0));
+                    this.ws.send(framePipePayload(this.pipeIdBytes, await this.channel.seal(notice)));
+                }
+            }
+        }
+        catch (error) {
+            this.onError(error);
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    async close(reason) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.queue.length = 0;
+        try {
+            const frame = encodeTunnelFrame({ id: this.streamId, kind: 'stream-close', ...(reason ? { reason } : {}) }, new Uint8Array(0));
+            this.ws.send(framePipePayload(this.pipeIdBytes, await this.channel.seal(frame)));
+        }
+        catch (error) {
+            this.onError(error);
+        }
+    }
+}
+export function createRelayDaemonRegistration(options) {
+    const logger = options.logger ?? SILENT;
+    const makeSocket = options.webSocketImpl ?? defaultWebSocket;
+    const ridBytes = encodeUtf8(options.rid);
+    const baseDelay = options.reconnectBaseDelayMs ?? 500;
+    const maxDelay = options.reconnectMaxDelayMs ?? 30_000;
+    const maxStreamsPerPipe = options.maxStreamsPerPipe ?? DEFAULT_MAX_STREAMS_PER_PIPE;
+    const streamBufferChunks = options.streamBufferChunks ?? DEFAULT_STREAM_BUFFER_CHUNKS;
+    let status = 'idle';
+    let socket = null;
+    let stopped = false;
+    let attempt = 0;
+    let reconnectTimer = null;
+    const channels = new Map();
+    // Per-pipe live event subscriptions: pipeKey -> (streamId -> record).
+    const pipeStreams = new Map();
+    function closePipeStreams(pipeKey) {
+        const streams = pipeStreams.get(pipeKey);
+        if (!streams)
+            return;
+        for (const record of streams.values()) {
+            record.reader?.cancel().catch(() => { });
+            void record.pump.close('pipe-closed');
+        }
+        pipeStreams.delete(pipeKey);
+    }
+    function setStatus(next) {
+        status = next;
+        options.onStatusChange?.(next);
+    }
+    function scheduleReconnect() {
+        if (stopped)
+            return;
+        setStatus('reconnecting');
+        const delay = Math.min(baseDelay * 2 ** attempt, maxDelay);
+        attempt += 1;
+        reconnectTimer = setTimeout(openConnection, delay);
+    }
+    async function handleDaemonFrame(pipeIdBytes, payload, ws) {
+        const pipeKey = toBase64Url(pipeIdBytes);
+        const existing = channels.get(pipeKey);
+        if (!existing) {
+            // First frame on a new pipe is the client's handshake initiation.
+            const { keys, message2 } = await respondToHandshake(options.identity, ridBytes, payload);
+            channels.set(pipeKey, new RelaySecureChannel(keys, 'daemon'));
+            ws.send(framePipePayload(pipeIdBytes, message2));
+            return;
+        }
+        await serveTunneledFrame(pipeKey, existing, pipeIdBytes, payload, ws);
+    }
+    async function serveTunneledFrame(pipeKey, channel, pipeIdBytes, sealed, ws) {
+        const framed = decodeTunnelFrame(await channel.open(sealed));
+        if (!framed)
+            return;
+        const header = framed.header;
+        if (header.kind === 'request') {
+            await serveTunneledRequest(header, framed.body, channel, pipeIdBytes, ws);
+            return;
+        }
+        if (header.kind === 'stream-open') {
+            await openTunneledStream(pipeKey, header, channel, pipeIdBytes, ws);
+            return;
+        }
+        if (header.kind === 'stream-close') {
+            closeTunneledStream(pipeKey, header.id);
+            return;
+        }
+        // Other kinds (response, stream-data, stream-overflow) are daemon → surface
+        // only; a surface should never send them. Ignore rather than trust.
+    }
+    async function serveTunneledRequest(header, body, channel, pipeIdBytes, ws) {
+        const request = new Request(new URL(header.path, options.localBaseUrl), {
+            method: header.method,
+            headers: [...header.headers.map(([k, v]) => [k, v]), [RELAY_VIA_HEADER, '1']],
+            ...(body.length > 0 ? { body } : {}),
+        });
+        let response;
+        try {
+            response = (await options.dispatch(request)) ?? new Response('Not found', { status: 404 });
+        }
+        catch (err) {
+            logger.error('relay dispatch failed', { error: String(err) });
+            response = new Response('Internal error', { status: 500 });
+        }
+        const bodyBytes = new Uint8Array(await response.arrayBuffer());
+        const respHeaders = [];
+        response.headers.forEach((value, key) => respHeaders.push([key, value]));
+        const out = encodeTunnelFrame({ id: header.id, kind: 'response', status: response.status, headers: respHeaders }, new Uint8Array(bodyBytes.buffer.slice(bodyBytes.byteOffset, bodyBytes.byteOffset + bodyBytes.byteLength)));
+        ws.send(framePipePayload(pipeIdBytes, await channel.seal(out)));
+    }
+    async function openTunneledStream(pipeKey, header, channel, pipeIdBytes, ws) {
+        const streams = pipeStreams.get(pipeKey) ?? new Map();
+        pipeStreams.set(pipeKey, streams);
+        const pump = new DaemonStreamPump(header.id, channel, pipeIdBytes, ws, streamBufferChunks, (error) => logger.error('relay stream send failed', { error: String(error) }));
+        // Per-pipe stream cap: refuse a new stream with an immediate close notice.
+        if (streams.size >= maxStreamsPerPipe || streams.has(header.id)) {
+            await pump.close('stream-limit');
+            return;
+        }
+        const record = { pump, reader: null };
+        streams.set(header.id, record);
+        const request = new Request(new URL(header.path, options.localBaseUrl), {
+            method: header.method,
+            headers: [...header.headers.map(([k, v]) => [k, v]), [RELAY_VIA_HEADER, '1']],
+        });
+        let response;
+        try {
+            response = await options.dispatch(request);
+        }
+        catch (err) {
+            logger.error('relay stream dispatch failed', { error: String(err) });
+            response = null;
+        }
+        if (!response || !response.body) {
+            streams.delete(header.id);
+            await pump.close('no-stream');
+            return;
+        }
+        const reader = response.body.getReader();
+        record.reader = reader;
+        // Pump loop: read the daemon's event source and forward chunks. The await on
+        // each read applies natural backpressure to the source; the pump's bounded
+        // buffer + overflow notice covers the send side.
+        void (async () => {
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (value)
+                        pump.enqueue(new Uint8Array(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength)));
+                }
+                await pump.close('source-ended');
+            }
+            catch (err) {
+                logger.warn('relay stream source error', { error: String(err) });
+                await pump.close('source-error');
+            }
+            finally {
+                streams.delete(header.id);
+                if (streams.size === 0)
+                    pipeStreams.delete(pipeKey);
+            }
+        })();
+    }
+    function closeTunneledStream(pipeKey, streamId) {
+        const streams = pipeStreams.get(pipeKey);
+        const record = streams?.get(streamId);
+        if (!record)
+            return;
+        record.reader?.cancel().catch(() => { });
+        void record.pump.close('client-unsubscribed');
+        streams.delete(streamId);
+        if (streams.size === 0)
+            pipeStreams.delete(pipeKey);
+    }
+    function openConnection() {
+        if (stopped)
+            return;
+        reconnectTimer = null;
+        setStatus(attempt === 0 ? 'connecting' : 'reconnecting');
+        for (const pipeKey of [...pipeStreams.keys()])
+            closePipeStreams(pipeKey);
+        channels.clear();
+        let ws;
+        try {
+            ws = makeSocket(options.relayUrl);
+        }
+        catch (err) {
+            logger.error('relay socket construction failed', { error: String(err) });
+            scheduleReconnect();
+            return;
+        }
+        ws.binaryType = 'arraybuffer';
+        socket = ws;
+        ws.addEventListener('open', () => {
+            ws.send(encodeControlFrame({ t: 'register', role: 'daemon', protocol: RELAY_PROTOCOL_VERSION, rid: options.rid }));
+        });
+        ws.addEventListener('message', (event) => {
+            const data = event.data;
+            void (async () => {
+                try {
+                    if (typeof data === 'string') {
+                        const frame = decodeControlFrame(data);
+                        if (!frame)
+                            return;
+                        if (frame.t === 'registered') {
+                            attempt = 0;
+                            setStatus('registered');
+                            logger.info('relay registered', { rid: options.rid });
+                        }
+                        else if (frame.t === 'pipe-close') {
+                            channels.delete(frame.pipe);
+                            closePipeStreams(frame.pipe);
+                        }
+                        else if (frame.t === 'error') {
+                            logger.warn('relay error frame', { code: frame.code, message: frame.message });
+                        }
+                        return;
+                    }
+                    const bytes = toBytes(data);
+                    if (!bytes)
+                        return;
+                    const split = unframePipePayload(bytes);
+                    if (!split)
+                        return;
+                    await handleDaemonFrame(split.pipeId.slice(), split.payload.slice(), ws);
+                }
+                catch (err) {
+                    logger.error('relay frame handling failed', { error: String(err) });
+                }
+            })();
+        });
+        ws.addEventListener('close', () => {
+            socket = null;
+            if (!stopped)
+                scheduleReconnect();
+        });
+        ws.addEventListener('error', () => {
+            logger.warn('relay websocket error', { rid: options.rid });
+        });
+    }
+    return {
+        start() {
+            if (!stopped && status !== 'idle')
+                return;
+            stopped = false;
+            attempt = 0;
+            openConnection();
+        },
+        stop() {
+            stopped = true;
+            if (reconnectTimer)
+                clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+            for (const pipeKey of [...pipeStreams.keys()])
+                closePipeStreams(pipeKey);
+            channels.clear();
+            try {
+                socket?.close();
+            }
+            catch {
+                // ignore
+            }
+            socket = null;
+            setStatus('stopped');
+        },
+        get status() {
+            return status;
+        },
+        async mintPairing(label) {
+            return createRelayPairingPayload({
+                relayUrl: options.relayUrl,
+                rid: options.rid,
+                daemonPublicKey: await relayIdentityPublicKeyBase64Url(options.identity),
+                ...(label !== undefined ? { label } : {}),
+            });
+        },
+    };
+}

package/dist/relay-server-entry.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env bun
+import { type RelayConnection, type RelayServerLimits, type RelayServerLogger } from './relay-server.js';
+interface RelayConnectionData {
+    conn: RelayConnection | null;
+    readonly addr: string;
+}
+/** Options for {@link createBunRelayServer}. */
+export interface BunRelayServerOptions {
+    /** TCP port to listen on (default 8787). */
+    readonly port?: number;
+    /** Hostname/interface to bind (default all interfaces). */
+    readonly hostname?: string;
+    /** Caps and rate limits (merged over DEFAULT_RELAY_LIMITS). */
+    readonly limits?: Partial<RelayServerLimits>;
+    /** Structured logger (default console). */
+    readonly logger?: RelayServerLogger;
+}
+/**
+ * Start the relay on Bun. Returns the Bun server handle (call `.stop()` to shut
+ * down). The health endpoint `GET /` reports occupancy; everything else is the
+ * WebSocket upgrade path.
+ */
+export declare function createBunRelayServer(options?: BunRelayServerOptions): Bun.Server<RelayConnectionData>;
+export {};
+//# sourceMappingURL=relay-server-entry.d.ts.map

package/dist/relay-server-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-server-entry.d.ts","sourceRoot":"","sources":["../src/relay-server-entry.ts"],"names":[],"mappings":";AAcA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAE3B,UAAU,mBAAmB;IAC3B,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,gDAAgD;AAChD,MAAM,WAAW,qBAAqB;IACpC,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC7C,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC;AAaD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,mCAsDvE"}

package/dist/relay-server-entry.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env bun
+// relay-server-entry.ts
+//
+// The Bun.serve adapter and standalone entry point for the rendezvous relay.
+// This is what you deploy on a VPS:
+//
+//     bun packages/daemon-sdk/dist/relay-server-entry.js
+//   or, once published:
+//     bunx --bun @pellux/goodvibes-daemon-sdk-relay
+//
+// It binds a WebSocket endpoint and drives the runtime-neutral RelayHub. All the
+// zero-knowledge properties live in the hub and the transport-core relay crypto;
+// this file is only glue.
+import { DEFAULT_RELAY_LIMITS, RelayHub, } from './relay-server.js';
+const consoleLogger = {
+    info: (m, f) => console.log(`[relay] ${m}`, f ?? ''),
+    warn: (m, f) => console.warn(`[relay] ${m}`, f ?? ''),
+    error: (m, f) => console.error(`[relay] ${m}`, f ?? ''),
+};
+function toArrayBufferBytes(message) {
+    if (message instanceof ArrayBuffer)
+        return new Uint8Array(message.slice(0));
+    return new Uint8Array(new Uint8Array(message.buffer, message.byteOffset, message.byteLength));
+}
+/**
+ * Start the relay on Bun. Returns the Bun server handle (call `.stop()` to shut
+ * down). The health endpoint `GET /` reports occupancy; everything else is the
+ * WebSocket upgrade path.
+ */
+export function createBunRelayServer(options = {}) {
+    const hub = new RelayHub({
+        ...(options.limits ? { limits: options.limits } : {}),
+        logger: options.logger ?? consoleLogger,
+    });
+    const port = options.port ?? 8787;
+    const server = Bun.serve({
+        port,
+        ...(options.hostname !== undefined ? { hostname: options.hostname } : {}),
+        fetch(req, srv) {
+            const url = new URL(req.url);
+            if (req.headers.get('upgrade')?.toLowerCase() === 'websocket') {
+                const addr = srv.requestIP(req)?.address ?? 'unknown';
+                const data = { conn: null, addr };
+                if (srv.upgrade(req, { data }))
+                    return undefined;
+                return new Response('WebSocket upgrade failed', { status: 400 });
+            }
+            if (url.pathname === '/' || url.pathname === '/healthz') {
+                return Response.json({ ok: true, protocol: 1, ...hub.stats() });
+            }
+            return new Response('Not found', { status: 404 });
+        },
+        websocket: {
+            maxPayloadLength: (options.limits?.maxMessageBytes ?? DEFAULT_RELAY_LIMITS.maxMessageBytes) + 1024,
+            open(ws) {
+                ws.data.conn = hub.accept({
+                    send: (data) => {
+                        ws.send(data);
+                    },
+                    close: (code, reason) => {
+                        ws.close(code, reason);
+                    },
+                }, ws.data.addr);
+            },
+            message(ws, message) {
+                const conn = ws.data.conn;
+                if (!conn)
+                    return;
+                if (typeof message === 'string') {
+                    conn.handleText(message);
+                }
+                else {
+                    conn.handleBinary(toArrayBufferBytes(message));
+                }
+            },
+            close(ws) {
+                ws.data.conn?.handleClose();
+            },
+        },
+    });
+    return server;
+}
+if (import.meta.main) {
+    const port = Number(process.env['GOODVIBES_RELAY_PORT'] ?? 8787);
+    const hostname = process.env['GOODVIBES_RELAY_HOST'];
+    const server = createBunRelayServer({
+        port,
+        ...(hostname ? { hostname } : {}),
+    });
+    console.log(`[relay] listening on ${server.hostname}:${server.port} (protocol 1)`);
+}

package/dist/relay-server.d.ts

@@ -0,0 +1,87 @@
+import { type PipeId, type RelayErrorCode, type RendezvousId } from '@pellux/goodvibes-transport-core/relay';
+/** The subset of a WebSocket the hub needs. Keeps the hub runtime-neutral. */
+export interface RelayServerSocket {
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+}
+/** Optional structured logger; defaults to silent. */
+export interface RelayServerLogger {
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+}
+/** Caps and rate limits that keep a public instance from becoming a liability. */
+export interface RelayServerLimits {
+    /** Maximum concurrently-registered daemons. */
+    readonly maxDaemons: number;
+    /** Maximum concurrent client pipes across all daemons. */
+    readonly maxPipes: number;
+    /** Maximum concurrent client pipes for a single daemon. */
+    readonly maxPipesPerDaemon: number;
+    /** Maximum bytes in a single forwarded data frame. */
+    readonly maxMessageBytes: number;
+    /** Maximum register/connect attempts per remote address per rolling minute. */
+    readonly maxHandshakesPerMinutePerAddr: number;
+}
+export declare const DEFAULT_RELAY_LIMITS: RelayServerLimits;
+/**
+ * The runtime-neutral rendezvous core. One instance per relay process. Every
+ * connection is represented by a `RelayConnection` returned from `accept`.
+ */
+export declare class RelayHub {
+    private readonly daemons;
+    private readonly pipes;
+    private readonly limits;
+    private readonly logger;
+    private readonly rateLimiter;
+    constructor(options?: {
+        limits?: Partial<RelayServerLimits>;
+        logger?: RelayServerLogger;
+    });
+    /** Current occupancy — surfaces/monitoring can read this. */
+    stats(): {
+        readonly daemons: number;
+        readonly pipes: number;
+    };
+    /** Maximum bytes allowed in a single forwarded data frame. */
+    get maxMessageBytes(): number;
+    /** Begin tracking a freshly-connected socket. */
+    accept(socket: RelayServerSocket, remoteAddr: string): RelayConnection;
+    /** @internal */
+    _rateOk(addr: string): boolean;
+    /** @internal Register a daemon under a rendezvous id. Returns an error code or null on success. */
+    _register(rid: RendezvousId, socket: RelayServerSocket): RelayErrorCode | null;
+    /** @internal Open a client pipe to a registered daemon. */
+    _openPipe(rid: RendezvousId, client: RelayServerSocket): {
+        pipeId: PipeId;
+        pipeIdBytes: Uint8Array<ArrayBuffer>;
+    } | RelayErrorCode;
+    /** @internal Forward an opaque payload from a client to its daemon (adds pipe prefix). */
+    _clientToDaemon(pipeId: PipeId, payload: Uint8Array<ArrayBuffer>): boolean;
+    /** @internal Forward an opaque daemon frame ([pipeId][payload]) to the right client. */
+    _daemonToClient(frame: Uint8Array<ArrayBuffer>): boolean;
+    /** @internal Tear down a single pipe, notifying the surviving peer. */
+    _closePipe(pipeId: PipeId, notify: 'client' | 'daemon' | 'both', reason?: string): void;
+    /** @internal Remove a daemon registration and close all its pipes. */
+    _unregister(rid: RendezvousId): void;
+}
+/** Per-connection state machine. One instance per accepted socket. */
+export declare class RelayConnection {
+    private readonly hub;
+    private readonly socket;
+    private readonly remoteAddr;
+    private role;
+    private rid;
+    private pipeId;
+    constructor(hub: RelayHub, socket: RelayServerSocket, remoteAddr: string);
+    /** Handle a text (control) frame from this socket. */
+    handleText(text: string): void;
+    /** Handle a binary (data) frame from this socket. */
+    handleBinary(bytes: Uint8Array<ArrayBuffer>): void;
+    /** Handle socket closure. */
+    handleClose(): void;
+    private onRegister;
+    private onConnect;
+    private fail;
+}
+//# sourceMappingURL=relay-server.d.ts.map