@inetafrica/open-claudia 3.4.24 → 3.5.1

package/bin/transcript-search.js

@@ -10,6 +10,8 @@
 
 const path = require("path");
 const index = require(path.join(__dirname, "..", "core", "transcript-index"));
+const { whoami } = require("./loopback-client");
+const { transcriptOwnerOf } = require(path.join(__dirname, "..", "project-transcripts"));
 
 function parseArgs(argv) {
   const out = { query: [], all: false, project: null, limit: 8, raw: false, rebuild: false, json: false, help: false };
@@ -47,7 +49,41 @@ Options:
 Exit codes: 0 hits, 1 no hits, 2 usage error, 3 index unavailable.`);
 }
 
-function run(argv) {
+// A non-owner's search must stay in their own room: no cross-room widening
+// (--all / --project / --rebuild) and results scoped to the caller's OWN
+// transcript. The room is decided by the RUNNING BOT (whoami — run-attested),
+// never by the process's own env; and the scoped file is confirmed to belong
+// to that principal, so an env-forged OC_TRANSCRIPT_PATH aimed at someone
+// else's transcript is refused. An attributed owner is unrestricted.
+async function resolveScope(opts) {
+  let caller;
+  try { caller = await whoami(); } catch (e) { caller = { attributed: false, owner: false }; }
+  if (caller && caller.owner === true) {
+    const file = (!opts.all && !opts.project) ? (process.env.OC_TRANSCRIPT_PATH || null) : null;
+    if (!opts.all && !opts.project && !file) {
+      console.error("No current-project transcript (OC_TRANSCRIPT_PATH unset). Use --all, --project <name>, or run inside a bot-spawned task.");
+      process.exit(2);
+    }
+    return { file, project: opts.project, all: opts.all };
+  }
+  if (opts.all || opts.project || opts.rebuild) {
+    console.error("Searching or reindexing other rooms (--all / --project / --rebuild) is owner-only. Your search is limited to this room.");
+    process.exit(2);
+  }
+  const file = process.env.OC_TRANSCRIPT_PATH || null;
+  if (!file) {
+    console.error("No room transcript to search (OC_TRANSCRIPT_PATH unset).");
+    process.exit(2);
+  }
+  const owner = transcriptOwnerOf(file);
+  if (!caller || !caller.attributed || !caller.canonicalUserId || owner !== caller.canonicalUserId) {
+    console.error("That transcript is not yours to search — search is limited to your own room.");
+    process.exit(2);
+  }
+  return { file, project: null, all: false };
+}
+
+async function run(argv) {
   const opts = parseArgs(argv);
   if (opts.help) { printHelp(); process.exit(0); }
 
@@ -56,6 +92,10 @@ function run(argv) {
     process.exit(3);
   }
 
+  // Resolve (and room-restrict) the scope BEFORE any index write: a non-owner
+  // may not --rebuild the whole index either.
+  const scope = await resolveScope(opts);
+
   if (opts.rebuild) {
     const r = index.rebuild();
     console.error(`Rebuilt index: ${r.added} entries from ${r.files} transcript files.`);
@@ -67,13 +107,7 @@ function run(argv) {
 
   if (!opts.query) { printHelp(); process.exit(2); }
 
-  const file = (!opts.all && !opts.project) ? (process.env.OC_TRANSCRIPT_PATH || null) : null;
-  if (!opts.all && !opts.project && !file) {
-    console.error("No current-project transcript (OC_TRANSCRIPT_PATH unset). Use --all, --project <name>, or run inside a bot-spawned task.");
-    process.exit(2);
-  }
-
-  const { hits, error } = index.search(opts.query, { project: opts.project, file, limit: opts.limit, raw: opts.raw });
+  const { hits, error } = index.search(opts.query, { project: scope.project, file: scope.file, limit: opts.limit, raw: opts.raw });
   if (error) { console.error(`Query error: ${error}${opts.raw ? "" : " (internal — please report)"}`); process.exit(2); }
   if (hits.length === 0) {
     console.error(`No matches for ${JSON.stringify(opts.query)}${opts.all ? " across all projects" : ""}.`);

package/bin/transcript-window.js

@@ -10,6 +10,9 @@
 //   3. error out — we don't try to guess
 
 const fs = require("fs");
+const path = require("path");
+const { whoami } = require("./loopback-client");
+const { transcriptOwnerOf } = require(path.join(__dirname, "..", "project-transcripts"));
 
 const DEFAULTS = {
   before: 2,
@@ -78,6 +81,32 @@ function resolveTranscriptPath(flagPath) {
   return null;
 }
 
+// A non-owner may only read their OWN room's transcript: --path (an arbitrary
+// file, e.g. the owner's) is refused, and the default OC_TRANSCRIPT_PATH is
+// confirmed to belong to the caller (whoami — run-attested, not the process's
+// own env) so an env-forged path aimed elsewhere is refused. Returns the
+// transcript path to read, or exits with a refusal. Owner is unrestricted.
+async function resolveScopedTranscriptPath(opts) {
+  let caller;
+  try { caller = await whoami(); } catch (e) { caller = { attributed: false, owner: false }; }
+  if (caller && caller.owner === true) return resolveTranscriptPath(opts.path);
+  if (opts.path) {
+    console.error("Reading another transcript with --path is owner-only. You can read only your own room's transcript.");
+    process.exit(2);
+  }
+  const file = process.env.OC_TRANSCRIPT_PATH || null;
+  if (!file) {
+    console.error("No room transcript to read (OC_TRANSCRIPT_PATH unset).");
+    process.exit(2);
+  }
+  const owner = transcriptOwnerOf(file);
+  if (!caller || !caller.attributed || !caller.canonicalUserId || owner !== caller.canonicalUserId) {
+    console.error("That transcript is not yours to read — you can read only your own room's transcript.");
+    process.exit(2);
+  }
+  return file;
+}
+
 function loadTurns(transcriptPath) {
   const raw = fs.readFileSync(transcriptPath, "utf-8");
   const turns = [];
@@ -125,13 +154,13 @@ function formatTurn(turn, label, maxChars) {
   ].join("\n");
 }
 
-function run(argv) {
+async function run(argv) {
   const opts = parseArgs(argv);
   if (opts.help || !opts.pattern) {
     printHelp();
     process.exit(opts.help ? 0 : 2);
   }
-  const transcriptPath = resolveTranscriptPath(opts.path);
+  const transcriptPath = await resolveScopedTranscriptPath(opts);
   if (!transcriptPath) {
     console.error("No transcript path. Pass --path <file>, or run inside an active bot-spawned task (OC_TRANSCRIPT_PATH).");
     process.exit(2);

package/core/actions.js

@@ -741,15 +741,26 @@ async function handleAction(envelope) {
     const reach = parts[2]; // "room" | "all"
     if (reach !== "room" && reach !== "all") return;
     if (!rec) return send("That request expired — nothing to grant from it.");
+    // Destructive is never a standing permission: each destructive run gets
+    // its own card, however often the owner has approved one before.
+    if (String(rec.tier || "").toLowerCase() === "destructive") {
+      return send("Destructive actions always ask; no standing permission. Use Approve once for this run.");
+    }
     if (!rec.speakerId || !rec.room) return send("I can't tell who asked apart from where they asked — no grant written.");
+    // A grant covers one identifiable person. An anonymous admin, a channel
+    // post, a missing sender or the bot itself would hand it to whoever
+    // hides behind that id.
+    const grantsLib = require("./grants");
+    const refusal = grantsLib.principalRefusal({ adapter: rec.targetAdapter || rec.adapter, senderId: rec.speakerId, room: rec.room });
+    if (refusal) {
+      return send(`No standing permission for ${refusal} — a grant needs one identifiable person. Use Approve once for this request.`);
+    }
     // A reply/triage card only ever cleared talking; an action card carries the
     // tier it asked for. Never grant more than the card actually showed.
-    const capability = rec.kind === "action"
-      ? (String(rec.tier || "") === "destructive" ? "destructive" : "act")
-      : "read";
+    const capability = rec.kind === "action" ? "act" : "read";
     let record;
     try {
-      record = require("./grants").grant({
+      record = grantsLib.grant({
         adapter: rec.targetAdapter || rec.adapter,
         senderId: rec.speakerId,
         room: rec.room,

package/core/approvals.js

@@ -112,7 +112,7 @@ function prune() {
 // speaker), the vetted `payloadText` to deliver on a reply approval, the
 // `target*` external channel, and person/entity pointers for Always-allow.
 function create({
-  tool, verb = "", tier = "destructive", command = "", channelId = "", adapter = "",
+  tool, verb = "", tier = "", command = "", channelId = "", adapter = "",
   canonicalUserId = "", userId = "", provider = "", providerSettings = {},
   project = "", projectDir = "", sessionId = "", previousSessionId = "", originRunId = "",
   kind = "tool", approverAdapter = "", approverChannel = "",
@@ -205,10 +205,30 @@ function detach(id) {
   } finally { releaseRecordLock(held); }
 }
 
+// Risk tiers an approval can carry for a tool run. A record's `tier` is what
+// the owner saw on the card; reply/triage records carry non-tool tiers.
+const TIER_RANK = { "read-only": 0, write: 1, destructive: 2 };
+
+function riskTier(value) {
+  const tier = String(value || "").trim().toLowerCase();
+  return Object.prototype.hasOwnProperty.call(TIER_RANK, tier) ? tier : "";
+}
+
+// The tier a redeemed approval authorizes: exactly the tier on the record the
+// owner approved. A record without one (created before tiers were recorded)
+// falls back to the tier the tool/verb declares for this run — never to
+// "destructive" by default.
+function approvedTier(record, runTier) {
+  return riskTier(record && record.tier) || riskTier(runTier) || "read-only";
+}
+
 // One-shot token redemption for the async path. Fail-closed on every branch:
 // only an approved, un-consumed, un-expired record whose stored command is
 // byte-identical to what is about to run can be consumed — and only once.
-function consume(id, commandLine) {
+// With `tier` (the run's resolved tier), a run that now resolves above the tier
+// the owner approved (the verb was reclassified since) is refused WITHOUT
+// consuming the token: an approval never stretches past what the card showed.
+function consume(id, commandLine, { tier = "" } = {}) {
   try { fileOf(id); }
   catch (_) { return { ok: false, reason: "unknown or expired approval id" }; }
   const held = acquireRecordLock(id);
@@ -231,6 +251,11 @@ function consume(id, commandLine) {
       : Buffer.byteLength(String(rec.command || "")) <= MAX_COMMAND_BYTES
         && candidate === String(rec.command || "");
     if (!matches) return { ok: false, reason: "command does not match the approved payload" };
+    const approved = riskTier(rec.tier);
+    const wanted = riskTier(tier);
+    if (approved && wanted && TIER_RANK[wanted] > TIER_RANK[approved]) {
+      return { ok: false, reason: `approval covers a ${approved} run, but this run is ${wanted}` };
+    }
     rec.consumedAt = new Date().toISOString();
     writeRecord(rec);
     return { ok: true, record: rec };
@@ -277,6 +302,7 @@ function markMined(ids) {
 module.exports = {
   APPROVALS_DIR,
   MAX_COMMAND_BYTES,
+  approvedTier,
   commandHash,
   consume,
   create,

package/core/bot-endpoint.js

@@ -0,0 +1,194 @@
+// Which loopback endpoint may a CLI believe about WHO it acts for?
+//
+// Owner-only CLI verbs and staff tool writes are decided by asking the bot
+// (whoami, tool-gate). The address to ask comes from this process's env
+// (OC_SEND_URL), and a staff turn's shell can point that at a server of its
+// own that answers "owner" (Phase 0 review, CRITICAL). So an endpoint is
+// believed for those answers only when:
+//   1. the process LISTENING on it is this process or one of its ancestors —
+//      the bot spawns every run, so the real bot is always above the CLI,
+//      while a server a turn starts is beside it at best; and
+//   2. nothing above that listener was STARTED with OC_GUARDED_RUN=1 in its
+//      environment — the listener was not itself started inside a staff turn
+//      (such a server could run the CLI as its own child, making itself an
+//      ancestor). A process's start-up environment is fixed by whoever spawned
+//      it; a turn's shell cannot rewrite its provider's.
+// Linux reads /proc; macOS asks /bin/ps and /usr/sbin/lsof by absolute path
+// (PATH belongs to the caller). Anything that cannot be established is a
+// refusal, and a refused caller is unattributed — never the owner.
+//
+// Residual, closed by Phase 2's tool-only staff turns: a staff shell that
+// detaches a server from its turn and runs the CLI beneath that server is no
+// longer below the guarded provider, so rule 2 cannot see it.
+
+const fs = require("fs");
+const { execFileSync } = require("child_process");
+
+const MAX_DEPTH = 64;
+const PS = "/bin/ps";
+const LSOF = "/usr/sbin/lsof";
+const EXEC_TIMEOUT_MS = 5000;
+
+function parsePort(url) {
+  let parsed;
+  try { parsed = new URL(String(url)); } catch (_) { return null; }
+  if (parsed.protocol !== "http:") return null;
+  if (parsed.hostname !== "127.0.0.1" && parsed.hostname !== "localhost") return null;
+  const port = Number(parsed.port);
+  return Number.isInteger(port) && port > 0 && port < 65536 ? port : null;
+}
+
+// ── Linux: /proc ─────────────────────────────────────────────────────────────
+// The loopback binds 127.0.0.1 itself, never a wildcard, and nothing else can
+// bind that exact address and port while it listens (no SO_REUSEPORT), so the
+// only listener that counts is an IPv4 127.0.0.1 socket. /proc/net/tcp shows
+// the address as little-endian hex.
+const LINUX_LOOPBACK_HEX = "0100007F";
+
+function linuxSystem(procRoot = "/proc") {
+  return {
+    parentOf(pid) {
+      const stat = fs.readFileSync(`${procRoot}/${pid}/stat`, "utf8");
+      // "pid (comm) state ppid ..." — comm may hold spaces and parentheses.
+      const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+      const ppid = Number(fields[1]);
+      return Number.isInteger(ppid) ? ppid : null;
+    },
+    // The pid in `pids` that owns the 127.0.0.1:port listening socket, else null.
+    listenerAmong(port, pids) {
+      const inodes = new Set();
+      const text = fs.readFileSync(`${procRoot}/net/tcp`, "utf8");
+      for (const line of text.split("\n").slice(1)) {
+        const cols = line.trim().split(/\s+/);
+        if (cols.length < 10 || cols[3] !== "0A") continue; // 0A = LISTEN
+        const [addr, portHex] = cols[1].split(":");
+        if (addr === LINUX_LOOPBACK_HEX && parseInt(portHex, 16) === port) inodes.add(cols[9]);
+      }
+      if (!inodes.size) return null;
+      for (const pid of pids) {
+        let fds = [];
+        try { fds = fs.readdirSync(`${procRoot}/${pid}/fd`); } catch (_) { continue; }
+        for (const fd of fds) {
+          let link = "";
+          try { link = fs.readlinkSync(`${procRoot}/${pid}/fd/${fd}`); } catch (_) { continue; }
+          const match = /^socket:\[(\d+)\]$/.exec(link);
+          if (match && inodes.has(match[1])) return pid;
+        }
+      }
+      return null;
+    },
+    startEnvHas(pid, key, value) {
+      const raw = fs.readFileSync(`${procRoot}/${pid}/environ`, "utf8");
+      return raw.split("\0").includes(`${key}=${value}`);
+    },
+  };
+}
+
+// ── macOS: /bin/ps + /usr/sbin/lsof ─────────────────────────────────────────
+function run(file, args) {
+  return execFileSync(file, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: EXEC_TIMEOUT_MS,
+    maxBuffer: 64 * 1024 * 1024,
+    env: { PATH: "/usr/bin:/bin:/usr/sbin:/sbin", LANG: "C", LC_ALL: "C" },
+  });
+}
+
+function darwinSystem() {
+  let parents = null;
+  return {
+    parentOf(pid) {
+      if (!parents) {
+        parents = new Map();
+        for (const line of run(PS, ["-Ao", "pid=,ppid="]).split("\n")) {
+          const [p, pp] = line.trim().split(/\s+/).map(Number);
+          if (Number.isInteger(p) && Number.isInteger(pp)) parents.set(p, pp);
+        }
+      }
+      return parents.has(pid) ? parents.get(pid) : null;
+    },
+    listenerAmong(port, pids) {
+      let out = "";
+      try { out = run(LSOF, ["-nP", "-a", "-p", pids.join(","), `-iTCP@127.0.0.1:${port}`, "-sTCP:LISTEN", "-Fpn"]); }
+      catch (error) {
+        // Exit 1 whenever some listed pid matched nothing (or is another
+        // user's); what did match is still on stdout.
+        if (!error || error.status !== 1) throw error;
+        out = String(error.stdout || "");
+      }
+      const owners = new Set();
+      let current = null;
+      for (const line of out.split("\n")) {
+        if (line.startsWith("p")) current = Number(line.slice(1));
+        else if (line === `n127.0.0.1:${port}` && current != null) owners.add(current);
+      }
+      for (const pid of pids) if (owners.has(pid)) return pid;
+      return null;
+    },
+    // ps -E prints the command line followed by the environment the process
+    // started with; the environment is what follows the plain command line.
+    startEnvHas(pid, key, value) {
+      const withEnv = run(PS, ["-E", "-ww", "-o", "command=", "-p", String(pid)]).replace(/\n+$/, "");
+      const bare = run(PS, ["-ww", "-o", "command=", "-p", String(pid)]).replace(/\n+$/, "");
+      if (!withEnv.startsWith(bare)) return false;
+      return withEnv.slice(bare.length).split(" ").includes(`${key}=${value}`);
+    },
+  };
+}
+
+function currentSystem() {
+  if (process.platform === "linux") return linuxSystem();
+  if (process.platform === "darwin") return darwinSystem();
+  return null;
+}
+
+function ancestry(pid, system) {
+  const chain = [pid];
+  let current = pid;
+  while (chain.length < MAX_DEPTH) {
+    const parent = system.parentOf(current);
+    if (!Number.isInteger(parent) || parent <= 0 || chain.includes(parent)) break;
+    chain.push(parent);
+    current = parent;
+  }
+  return chain;
+}
+
+function refuse(reason) {
+  return { ok: false, reason };
+}
+
+// { ok: true, url, port, listenerPid } when `url` may be believed about who
+// this process acts for; { ok: false, reason } otherwise.
+function verifyEndpoint(url, { pid = process.pid, system = currentSystem() } = {}) {
+  const port = parsePort(url);
+  if (!port) return refuse("the loopback address is not a 127.0.0.1 endpoint");
+  if (!system) return refuse(`cannot inspect processes on ${process.platform}`);
+  let chain;
+  let listener;
+  try {
+    chain = ancestry(pid, system);
+    listener = system.listenerAmong(port, chain);
+  } catch (error) {
+    return refuse(`cannot read the process tree (${error && error.message ? error.message : error})`);
+  }
+  if (listener == null) return refuse("the loopback endpoint is not served by this process or an ancestor");
+  for (const above of chain.slice(chain.indexOf(listener) + 1)) {
+    let guarded = false;
+    // Unreadable = another user's process, never a guarded provider (the bot
+    // starts providers as its own user).
+    try { guarded = system.startEnvHas(above, "OC_GUARDED_RUN", "1") === true; } catch (_) { guarded = false; }
+    if (guarded) return refuse("the loopback endpoint was started inside a guarded (non-owner) run");
+  }
+  return { ok: true, url: `http://127.0.0.1:${port}`, port, listenerPid: listener };
+}
+
+const verified = new Map();
+function verifyEndpointCached(url) {
+  const key = String(url || "");
+  if (!verified.has(key)) verified.set(key, verifyEndpoint(url));
+  return verified.get(key);
+}
+
+module.exports = { verifyEndpoint, verifyEndpointCached, parsePort, linuxSystem, darwinSystem, ancestry };

package/core/grants.js

@@ -25,6 +25,13 @@ const { atomicWriteFileSync, readJsonWithFallback } = require("./fsutil");
 // maps a proposed action onto the same ladder and refuses anything above.
 const CAPABILITIES = ["read", "act", "destructive"];
 
+// Destructive is never a standing permission: every destructive run gets its
+// own owner card. grant() refuses it, and a legacy `destructive` record still
+// on disk counts as `act` — the owner plainly trusted that person to act, but
+// a destructive run keeps asking. The file itself is left untouched.
+const STANDING_CEILING = "act";
+const DESTRUCTIVE_REFUSAL = "Destructive actions always ask; no standing permission.";
+
 const ALL_ROOMS = "*";
 
 function nowIso() { return new Date().toISOString(); }
@@ -39,6 +46,78 @@ function normalizeCapability(capability) {
   return CAPABILITIES.includes(c) ? c : "read";
 }
 
+function grantError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+// Logged once per record per process, so a busy room doesn't flood the audit.
+const noted = new Set();
+function noteOnce(kind, g, extra = {}) {
+  const key = `${kind}:${g && g.id}`;
+  if (noted.has(key)) return;
+  noted.add(key);
+  try {
+    require("./audit").log(kind, {
+      id: g && g.id,
+      principal: principalKey(g && g.principal && g.principal.adapter, g && g.principal && g.principal.channelId),
+      room: g && g.room,
+      ...extra,
+    });
+  } catch (e) { /* best effort */ }
+}
+
+// The capability a stored grant actually confers.
+function effectiveCapability(g) {
+  const stored = normalizeCapability(g && g.capability);
+  if (capabilityRank(stored) <= capabilityRank(STANDING_CEILING)) return stored;
+  noteOnce("grant.destructive-downgraded", g, { effective: STANDING_CEILING });
+  return STANDING_CEILING;
+}
+
+// Senders that are not one identifiable person. A grant to any of them would
+// cover whoever hides behind them, so they are refused. Telegram gives
+// messages sent on behalf of a chat (Bot API `sender_chat`) a fake `from`,
+// and each of these ids is shared by EVERY such sender in every group.
+const TELEGRAM_STAND_IN_SENDERS = new Map([
+  ["1087968824", "an anonymous group admin"],        // @GroupAnonymousBot
+  ["136817688", "someone posting as a channel"],     // @Channel_Bot
+  ["777000", "a channel post forwarded by Telegram"], // Telegram service account
+]);
+
+// The bot's own ids, from the operator's config (never the token itself).
+function botSelfIds(adapter) {
+  let cfg = {};
+  try { cfg = require("./config").config || {}; } catch (e) { return []; }
+  const ids = [];
+  if (adapter === "telegram") ids.push(String(cfg.TELEGRAM_BOT_TOKEN || "").split(":")[0].trim());
+  if (adapter === "kazee" || adapter === "spaces") ids.push(String(cfg.KAZEE_BOT_USER_ID || "").trim());
+  return ids.filter(Boolean);
+}
+
+// null when (adapter, sender) is one verifiable person; otherwise who it is
+// instead, for the refusal message. `room` is the `<surface>:<id>` key.
+function principalRefusal({ adapter, senderId, room = "" } = {}) {
+  const a = String(adapter || "").trim().toLowerCase();
+  const s = String(senderId || "").trim();
+  if (!a || !s) return "a sender with no id";
+  if (botSelfIds(a).includes(s)) return "the bot itself";
+  if (a === "telegram") {
+    if (TELEGRAM_STAND_IN_SENDERS.has(s)) return TELEGRAM_STAND_IN_SENDERS.get(s);
+    // Telegram people have positive numeric ids; groups and channels negative.
+    if (!/^\d+$/.test(s)) return "a group or channel rather than a person";
+  }
+  if (a === "spaces" && s.startsWith("unknown-actor:")) return "an unidentified Spaces actor";
+  // An adapter that lost the sender falls back to the room id (Kazee does);
+  // only a Telegram DM legitimately has sender id == chat id.
+  const r = String(room || "");
+  if (a !== "telegram" && r.startsWith(`${a}:`) && r.slice(a.length + 1) === s) {
+    return "the room itself (no sender id)";
+  }
+  return null;
+}
+
 // Rooms are keyed `<surface>:<id>`, matching core/identity.conversationKeyFor
 // so a caller can hand us a conversation key directly.
 function roomKey(surface, roomId) {
@@ -72,48 +151,87 @@ function isLive(grant, at = Date.now()) {
   return true;
 }
 
-// The deterministic lookup that replaces the LLM as the gate. Returns the
-// strongest live grant for this principal in this room, preferring a grant
-// issued for this exact room over an all-rooms grant, so a narrow room grant
-// can never be weakened by a broad one and vice versa.
-function resolve({ adapter, senderId, room }) {
+// Every live grant for this principal that reaches this room. Records for a
+// principal that could not be granted today (anonymous, the bot itself) are
+// ignored rather than honoured.
+function matchingGrants({ adapter, senderId, room }) {
   const principal = principalKey(adapter, senderId);
+  if (!principal) return [];
   const target = String(room || "");
-  if (!principal) return null;
   const at = Date.now();
-  const candidates = load().filter((g) =>
-    isLive(g, at)
-    && principalKey(g.principal?.adapter, g.principal?.channelId) === principal
-    && (g.room === target || g.room === ALL_ROOMS));
-  if (!candidates.length) return null;
-  candidates.sort((a, b) => {
-    // Exact room beats all-rooms; then the stronger capability wins.
-    const exact = (b.room === target) - (a.room === target);
-    if (exact) return exact;
-    return capabilityRank(b.capability) - capabilityRank(a.capability);
+  return load().filter((g) => {
+    if (!isLive(g, at)) return false;
+    if (principalKey(g.principal?.adapter, g.principal?.channelId) !== principal) return false;
+    if (g.room !== target && g.room !== ALL_ROOMS) return false;
+    const refusal = principalRefusal({ adapter: g.principal?.adapter, senderId: g.principal?.channelId, room: g.room });
+    if (refusal) { noteOnce("grant.unverifiable-ignored", g, { refusal }); return false; }
+    return true;
   });
-  return candidates[0];
 }
 
-// True when this principal may take an action at `needed` strength in `room`.
+// The record as it applies now: a legacy destructive grant reads as `act`.
+function asEffective(g) {
+  const effective = effectiveCapability(g);
+  return effective === normalizeCapability(g.capability) ? g : { ...g, capability: effective, storedCapability: g.capability };
+}
+
+// Among grants that all answer the question: a standing grant before a
+// turn-limited one (never burn a "just this once" while a standing grant
+// covers it), then the exact room before all-rooms (the audit names the most
+// specific record), then the newest.
+function preference(target) {
+  return (a, b) => ((a.turnsRemaining != null) - (b.turnsRemaining != null))
+    || ((b.room === target) - (a.room === target))
+    || String(b.grantedAt || "").localeCompare(String(a.grantedAt || ""));
+}
+
+function strongestFirst(target) {
+  const prefer = preference(target);
+  return (a, b) => (capabilityRank(effectiveCapability(b)) - capabilityRank(effectiveCapability(a))) || prefer(a, b);
+}
+
+// The deterministic lookup that replaces the LLM as the gate. Grants add up:
+// the effective grant is the STRONGEST live match, so an exact-room grant
+// never weakens an all-rooms one or the other way round. To take access
+// away, revoke; a narrower grant does not.
+function resolve({ adapter, senderId, room }) {
+  const candidates = matchingGrants({ adapter, senderId, room });
+  if (!candidates.length) return null;
+  candidates.sort(strongestFirst(String(room || "")));
+  return asEffective(candidates[0]);
+}
+
+// True when this principal may take an action at `needed` strength in `room`:
+// some matching grant is strong enough and its scope covers the subject.
+// Destructive never passes — no standing grant confers it.
 // Owners never reach here — they are resolved before any grant lookup.
 function allows({ adapter, senderId, room, needed = "read", subject = null }) {
-  const grant = resolve({ adapter, senderId, room });
-  if (!grant) return { ok: false, reason: "no_grant", grant: null };
-  if (capabilityRank(grant.capability) < capabilityRank(needed)) {
-    return { ok: false, reason: "capability_too_low", grant };
+  const target = String(room || "");
+  const candidates = matchingGrants({ adapter, senderId, room });
+  if (!candidates.length) return { ok: false, reason: "no_grant", grant: null };
+  const strong = candidates.filter((g) => capabilityRank(effectiveCapability(g)) >= capabilityRank(needed));
+  if (!strong.length) {
+    candidates.sort(strongestFirst(target));
+    return { ok: false, reason: "capability_too_low", grant: asEffective(candidates[0]) };
   }
-  const scope = Array.isArray(grant.scope) ? grant.scope : [];
   // An empty scope means "anything within this capability" — a scoped grant
   // only covers the subjects it names.
-  if (scope.length && subject && !scope.includes(String(subject))) {
-    return { ok: false, reason: "out_of_scope", grant };
+  const covers = (g) => {
+    const scope = Array.isArray(g.scope) ? g.scope : [];
+    return !scope.length || !subject || scope.includes(String(subject));
+  };
+  const covering = strong.filter(covers);
+  if (!covering.length) {
+    strong.sort(preference(target));
+    return { ok: false, reason: "out_of_scope", grant: asEffective(strong[0]) };
   }
-  return { ok: true, reason: "granted", grant };
+  covering.sort(preference(target));
+  return { ok: true, reason: "granted", grant: asEffective(covering[0]) };
 }
 
 // Only an owner may call this — enforced by the caller, which holds the turn
-// context needed to know who is asking.
+// context needed to know who is asking. Refuses destructive (never standing)
+// and any principal that is not one identifiable person.
 function grant({
   adapter,
   senderId,
@@ -130,6 +248,13 @@ function grant({
   if (!principal) throw new Error("adapter and senderId are required");
   const target = allRooms ? ALL_ROOMS : String(room || "");
   if (!target) throw new Error("room is required unless allRooms is set");
+  if (capabilityRank(normalizeCapability(capability)) > capabilityRank(STANDING_CEILING)) {
+    throw grantError("GRANT_DESTRUCTIVE_REFUSED", DESTRUCTIVE_REFUSAL);
+  }
+  const refusal = principalRefusal({ adapter, senderId, room });
+  if (refusal) {
+    throw grantError("GRANT_PRINCIPAL_UNVERIFIABLE", `No standing permission for ${refusal} — a grant needs one identifiable person.`);
+  }
   const grants = load();
   // Re-granting the same pair replaces rather than stacks, so revoking one
   // record can never leave a weaker duplicate behind still granting access.
@@ -203,12 +328,16 @@ function listForRoom(room, { includeExpired = false } = {}) {
 
 module.exports = {
   CAPABILITIES,
+  STANDING_CEILING,
+  DESTRUCTIVE_REFUSAL,
   ALL_ROOMS,
   GRANTS_FILE,
   roomKey,
   principalKey,
+  principalRefusal,
   capabilityRank,
   normalizeCapability,
+  effectiveCapability,
   isLive,
   resolve,
   allows,