sigild 0.0.1 → 0.0.2

package/dist/src/control/client.js

@@ -0,0 +1,76 @@
+import { createConnection } from 'node:net';
+const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * Sends a single request to the running sigil-mcp control socket and returns
+ * the parsed response. Throws ControlClientError if:
+ *   - the socket file is missing or refused (server not running)
+ *   - the connection times out
+ *   - the response is not valid JSON
+ *
+ * Note: a server-side denial (wrong passphrase, etc.) is NOT thrown — it
+ * comes back as a ControlResponse with `ok: false`. Callers branch on that.
+ */
+export async function controlRequest(opts) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const sock = createConnection(opts.socketPath);
+    sock.setEncoding('utf8');
+    let timer = null;
+    const cleanupTimer = () => { if (timer)
+        clearTimeout(timer); timer = null; };
+    return new Promise((resolve, reject) => {
+        timer = setTimeout(() => {
+            sock.destroy();
+            reject(new ControlClientError(`control socket timeout after ${timeoutMs}ms`, 'TIMEOUT'));
+        }, timeoutMs);
+        let buf = '';
+        let resolved = false;
+        const finish = (fn) => {
+            if (resolved)
+                return;
+            resolved = true;
+            cleanupTimer();
+            fn();
+        };
+        sock.on('connect', () => {
+            sock.write(JSON.stringify(opts.request) + '\n');
+        });
+        sock.on('data', (chunk) => {
+            buf += chunk;
+            const nl = buf.indexOf('\n');
+            if (nl === -1)
+                return;
+            const line = buf.slice(0, nl);
+            sock.end();
+            try {
+                const parsed = JSON.parse(line);
+                finish(() => resolve(parsed));
+            }
+            catch {
+                finish(() => reject(new ControlClientError('control socket returned non-JSON response', 'BAD_RESPONSE')));
+            }
+        });
+        sock.on('end', () => {
+            if (!resolved) {
+                if (buf.length === 0) {
+                    finish(() => reject(new ControlClientError('control socket closed without sending a response', 'NO_RESPONSE')));
+                }
+            }
+        });
+        sock.on('error', (err) => {
+            const code = err.code;
+            let mapped = 'CONNECT_FAILED';
+            if (code === 'ENOENT' || code === 'ECONNREFUSED')
+                mapped = 'SERVER_DOWN';
+            finish(() => reject(new ControlClientError(`control socket: ${err.message}`, mapped)));
+        });
+    });
+}
+export class ControlClientError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'ControlClientError';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/src/control/client.js.map

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

package/dist/src/control/index.d.ts

@@ -0,0 +1,4 @@
+export { CONTROL_SOCKET_VERSION, type ControlRequest, type ControlResponse, type ControlSuccess, type ControlError, type ControlErrorCode, type PortalSummary, isControlError, parseControlRequest, } from './protocol.js';
+export { type ControlServerOpts, type ControlServerHandle, type ControlLogEvent, startControlServer, } from './server.js';
+export { type ControlRequestOpts, type ControlClientErrorCode, ControlClientError, controlRequest, } from './client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/control/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/control/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,cAAc,EACd,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,kBAAkB,EAClB,cAAc,GACf,MAAM,aAAa,CAAC"}

package/dist/src/control/index.js

@@ -0,0 +1,4 @@
+export { CONTROL_SOCKET_VERSION, isControlError, parseControlRequest, } from './protocol.js';
+export { startControlServer, } from './server.js';
+export { ControlClientError, controlRequest, } from './client.js';
+//# sourceMappingURL=index.js.map

package/dist/src/control/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/control/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EAOtB,cAAc,EACd,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAGL,kBAAkB,EAClB,cAAc,GACf,MAAM,aAAa,CAAC"}

package/dist/src/control/protocol.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Wire protocol for the sigil-mcp control socket.
+ *
+ * One NDJSON request per connection, one NDJSON response, then the server
+ * half-closes. The socket lives at `~/.sigil/control.sock` (0600).
+ *
+ * Methods:
+ *   - unlock: load keyfiles from disk into the running MCP server's
+ *     HandleTable. Passphrase is shipped as base64 because raw bytes
+ *     don't survive JSON's UTF-8 round-trip cleanly. Server decodes
+ *     into a Buffer + zeroizes after use.
+ *   - lock: zeroize the HandleTable. Re-lockable; a later unlock works.
+ *   - status: probe — returns PID + unlocked flag + portal count.
+ *
+ * Error responses always carry a machine-readable `code` so the CLI can
+ * branch on it without parsing the message.
+ */
+export declare const CONTROL_SOCKET_VERSION = 1;
+export type ControlRequest = {
+    method: 'unlock';
+    passphraseB64: string;
+} | {
+    method: 'lock';
+} | {
+    method: 'status';
+};
+export type ControlResponse = ControlSuccess | ControlError;
+export interface ControlSuccess {
+    ok: true;
+    /** Server protocol version — clients should verify this matches. */
+    version: number;
+    /** Process ID of the running sigil-mcp. */
+    pid: number;
+    /** Whether the HandleTable is currently unlocked. */
+    unlocked: boolean;
+    /** Currently loaded portals (empty when locked, or when zero on disk). */
+    portals: PortalSummary[];
+}
+export interface PortalSummary {
+    handle: string;
+    kind: 'eth';
+    address: string;
+}
+export interface ControlError {
+    ok: false;
+    /** Stable error code. */
+    code: ControlErrorCode;
+    /** Human-readable message. */
+    error: string;
+}
+export type ControlErrorCode = 'INVALID_REQUEST' | 'UNKNOWN_METHOD' | 'ALREADY_UNLOCKED' | 'WRONG_PASSPHRASE' | 'KEYS_LOAD_FAILED' | 'INTERNAL';
+export declare function parseControlRequest(line: string): ControlRequest | ControlError;
+export declare function isControlError(resp: ControlResponse): resp is ControlError;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/src/control/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../src/control/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,MAAM,MAAM,cAAc,GACtB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEzB,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,YAAY,CAAC;AAEjB,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,IAAI,CAAC;IACT,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,QAAQ,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,KAAK,CAAC;IACV,yBAAyB;IACzB,IAAI,EAAE,gBAAgB,CAAC;IACvB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,gBAAgB,GAChB,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,UAAU,CAAC;AAMf,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,YAAY,CA8B/E;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,IAAI,YAAY,CAE1E"}

package/dist/src/control/protocol.js

@@ -0,0 +1,60 @@
+/**
+ * Wire protocol for the sigil-mcp control socket.
+ *
+ * One NDJSON request per connection, one NDJSON response, then the server
+ * half-closes. The socket lives at `~/.sigil/control.sock` (0600).
+ *
+ * Methods:
+ *   - unlock: load keyfiles from disk into the running MCP server's
+ *     HandleTable. Passphrase is shipped as base64 because raw bytes
+ *     don't survive JSON's UTF-8 round-trip cleanly. Server decodes
+ *     into a Buffer + zeroizes after use.
+ *   - lock: zeroize the HandleTable. Re-lockable; a later unlock works.
+ *   - status: probe — returns PID + unlocked flag + portal count.
+ *
+ * Error responses always carry a machine-readable `code` so the CLI can
+ * branch on it without parsing the message.
+ */
+export const CONTROL_SOCKET_VERSION = 1;
+// ---------------------------------------------------------------------------
+// Parsing helpers
+// ---------------------------------------------------------------------------
+export function parseControlRequest(line) {
+    let raw;
+    try {
+        raw = JSON.parse(line);
+    }
+    catch {
+        return invalid('request is not valid JSON');
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return invalid('request must be a JSON object');
+    }
+    const obj = raw;
+    const method = obj['method'];
+    if (typeof method !== 'string') {
+        return invalid('request.method must be a string');
+    }
+    if (method === 'lock' || method === 'status') {
+        return { method };
+    }
+    if (method === 'unlock') {
+        const p = obj['passphraseB64'];
+        if (typeof p !== 'string') {
+            return invalid('unlock.passphraseB64 must be a string');
+        }
+        return { method: 'unlock', passphraseB64: p };
+    }
+    return {
+        ok: false,
+        code: 'UNKNOWN_METHOD',
+        error: `unknown control method "${method}"`,
+    };
+}
+export function isControlError(resp) {
+    return resp.ok === false;
+}
+function invalid(message) {
+    return { ok: false, code: 'INVALID_REQUEST', error: message };
+}
+//# sourceMappingURL=protocol.js.map

package/dist/src/control/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/control/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AA6CxC,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,OAAO,OAAO,CAAC,+BAA+B,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAC3C,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7B,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,OAAO,CAAC,iCAAiC,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC7C,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;IACD,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxB,MAAM,CAAC,GAAG,GAAG,CAAC,eAAe,CAAC,CAAC;QAC/B,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC1B,OAAO,OAAO,CAAC,uCAAuC,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;IAChD,CAAC;IACD,OAAO;QACL,EAAE,EAAE,KAAK;QACT,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,2BAA2B,MAAM,GAAG;KAC5C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAqB;IAClD,OAAO,IAAI,CAAC,EAAE,KAAK,KAAK,CAAC;AAC3B,CAAC;AAED,SAAS,OAAO,CAAC,OAAe;IAC9B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAChE,CAAC"}

package/dist/src/control/server.d.ts

@@ -0,0 +1,52 @@
+import { HandleTable } from '../daemon/handles.js';
+export interface ControlServerOpts {
+    /** Path to bind the Unix socket. */
+    socketPath: string;
+    /** Directory of encrypted keyfiles to load on unlock. */
+    keysDir: string;
+    /** Live HandleTable shared with the MCP server. */
+    handles: HandleTable;
+    /** Optional log sink — defaults to no-op. */
+    onLog?: (event: ControlLogEvent) => void;
+    /** Optional process ID override (tests). */
+    pid?: number;
+}
+export type ControlLogEvent = {
+    kind: 'listening';
+    path: string;
+} | {
+    kind: 'accepted';
+} | {
+    kind: 'request';
+    method: string;
+} | {
+    kind: 'response';
+    ok: boolean;
+    code?: string;
+} | {
+    kind: 'parse_error';
+    line: string;
+} | {
+    kind: 'stale_socket_cleared';
+    path: string;
+} | {
+    kind: 'bind_error';
+    error: string;
+};
+export interface ControlServerHandle {
+    /** Returns when the server socket is closed (and the file unlinked). */
+    close(): Promise<void>;
+    /** The bound socket path (echoed back for convenience). */
+    socketPath: string;
+}
+/**
+ * Start a control listener bound to `socketPath`. Returns once the server is
+ * listening. On EADDRINUSE, probes the existing socket: if it answers, throws
+ * (a live sigil-mcp owns it); if it doesn't, unlinks the stale socket and
+ * re-binds.
+ *
+ * The server is unref'd — it doesn't keep the event loop alive on its own,
+ * so sigil-mcp can still exit when stdin closes.
+ */
+export declare function startControlServer(opts: ControlServerOpts): Promise<ControlServerHandle>;
+//# sourceMappingURL=server.d.ts.map

package/dist/src/control/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/control/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAWpE,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,OAAO,EAAE,WAAW,CAAC;IACrB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IACzC,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA8B9F"}

package/dist/src/control/server.js

@@ -0,0 +1,199 @@
+import { chmodSync, existsSync, unlinkSync } from 'node:fs';
+import { createConnection, createServer } from 'node:net';
+import { HandleLoadError } from '../daemon/handles.js';
+import { CONTROL_SOCKET_VERSION, parseControlRequest, } from './protocol.js';
+/**
+ * Start a control listener bound to `socketPath`. Returns once the server is
+ * listening. On EADDRINUSE, probes the existing socket: if it answers, throws
+ * (a live sigil-mcp owns it); if it doesn't, unlinks the stale socket and
+ * re-binds.
+ *
+ * The server is unref'd — it doesn't keep the event loop alive on its own,
+ * so sigil-mcp can still exit when stdin closes.
+ */
+export async function startControlServer(opts) {
+    const log = (e) => opts.onLog?.(e);
+    const pid = opts.pid ?? process.pid;
+    const server = createServer((sock) => {
+        handleConnection(sock, opts, pid, log).catch((err) => {
+            log({ kind: 'bind_error', error: err.message });
+            sock.destroy();
+        });
+    });
+    server.unref();
+    await bindWithStaleSocketRecovery(server, opts.socketPath, log);
+    try {
+        chmodSync(opts.socketPath, 0o600);
+    }
+    catch {
+        // Best-effort; on some platforms this may not be needed.
+    }
+    log({ kind: 'listening', path: opts.socketPath });
+    return {
+        socketPath: opts.socketPath,
+        close: () => new Promise((resolve) => {
+            server.close(() => {
+                try {
+                    unlinkSync(opts.socketPath);
+                }
+                catch { /* may already be gone */ }
+                resolve();
+            });
+        }),
+    };
+}
+// ---------------------------------------------------------------------------
+// Bind + stale-socket recovery
+// ---------------------------------------------------------------------------
+async function bindWithStaleSocketRecovery(server, socketPath, log) {
+    try {
+        await listen(server, socketPath);
+        return;
+    }
+    catch (err) {
+        if (err.code !== 'EADDRINUSE')
+            throw err;
+    }
+    // Something is at the socket path. Probe it.
+    const alive = await isSocketAlive(socketPath);
+    if (alive) {
+        throw new Error(`control socket ${socketPath} is already in use by another sigil-mcp process`);
+    }
+    // Stale — unlink and retry.
+    try {
+        unlinkSync(socketPath);
+    }
+    catch { /* race: someone else cleaned it */ }
+    log({ kind: 'stale_socket_cleared', path: socketPath });
+    await listen(server, socketPath);
+}
+function listen(server, socketPath) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.removeListener('listening', onListening);
+            reject(err);
+        };
+        const onListening = () => {
+            server.removeListener('error', onError);
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(socketPath);
+    });
+}
+function isSocketAlive(socketPath) {
+    if (!existsSync(socketPath))
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        const sock = createConnection(socketPath);
+        const cleanup = (alive) => {
+            sock.removeAllListeners();
+            sock.destroy();
+            resolve(alive);
+        };
+        sock.once('connect', () => cleanup(true));
+        sock.once('error', () => cleanup(false));
+    });
+}
+// ---------------------------------------------------------------------------
+// Per-connection handler
+// ---------------------------------------------------------------------------
+async function handleConnection(sock, opts, pid, log) {
+    log({ kind: 'accepted' });
+    let buf = '';
+    // Read until we have one line, then dispatch.
+    const line = await new Promise((resolve) => {
+        sock.setEncoding('utf8');
+        const onData = (chunk) => {
+            buf += chunk;
+            const nl = buf.indexOf('\n');
+            if (nl !== -1) {
+                sock.off('data', onData);
+                resolve(buf.slice(0, nl));
+            }
+        };
+        sock.on('data', onData);
+        sock.once('end', () => resolve(buf.length > 0 ? buf : null));
+        sock.once('error', () => resolve(null));
+    });
+    if (line === null) {
+        sock.end();
+        return;
+    }
+    const parsed = parseControlRequest(line);
+    if ('ok' in parsed && parsed.ok === false) {
+        log({ kind: 'parse_error', line });
+        write(sock, parsed);
+        return;
+    }
+    const request = parsed;
+    log({ kind: 'request', method: request.method });
+    const response = dispatch(request, opts, pid);
+    log({ kind: 'response', ok: response.ok, ...(response.ok ? {} : { code: response.code }) });
+    write(sock, response);
+}
+function write(sock, resp) {
+    sock.end(JSON.stringify(resp) + '\n');
+}
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+function dispatch(req, opts, pid) {
+    switch (req.method) {
+        case 'status':
+            return statusResponse(opts.handles, pid);
+        case 'lock':
+            opts.handles.lock();
+            return statusResponse(opts.handles, pid);
+        case 'unlock':
+            return doUnlock(req.passphraseB64, opts, pid);
+    }
+}
+function doUnlock(passphraseB64, opts, pid) {
+    if (opts.handles.isUnlocked()) {
+        return {
+            ok: false,
+            code: 'ALREADY_UNLOCKED',
+            error: 'sigil is already unlocked; run "sigil lock" first to re-unlock',
+        };
+    }
+    let passphrase;
+    try {
+        passphrase = Buffer.from(passphraseB64, 'base64');
+    }
+    catch {
+        return { ok: false, code: 'INVALID_REQUEST', error: 'passphraseB64 is not valid base64' };
+    }
+    try {
+        opts.handles.loadFromDir(opts.keysDir, passphrase);
+    }
+    catch (err) {
+        if (err instanceof HandleLoadError) {
+            // Distinguish wrong-passphrase from other load failures so the CLI can
+            // suggest re-running unlock specifically.
+            if (/wrong passphrase|tampered/.test(err.message)) {
+                return { ok: false, code: 'WRONG_PASSPHRASE', error: err.message };
+            }
+            return { ok: false, code: 'KEYS_LOAD_FAILED', error: err.message };
+        }
+        return { ok: false, code: 'INTERNAL', error: err.message };
+    }
+    finally {
+        passphrase.fill(0);
+    }
+    return statusResponse(opts.handles, pid);
+}
+function statusResponse(handles, pid) {
+    const portals = handles.isUnlocked()
+        ? handles.list().map((p) => ({ handle: p.handle, kind: p.kind, address: p.address }))
+        : [];
+    return {
+        ok: true,
+        version: CONTROL_SOCKET_VERSION,
+        pid,
+        unlocked: handles.isUnlocked(),
+        portals,
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/src/control/server.js.map

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

package/dist/src/daemon/handles.d.ts

@@ -11,9 +11,16 @@ export declare class HandleLoadError extends Error {
 /**
  * In-memory registry of handle → unlocked SecretBuffer.
  *
- * The expectation is that this is constructed once at daemon startup, populated
- * via loadFromDir (or addEntry from tests), and disposed once at shutdown.
- * After dispose() any further get/list calls throw.
+ * Lifecycle inside sigil-mcp:
+ *   - Constructed empty + locked at startup.
+ *   - `sigil unlock` calls loadFromDir / addEntry → table becomes unlocked.
+ *   - `sigil lock` calls lock() → entries zeroed + cleared, table re-lockable.
+ *   - Process exit calls dispose() → final teardown, no further use.
+ *
+ * The unlocked flag is tracked separately from entry count so that an unlock
+ * with zero portals on disk still distinguishes "no portals exist" (handle
+ * lookup → PORTAL_NOT_FOUND) from "never unlocked" (handle lookup →
+ * DAEMON_LOCKED).
  */
 export declare class HandleTable {
     #private;
@@ -24,17 +31,31 @@ export declare class HandleTable {
     static handleFromFilename(filename: string): string | null;
     /**
      * Load every keyfile in `dir` named `<handle>.sigil`, decrypting each with
-     * the same passphrase. Throws HandleLoadError on any failure.
+     * the same passphrase. Throws HandleLoadError on any failure; on failure
+     * the table is left locked with any partially-loaded entries zeroized.
      *
      * Order: deterministic by sorted filename, so audit logs and list_portals
      * output are stable across restarts.
+     *
+     * Marks the table as unlocked on success — even if the directory was
+     * empty (zero portals to load). After that, sign calls see PORTAL_NOT_FOUND
+     * instead of DAEMON_LOCKED.
      */
     loadFromDir(dir: string, passphrase: Buffer): void;
     /**
      * Add a handle directly (for tests or for non-file-backed key sources).
-     * Takes ownership of the SecretBuffer; dispose() will zeroize it.
+     * Takes ownership of the SecretBuffer; lock()/dispose() will zeroize it.
+     * Does NOT flip the unlocked flag — loadFromDir does that once after a
+     * successful pass. Tests that want an unlocked table should call
+     * markUnlocked() explicitly.
      */
     addEntry(handle: string, secret: SecretBuffer): void;
+    /**
+     * Explicitly mark the table as unlocked without loading anything. Useful
+     * for tests that pre-populate via addEntry and want sign methods to
+     * succeed.
+     */
+    markUnlocked(): void;
     has(handle: string): boolean;
     /**
      * Returns the SecretBuffer for the handle. Caller must NOT dispose it —
@@ -42,8 +63,16 @@ export declare class HandleTable {
      */
     get(handle: string): SecretBuffer | undefined;
     list(): PortalInfo[];
+    isUnlocked(): boolean;
+    /**
+     * Zeroize every entry and re-lock the table. The table remains usable —
+     * a subsequent unlock can repopulate it. Idempotent.
+     */
+    lock(): void;
     /**
-     * Zeroize every key and mark the table unusable. Idempotent.
+     * Final teardown: zeroize every key and mark the table unusable. After
+     * dispose(), get/has/list/lock/markUnlocked/addEntry/loadFromDir throw.
+     * Idempotent.
      */
     dispose(): void;
     get isDisposed(): boolean;

package/dist/src/daemon/handles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../../../src/daemon/handles.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,oBAAoB,CAAC;AAQ5B,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBACtB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAK7C;AAED;;;;;;GAMG;AACH,qBAAa,WAAW;;IAKtB,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAMjE,MAAM,CAAC,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAO1D;;;;;;OAMG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAgClD;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAcpD,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAK5B;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAK7C,IAAI,IAAI,UAAU,EAAE;IAKpB;;OAEG;IACH,OAAO,IAAI,IAAI;IAOf,IAAI,UAAU,IAAI,OAAO,CAExB;CACF"}
+{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../../../src/daemon/handles.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,oBAAoB,CAAC;AAQ5B,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBACtB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAK7C;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW;;IAMtB,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAMjE,MAAM,CAAC,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAO1D;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAyClD;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAcpD;;;;OAIG;IACH,YAAY,IAAI,IAAI;IAKpB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAK5B;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAK7C,IAAI,IAAI,UAAU,EAAE;IAKpB,UAAU,IAAI,OAAO;IAKrB;;;OAGG;IACH,IAAI,IAAI,IAAI;IAOZ;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAQf,IAAI,UAAU,IAAI,OAAO,CAExB;CACF"}