agent-sanitizer 2.58.10 → 2.58.11

package/THREAT-MODEL.md

@@ -240,11 +240,14 @@ plugin injects the Python engine from `agent-sanitizer[secrets]`
 
 **It is the one fail-closed layer.** A redactor that throws — unreachable
 daemon, engine error — is rethrown from `sanitizeValue` as `CRITICAL: secret
-redaction failed …` (`src/output.mjs`), so the caller suppresses the output
-rather than emit a value nothing vetted. That is distinct from an engine that
-was never provisioned: there the hooks' posture applies, passing the output
-through with a loud warning by default and suppressing it under
-`AGENT_SANITIZER_FAIL_OPEN=0`. Either way the gap is announced, never silent.
+redaction failed …` (`src/output.mjs`).
+With the layer opted in, the output hook's fault policy (`alwaysClosed` in
+`claude-hooks/sanitize-output.mjs`, resolved in `lib/hook-fault.mjs`) then
+suppresses the output under **either** `AGENT_SANITIZER_FAIL_OPEN` posture —
+and so does any other fault of that hook, since an output the hook failed on
+was never vetted for secrets either. One accepted gap: a launcher-level failure
+(no `node`, corrupt bundle) never runs the policy, so the launcher's own
+posture applies there, warning by default.
 
 **Lone surrogates are normalized to U+FFFD before the redactor sees the text.**
 A secret split by an interposed lone surrogate renders as contiguous to the
@@ -839,8 +842,10 @@ to hold precision. All other faults keep the open default, and
 **The open default is not enforceable against content.** Several of those
 failures are composable by whoever authored the payload — in the output hook
 alone, a nesting depth that overflows the sanitize walk and a redaction budget
-exhausted by many secret-shaped leaves. (A **key collision** — two field names
-that collapse to one after Layer 1 — used to be on that list. It no longer
+exhausted by many secret-shaped leaves — though with Layer 4 opted in, the
+output hook withholds on any fault whatever the knob says (see Layer 4). (A
+**key collision** — two field names that collapse to one after Layer 1 — used
+to be on that list. It no longer
 fails the hook at all: only the colliding fields are withheld, and every sibling
 field survives. Both colliding values are replaced **whole** by a marker string,
 not walked leaf-wise: a shape-preserving walk rewrites only string leaves, so a

package/bin/sanitize-cli.mjs

@@ -51,26 +51,13 @@ import { realpathSync } from "node:fs";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 
+import { readKnob } from "../claude-hooks/lib/knobs.mjs";
 import { sanitize } from "../src/index.mjs";
 
 /** Largest single request accepted, in UTF-8 bytes. Caps memory per request so
- * a hostile or runaway caller can't OOM the process; override via the env var. */
-const DEFAULT_MAX_INPUT_BYTES = 10 * 1024 * 1024;
-
-/** Resolve the configured input cap, falling back to the default for an unset,
- * empty, non-numeric, or non-positive value. */
-function maxInputBytes() {
-  const raw = process.env.AGENT_SANITIZER_MAX_INPUT_BYTES;
-  const parsed = Number(raw);
-  if (
-    raw === undefined ||
-    raw === "" ||
-    !Number.isFinite(parsed) ||
-    parsed <= 0
-  )
-    return DEFAULT_MAX_INPUT_BYTES;
-  return Math.floor(parsed);
-}
+ * a hostile or runaway caller can't OOM the process; override via the env var.
+ * An unrecognized value is reported on stderr and the default applies. */
+const maxInputBytes = () => readKnob("AGENT_SANITIZER_MAX_INPUT_BYTES");
 
 /** The one-line reason reported for a caught throw. A thrown non-Error that
  * still carries a `message` keeps reporting it (the historical behaviour);

package/claude-hooks/lib/authored-content.mjs

@@ -50,6 +50,7 @@
  * AGENT_SANITIZER_OUTPUT_DISABLED=1 disables both.
  */
 import { lazyImport } from "./hook-io.mjs";
+import { readKnob } from "./knobs.mjs";
 
 // Bound via lazyImport (see its doc for the fail-OPEN hazard of a bare static
 // npm import — here the load crash would fire inside pretooluse-sanitize.mjs's
@@ -207,7 +208,7 @@ function sanitizeField(value) {
     // view sanitize-output uses. Compare before/after rather than pre-testing
     // for ESC: escapes this layer deliberately leaves in place — a lone control
     // byte, display-only colour — must not be reported as a strip.
-    if (process.env.AGENT_SANITIZER_TERMINAL_DISABLED !== "1") {
+    if (!readKnob("AGENT_SANITIZER_TERMINAL_DISABLED")) {
       const deAnsi = stripTerminalControls(cleaned);
       if (deAnsi !== cleaned) {
         cleaned = deAnsi;
@@ -216,7 +217,7 @@ function sanitizeField(value) {
     }
 
     if (
-      process.env.AGENT_SANITIZER_INVISIBLE_DISABLED !== "1" &&
+      !readKnob("AGENT_SANITIZER_INVISIBLE_DISABLED") &&
       isPayloadCapable(cleaned)
     ) {
       cleaned = stripInvisible(cleaned);

package/claude-hooks/lib/env-config.mjs

@@ -25,6 +25,7 @@ import credentialNames from "../../python/agent_sanitizer/secrets/data/credentia
 import redactionFloor from "../../python/agent_sanitizer/secrets/data/redaction-floor.json" with { type: "json" };
 import inferenceKeys from "../config/inference-key-vars.json" with { type: "json" };
 import scrubbed from "../config/scrubbed-env-vars.json" with { type: "json" };
+import { readKnob } from "./knobs.mjs";
 
 /**
  * The inference-provider key env vars. Their values authenticate the agent to a
@@ -205,7 +206,7 @@ const EXTRA_TOKEN_RE = /^[A-Z0-9_]+$/;
  * @returns {string[]}
  */
 export function extraSecretVars(env = process.env) {
-  const raw = env[EXTRA_SECRET_VARS_ENV];
+  const raw = readKnob(EXTRA_SECRET_VARS_ENV, env);
   if (raw === undefined || raw.trim() === "") return [];
   const tokens = raw.split(",").map((token) => token.trim());
   for (const token of tokens)
@@ -227,15 +228,16 @@ export function extraSecretVars(env = process.env) {
 export const SECRETS_ENABLED_ENV = "AGENT_SANITIZER_SECRETS_ENABLED";
 
 /**
- * True when the operator opted into the secret-redaction layer. `=== "1"`
- * matches the other public knobs (`AGENT_SANITIZER_*_DISABLED`): any other
- * value — unset, "true", "yes" — keeps the layer off, so a typo can only fail
- * toward the default (no secret machinery), never silently enable it.
+ * True when the operator opted into the secret-redaction layer. Only `1`
+ * enables it, matching the other public switches (`AGENT_SANITIZER_*_DISABLED`)
+ * and the SessionStart provisioning gate in provision-redactor.sh, so the hooks
+ * never redact through an engine that was not provisioned. Any other value
+ * keeps the layer off — reported, so `true` is not silently a no-op.
  * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
  * @returns {boolean}
  */
 export function secretsEnabled(env = process.env) {
-  return env[SECRETS_ENABLED_ENV] === "1";
+  return readKnob(SECRETS_ENABLED_ENV, env);
 }
 
 // Layer 3's digest exemption, which lets a URL carry an exact-digest-length hex
@@ -246,14 +248,14 @@ export function secretsEnabled(env = process.env) {
 export const FLAG_DIGEST_VALUES_ENV = "AGENT_SANITIZER_FLAG_DIGEST_VALUES";
 
 /**
- * True when the operator opted into flagging digest-shaped URL values. `=== "1"`
- * for the reason {@link secretsEnabled} gives: a typo fails toward the default,
- * which is the exemption the precision rule prefers.
+ * True when the operator opted into flagging digest-shaped URL values. Only
+ * `1`, for the reason {@link secretsEnabled} gives: a typo fails toward the
+ * default (reported), which is the exemption the precision rule prefers.
  * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
  * @returns {boolean}
  */
 export function digestFlaggingEnabled(env = process.env) {
-  return env[FLAG_DIGEST_VALUES_ENV] === "1";
+  return readKnob(FLAG_DIGEST_VALUES_ENV, env);
 }
 
 /**

package/claude-hooks/lib/hook-fault.mjs

@@ -83,22 +83,43 @@ export const FAULT_POLICY_HOOKS = Object.freeze([
 
 /**
  * The context a builder is handed: the caller's own inputs (whatever it passed
- * to {@link hookFaultOutcome}) plus the three values every hook derived by hand
+ * to {@link hookFaultOutcome}) plus the values every hook derived by hand
  * before — the hook name, the scrubbed error message, and the model-facing
- * open-posture warning.
+ * open-posture warning — and `pinnedClosed`, true when the policy's
+ * `alwaysClosed` overrode an open knob, so the closed arm can say why.
  * @typedef {Record<string, any> & {
  *   hook: string,
  *   err: unknown,
  *   message: string,
  *   openContext: string,
+ *   pinnedClosed: boolean,
  * }} FaultContext
  */
 
 /**
- * A hook's declared posture.
+ * Whether a hook's faults are withheld whatever AGENT_SANITIZER_FAIL_OPEN says,
+ * for the caller's environment.
+ * @typedef {(
+ *   env: NodeJS.ProcessEnv | Record<string, string | undefined> | undefined,
+ * ) => boolean} AlwaysClosed
+ */
+
+/**
+ * The `alwaysClosed` of a hook whose posture the knob alone decides.
+ * @type {AlwaysClosed}
+ */
+export const KNOB_DECIDES = Object.freeze(() => false);
+
+/**
+ * A hook's declared posture. `alwaysClosed` is REQUIRED, so every hook states
+ * on the record whether the knob can open it: {@link KNOB_DECIDES}, or a
+ * predicate that pins the CLOSED arm — how a guarantee the docs make
+ * unconditionally (Layer 4 withholds what it could not vet) is enforced in the
+ * one posture resolver rather than by a hook re-reading the knob.
  * @typedef {{
  *   event: string | null,
  *   guarded: string,
+ *   alwaysClosed: AlwaysClosed,
  *   open?: (ctx: FaultContext) => FaultParts,
  *   closed: (ctx: FaultContext) => FaultParts,
  * }} FaultPolicy
@@ -120,6 +141,14 @@ export function registerFaultPolicy(hook, policy) {
       `unknown hook ${JSON.stringify(hook)}: add it to FAULT_POLICY_HOOKS in ` +
         "claude-hooks/lib/hook-fault.mjs before registering a posture for it",
     );
+  // Checked here, not at fault time: a posture that is incomplete must fail the
+  // import, never the one fault it was supposed to answer.
+  for (const arm of /** @type {const} */ (["alwaysClosed", "closed"]))
+    if (typeof policy[arm] !== "function")
+      throw new Error(
+        `fault policy for ${JSON.stringify(hook)} declares no \`${arm}\`; ` +
+          "every hook states it explicitly (KNOB_DECIDES for alwaysClosed)",
+      );
   policies.set(hook, policy);
 }
 
@@ -161,7 +190,8 @@ export function defaultOpen(ctx) {
 /**
  * Resolve `hook`'s response to its own failure under the caller's posture. This
  * is the ONLY place {@link failOpenEnabled} is consulted on a hook fault, so the
- * knob cannot be honored in three hooks and skipped in the fourth.
+ * knob cannot be honored in three hooks and skipped in the fourth — and the
+ * only place a policy's `alwaysClosed` can override it.
  * @param {string} hook
  * @param {unknown} err
  * @param {Record<string, any> & {
@@ -174,7 +204,9 @@ export function defaultOpen(ctx) {
  */
 export function hookFaultOutcome(hook, err, ctx = {}) {
   const policy = faultPolicy(hook);
-  const open = failOpenEnabled(ctx.env);
+  const knobOpen = failOpenEnabled(ctx.env);
+  const pinnedClosed = knobOpen && policy.alwaysClosed(ctx.env);
+  const open = knobOpen && !pinnedClosed;
   /** @type {FaultContext} */
   const full = {
     ...ctx,
@@ -182,6 +214,7 @@ export function hookFaultOutcome(hook, err, ctx = {}) {
     err,
     message: safeErrMessage(err),
     openContext: failOpenContext(hook, policy.guarded, err),
+    pinnedClosed,
   };
   const parts = (open ? (policy.open ?? defaultOpen) : policy.closed)(full);
   const fields = parts.fields ?? null;

package/claude-hooks/lib/hook-io.mjs

@@ -9,10 +9,10 @@ import {
   writeFileSync,
 } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { userInfo } from "node:os";
 import { createHash } from "node:crypto";
 import { pathToFileURL } from "node:url";
 import { excludeProvisioning } from "./hook-timing.mjs";
+import { readKnob } from "./knobs.mjs";
 
 /**
  * EVERY process-wide slot these helpers keep — the four a host can observe or
@@ -212,20 +212,11 @@ export const PermissionDecision = Object.freeze({
 export const FAIL_OPEN_ENV = "AGENT_SANITIZER_FAIL_OPEN";
 
 /**
- * Values that turn the default posture back to fail-closed. Matched exactly:
- * a case-insensitive match would need `tr`, which the launcher cannot reach
- * (it runs its no-node arm on shell builtins alone).
- *
- * THE SINGLE SOURCE OF TRUTH for the closed set. The shell shims cannot import
- * it, so `plugin/scripts/lib/fail-open.sh` is GENERATED from it by
- * `scripts/gen-fail-open-lib.mjs` and committed; the round trip is asserted in
- * plugin/test/fail-open-parity.test.mjs. Everything else that spells the set
- * out by hand is an implementation that must appear in the parity table in
- * tests/test_safe_launch.py.
+ * Values that turn the default posture back to fail-closed. Defined beside the
+ * knob's grammar in lib/knobs.mjs and published here, where hosts and
+ * `scripts/gen-fail-open-lib.mjs` read it.
  */
-export const FAIL_CLOSED_VALUES = Object.freeze(["0", "false"]);
-
-const FAIL_CLOSED_SET = new Set(FAIL_CLOSED_VALUES);
+export { FAIL_CLOSED_VALUES } from "./knobs.mjs";
 
 /**
  * Whether hook failures pass the guarded action through. True unless the caller
@@ -236,12 +227,13 @@ const FAIL_CLOSED_SET = new Set(FAIL_CLOSED_VALUES);
  * mistake is reversed: those default to the safe side, so an unrecognized value
  * there costs nothing, while here it leaves an operator who asked for
  * strictness without it. `"false"` is the one spelling reached for by reflex,
- * so it is honored; everything else (`""`, `"no"`, `"off"`) is the open posture.
+ * so it is honored; everything else (`""`, `"no"`, `"off"`) is the open posture,
+ * and a value that is neither a closed nor an open spelling is reported.
  * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
  * @returns {boolean}
  */
 export function failOpenEnabled(env = process.env) {
-  return !FAIL_CLOSED_SET.has(env[FAIL_OPEN_ENV] ?? "");
+  return readKnob(FAIL_OPEN_ENV, env);
 }
 
 /**
@@ -275,7 +267,7 @@ export function disabledHooks(
   env = process.env,
   report = (message) => process.stderr.write(`${message}\n`),
 ) {
-  const named = (env[DISABLED_HOOKS_ENV] ?? "")
+  const named = (readKnob(DISABLED_HOOKS_ENV, env) ?? "")
     .split(",")
     .map((name) => name.trim())
     .filter((name) => name !== "");
@@ -787,24 +779,70 @@ export function hookgateMarkerPath(
 export const SETUP_LOCK_DECLARATION = "flock";
 
 /**
- * Whether an exclusive lock is currently held on `markerPath`, or null when the
- * question cannot be answered here (no `flock(1)` — it is util-linux, absent from a
- * stock macOS — or an exit status neither "acquired" nor "busy").
- * @param {string} markerPath
+ * Whether an exclusive lock is currently held on the file open at `fd`, or null
+ * when the question cannot be answered here (no `flock(1)` — it is util-linux,
+ * absent from a stock macOS — or an exit status neither "acquired" nor "busy").
+ *
+ * The probe locks the DESCRIPTOR the caller already opened, never the path.
+ * `flock <path>` opens with O_CREAT, so a probe that lost the race against the
+ * writer's final unlink re-created the marker — empty, owned by us, declaring
+ * nothing — and every later reader took that husk for a live setup whose pid it
+ * could not parse: a 900-second wait on each cold hook and a gap notice silenced
+ * for the session. Locking the inherited fd cannot create anything, and it judges
+ * the same inode the caller just read. The child's lock lives on the shared open
+ * file description, so it is released when the caller closes `fd`.
+ * @param {number} fd
  * @returns {boolean | null}
  */
-function markerLockHeld(markerPath) {
-  const probe = spawnSync(
-    "flock",
-    ["--nonblock", "--exclusive", markerPath, "true"],
-    { stdio: "ignore" },
-  );
+function lockHeldOn(fd) {
+  const probe = spawnSync("flock", ["--nonblock", "--exclusive", "3"], {
+    stdio: ["ignore", "ignore", "ignore", fd],
+  });
   if (probe.error) return null;
   if (probe.status === 0) return false; // acquired: nobody holds it
   if (probe.status === 1) return true; // busy: the writer still holds it
   return null;
 }
 
+/**
+ * A setup marker's trimmed lines and, when it declares
+ * {@link SETUP_LOCK_DECLARATION}, whether that lock is held (null: the
+ * declaration is absent, or no `flock(1)` could answer). Null when the marker
+ * cannot be opened or read — a missing marker included, which is how a probe
+ * that runs after the writer's unlink learns the install is over WITHOUT
+ * re-creating the file (see {@link lockHeldOn}).
+ *
+ * One descriptor serves both the read and the lock probe, so the two halves
+ * describe one inode: reading the path and then locking it by name can judge a
+ * marker the writer replaced in between.
+ * @param {string} markerPath
+ * @returns {{ lines: string[], lockHeld: boolean | null } | null}
+ */
+function readSetupMarker(markerPath) {
+  let fd;
+  try {
+    fd = openSync(markerPath, "r");
+  } catch {
+    return null;
+  }
+  try {
+    let raw;
+    try {
+      raw = readFileSync(fd, "utf8");
+    } catch {
+      // EISDIR and kin: opened but unreadable, the same answer as unopenable.
+      return null;
+    }
+    const lines = raw.split("\n").map((line) => line.trim());
+    return {
+      lines,
+      lockHeld: lines.includes(SETUP_LOCK_DECLARATION) ? lockHeldOn(fd) : null,
+    };
+  } finally {
+    closeSync(fd);
+  }
+}
+
 /**
  * Is a setup process DEMONSTRABLY running right now?
  *
@@ -827,18 +865,10 @@ function markerLockHeld(markerPath) {
  */
 export function setupRunning(markerPath) {
   if (!markerIsTrusted(markerPath)) return false;
-  let raw;
-  try {
-    raw = readFileSync(/** @type {string} */ (markerPath), "utf8");
-  } catch {
-    return false;
-  }
-  const lines = raw.split("\n").map((line) => line.trim());
-  if (lines.includes(SETUP_LOCK_DECLARATION)) {
-    const held = markerLockHeld(/** @type {string} */ (markerPath));
-    if (held !== null) return held;
-  }
-  const pid = parseInt(lines[0], 10);
+  const marker = readSetupMarker(/** @type {string} */ (markerPath));
+  if (marker === null) return false;
+  if (marker.lockHeld !== null) return marker.lockHeld;
+  const pid = parseInt(marker.lines[0], 10);
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
     process.kill(pid, 0);
@@ -871,20 +901,12 @@ export function setupRunning(markerPath) {
  */
 export function probeSetupAlive(markerPath) {
   if (markerPath === null) return true;
-  let raw;
-  try {
-    raw = readFileSync(markerPath, "utf8");
-  } catch {
-    return true;
-  }
-  const lines = raw.split("\n").map((line) => line.trim());
-  if (lines.includes(SETUP_LOCK_DECLARATION)) {
-    const held = markerLockHeld(markerPath);
-    // null only: a host without flock(1) still gets the pid reading below rather
-    // than an answer this probe cannot support.
-    if (held !== null) return held;
-  }
-  const pid = parseInt(lines[0], 10);
+  const marker = readSetupMarker(markerPath);
+  if (marker === null) return true;
+  // null only: a host without flock(1) still gets the pid reading below rather
+  // than an answer this probe cannot support.
+  if (marker.lockHeld !== null) return marker.lockHeld;
+  const pid = parseInt(marker.lines[0], 10);
   if (!Number.isInteger(pid) || pid <= 0) return true;
   try {
     process.kill(pid, 0);
@@ -1022,7 +1044,64 @@ export function markerIsTrusted(path) {
   } catch {
     return false;
   }
-  return st.isFile() && st.uid === userInfo().uid;
+  return st.isFile() && ownedByCurrentUser(st);
+}
+
+/**
+ * This process's real uid, or null on a platform with no POSIX uid model.
+ *
+ * `process.getuid()` and never `os.userInfo().uid`: userInfo() resolves the
+ * uid through the passwd database and THROWS (ENOENT) when the uid has no entry
+ * — the ordinary state of a container started with `--user 54321` — so every
+ * ownership check built on it crashed the hook that asked, and a crashed hook
+ * is non-blocking. The uid is a kernel fact; the passwd name is not needed.
+ *
+ * Null is explicit rather than the -1 userInfo() reports on Windows: callers
+ * test ownership through {@link ownedByCurrentUser}, which reads null as "cannot
+ * prove ownership" — the untrusted side every caller already handles.
+ * @returns {number | null}
+ */
+export function currentUid() {
+  return typeof process.getuid === "function" ? process.getuid() : null;
+}
+
+/**
+ * Whether `st` (an lstat result) is owned by this process's uid. THE ownership
+ * predicate for every $TMPDIR store these hooks trust — a second spelling is how
+ * four call sites came to share the passwd-lookup crash {@link currentUid}
+ * documents. False when the platform has no uid model: ownership that cannot be
+ * proven is not granted. `uid` is a seam for a test that must model another
+ * uid's file; production takes the default.
+ * @param {{ uid: number }} st
+ * @param {number | null} [uid]
+ * @returns {boolean}
+ */
+export function ownedByCurrentUser(st, uid = currentUid()) {
+  return uid !== null && st.uid === uid;
+}
+
+/**
+ * Whether `st` (an lstat result) is a directory no untrusted uid can change: a
+ * real directory (lstat, so a planted symlink is not one), owned by this uid —
+ * or by root where `rootMayOwn` — with no group/other write bit. THE trust test
+ * for every private directory these hooks keep in $TMPDIR. Write is the
+ * property because creating, unlinking or replacing an entry needs write on its
+ * parent: a co-tenant holding it can delete the finding a gate needs, swap a
+ * reveal file, or rebind the redactor socket to a listener that redacts nothing.
+ * Root ownership is strictly stronger than ours, so a deployment may hand a dir
+ * to root (`rootMayOwn`); with no uid model nothing is trusted, root included.
+ * @param {{ isDirectory(): boolean, uid: number, mode: number }} st
+ * @param {{ uid?: number | null, rootMayOwn?: boolean }} [opts]  `uid` as in
+ *   {@link ownedByCurrentUser}
+ * @returns {boolean}
+ */
+export function isPrivateDir(
+  st,
+  { uid = currentUid(), rootMayOwn = false } = {},
+) {
+  const owner =
+    ownedByCurrentUser(st, uid) || (uid !== null && rootMayOwn && st.uid === 0);
+  return st.isDirectory() && owner && (st.mode & 0o022) === 0;
 }
 
 /**

package/claude-hooks/lib/invisible-alert.mjs

@@ -21,11 +21,12 @@ import {
 } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { basename, join } from "node:path";
-import { homedir, tmpdir, userInfo } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import {
   hookgateMarkerPath,
   lazyImport,
   markerIsTrusted,
+  isPrivateDir,
   probeSetupAlive,
   PROJECT_DIR,
   PROJECT_HASH,
@@ -205,11 +206,12 @@ function withinTtl(path, ttlMs) {
 const withinFallbackTtl = (path) => withinTtl(path, FALLBACK_TTL_MS);
 
 /**
- * Whether `path` is a real directory this uid owns — the directory counterpart
- * of markerIsTrusted. `lstat`, so a symlink planted at the predictable alert-dir
- * path is judged on ITSELF: followed, it would let a co-tenant aim the gate's
- * reader at a directory of unrelated files this uid owns and splice their bytes
- * into a permission prompt.
+ * Whether `path` is a private directory of this uid ({@link isPrivateDir}) —
+ * the directory counterpart of markerIsTrusted. `lstat`, so a symlink planted
+ * at the predictable alert-dir path is judged on ITSELF: followed, it would let
+ * a co-tenant aim the gate's reader at a directory of unrelated files this uid
+ * owns and splice their bytes into a permission prompt. A group/other-writable
+ * one is refused too: a co-tenant could unlink the finding the gate needs.
  * @param {string} path
  * @returns {boolean}
  */
@@ -220,7 +222,7 @@ function dirIsTrusted(path) {
   } catch {
     return false;
   }
-  return st.isDirectory() && st.uid === userInfo().uid;
+  return isPrivateDir(st);
 }
 
 /**