@ouro.bot/cli 0.1.0-alpha.886 → 0.1.0-alpha.887

package/dist/a2a/operator-trust.js

@@ -0,0 +1,382 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrustDirectoryError = exports.TRUST_DIR_ENV = exports.OPERATOR_TRUST_ROOT = void 0;
+exports.overrideTrustRootForTests = overrideTrustRootForTests;
+exports.agentNameFromRoot = agentNameFromRoot;
+exports.operatorTrustDir = operatorTrustDir;
+exports.operatorTrustFile = operatorTrustFile;
+exports.readGrantFile = readGrantFile;
+exports.overrideFchownForTests = overrideFchownForTests;
+exports.ensureTrustDirectory = ensureTrustDirectory;
+exports.overrideDirectoryFlushForTests = overrideDirectoryFlushForTests;
+exports.overrideLockTimeoutForTests = overrideLockTimeoutForTests;
+exports.withTrustedWriteLock = withTrustedWriteLock;
+exports.writeTrustedFile = writeTrustedFile;
+exports.describeGrantFile = describeGrantFile;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+const trusted_files_1 = require("./trusted-files");
+/**
+ * Operator-set grants live in a trust directory outside the agent bundle: `/etc/ouro/trust/<agent>/` by default, or
+ * `<OURO_OPERATOR_TRUST_DIR>/<agent>/` when that variable replaces the trust root. The agent's own uid cannot write there, and the bundle's recursive
+ * `chown` during an in-place upgrade cannot reach it. A file in it counts only when the whole chain above it passes
+ * the trusted-files check (real directories, root-owned, closed to group and other writes, up to `/`).
+ */
+exports.OPERATOR_TRUST_ROOT = "/etc/ouro/trust";
+exports.TRUST_DIR_ENV = "OURO_OPERATOR_TRUST_DIR";
+let trustRoot = exports.OPERATOR_TRUST_ROOT;
+/** Tests keep trust directories under their private temp root instead of `/etc`. Refused outside a test runner. */
+function overrideTrustRootForTests(root) {
+    if (process.env.VITEST === undefined)
+        throw new Error("overrideTrustRootForTests is for tests only");
+    trustRoot = root ?? exports.OPERATOR_TRUST_ROOT;
+}
+/** The agent a bundle root belongs to: `~/AgentBundles/sanctuary.ouro` is `sanctuary`. */
+function agentNameFromRoot(agentRoot) {
+    return path.basename(agentRoot).replace(/\.ouro$/u, "");
+}
+/**
+ * The real path of `target`, resolved once. The deepest ancestor that exists is resolved through every symlink and the rest of
+ * the (not yet created) tail is appended, so a configured `/etc/ouro/trust` becomes `/private/etc/ouro/trust` on macOS and the
+ * ancestor check then walks the directories the grants actually sit in.
+ */
+function resolveReal(target) {
+    const tail = [];
+    for (let current = path.resolve(target);; current = path.dirname(current)) {
+        try {
+            return path.join(fs.realpathSync(current), ...tail);
+        }
+        catch {
+            /* v8 ignore next -- the filesystem root always resolves, so this loop never runs out of ancestors @preserve */
+            if (path.dirname(current) === current)
+                return path.resolve(target);
+            tail.unshift(path.basename(current));
+        }
+    }
+}
+/**
+ * Where this agent's operator-set grants live: `<trust root>/<agent>`. `OURO_OPERATOR_TRUST_DIR` replaces the trust root
+ * (`/etc/ouro/trust`) and keeps the per-agent subdirectory, so one setting serves every agent on the host.
+ */
+function operatorTrustDir(agentRoot) {
+    const override = process.env[exports.TRUST_DIR_ENV];
+    const root = override && override.trim().length > 0 ? override : trustRoot;
+    return path.join(resolveReal(root), agentNameFromRoot(agentRoot));
+}
+function operatorTrustFile(agentRoot, fileName) {
+    return path.join(operatorTrustDir(agentRoot), fileName);
+}
+/**
+ * Reads `{ schemaVersion: 1, grants: { <friendId>: entry } }` from the trust directory. A file that is not trusted, not
+ * JSON or not this shape is `untrusted` and holds no grants; a missing file is `missing`. Within a trusted file, an
+ * entry that fails `valid` is dropped and its friend id is listed in `ignored`.
+ */
+function readGrantFile(agentRoot, fileName, valid) {
+    const raw = (0, trusted_files_1.inspectTrustedJson)(operatorTrustFile(agentRoot, fileName));
+    if (raw.state === "missing")
+        return { state: "missing", grants: {}, ignored: [] };
+    if (raw.state === "untrusted")
+        return { state: "untrusted", reason: raw.reason, grants: {}, ignored: [] };
+    const file = raw.value;
+    const grants = file?.grants;
+    if (!file || typeof file !== "object" || file.schemaVersion !== 1 || !grants || typeof grants !== "object" || Array.isArray(grants)) {
+        return { state: "untrusted", reason: "file is not { schemaVersion: 1, grants: {...} }", grants: {}, ignored: [] };
+    }
+    const kept = {};
+    const ignored = [];
+    for (const [friendId, entry] of Object.entries(grants)) {
+        if (valid(entry))
+            kept[friendId] = entry;
+        else
+            ignored.push(friendId);
+    }
+    return { state: "trusted", grants: kept, ignored };
+}
+/** Why the operator command refused to write. The message says what to fix. */
+class TrustDirectoryError extends Error {
+}
+exports.TrustDirectoryError = TrustDirectoryError;
+const isRoot = () => process.geteuid?.() === 0;
+let fchownHook;
+/** Tests are not root, so they watch ownership changes instead of making them. Refused outside a test runner. */
+function overrideFchownForTests(hook) {
+    if (process.env.VITEST === undefined)
+        throw new Error("overrideFchownForTests is for tests only");
+    fchownHook = hook;
+}
+/* v8 ignore start -- the real fchown only succeeds as root; tests watch the hook instead @preserve */
+function chownToRoot(fd) {
+    if (fchownHook)
+        fchownHook(fd, 0, 0);
+    else
+        fs.fchownSync(fd, 0, 0);
+}
+/* v8 ignore stop */
+/**
+ * Makes sure the trust directory exists and is trusted. A missing directory is created root-owned 0755, one component
+ * at a time, but only below an ancestor that is already trusted. An existing directory (or ancestor) that is not
+ * trusted is refused: the command never takes ownership of something the agent could have made.
+ */
+function ensureTrustDirectory(dir) {
+    const missing = [];
+    let base = path.resolve(dir);
+    for (;;) {
+        const result = (0, trusted_files_1.inspectTrustedDirectory)(base);
+        if (result.state === "trusted")
+            break;
+        if (result.state === "untrusted")
+            throw new TrustDirectoryError(`refusing to write: ${base} is not trusted (${result.reason}). Fix its owner and mode as root; this command never takes ownership of an existing directory.`);
+        missing.push(base);
+        base = path.dirname(base);
+    }
+    for (const next of missing.reverse()) {
+        fs.mkdirSync(next, { mode: 0o755 });
+        const fd = fs.openSync(next, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+        try {
+            if (isRoot())
+                chownToRoot(fd);
+            fs.fchmodSync(fd, 0o755);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+}
+/** Flushes a directory's entries to disk, so a rename or a new file in it survives a crash. */
+function fsyncDirectory(dir) {
+    const fd = fs.openSync(dir, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    try {
+        fs.fsyncSync(fd);
+        directoryFlushHook?.(dir);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+let directoryFlushHook;
+/** Tests watch directory flushes (the ESM fs namespace cannot be spied on). Refused outside a test runner. */
+function overrideDirectoryFlushForTests(hook) {
+    if (process.env.VITEST === undefined)
+        throw new Error("overrideDirectoryFlushForTests is for tests only");
+    directoryFlushHook = hook;
+}
+const LOCK_FILE = ".lock";
+const LOCK_STALE_MS = 2 * 60_000;
+/** A lock written by another host or pid namespace (a different hostname in its body) cannot be checked for a live holder, so it is only taken over after this long. */
+const LOCK_FOREIGN_STALE_MS = 60 * 60_000;
+let lockTimeoutMs = 5000;
+let lockWaitHook;
+let beforeReclaimHook;
+/** Tests shorten the wait for a held lock, can act while it waits, and can act between judging a lock stale and reclaiming it. Refused outside a test runner. */
+function overrideLockTimeoutForTests(timeoutMs, onWait, onBeforeReclaim) {
+    if (process.env.VITEST === undefined)
+        throw new Error("overrideLockTimeoutForTests is for tests only");
+    lockTimeoutMs = timeoutMs ?? 5000;
+    lockWaitHook = onWait;
+    beforeReclaimHook = onBeforeReclaim;
+}
+/** How long ago `file` was last written; a file that is gone counts as brand new, so nobody treats it as stale. */
+function ageMs(file) {
+    try {
+        return Date.now() - fs.lstatSync(file).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+const lockBody = () => `pid ${process.pid} host ${os.hostname()} at ${new Date().toISOString()}\n`;
+/** True when a process with this pid exists on this host. EPERM means it exists but is someone else's. */
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+/**
+ * Whether `lock` was left by a writer that is gone. Age alone is not enough: a slow writer can hold the lock for longer than two
+ * minutes. So a lock older than that is stale only when the pid in its body is no longer running on this host. A body that cannot be
+ * read as `pid N host H at T` names no holder at all, and a lock from another host or pid namespace cannot be checked, so it waits
+ * out a much longer age.
+ */
+function lockIsStale(lock) {
+    const age = ageMs(lock);
+    if (age <= LOCK_STALE_MS)
+        return false;
+    let held = null;
+    try {
+        held = /^pid (\d+) host (\S+) at /.exec(fs.readFileSync(lock, "utf8"));
+    }
+    catch {
+        return false;
+    }
+    if (!held)
+        return true;
+    if (held[2] !== os.hostname())
+        return age > LOCK_FOREIGN_STALE_MS;
+    return !processAlive(Number(held[1]));
+}
+/**
+ * Removes a lock that looked stale, but only while holding a second exclusive file (`.lock.reclaim`) and only after looking again:
+ * two writers that both judged the same lock stale cannot then each delete it, which would let the second delete the fresh lock
+ * the first had just taken. A reclaim file that is itself stale belongs to a writer that died and is removed.
+ */
+function reclaimStaleLock(lock) {
+    const guard = `${lock}.reclaim`;
+    try {
+        createExclusive(guard, lockBody());
+    }
+    catch {
+        if (ageMs(guard) > LOCK_STALE_MS)
+            fs.rmSync(guard, { force: true });
+        return;
+    }
+    try {
+        if (lockIsStale(lock))
+            fs.rmSync(lock, { force: true });
+    }
+    finally {
+        fs.rmSync(guard, { force: true });
+    }
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Runs a read-modify-write of the trust files under an exclusive lock file in the trust directory, so two grant commands
+ * cannot both read the old file and then overwrite each other. The lock is created with O_EXCL and records the writer's pid and host;
+ * a lock older than two minutes whose writer is no longer running is taken over. A lock that stays held past the wait names the file to remove.
+ */
+function withTrustedWriteLock(agentRoot, fn) {
+    const dir = operatorTrustDir(agentRoot);
+    ensureTrustDirectory(dir);
+    const lock = path.join(dir, LOCK_FILE);
+    const deadline = Date.now() + lockTimeoutMs;
+    for (;;) {
+        try {
+            createExclusive(lock, lockBody());
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (lockIsStale(lock)) {
+                beforeReclaimHook?.();
+                reclaimStaleLock(lock);
+            }
+            if (Date.now() >= deadline)
+                throw new TrustDirectoryError(`refusing to write: another grant command is writing to ${dir} (lock file ${lock}). If none is running, remove that file and retry. Nothing was written.`);
+            lockWaitHook?.();
+            sleepSync(25);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        fs.rmSync(lock, { force: true });
+    }
+}
+/** Creates `file` exclusively (never through a link or over anything), owned by root with mode 0644 when run as root, and fsyncs it. */
+function createExclusive(file, body) {
+    const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+        if (isRoot())
+            chownToRoot(fd);
+        fs.fchmodSync(fd, 0o644);
+        fs.writeFileSync(fd, body);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function rawBytes(file) {
+    let fd;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        return fs.fstatSync(fd).isFile() ? fs.readFileSync(fd) : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/**
+ * Replaces one file in the trust directory. The previous bytes are kept beside it as a timestamped backup, created the
+ * same safe way. The new file is written to an exclusive random temporary name, owned and moded through its descriptor,
+ * fsynced and renamed into place, so a reader never sees a half-written file and nothing already on disk is followed.
+ */
+function writeTrustedFile(agentRoot, fileName, body, now) {
+    const dir = operatorTrustDir(agentRoot);
+    ensureTrustDirectory(dir);
+    const file = path.join(dir, fileName);
+    const previous = rawBytes(file);
+    let backup = null;
+    if (previous) {
+        backup = `${file}.bak-${now.toISOString().replace(/[:.]/gu, "-")}`;
+        createExclusive(backup, previous);
+        fsyncDirectory(dir);
+    }
+    const tmp = path.join(dir, `.${fileName}.${(0, node_crypto_1.randomBytes)(8).toString("hex")}.tmp`);
+    try {
+        createExclusive(tmp, body);
+        fs.renameSync(tmp, file);
+        fsyncDirectory(dir);
+    }
+    catch (error) {
+        fs.rmSync(tmp, { force: true });
+        throw error;
+    }
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.a2a_trust_file_written", message: "wrote an operator-set trust file", meta: { file, backedUp: backup !== null } });
+    return { backup };
+}
+/** A short human line about the file's state for `list` output and warnings. */
+function describeGrantFile(view, file) {
+    if (view.state === "trusted")
+        return `trusted: ${file}`;
+    if (view.state === "missing")
+        return `not present: ${file}`;
+    return `NOT TRUSTED: ${file} (${view.reason}); no grant in it is honoured`;
+}

package/dist/a2a/outbox-wire.js

@@ -74,7 +74,7 @@ async function handleOutboxCommand(input) {
             return invalid(`ids must be 1 to ${MAX_ACK_IDS} strings`);
         return { ok: true, result: { ...outbox.ack(friend.id, ids) } };
     }
-    if (!(0, escalation_grants_1.holdsEscalation)(agentRoot, friend)) {
+    if (!(0, escalation_grants_1.holdsEscalation)(agentRoot, friend, input.now)) {
         (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_report_resolve_refused", message: "refused report/resolve from a peer without the escalation grant", meta: { friendId: friend.id } });
         return refuse("report/resolve needs the escalation grant");
     }
@@ -82,7 +82,7 @@ async function handleOutboxCommand(input) {
     if (typeof id !== "string" || typeof version !== "string" || typeof note !== "string" || typeof resolvedAt !== "string")
         return invalid("id, version, note and resolvedAt must be strings");
     // The key is the DID the operator pinned in the root-owned grant, never the friend record; and the A2A-verified caller must be that same DID.
-    const holderDid = (0, escalation_grants_1.pinnedHolderDid)(agentRoot, friend.id);
+    const holderDid = (0, escalation_grants_1.pinnedHolderDid)(agentRoot, friend.id, input.now);
     if (!holderDid || input.verifiedDid !== holderDid) {
         (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_report_resolve_refused", message: "refused report/resolve from a caller whose verified DID is not the pinned holder DID", meta: { friendId: friend.id } });
         return refuse("report not resolved: the caller is not the pinned escalation holder");

package/dist/a2a/replay-grant-holders.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPLAY_GRANT_HOLDERS_FILE = void 0;
+exports.isReplayGrantHolder = isReplayGrantHolder;
+const runtime_1 = require("../nerves/runtime");
+const operator_trust_1 = require("./operator-trust");
+/**
+ * The friends the replay gate provisioned as replay peers, kept by the gate itself as root inside the operator trust directory
+ * (`replay-identities.json`, `{ schemaVersion: 1, grants: { <friend id>: { who, name, did } } }`). A grant for one of them must
+ * carry an expiry (and so must every grant when this file is present but cannot be trusted), so a permanent grant can never be left behind by a replay run. This list is the authority for that rule: the
+ * bundle's own replay registry and a grant's free-text source are the agent's to edit and decide nothing here.
+ */
+exports.REPLAY_GRANT_HOLDERS_FILE = "replay-identities.json";
+function validHolder(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const holder = value;
+    return typeof holder.who === "string" && typeof holder.name === "string" && typeof holder.did === "string";
+}
+/**
+ * True when a grant with no expiry for this friend must be refused. That is the case for a friend the list names, for an entry in the list
+ * that is malformed (its id is read from the file but its content is not trusted), and for every friend when the list is present but
+ * untrusted or malformed: a list the Butler cannot rely on must never let a permanent replay grant through. A list that does not exist
+ * yet (no replay gate has run) names nobody.
+ */
+function isReplayGrantHolder(agentRoot, friendId) {
+    const view = (0, operator_trust_1.readGrantFile)(agentRoot, exports.REPLAY_GRANT_HOLDERS_FILE, validHolder);
+    if (view.state === "untrusted") {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_replay_list_untrusted", message: "the replay list is present but cannot be trusted, so no grant without an expiry is honoured", meta: { file: exports.REPLAY_GRANT_HOLDERS_FILE } });
+        return true;
+    }
+    return Object.prototype.hasOwnProperty.call(view.grants, friendId) || view.ignored.includes(friendId);
+}

package/dist/a2a/server.js

@@ -73,8 +73,8 @@ class A2ARequestError extends Error {
 function jsonResponse(id, result) {
     return { jsonrpc: "2.0", id: id ?? null, result };
 }
-function errorResponse(id, code, message) {
-    return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+function errorResponse(id, code, message, data) {
+    return { jsonrpc: "2.0", id: id ?? null, error: { code, message, ...(data !== undefined ? { data } : {}) } };
 }
 async function readBody(req) {
     const chunks = [];
@@ -593,10 +593,10 @@ async function startA2AServer(options) {
                     : undefined;
                 let turnText = text;
                 let delegatedCommand;
-                // Only the server writes the delegated banner; a peer typing it gets it marked as its own words.
-                if (verifiedChat && verifiedChat.onBehalfOf !== "principal" && delegated_command_1.DELEGATED_BANNER.test(text)) {
-                    turnText = `[unverified: the sender typed this banner itself; it is not a delegated command] ${text}`;
-                }
+                // Only the server writes the delegated banner. Any turn that is not about to be admitted as a delegated command
+                // (verified or not, including a plain unauthenticated text turn) gets a typed banner marked as the sender's own words.
+                if (verifiedChat?.onBehalfOf !== "principal")
+                    turnText = (0, delegated_command_1.shieldDelegatedBanner)(text);
                 if (verifiedChat?.onBehalfOf === "principal") {
                     // A delegated command runs with the principal's authority only after the
                     // server, never the model, has checked the grant and told the principal.
@@ -612,7 +612,12 @@ async function startA2AServer(options) {
                         throw new Error("verified chat has no friend record");
                     const admission = await (0, delegated_command_1.admitDelegatedCommand)({ friend: verifiedChat.friend, did: verifiedChat.did, text, commandId: (0, node_crypto_1.randomUUID)(), store: inboundShareDeps.store, registry, options: options.delegation });
                     if (!admission.ok) {
-                        writeJson(res, 200, errorResponse(rpc.id, -32004, `delegated command refused: ${admission.reason}`));
+                        // The code and the "delegated command refused: <reason>" prefix stay: the replay gate and older CLIs match them.
+                        // Only an active family peer is told why: anyone else gets no_grant whatever the real reason was (a broken trust file, a key mismatch), which stays in the local log and nerves.
+                        const activeFamily = verifiedChat.friend.trustLevel === "family" && verifiedChat.friend.admissionState === "active";
+                        const shown = activeFamily ? admission.reason : "no_grant";
+                        const guidance = (0, delegated_command_1.delegationRefusalGuidance)(shown, { legacyRecordGrant: activeFamily && verifiedChat.friend.delegationGrant !== undefined });
+                        writeJson(res, 200, errorResponse(rpc.id, -32004, `delegated command refused: ${shown} (${guidance.message}). Nothing ran. Next: ${guidance.next}`, { reason: shown, nothingRan: true, retry: guidance.retry, next: guidance.next }));
                         return;
                     }
                     relationshipAuthorization = admission.relationship;