@phuetz/code-buddy 0.3.0 → 1.0.0-rc.8

package/dist/gateway/device-pairing.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Gateway device pairing.
+ *
+ * Transport-agnostic, file-backed registry of paired and pending devices,
+ * modelled on the OpenClaw `~/.openclaw/devices/{paired,pending}.json` shape and
+ * Hermes' pairing flow (pending -> approve/reject -> scoped device token).
+ *
+ * Security notes:
+ * - Tokens are issued once on approval and returned to the caller; the store
+ *   persists only a SHA-256 hash, so the plaintext token never touches disk.
+ * - Read/list methods return token-free views; the secret is only comparable via
+ *   {@link DevicePairingStore.verifyToken}.
+ * - Files are written 0600.
+ *
+ * Pure of any WebSocket/transport concern so it can back either the production
+ * `src/server/websocket` auth path or the `src/gateway` handshake.
+ */
+export type DeviceRole = 'operator' | 'node' | 'control' | 'webchat';
+export declare function isDeviceRole(value: unknown): value is DeviceRole;
+export interface PendingDevice {
+    deviceId: string;
+    displayName?: string;
+    clientId?: string;
+    role: DeviceRole;
+    requestedScopes: string[];
+    requestedAtMs: number;
+    publicKey?: string;
+}
+/** A paired device as stored on disk — holds the token hash, never the token. */
+export interface PairedDevice {
+    deviceId: string;
+    displayName?: string;
+    clientId?: string;
+    role: DeviceRole;
+    scopes: string[];
+    /** SHA-256 hex of the issued token. */
+    tokenHash: string;
+    createdAtMs: number;
+    approvedAtMs: number;
+    approvedBy?: string;
+    lastSeenAtMs?: number;
+    lastSeenReason?: string;
+}
+/** Token-free view returned by list/get/approve so secrets never leak through surfaces. */
+export type PairedDeviceView = Omit<PairedDevice, 'tokenHash'>;
+export interface DevicePairingStoreConfig {
+    /** Directory holding paired.json + pending.json (default ~/.codebuddy/gateway/devices). */
+    dir?: string;
+    /** Injectable clock (epoch ms) for deterministic tests. */
+    now?: () => number;
+    /** Injectable token generator for deterministic tests. */
+    generateToken?: () => string;
+}
+export interface PairingRequestInput {
+    deviceId: string;
+    displayName?: string;
+    clientId?: string;
+    role?: DeviceRole;
+    requestedScopes?: string[];
+    publicKey?: string;
+}
+export interface ApproveInput {
+    scopes?: string[];
+    role?: DeviceRole;
+    approvedBy?: string;
+}
+export interface PairingRequestResult {
+    status: 'paired' | 'pending';
+    device: PairedDeviceView | PendingDevice;
+}
+export interface ApproveResult {
+    device: PairedDeviceView;
+    /** Plaintext token — shown once; only its hash is persisted. */
+    token: string;
+}
+export declare class DevicePairingStore {
+    private readonly dir;
+    private readonly pairedPath;
+    private readonly pendingPath;
+    private readonly now;
+    private readonly generateToken;
+    constructor(config?: DevicePairingStoreConfig);
+    listPaired(): PairedDeviceView[];
+    listPending(): PendingDevice[];
+    getPaired(deviceId: string): PairedDeviceView | null;
+    isPaired(deviceId: string): boolean;
+    /** Constant-time-ish token check against the stored hash. */
+    verifyToken(deviceId: string, token: string): boolean;
+    /**
+     * Record a device's pairing request. Already-paired devices short-circuit to
+     * `paired`; everything else is upserted into the pending queue for approval.
+     */
+    requestPairing(input: PairingRequestInput): PairingRequestResult;
+    /**
+     * Approve a device: mint a scoped token, move it from pending to paired, and
+     * return the plaintext token exactly once.
+     */
+    approve(deviceId: string, input?: ApproveInput): ApproveResult;
+    /** Reject (remove) a pending pairing request. Returns false if it was not pending. */
+    reject(deviceId: string, _reason?: string): boolean;
+    /** Revoke a paired device (e.g. lost/compromised). Returns false if not paired. */
+    revoke(deviceId: string): boolean;
+    /** Record last-seen metadata for a paired device (no-op if unknown). */
+    touch(deviceId: string, reason?: string): void;
+    private requireDeviceId;
+    private readFile;
+    private writeFile;
+    /** Directory backing this store (for diagnostics/CLI). */
+    getDir(): string;
+}
+/**
+ * Shared pairing store for the running gateway + the operator CLI, so both read
+ * and write the same `~/.codebuddy/gateway/devices` files.
+ */
+export declare function getGatewayPairingStore(config?: DevicePairingStoreConfig): DevicePairingStore;
+/** Reset the shared store (tests). */
+export declare function resetGatewayPairingStore(): void;
+/** Opt-in gate: device pairing is only enforced when explicitly enabled. */
+export declare function isDevicePairingRequired(): boolean;
+export interface DeviceAuthInput {
+    deviceId?: string;
+    deviceToken?: string;
+    displayName?: string;
+    clientId?: string;
+    requestedScopes?: string[];
+}
+export interface DeviceAuthOutcome {
+    /**
+     * - `skip`: pairing not required, or no device identity offered → fall through
+     *   to the gateway's existing JWT/api-key auth (existing paths stay intact).
+     * - `authenticated`: a paired device presented a valid token.
+     * - `pending`: an unknown device was queued for operator approval.
+     * - `rejected`: an already-paired device presented a missing/invalid token —
+     *   an auth failure, not re-queued (it is already approved).
+     */
+    outcome: 'skip' | 'authenticated' | 'pending' | 'rejected';
+    deviceId?: string;
+    scopes?: string[];
+    message?: string;
+}
+/**
+ * Layer device pairing over the existing gateway auth without replacing it.
+ * Returns `skip` (the default, when pairing is off) so callers leave their
+ * JWT/api-key flow untouched.
+ */
+export declare function authenticateDevice(store: DevicePairingStore, input: DeviceAuthInput, required?: boolean): DeviceAuthOutcome;

package/dist/gateway/device-pairing.js

@@ -0,0 +1,258 @@
+/**
+ * Gateway device pairing.
+ *
+ * Transport-agnostic, file-backed registry of paired and pending devices,
+ * modelled on the OpenClaw `~/.openclaw/devices/{paired,pending}.json` shape and
+ * Hermes' pairing flow (pending -> approve/reject -> scoped device token).
+ *
+ * Security notes:
+ * - Tokens are issued once on approval and returned to the caller; the store
+ *   persists only a SHA-256 hash, so the plaintext token never touches disk.
+ * - Read/list methods return token-free views; the secret is only comparable via
+ *   {@link DevicePairingStore.verifyToken}.
+ * - Files are written 0600.
+ *
+ * Pure of any WebSocket/transport concern so it can back either the production
+ * `src/server/websocket` auth path or the `src/gateway` handshake.
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+const DEVICE_ROLES = ['operator', 'node', 'control', 'webchat'];
+export function isDeviceRole(value) {
+    return typeof value === 'string' && DEVICE_ROLES.includes(value);
+}
+const STORE_VERSION = 1;
+function sha256Hex(value) {
+    return createHash('sha256').update(value, 'utf-8').digest('hex');
+}
+function stripToken(device) {
+    const { tokenHash: _tokenHash, ...view } = device;
+    return view;
+}
+function sanitizeScopes(scopes) {
+    if (!Array.isArray(scopes))
+        return [];
+    return [...new Set(scopes.filter((s) => typeof s === 'string' && s.trim().length > 0))].sort();
+}
+export class DevicePairingStore {
+    dir;
+    pairedPath;
+    pendingPath;
+    now;
+    generateToken;
+    constructor(config = {}) {
+        this.dir = config.dir ?? path.join(os.homedir(), '.codebuddy', 'gateway', 'devices');
+        this.pairedPath = path.join(this.dir, 'paired.json');
+        this.pendingPath = path.join(this.dir, 'pending.json');
+        this.now = config.now ?? (() => Date.now());
+        this.generateToken = config.generateToken ?? (() => randomBytes(32).toString('hex'));
+    }
+    // ── Queries ───────────────────────────────────────────────────────────────
+    listPaired() {
+        return Object.values(this.readFile(this.pairedPath).devices).map(stripToken);
+    }
+    listPending() {
+        return Object.values(this.readFile(this.pendingPath).devices).map((d) => ({ ...d }));
+    }
+    getPaired(deviceId) {
+        const device = this.readFile(this.pairedPath).devices[deviceId];
+        return device ? stripToken(device) : null;
+    }
+    isPaired(deviceId) {
+        return Boolean(this.readFile(this.pairedPath).devices[deviceId]);
+    }
+    /** Constant-time-ish token check against the stored hash. */
+    verifyToken(deviceId, token) {
+        const device = this.readFile(this.pairedPath).devices[deviceId];
+        if (!device || typeof token !== 'string' || token.length === 0)
+            return false;
+        const candidate = Buffer.from(sha256Hex(token));
+        const stored = Buffer.from(device.tokenHash);
+        return candidate.length === stored.length && timingSafeEqual(candidate, stored);
+    }
+    // ── Mutations ───────────────────────────────────────────────────────────────
+    /**
+     * Record a device's pairing request. Already-paired devices short-circuit to
+     * `paired`; everything else is upserted into the pending queue for approval.
+     */
+    requestPairing(input) {
+        const deviceId = this.requireDeviceId(input.deviceId);
+        const paired = this.readFile(this.pairedPath);
+        const existing = paired.devices[deviceId];
+        if (existing) {
+            return { status: 'paired', device: stripToken(existing) };
+        }
+        const pendingFile = this.readFile(this.pendingPath);
+        const prior = pendingFile.devices[deviceId];
+        const pending = {
+            deviceId,
+            role: isDeviceRole(input.role) ? input.role : (prior?.role ?? 'control'),
+            requestedScopes: sanitizeScopes(input.requestedScopes ?? prior?.requestedScopes),
+            requestedAtMs: prior?.requestedAtMs ?? this.now(),
+            ...(input.displayName?.trim() ? { displayName: input.displayName.trim() } : prior?.displayName ? { displayName: prior.displayName } : {}),
+            ...(input.clientId?.trim() ? { clientId: input.clientId.trim() } : prior?.clientId ? { clientId: prior.clientId } : {}),
+            ...(input.publicKey?.trim() ? { publicKey: input.publicKey.trim() } : prior?.publicKey ? { publicKey: prior.publicKey } : {}),
+        };
+        pendingFile.devices[deviceId] = pending;
+        this.writeFile(this.pendingPath, pendingFile);
+        return { status: 'pending', device: { ...pending } };
+    }
+    /**
+     * Approve a device: mint a scoped token, move it from pending to paired, and
+     * return the plaintext token exactly once.
+     */
+    approve(deviceId, input = {}) {
+        const id = this.requireDeviceId(deviceId);
+        const pendingFile = this.readFile(this.pendingPath);
+        const pending = pendingFile.devices[id];
+        const pairedFile = this.readFile(this.pairedPath);
+        const prior = pairedFile.devices[id];
+        if (!pending && !prior) {
+            throw new Error(`Cannot approve unknown device '${id}': no pending request and not already paired.`);
+        }
+        const token = this.generateToken();
+        const role = isDeviceRole(input.role) ? input.role : (pending?.role ?? prior?.role ?? 'control');
+        const scopes = sanitizeScopes(input.scopes ?? pending?.requestedScopes ?? prior?.scopes ?? []);
+        const nowMs = this.now();
+        const paired = {
+            deviceId: id,
+            role,
+            scopes,
+            tokenHash: sha256Hex(token),
+            createdAtMs: prior?.createdAtMs ?? pending?.requestedAtMs ?? nowMs,
+            approvedAtMs: nowMs,
+            ...(input.approvedBy?.trim() ? { approvedBy: input.approvedBy.trim() } : {}),
+            ...(pending?.displayName ?? prior?.displayName ? { displayName: (pending?.displayName ?? prior?.displayName) } : {}),
+            ...(pending?.clientId ?? prior?.clientId ? { clientId: (pending?.clientId ?? prior?.clientId) } : {}),
+            ...(prior?.lastSeenAtMs !== undefined ? { lastSeenAtMs: prior.lastSeenAtMs } : {}),
+            ...(prior?.lastSeenReason ? { lastSeenReason: prior.lastSeenReason } : {}),
+        };
+        pairedFile.devices[id] = paired;
+        this.writeFile(this.pairedPath, pairedFile);
+        if (pending) {
+            delete pendingFile.devices[id];
+            this.writeFile(this.pendingPath, pendingFile);
+        }
+        return { device: stripToken(paired), token };
+    }
+    /** Reject (remove) a pending pairing request. Returns false if it was not pending. */
+    reject(deviceId, _reason) {
+        const id = this.requireDeviceId(deviceId);
+        const pendingFile = this.readFile(this.pendingPath);
+        if (!pendingFile.devices[id])
+            return false;
+        delete pendingFile.devices[id];
+        this.writeFile(this.pendingPath, pendingFile);
+        return true;
+    }
+    /** Revoke a paired device (e.g. lost/compromised). Returns false if not paired. */
+    revoke(deviceId) {
+        const id = this.requireDeviceId(deviceId);
+        const pairedFile = this.readFile(this.pairedPath);
+        if (!pairedFile.devices[id])
+            return false;
+        delete pairedFile.devices[id];
+        this.writeFile(this.pairedPath, pairedFile);
+        return true;
+    }
+    /** Record last-seen metadata for a paired device (no-op if unknown). */
+    touch(deviceId, reason) {
+        const id = this.requireDeviceId(deviceId);
+        const pairedFile = this.readFile(this.pairedPath);
+        const device = pairedFile.devices[id];
+        if (!device)
+            return;
+        device.lastSeenAtMs = this.now();
+        if (reason)
+            device.lastSeenReason = reason;
+        this.writeFile(this.pairedPath, pairedFile);
+    }
+    // ── Persistence ───────────────────────────────────────────────────────────
+    requireDeviceId(deviceId) {
+        const trimmed = typeof deviceId === 'string' ? deviceId.trim() : '';
+        if (!trimmed)
+            throw new Error('A non-empty deviceId is required.');
+        return trimmed;
+    }
+    readFile(filePath) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+            if (parsed.version === STORE_VERSION && parsed.devices && typeof parsed.devices === 'object') {
+                return { version: STORE_VERSION, updatedAt: parsed.updatedAt ?? '', devices: parsed.devices };
+            }
+        }
+        catch {
+            // Missing or corrupt file — start empty.
+        }
+        return { version: STORE_VERSION, updatedAt: '', devices: {} };
+    }
+    writeFile(filePath, file) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        const payload = {
+            version: STORE_VERSION,
+            updatedAt: new Date(this.now()).toISOString(),
+            devices: file.devices,
+        };
+        fs.writeFileSync(filePath, JSON.stringify(payload, null, 2), { encoding: 'utf-8', mode: 0o600 });
+    }
+    /** Directory backing this store (for diagnostics/CLI). */
+    getDir() {
+        return this.dir;
+    }
+}
+// ── Production gateway integration (shared singleton + auth helper) ───────────
+let sharedStore = null;
+/**
+ * Shared pairing store for the running gateway + the operator CLI, so both read
+ * and write the same `~/.codebuddy/gateway/devices` files.
+ */
+export function getGatewayPairingStore(config) {
+    if (!sharedStore) {
+        sharedStore = new DevicePairingStore(config);
+    }
+    return sharedStore;
+}
+/** Reset the shared store (tests). */
+export function resetGatewayPairingStore() {
+    sharedStore = null;
+}
+/** Opt-in gate: device pairing is only enforced when explicitly enabled. */
+export function isDevicePairingRequired() {
+    return process.env['CODEBUDDY_GATEWAY_REQUIRE_PAIRING'] === 'true';
+}
+/**
+ * Layer device pairing over the existing gateway auth without replacing it.
+ * Returns `skip` (the default, when pairing is off) so callers leave their
+ * JWT/api-key flow untouched.
+ */
+export function authenticateDevice(store, input, required = isDevicePairingRequired()) {
+    if (!required)
+        return { outcome: 'skip' };
+    const deviceId = input.deviceId?.trim();
+    if (!deviceId)
+        return { outcome: 'skip' };
+    if (input.deviceToken && store.verifyToken(deviceId, input.deviceToken)) {
+        const device = store.getPaired(deviceId);
+        store.touch(deviceId, 'authenticate');
+        return { outcome: 'authenticated', deviceId, scopes: device?.scopes ?? [] };
+    }
+    // Already-paired device with a missing/invalid token is an auth failure, not a
+    // new pairing request — never re-queue an approved device.
+    if (store.isPaired(deviceId)) {
+        return { outcome: 'rejected', deviceId, message: 'Invalid device token for a paired device.' };
+    }
+    store.requestPairing({
+        deviceId,
+        ...(input.displayName ? { displayName: input.displayName } : {}),
+        ...(input.clientId ? { clientId: input.clientId } : {}),
+        ...(input.requestedScopes ? { requestedScopes: input.requestedScopes } : {}),
+    });
+    return {
+        outcome: 'pending',
+        deviceId,
+        message: 'Device pairing required — request recorded, awaiting operator approval.',
+    };
+}
+//# sourceMappingURL=device-pairing.js.map

package/dist/gateway/device-pairing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-pairing.js","sourceRoot":"","sources":["../../src/gateway/device-pairing.ts"],"names":[],"mappings":"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"}

package/dist/gateway/index.d.ts

@@ -2,9 +2,9 @@
  * Gateway Module
  *
  * Centralized WebSocket gateway for multi-client communication.
- * Inspired by OpenClaw's WebSocket gateway (ws://127.0.0.1:18789)
+ * Advanced enterprise architecture for WebSocket gateway (ws://127.0.0.1:18789)
  */
-export type { GatewayMessageType, GatewayMessage, AuthPayload, ChatPayload, ChatStreamPayload, ToolPayload, SessionPayload, ErrorPayload, ClientState, GatewayConfig, GatewayEvents, } from './types.js';
+export type { GatewayMessageType, GatewayMessage, ConnectPayload, HelloOkPayload, AuthPayload, SessionPatchPayload, PresencePayload, ChatPayload, ChatStreamPayload, ToolPayload, SessionPayload, ErrorPayload, ClientState, GatewayConfig, GatewayAuthMode, GatewayBindMode, GatewayTailscaleConfig, GatewayEvents, } from './types.js';
 export { DEFAULT_GATEWAY_CONFIG } from './types.js';
 export type { MessageHandler } from './server.js';
 export { createMessage, createErrorMessage, SessionManager, GatewayServer, getGatewayServer, resetGatewayServer, } from './server.js';

package/dist/gateway/index.js

@@ -2,7 +2,7 @@
  * Gateway Module
  *
  * Centralized WebSocket gateway for multi-client communication.
- * Inspired by OpenClaw's WebSocket gateway (ws://127.0.0.1:18789)
+ * Advanced enterprise architecture for WebSocket gateway (ws://127.0.0.1:18789)
  */
 export { DEFAULT_GATEWAY_CONFIG } from './types.js';
 export { createMessage, createErrorMessage, SessionManager, GatewayServer, getGatewayServer, resetGatewayServer, } from './server.js';

package/dist/gateway/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiBH,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAKpD,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAWrB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwBH,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAKpD,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAWrB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC"}

package/dist/gateway/protocol.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Gateway handshake protocol helpers.
+ *
+ * Pure, dependency-free logic for the `connect` -> `hello_ok` handshake so it can
+ * be unit-tested without spinning up a WebSocket server. Inspired by the OpenClaw
+ * gateway (min/max protocol negotiation, `protocol` echo, `server.{version,connId}`,
+ * `features.methods` capability advertisement) and Hermes' capability discovery.
+ */
+import type { HelloOkPayload } from './types.js';
+/** Lowest protocol version this gateway still accepts from a client. */
+export declare const GATEWAY_MIN_PROTOCOL_VERSION = 1;
+/** Preferred / newest protocol version this gateway speaks. */
+export declare const GATEWAY_PROTOCOL_VERSION = 2;
+/** Highest protocol version this gateway can negotiate. */
+export declare const GATEWAY_MAX_PROTOCOL_VERSION = 2;
+export interface ProtocolNegotiationInput {
+    /** Client's preferred protocol version (legacy single-value field). */
+    protocolVersion?: number;
+    /** Client's minimum acceptable protocol version. */
+    minProtocolVersion?: number;
+    /** Client's maximum acceptable protocol version. */
+    maxProtocolVersion?: number;
+}
+export interface ProtocolNegotiationResult {
+    /** The version the gateway will speak on this connection. */
+    protocolVersion: number;
+    /** True when the client's requested range overlaps the gateway's. */
+    compatible: boolean;
+}
+/**
+ * Negotiate a protocol version against the gateway's supported range.
+ *
+ * - A client that declares a `[min, max]` range gets the highest version in the
+ *   overlap with `[serverMin, serverMax]`.
+ * - A legacy client that only sends `protocolVersion` is honoured at that exact
+ *   version when the gateway still supports it.
+ * - A client that declares nothing defaults to the gateway's newest version.
+ * - When there is no overlap the gateway reports `compatible: false` and echoes
+ *   its own preferred version so the client can adapt or refuse.
+ */
+export declare function negotiateGatewayProtocol(client?: ProtocolNegotiationInput, serverMin?: number, serverMax?: number): ProtocolNegotiationResult;
+/** Resolve the running server version (set from package.json by the CLI bootstrap). */
+export declare function gatewayServerVersion(): string;
+export interface HelloOkBuildParams {
+    paired: boolean;
+    uptime: number;
+    stateVersion: number;
+    presence: HelloOkPayload['presence'];
+    health: HelloOkPayload['health'];
+    authRequired: boolean;
+    negotiation: ProtocolNegotiationResult;
+    serverVersion: string;
+    /** Stable per-connection id (mirrors OpenClaw's `server.connId`). */
+    connId: string;
+    /** Handler/method names the gateway advertises for capability discovery. */
+    methods: string[];
+    challengeNonce?: string;
+}
+/**
+ * Assemble the enriched `hello_ok` payload. Pure so the exact shape (negotiated
+ * protocol, server identity, advertised capabilities) can be asserted in tests.
+ */
+export declare function buildHelloOkPayload(params: HelloOkBuildParams): HelloOkPayload;

package/dist/gateway/protocol.js

@@ -0,0 +1,65 @@
+/**
+ * Gateway handshake protocol helpers.
+ *
+ * Pure, dependency-free logic for the `connect` -> `hello_ok` handshake so it can
+ * be unit-tested without spinning up a WebSocket server. Inspired by the OpenClaw
+ * gateway (min/max protocol negotiation, `protocol` echo, `server.{version,connId}`,
+ * `features.methods` capability advertisement) and Hermes' capability discovery.
+ */
+/** Lowest protocol version this gateway still accepts from a client. */
+export const GATEWAY_MIN_PROTOCOL_VERSION = 1;
+/** Preferred / newest protocol version this gateway speaks. */
+export const GATEWAY_PROTOCOL_VERSION = 2;
+/** Highest protocol version this gateway can negotiate. */
+export const GATEWAY_MAX_PROTOCOL_VERSION = GATEWAY_PROTOCOL_VERSION;
+function asFiniteInt(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : undefined;
+}
+/**
+ * Negotiate a protocol version against the gateway's supported range.
+ *
+ * - A client that declares a `[min, max]` range gets the highest version in the
+ *   overlap with `[serverMin, serverMax]`.
+ * - A legacy client that only sends `protocolVersion` is honoured at that exact
+ *   version when the gateway still supports it.
+ * - A client that declares nothing defaults to the gateway's newest version.
+ * - When there is no overlap the gateway reports `compatible: false` and echoes
+ *   its own preferred version so the client can adapt or refuse.
+ */
+export function negotiateGatewayProtocol(client = {}, serverMin = GATEWAY_MIN_PROTOCOL_VERSION, serverMax = GATEWAY_MAX_PROTOCOL_VERSION) {
+    const preferred = asFiniteInt(client.protocolVersion);
+    const clientMinRaw = asFiniteInt(client.minProtocolVersion) ?? preferred ?? serverMin;
+    const clientMaxRaw = asFiniteInt(client.maxProtocolVersion) ?? preferred ?? serverMax;
+    const clientMin = Math.min(clientMinRaw, clientMaxRaw);
+    const clientMax = Math.max(clientMinRaw, clientMaxRaw);
+    const overlapLow = Math.max(serverMin, clientMin);
+    const overlapHigh = Math.min(serverMax, clientMax);
+    if (overlapLow <= overlapHigh) {
+        return { protocolVersion: overlapHigh, compatible: true };
+    }
+    return { protocolVersion: serverMax, compatible: false };
+}
+/** Resolve the running server version (set from package.json by the CLI bootstrap). */
+export function gatewayServerVersion() {
+    return process.env['CODEBUDDY_CLI_VERSION'] || '0.0.0-dev';
+}
+/**
+ * Assemble the enriched `hello_ok` payload. Pure so the exact shape (negotiated
+ * protocol, server identity, advertised capabilities) can be asserted in tests.
+ */
+export function buildHelloOkPayload(params) {
+    return {
+        paired: params.paired,
+        ...(params.challengeNonce ? { challengeNonce: params.challengeNonce } : {}),
+        uptime: params.uptime,
+        stateVersion: params.stateVersion,
+        presence: params.presence,
+        health: params.health,
+        authRequired: params.authRequired,
+        protocolVersion: params.negotiation.protocolVersion,
+        protocolCompatible: params.negotiation.compatible,
+        server: { version: params.serverVersion, connId: params.connId },
+        capabilities: { methods: [...new Set(params.methods)].sort() },
+    };
+}
+//# sourceMappingURL=protocol.js.map

package/dist/gateway/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/gateway/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,wEAAwE;AACxE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAC9C,+DAA+D;AAC/D,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAC1C,2DAA2D;AAC3D,MAAM,CAAC,MAAM,4BAA4B,GAAG,wBAAwB,CAAC;AAkBrE,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7F,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CACtC,SAAmC,EAAE,EACrC,YAAoB,4BAA4B,EAChD,YAAoB,4BAA4B;IAEhD,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IACtD,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,CAAC,kBAAkB,CAAC,IAAI,SAAS,IAAI,SAAS,CAAC;IACtF,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,CAAC,kBAAkB,CAAC,IAAI,SAAS,IAAI,SAAS,CAAC;IACtF,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IAEvD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAClD,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAEnD,IAAI,UAAU,IAAI,WAAW,EAAE,CAAC;QAC9B,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAC3D,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,oBAAoB;IAClC,OAAO,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,IAAI,WAAW,CAAC;AAC7D,CAAC;AAkBD;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA0B;IAC5D,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,eAAe,EAAE,MAAM,CAAC,WAAW,CAAC,eAAe;QACnD,kBAAkB,EAAE,MAAM,CAAC,WAAW,CAAC,UAAU;QACjD,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAChE,YAAY,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE;KAC/D,CAAC;AACJ,CAAC"}

package/dist/gateway/server.d.ts

@@ -84,6 +84,8 @@ export declare class GatewayServer extends EventEmitter {
     protected sessions: SessionManager;
     protected handlers: Map<GatewayMessageType, MessageHandler>;
     protected running: boolean;
+    protected startedAt: number | null;
+    protected stateVersion: number;
     private pingInterval;
     constructor(config?: Partial<GatewayConfig>);
     /**
@@ -95,6 +97,14 @@ export declare class GatewayServer extends EventEmitter {
      * Override this method for custom authentication
      */
     protected validateToken(_token: string): Promise<boolean>;
+    /**
+     * Whether a device is considered paired for the `hello_ok` response.
+     *
+     * Default: permissive — every device is paired unless `requirePairing` is on.
+     * Override (or pair a `requirePairing` gateway with a device registry) to
+     * enforce OpenClaw/Hermes-style pairing approval (pending -> approve -> token).
+     */
+    protected isPairedDevice(_deviceId: string, _client?: ClientState): boolean;
     /**
      * Register a message handler
      */
@@ -132,6 +142,10 @@ export declare class GatewayServer extends EventEmitter {
      * Stop ping interval
      */
     protected stopPingInterval(): void;
+    /**
+     * Resolve the bind address from the bind mode config.
+     */
+    getBindAddress(): string;
     /**
      * Start the server
      * Override in transport-specific subclass