@code-yeongyu/senpi 2026.10.24-2 → 2026.10.24-4

package/dist/modes/rpc/rpc-public-auth.js

@@ -0,0 +1,237 @@
+import { randomBytes } from "node:crypto";
+import { Duplex, PassThrough } from "node:stream";
+import { attachJsonlLineReader, MAX_RPC_LINE_CHARACTERS, serializeJsonLine } from "./jsonl.js";
+import { authRecord, RPC_AUTH_CAPABILITY, RPC_AUTH_HEX, rpcAuthProof, rpcProofMatches } from "./rpc-auth-proof.js";
+import { SOCKET_HANDSHAKE_TIMEOUT_MS } from "./socket-transport.js";
+const PREAUTH_BYTES = 8 * 1024;
+/** Filters public input before it can reach either the proxy or the bare host's router. */
+export class PublicRpcConnection {
+    /**
+     * The admitted connection as one duplex for a router that reads and writes a single stream: it reads only
+     * frames this filter released and writes through `response()`, so the challenge answer gains its proof.
+     */
+    get stream() {
+        this.view ??= this.duplex();
+        return this.view;
+    }
+    constructor(socket, endpoint, requireToken = process.env.SENPI_RPC_REQUIRE_TOKEN === "1") {
+        this.input = new PassThrough();
+        this.raw = new PassThrough();
+        this.bytes = 0;
+        this.active = false;
+        this.failed = false;
+        this.first = true;
+        this.protocolPending = false;
+        this.socket = socket;
+        this.endpoint = endpoint;
+        this.requireToken = requireToken;
+        socket.pause();
+        // Enforcing: a client that has not proven the key by the deadline is dropped. Grace: a silent or slow legacy client
+        // (a passive observer) is served as before, with its one deprecation line; a challenge in flight is left to
+        // finish, so its `authenticate` still reaches this filter instead of the router.
+        this.timer = setTimeout(() => {
+            if (this.requireToken)
+                this.drop("pre-auth deadline");
+            else if (!this.active && !this.failed && this.challenge === undefined)
+                this.grace();
+        }, SOCKET_HANDSHAKE_TIMEOUT_MS);
+        const detach = attachJsonlLineReader(this.raw, (line) => this.line(line), {
+            maxLineLength: MAX_RPC_LINE_CHARACTERS,
+            onOversizedLine: () => (this.active ? socket.destroy() : this.drop("first frame over the line limit")),
+        });
+        socket.on("error", () => socket.destroy());
+        socket.once("close", () => {
+            if (!this.active && !this.failed && !this.requireToken && !this.first)
+                this.grace();
+            clearTimeout(this.timer);
+            detach();
+            this.raw.destroy();
+            this.input.end();
+        });
+        socket.once("end", () => this.raw.end());
+        this.input.on("drain", () => socket.resume());
+        socket.on("data", (chunk) => {
+            // Feed a coalesced chunk one LF segment at a time: proof verification can remove
+            // the 8 KiB budget before a large authenticated command in that same chunk.
+            for (let offset = 0; offset < chunk.length && !this.failed;) {
+                const newline = chunk.indexOf(0x0a, offset);
+                const end = newline === -1 ? chunk.length : newline + 1;
+                const segment = chunk.subarray(offset, end);
+                if (!this.active)
+                    this.bytes += segment.length;
+                // Only enforcement bounds pre-auth input: in grace a keyless legacy client is served whatever its first frame
+                // (a long prompt, an image), with or without a challenge it could not answer (no key record).
+                if (!this.active && this.requireToken && this.bytes > PREAUTH_BYTES) {
+                    this.drop("pre-auth budget exceeded");
+                    return;
+                }
+                this.raw.write(segment);
+                offset = end;
+            }
+        });
+        void endpoint.ready.then(() => {
+            if (!socket.destroyed)
+                socket.resume();
+        }, () => this.drop("key publication failed"));
+    }
+    duplex() {
+        const input = this.input;
+        const stream = new Duplex({
+            read: () => input.resume(),
+            write: (chunk, _encoding, callback) => {
+                const output = this.response(chunk.toString());
+                if (output === "")
+                    callback();
+                else
+                    this.socket.write(output, callback);
+            },
+            final: (callback) => this.socket.end(callback),
+            destroy: (error, callback) => {
+                this.socket.destroy();
+                callback(error);
+            },
+        });
+        input.on("data", (chunk) => {
+            if (!stream.push(chunk))
+                input.pause();
+        });
+        // Released frames already queued when the peer goes away are still delivered, then the view closes.
+        input.once("end", () => {
+            stream.push(null);
+            stream.destroy();
+        });
+        if (input.readableEnded)
+            stream.destroy();
+        return stream;
+    }
+    line(line) {
+        if (this.failed || this.socket.destroyed)
+            return;
+        let request;
+        try {
+            request = authRecord(JSON.parse(line));
+        }
+        catch {
+            // Malformed JSON is left to the existing router only after admission.
+        }
+        if (!this.active) {
+            if (this.first && request?.type === "get_protocol_info") {
+                this.first = false;
+                this.protocolPending = true;
+                const nonce = authRecord(request.auth)?.client_nonce;
+                if (nonce !== undefined) {
+                    if (typeof nonce !== "string" || !RPC_AUTH_HEX.test(nonce)) {
+                        this.refuse(request, "auth_failed");
+                        return;
+                    }
+                    this.challenge = { id: request.id, client: nonce, server: randomBytes(32).toString("hex") };
+                }
+                else if (this.requireToken) {
+                    // Wire contract frame 5: under enforcement any other first frame, a keyless get_protocol_info included.
+                    this.refuse(request, "auth_required");
+                    return;
+                }
+                else
+                    this.grace();
+                this.forward(line);
+                return;
+            }
+            this.first = false;
+            if (request?.type === "authenticate") {
+                const c = this.challenge;
+                if (!c ||
+                    !rpcProofMatches(rpcAuthProof(this.endpoint.key, "client", this.endpoint.launchId, c.server, c.client), request.client_proof)) {
+                    this.refuse(request, "auth_failed");
+                    return;
+                }
+                this.active = true;
+                clearTimeout(this.timer);
+                this.socket.write(serializeJsonLine({ id: request.id, type: "response", command: "authenticate", success: true }));
+                return;
+            }
+            if (this.requireToken) {
+                this.refuse(request, "auth_required");
+                return;
+            }
+            this.grace();
+        }
+        this.forward(line);
+    }
+    forward(line) {
+        if (!this.input.write(`${line}\n`))
+            this.socket.pause();
+    }
+    grace() {
+        this.active = true;
+        clearTimeout(this.timer);
+        process.stderr.write(`senpi rpc host: served a client that did not prove the endpoint key on ${this.endpoint.endpoint} (deprecated, refused from the next release; see docs/rpc.md#authentication)\n`);
+    }
+    /** Every pre-auth drop says why on stderr, by reason code only: never a frame, a nonce or key material. */
+    logDrop(reason) {
+        process.stderr.write(`senpi rpc host: dropped an unauthenticated connection on ${this.endpoint.endpoint}: ${reason}\n`);
+    }
+    drop(reason) {
+        if (this.failed)
+            return;
+        this.failed = true;
+        clearTimeout(this.timer);
+        this.logDrop(reason);
+        this.socket.destroy();
+    }
+    refuse(request, code) {
+        this.failed = true;
+        clearTimeout(this.timer);
+        this.logDrop(code);
+        this.socket.end(serializeJsonLine({
+            id: request?.id,
+            type: "response",
+            command: request?.type ?? "parse",
+            success: false,
+            error: code,
+            errorCode: code,
+        }), () => this.socket.destroy());
+    }
+    /**
+     * Writer/proxy batches contain whole JSONL records; ordinary authenticated bytes stay untouched. Before
+     * admission only the challenge answer leaves an enforcing host; a grace host keeps delivering records (the
+     * lifecycle broadcasts a passive legacy observer relies on).
+     */
+    response(chunk) {
+        if (this.failed)
+            return "";
+        if (this.active && !this.protocolPending)
+            return chunk;
+        let output = "";
+        for (const line of chunk.split("\n")) {
+            if (!line)
+                continue;
+            const record = authRecord(JSON.parse(line));
+            if (record?.type === "response" && record.command === "get_protocol_info" && record.success === true) {
+                this.protocolPending = false;
+                const data = authRecord(record.data) ?? {};
+                const capabilities = Array.isArray(data.capabilities) ? data.capabilities : [];
+                const c = this.challenge;
+                output += serializeJsonLine({
+                    ...record,
+                    data: {
+                        ...data,
+                        capabilities: [...new Set([...capabilities, RPC_AUTH_CAPABILITY])],
+                        ...(c && record.id === c.id
+                            ? {
+                                auth: {
+                                    launch_id: this.endpoint.launchId,
+                                    server_nonce: c.server,
+                                    server_proof: rpcAuthProof(this.endpoint.key, "server", this.endpoint.launchId, c.client, c.server),
+                                },
+                            }
+                            : {}),
+                    },
+                });
+            }
+            else if (this.active || !this.requireToken)
+                output += `${line}\n`;
+        }
+        return output;
+    }
+}
+//# sourceMappingURL=rpc-public-auth.js.map

package/dist/modes/rpc/rpc-public-key.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Key-root rule (#3795, shared with the desktop and omo clients): `<root>` and `<root>/rpc` are checked at their
+ * realpath and must be directories owned by this user with no group/other write (0755 is fine); `<root>/rpc/keys`
+ * itself must be a real (non-symlink) directory owned by this user with mode exactly 0700.
+ */
+export declare function checkRpcKeyDirectory(path: string, privateKeys?: boolean): Promise<void>;
+export declare function readRpcKeyRecord(root: string, launchId: string): Promise<Readonly<Record<string, unknown>> | undefined>;
+/** One public binder owns one in-memory key; it never reads a key back from disk. */
+export declare class RpcPublicEndpoint {
+    readonly key: NonSharedBuffer;
+    readonly launchId: `${string}-${string}-${string}-${string}-${string}`;
+    readonly recordPath: string;
+    readonly ready: Promise<void>;
+    private readonly publication;
+    private created;
+    private readonly exitCleanup;
+    readonly agentDir: string;
+    readonly endpoint: string;
+    constructor(agentDir: string, endpoint: string);
+    publish(): Promise<void>;
+    dispose(): Promise<void>;
+}
+/** Unknown process identity keeps a record; only death or observed PID reuse permits collection. */
+export declare function gcRpcPublicKeys(agentDir: string, budget?: {
+    readonly deadline?: number;
+    readonly maxRecords?: number;
+}): Promise<void>;
+//# sourceMappingURL=rpc-public-key.d.ts.map

package/dist/modes/rpc/rpc-public-key.js

@@ -0,0 +1,193 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { constants, unlinkSync } from "node:fs";
+import * as fs from "node:fs/promises";
+import { join } from "node:path";
+import { ProcessIdentityUnreadableError, processMatchesPidFile, readProcessStartTime, } from "../../utils/process-identity.js";
+import { authRecord, RPC_AUTH_HEX, RPC_LAUNCH_ID, RpcEndpointAuthError } from "./rpc-auth-proof.js";
+const MAX_KEY_RECORD_BYTES = 4096;
+/**
+ * Key-root rule (#3795, shared with the desktop and omo clients): `<root>` and `<root>/rpc` are checked at their
+ * realpath and must be directories owned by this user with no group/other write (0755 is fine); `<root>/rpc/keys`
+ * itself must be a real (non-symlink) directory owned by this user with mode exactly 0700.
+ */
+export async function checkRpcKeyDirectory(path, privateKeys = false) {
+    const checked = privateKeys ? path : await fs.realpath(path);
+    const problem = keyDirectoryProblem(await fs.lstat(checked), checked, privateKeys);
+    if (problem !== undefined)
+        throw new RpcEndpointAuthError("unsafe_key_record", `${checked} ${problem}`);
+}
+/** What is wrong with one key-root directory, worded so the message names the fix (senpi#3815 review L6). */
+function keyDirectoryProblem(info, path, privateKeys) {
+    if (!info.isDirectory())
+        return "is not a directory";
+    if (info.uid !== process.getuid?.())
+        return "is not owned by this user";
+    const mode = info.mode & 0o7777;
+    if (privateKeys)
+        return mode === 0o700 ? undefined : `must be mode 0700 (is 0${mode.toString(8)}); run: chmod 700 ${path}`;
+    return (mode & 0o022) === 0 ? undefined : `is writable by group or others; run: chmod go-w ${path}`;
+}
+async function checkRpcKeyParents(root) {
+    await checkRpcKeyDirectory(root);
+    await checkRpcKeyDirectory(join(root, "rpc"));
+}
+export async function readRpcKeyRecord(root, launchId) {
+    if (!RPC_LAUNCH_ID.test(launchId))
+        throw new RpcEndpointAuthError("unsafe_key_record", `invalid launch id under ${root}`);
+    const path = join(root, "rpc", "keys", launchId);
+    try {
+        await checkRpcKeyParents(root);
+        await checkRpcKeyDirectory(join(root, "rpc", "keys"), true);
+        const handle = await fs.open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() ||
+                info.uid !== process.getuid?.() ||
+                (info.mode & 0o7777) !== 0o600 ||
+                info.size > MAX_KEY_RECORD_BYTES)
+                throw new RpcEndpointAuthError("unsafe_key_record", path);
+            const record = authRecord(JSON.parse(await handle.readFile("utf8")));
+            if (record?.version !== 1 ||
+                record.launch_id !== launchId ||
+                typeof record.key !== "string" ||
+                !RPC_AUTH_HEX.test(record.key))
+                throw new RpcEndpointAuthError("unsafe_key_record", path);
+            return record;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return undefined;
+        if (cause instanceof RpcEndpointAuthError)
+            throw cause;
+        throw new RpcEndpointAuthError("unsafe_key_record", path, { cause });
+    }
+}
+/** One public binder owns one in-memory key; it never reads a key back from disk. */
+export class RpcPublicEndpoint {
+    constructor(agentDir, endpoint) {
+        this.key = randomBytes(32);
+        this.launchId = randomUUID();
+        this.publication = Promise.withResolvers();
+        this.created = false;
+        this.exitCleanup = () => {
+            if (!this.created)
+                return;
+            try {
+                unlinkSync(this.recordPath);
+            }
+            catch (cause) {
+                if (!(cause instanceof Error && "code" in cause && cause.code === "ENOENT"))
+                    process.stderr.write("senpi rpc host: could not remove own endpoint key record\n");
+            }
+        };
+        this.agentDir = agentDir;
+        this.endpoint = endpoint;
+        this.recordPath = join(agentDir, "rpc", "keys", this.launchId);
+        this.ready = this.publication.promise;
+        this.ready.catch(() => { });
+    }
+    async publish() {
+        try {
+            await fs.mkdir(join(this.agentDir, "rpc"), { recursive: true, mode: 0o700 });
+            await checkRpcKeyParents(this.agentDir);
+            const keys = join(this.agentDir, "rpc", "keys");
+            await fs.mkdir(keys, { recursive: true, mode: 0o700 });
+            // An existing keys directory this user owns is tightened; a symlink or a foreign one is refused.
+            const directory = await fs.lstat(keys);
+            if (!directory.isDirectory() || directory.uid !== process.getuid?.())
+                throw new RpcEndpointAuthError("unsafe_key_record", keys);
+            if ((directory.mode & 0o7777) !== 0o700)
+                await fs.chmod(keys, 0o700);
+            await checkRpcKeyDirectory(keys, true);
+            const handle = await fs.open(this.recordPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            this.created = true;
+            process.once("exit", this.exitCleanup);
+            try {
+                await handle.writeFile(JSON.stringify({
+                    version: 1,
+                    launch_id: this.launchId,
+                    key: this.key.toString("hex"),
+                    pid: process.pid,
+                    process_start: (await readProcessStartTime(process.pid)) ?? null,
+                    endpoint: this.endpoint,
+                    created_at: new Date().toISOString(),
+                }));
+                await handle.sync();
+                const info = await handle.stat();
+                if (!info.isFile() || info.uid !== process.getuid?.() || (info.mode & 0o7777) !== 0o600)
+                    throw new RpcEndpointAuthError("unsafe_key_record", this.recordPath);
+            }
+            finally {
+                await handle.close();
+            }
+            this.publication.resolve();
+        }
+        catch (cause) {
+            const error = new RpcEndpointAuthError("key_publication_failed", cause instanceof RpcEndpointAuthError ? cause.message : this.recordPath, { cause });
+            this.publication.reject(error);
+            throw error;
+        }
+    }
+    async dispose() {
+        process.off("exit", this.exitCleanup);
+        if (!this.created)
+            return;
+        this.created = false;
+        await fs.unlink(this.recordPath).catch((cause) => {
+            if (!(cause instanceof Error && "code" in cause && cause.code === "ENOENT"))
+                throw cause;
+        });
+    }
+}
+/** Unknown process identity keeps a record; only death or observed PID reuse permits collection. */
+export async function gcRpcPublicKeys(agentDir, budget = {}) {
+    const keys = join(agentDir, "rpc", "keys");
+    try {
+        await checkRpcKeyParents(agentDir);
+        await checkRpcKeyDirectory(keys, true);
+    }
+    catch (cause) {
+        if (cause instanceof RpcEndpointAuthError)
+            return;
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return;
+        throw cause;
+    }
+    const names = await fs.readdir(keys).catch((cause) => {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return [];
+        throw cause;
+    });
+    let examined = 0;
+    for (const name of names) {
+        if (Date.now() >= (budget.deadline ?? Infinity) || examined >= (budget.maxRecords ?? Infinity))
+            break;
+        if (!RPC_LAUNCH_ID.test(name))
+            continue;
+        examined++;
+        try {
+            const record = await readRpcKeyRecord(agentDir, name);
+            if (record === undefined ||
+                typeof record.pid !== "number" ||
+                !Number.isSafeInteger(record.pid) ||
+                record.pid <= 0 ||
+                !(record.process_start === null || typeof record.process_start === "string"))
+                continue;
+            if (await processMatchesPidFile({ pid: record.pid, processStartTime: record.process_start }))
+                continue;
+            await fs.unlink(join(keys, name));
+        }
+        catch (cause) {
+            if (cause instanceof ProcessIdentityUnreadableError || cause instanceof RpcEndpointAuthError)
+                continue;
+            if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+                continue;
+            throw cause;
+        }
+    }
+}
+//# sourceMappingURL=rpc-public-key.js.map

package/dist/modes/rpc/session-router-open-profile.js

@@ -1,3 +1,4 @@
+import { isSpawnedBy } from "../../core/session-spawned-by.js";
 import { HOST_DAEMON_DIR_ENV } from "./host-daemon-paths.js";
 import { hostInstanceId } from "./protocol-identity.js";
 import { sessionAutoTitleError, sessionBrowserEngineError, sessionContextError, sessionKindError, sessionPromptSurfaceError, sessionRetryFallbackError, } from "./rpc-input-validation.js";
@@ -6,16 +7,7 @@ import { error } from "./session-router-errors.js";
 /** `open_session.spawnedBy` must name the parent, root and task when present; the open answers `invalid_spawned_by` otherwise. */
 export function invalidSpawnedBy(command) {
     const ancestry = command.spawnedBy;
-    return (ancestry !== undefined &&
-        (typeof ancestry !== "object" ||
-            ancestry === null ||
-            Array.isArray(ancestry) ||
-            typeof ancestry.parentSessionId !== "string" ||
-            ancestry.parentSessionId.length === 0 ||
-            typeof ancestry.rootSessionId !== "string" ||
-            ancestry.rootSessionId.length === 0 ||
-            typeof ancestry.taskId !== "string" ||
-            ancestry.taskId.length === 0));
+    return ancestry !== undefined && !isSpawnedBy(ancestry);
 }
 export function validatedOpenProfile(host, command, options) {
     // A parked session's reopen replays what its park recorded; a field it left empty stays empty

package/dist/modes/rpc/socket-ownership.d.ts

@@ -98,4 +98,11 @@ export declare function unlinkOwnedSocket(socketPath: string, identity: SocketFi
  * `unlinkOwnedSocket` decides afterwards what may actually be deleted.
  */
 export declare function shieldSocketDuringClose(socketPath: string, close: () => Promise<void>): Promise<void>;
+/**
+ * Takes the public name over with a rename, once - and only while - that name still refers to the
+ * entry this handoff was decided against. A socket that changed underneath belongs to another
+ * process now: replacing it would unlink an endpoint this generation cannot prove it owns, so the
+ * successor aborts instead and leaves both the intruder's socket and its own bind entry alone.
+ */
+export declare function adoptPublicSocket(bindSocket: string, publicSocket: string, expected: SocketFileIdentity | undefined): Promise<void>;
 //# sourceMappingURL=socket-ownership.d.ts.map

package/dist/modes/rpc/socket-ownership.js

@@ -280,4 +280,21 @@ function errorMessage(cause) {
 function isNodeErrorCode(cause, code) {
     return cause instanceof Error && "code" in cause && cause.code === code;
 }
+/**
+ * Takes the public name over with a rename, once - and only while - that name still refers to the
+ * entry this handoff was decided against. A socket that changed underneath belongs to another
+ * process now: replacing it would unlink an endpoint this generation cannot prove it owns, so the
+ * successor aborts instead and leaves both the intruder's socket and its own bind entry alone.
+ */
+export async function adoptPublicSocket(bindSocket, publicSocket, expected) {
+    if (expected === undefined)
+        throw new Error(`${publicSocket}: a generation launch must name the entry it replaces`);
+    const current = await statSocketIdentity(publicSocket);
+    if (current === undefined || current.dev !== expected.dev || current.ino !== expected.ino) {
+        throw new Error(`${publicSocket}: owned by another socket entry now; refusing to replace it`);
+    }
+    // rename(2) is atomic for readers of the path: every connect either reaches the old entry or
+    // this one, never nothing. The inode this supervisor bound simply answers to a second name.
+    await rename(bindSocket, publicSocket);
+}
 //# sourceMappingURL=socket-ownership.js.map

package/docs/rpc.md

@@ -524,6 +524,111 @@ senpi --mode rpc --listen /tmp/senpi-rpc.sock [options]
 `unix://@name` where supported by the host platform. Socket mode accepts concurrent connections while retaining one
 process-global session registry.
 
+### Authentication
+
+Public POSIX endpoints advertise `socket_auth` and prove possession of a fresh per-launch key.
+This applies to ensured hosts, direct supervisors, and bare `--listen` hosts. Windows pipes keep
+their existing raw `.secret` handshake. Terminal control sockets and tool-child channels are unchanged.
+
+The host publishes `<agentDir>/rpc/keys/<launch_id>` before answering any connection. The agent
+directory and `rpc` must be user-owned, non-symlink directories without group/other write
+permission (0755 is supported). Only `rpc/keys` must be 0700. Before publication, the host
+tightens an existing user-owned, non-symlink `rpc/keys` directory to 0700; clients refuse
+unsafe modes rather than changing them.
+The record is exclusively created with `O_NOFOLLOW`, fsynced, and checked to be a user-owned
+regular file with mode 0600. Publication failure closes the endpoint with `key_publication_failed`.
+A group- or other-writable agent directory or `rpc` (for example one created under umask 002) is such a
+failure: the host exits, and its message names the directory and the fix, `chmod go-w <dir>`.
+Each launch generates a new UUID and a new 32-byte key in memory. Hosts delete only their own
+record; `senpi host gc` also collects records whose process is dead or whose PID has been reused.
+
+The JSON record is
+`{version:1, launch_id, key, pid, process_start, endpoint, created_at}`:
+`key` is 64 lowercase hexadecimal characters, `process_start` is the process start identity
+or `null`, and `created_at` is an ISO-8601 UTC timestamp. Never copy the record into logs.
+
+The client's key root defaults to its own agent directory. `SENPI_RPC_KEY_ROOT`,
+`senpi host ... --rpc-key-root <dir>`, and the `keyRoot` option on `RpcClient` and socket probes
+select the host's credential directory without changing the client's models, settings, skills,
+MCP environment, or other profile data. For example, a client using profile B can authenticate
+to an endpoint launched by profile A by selecting A as its key root while keeping B active.
+
+The exchange uses strict LF-delimited JSON:
+
+1. Preserve the caller's own first `get_protocol_info` frame, including `observe` and
+   `origin_host_instance`, and add top-level `auth: {client_nonce}`. A caller starting with
+   another command first sends an observing protocol probe. Both nonces are 32 fresh random
+   bytes encoded as 64 lowercase hex characters.
+2. The normal response's **`data.auth`** contains `{launch_id, server_nonce, server_proof}`.
+   Read and validate the named record, including `version === 1`, matching `launch_id`,
+   a 32-byte key, directory ownership/modes, and an `O_NOFOLLOW` file open.
+3. Verify the server proof, then send `{id, type:"authenticate", client_proof}`. Wait for
+   its successful correlated response before sending any other command. Proofs are lowercase
+   hex HMAC-SHA256 digests, compared as 32 raw bytes in constant time:
+
+   ```js
+   import { createHmac, timingSafeEqual } from "node:crypto";
+
+   const key = Buffer.from(record.key, "hex");
+   const serverProof = createHmac("sha256", key)
+     .update(["senpi-rpc-server", launchId, clientNonce, serverNonce].join("\n"), "utf8")
+     .digest();
+   // Validate that the received proof is exactly 64 lowercase hex characters first.
+   if (!timingSafeEqual(serverProof, Buffer.from(receivedServerProof, "hex")))
+     throw new Error("host_identity_unproven");
+   const clientProof = createHmac("sha256", key)
+     .update(["senpi-rpc-client", launchId, serverNonce, clientNonce].join("\n"), "utf8")
+     .digest("hex");
+   ```
+
+For third-party scripts, the shipped client implements the record checks and complete exchange:
+
+```js
+import { RpcClient } from "@code-yeongyu/senpi";
+
+const client = new RpcClient({ socketPath: endpoint, keyRoot: hostAgentDirectory });
+await client.start();
+try {
+  console.log(await client.listSessions());
+} finally {
+  await client.stop();
+}
+```
+
+The raw key never crosses the socket. A wrong server proof closes the client with
+`host_identity_unproven`; an unsafe record closes it with `unsafe_key_record`. Neither falls
+back. A host's `auth_failed` triggers one fresh connection and credential lookup, not an
+unauthenticated retry.
+
+This release serves clients that never prove the key, with one stderr deprecation line per
+connection and no limit beyond the normal JSONL ones, whatever the first frame (a long prompt or
+an image included) and whether or not the client first received a challenge it could not answer.
+A challenge in flight is not cut short: its `authenticate` may arrive after 2 seconds.
+`SENPI_RPC_REQUIRE_TOKEN=1` enforces now: the first frame must be a `get_protocol_info` carrying
+`auth.client_nonce`, and any other first frame, a keyless `get_protocol_info` included, receives
+`auth_required`; a wrong proof receives `auth_failed`; either way the connection closes before any
+later frame executes. Under enforcement, pre-authentication input is limited to 8 KiB and 2 seconds.
+
+The host never drops an unauthenticated connection silently. Each drop writes one stderr line,
+`senpi rpc host: dropped an unauthenticated connection on <endpoint>: <reason>`, where the reason
+is `auth_required`, `auth_failed`, `pre-auth budget exceeded`, `pre-auth deadline`,
+`first frame over the line limit` or `key publication failed`. The line carries no frame
+content, nonce or key material.
+
+A host is supervised only when it holds the internal key its supervisor hands it on stdin; the
+supervisor-watch environment (`SENPI_RPC_HOST_WATCH_*` and its companions) never switches public
+authentication off, and a host removes those variables once read, so nothing it starts
+inherits them.
+Clients accept pre-change hosts whose protocol answer has no `data.auth`. A missing record
+is the one grace exception: the client logs the key-root remedy and continues without sending
+`authenticate`; an enforcing host then refuses subsequent commands. Enforcement defaults and
+refusal of legacy hosts are separate follow-ups.
+
+Keep endpoints under the protected agent directory for the sandbox boundary. Choosing a `/tmp`
+path or Linux abstract name permits a process that can later bind that name to pose as a legacy
+host during the compatibility period. Challenge-response still prevents disclosure of the key
+to a listener that cannot prove it.
+
 ### Session runtime (`--session-runtime in-process|worker`)
 
 `--session-runtime` selects where a multi-session host runs its sessions:
@@ -1454,7 +1559,7 @@ survive it, and every subcommand accepts any of the three (plus the session's `n
 on every call, resuming a parked session as described above. A session parked before its first message has no
 transcript yet and cannot be resumed; a reference to it is `unknown_session`.
 
-Ownership: socket clients attach before mutating a session. The `senpi host session` commands already attach
+Ownership: public endpoints first use [authentication](#authentication); socket clients then attach before mutating a session. The `senpi host session` commands already attach
 on the acting connection. Raw clients use `attach_session` for a live identity or `open_session` to open/resume
 a path. This release serves and logs legacy unattached mutations unless `SENPI_RPC_REQUIRE_ATTACH=1`;
 see [Attachment admission](#attachment-admission). Reads remain available without an attachment. `close`
@@ -2061,7 +2166,8 @@ registrant opens no socket and writes no registry directory.
   fresh instance id). When that path is longer than a Unix socket path allows, it moves to
   `/tmp/senpi-rpc-<8hex>/tui/`, which must be a private directory of this user. The directory is 0700 and the
   socket 0600. A 32-byte secret is written 0600 beside the socket, and every connection must send it first, the
-  handshake every RPC socket shares; a wrong secret is disconnected before a line is read. After that it is
+  TUI-specific handshake; public RPC hosts use [challenge-response](#authentication). A wrong TUI secret
+  is disconnected before a line is read. After that it is
   ordinary RPC framing: one LF-terminated JSON object per request, one response carrying its `id`.
 - **Registration order.** Registering first writes the session header (so the session id is durable), reaps dead
   `tui` endpoints (`senpi host gc` scoped to `kinds: ["tui"]`), binds the socket and only then writes the

package/docs/settings.md

@@ -103,7 +103,7 @@ Permission rules are a confirmation policy, not a sandbox. Senpi, extensions, pa
 | `defaultModel` | string | - | Startup model ID (saved with Ctrl+S in `/model`, or edited manually) |
 | `recommendedModels` | string[] | `kimi-k3`, `gpt-6-astra`, `gpt-5.6-sol`, `claude-fable-5-1`, `claude-opus-5-5`, `glm-5.2` | Preferred default model ids in priority order. Built-in thinking levels are kimi-k3/`max`, GPT-6 Astra/`high`, GPT-5.6 Sol/`medium`, claude-fable-5-1/`high`, claude-opus-5-5/`max`, glm-5.2/`max`. Override the list or disable auto-switch with `--no-recommended-models` / `warnings.offRecommendedModel`. |
 | `defaultThinkingLevel` | string | - | Startup thinking level (saved with Ctrl+S in `/thinking`, or edited manually): `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"` |
-| `promptPreset` | string | `"auto"` | Force a system prompt preset: `"auto"`, `"kimi-k2-6"`, `"kimi-k2-7"`, `"kimi-k2-8"`, `"kimi-k3"`, `"glm-5.2"`, `"glm-5.3"`, `"grok-4.5"`, `"grok-4.6"`, `"grok-4.7"`, `"claude-fable-5"`, `"claude-fable-5-1"`, `"claude-opus-5-5"`, `"claude-opus-5"`, `"claude-sonnet-5-5"`, `"claude-haiku-5-5"`, `"claude-opus-4-5"`, `"claude-opus-4-6"`, `"claude-opus-4-7"`, `"claude-opus-4-8"`, `"deepseek-v4-flash"`, `"deepseek-v4-flash-0731"`, `"deepseek-v4-1-flash"`, `"deepseek-v4-pro"`, `"gemini-4-argon"`, `"gpt-5"`, `"gpt-5.2"`, `"gpt-5.3-codex"`, `"gpt-5.4"`, `"gpt-5.5"`, `"gpt-5.6"`, or `"gpt-6-astra"` |
+| `promptPreset` | string | `"auto"` | Force a system prompt preset: `"auto"`, `"kimi-k2-6"`, `"kimi-k2-7"`, `"kimi-k2-8"`, `"kimi-k3"`, `"kimi-k3-1"`, `"glm-5.2"`, `"glm-5.3"`, `"grok-4.5"`, `"grok-4.6"`, `"grok-4.7"`, `"claude-fable-5"`, `"claude-fable-5-1"`, `"claude-opus-5-5"`, `"claude-opus-5"`, `"claude-sonnet-5-5"`, `"claude-haiku-5-5"`, `"claude-opus-4-5"`, `"claude-opus-4-6"`, `"claude-opus-4-7"`, `"claude-opus-4-8"`, `"deepseek-v4-flash"`, `"deepseek-v4-flash-0731"`, `"deepseek-v4-1-flash"`, `"deepseek-v4-pro"`, `"gemini-4-argon"`, `"gpt-5"`, `"gpt-5.2"`, `"gpt-5.3-codex"`, `"gpt-5.4"`, `"gpt-5.5"`, `"gpt-5.6"`, or `"gpt-6-astra"` |
 | `hideThinkingBlock` | boolean | `false` | Hide thinking blocks in output |
 | `showCacheMissNotices` | boolean | `false` | Show transcript notices for significant prompt-cache misses, compaction or branch-summary usage, and provider recovery diagnostics such as dropped Anthropic thinking blocks |
 | `thinkingBudgets` | object | - | Custom token budgets per thinking level. Anthropic, Google, and Bedrock use these natively. OpenAI-compatible models use them when `compat.thinkingTokenBudgetField` (or `supportsThinkingTokenBudget`) is set. |