@mortz.prk/opencode-auto-mode 1.0.2 → 1.1.2

package/src/tiers.ts

@@ -1,12 +1,267 @@
 import * as path from "node:path";
 import { lstatSync, realpathSync } from "node:fs";
-import { classifyShell } from "./shell.js";
+import { homedir } from "node:os";
+import { isDataOption } from "./shell-policy.js";
+import { getWorktreeScope } from "./worktree.js";
 
-export type Tier = "auto-allow" | "auto-deny" | "review" | "unknown";
-export interface Classification { tier: Tier; reason: string }
-export interface ClassifyOptions { projectDir?: string; allowInProjectEdits?: boolean }
+/** Compatibility helper; invalid locations cannot establish a verified file scope. */
+export function projectRoot(location: string): string {
+  try { return getWorktreeScope(location).worktreeRoot; }
+  catch { return path.resolve(location); }
+}
+
+/**
+ * File extensions that name source or documentation rather than a credential
+ * store. A module such as `src/tokens.ts` is ordinary source, and treating a
+ * keyword plus one of these extensions as a secret name turns every source
+ * search or file read into a hard deny.
+ */
+const SOURCE_EXTENSION = String.raw`(?:[cm]?[jt]sx?|py|pyi|rb|go|rs|java|kt|kts|cs|php|swift|scala|sh|bash|zsh|fish|lua|pl|pm|vue|svelte|astro|html?|css|scss|sass|less|sql|mdx?)`;
+
+/**
+ * Filename-shaped sensitive names.
+ *
+ * These spellings are unambiguous file references, so they apply to a bare shell
+ * word as well as to a path: a dotfile, a key file, or a name that carries a
+ * credential keyword and an extension. A credential keyword followed by a source
+ * extension is excluded so `tokens.ts` stays a module name.
+ */
+const SENSITIVE_NAME = new RegExp([
+  // Repository, tool, editor, CI and agent configuration directories.
+  String.raw`(?:^|[/\\])\.(?:git|opencode|ssh|aws|gnupg|kube|docker|config|github|vscode|husky|devcontainer|idea|gitlab-ci\.yml|git-credentials|password-store|netrc|npmrc|pypirc|env[^/\\]*)(?:[/\\]|$)`,
+  // Credential stores and key material that are not hidden directories.
+  String.raw`(?:^|[/\\])(?:credentials?\.[^/\\]+|opencode\.json[^/\\]*|auth\.(?:json|ya?ml))(?:[/\\]|$)`,
+  String.raw`(?:^|[/\\])id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?(?:[/\\]|$)`,
+  String.raw`(?:^|[/\\])[^/\\]+\.(?:pem|key|p12|pfx|jks|keystore)(?:[/\\]|$)`,
+  // Files whose own name declares a credential, token, secret or password
+  // payload. The keyword must start the component or follow a separator, so a
+  // source file such as `tokenizer.ts` is not swept in, and a source extension
+  // disqualifies the name.
+  String.raw`(?:^|[/\\])(?![^/\\]*\.` + SOURCE_EXTENSION + String.raw`(?:[/\\]|$))(?:[^/\\]*[._-])?(?:credential|token|secret|password|passwd|private[_ -]?key)s?(?![a-z])[^/\\]*\.[^/\\]+(?:[/\\]|$)`,
+  // Infrastructure state and cloud service-account key files.
+  String.raw`(?:^|[/\\])(?:[^/\\]*[._-])?terraform\.tfstate[^/\\]*(?:[/\\]|$)`,
+  String.raw`(?:^|[/\\])(?:[^/\\]*[._-])?service[-_ ]?accounts?\.json(?:[/\\]|$)`,
+].join("|"), "i");
+
+/**
+ * Bare credential keywords. A word that is only a keyword is as likely to be a
+ * search pattern, a package name or a commit message as a file, so shell callers
+ * only apply these to a word that can name a path or to a redirect target.
+ */
+const SENSITIVE_KEYWORD = new RegExp([
+  String.raw`(?:^|[/\\])(?:credentials?|kubeconfig|auth)(?:[/\\]|$)`,
+  String.raw`(?:^|[/\\])(?:tokens?|secrets?|passwords?|passwd|private[ _-]?keys?|[^/\\]*[._-](?:credential|token|secret|password|passwd|private[_ -]?key)s?)(?:[/\\]|$)`,
+].join("|"), "i");
+
+/**
+ * Explicit sensitive names, checked both on the spelling supplied by the caller
+ * and on each component of the resolved path. This is the narrow set that also
+ * applies after resolution, so a project checked out below an unrelated dotted
+ * ancestor (for example `~/.local/share/project`) stays usable.
+ */
+export const SENSITIVE_PATH = new RegExp([SENSITIVE_NAME.source, SENSITIVE_KEYWORD.source].join("|"), "i");
+
+/**
+ * Broad lexical protection: any dot-prefixed path component supplied by the
+ * caller is sensitive, including dotfiles and dot-directories this module does
+ * not name explicitly. `.` and `..` are traversal, not names, and are left to
+ * the containment checks.
+ */
+const DOT_COMPONENT = /(?:^|[/\\])\.(?!\.?(?:[/\\]|$))[^/\\]+(?:[/\\]|$)/;
+
+/** Filesystem errors that mean a component cannot exist, so nothing is hidden there. */
+const ABSENT_COMPONENT = ["ENOENT", "ENOTDIR", "ENAMETOOLONG"];
+
+/** Lexical and canonical spellings of the project root a target is compared to. */
+function projectRootSpellings(projectDir?: string): string[] {
+  const directory = path.resolve(projectDir ?? process.cwd());
+  const roots = [directory];
+  try {
+    const real = realpathSync(directory);
+    if (!roots.includes(real)) roots.push(real);
+  } catch { /* Unverifiable root keeps the lexical spelling only. */ }
+  return roots;
+}
+
+function protectionSpelling(candidate: string, includeGit?: boolean): string {
+  // Metadata needs model review, not a credential deny. Do not normalize here:
+  // sensitive descendants and resolved symlink destinations must still count.
+  return includeGit === false ? candidate.replace(/(^|[/\\])\.git(?=[/\\]|$)/gi, "$1") : candidate;
+}
 
-const SENSITIVE_PATH = /(?:^|[/\\])(?:\.[^/\\]+|opencode\.jsonc?|id_(?:rsa|dsa|ecdsa|ed25519)|[^/\\]+\.(?:pem|key|p12|pfx)|[^/\\]*(?:credentials|token|secret|password|private.key)[^/\\]*)(?:[/\\]|$)/i;
+/**
+ * Sensitive spelling of one candidate.
+ *
+ * DOT_COMPONENT is applied to the path relative to the project root for an
+ * absolute target inside it, so an unrelated dotted ancestor such as
+ * `~/.local/share/project` does not mark every file below it. SENSITIVE_PATH is
+ * still applied to the whole candidate and, in `isProtected`, to every resolved
+ * component: a real `.ssh` or `.config` directory stays protected.
+ */
+function sensitiveSpelling(candidate: string, roots: readonly string[], includeGit?: boolean): boolean {
+  if (SENSITIVE_PATH.test(protectionSpelling(candidate, includeGit))) return true;
+  if (path.isAbsolute(candidate)) {
+    for (const root of roots) {
+      if (isInProject(candidate, root)) return DOT_COMPONENT.test(protectionSpelling(path.relative(root, path.resolve(candidate)), includeGit));
+    }
+  }
+  return DOT_COMPONENT.test(protectionSpelling(candidate, includeGit));
+}
+
+/** Inspect components before normalization can erase an alias followed by `..`.
+ * Absolute paths also start at their filesystem root, not at the location base.
+ */
+export function hasSymlinkTraversal(target: string, locationDir = process.cwd()): boolean {
+  let current: string;
+  try { current = path.isAbsolute(target) ? path.parse(target).root : realpathSync(locationDir); }
+  catch { current = path.resolve(locationDir); }
+  for (const part of target.split(path.sep).filter(Boolean)) {
+    if (part === ".") continue;
+    if (part === "..") { current = path.dirname(current); continue; }
+    current = path.join(current, part);
+    try {
+      if (lstatSync(current).isSymbolicLink()) return true;
+    } catch (error) {
+      // ENAMETOOLONG means the name cannot exist at all, so it hides no alias.
+      if (!ABSENT_COMPONENT.includes((error as NodeJS.ErrnoException).code ?? "")) return true;
+    }
+  }
+  return false;
+}
+
+/** Check lexical and resolved components. Excluding Git only removes the metadata
+ * marker; credentials inside it and symlink/.. traversal remain protected. */
+export function isProtected(target: string, projectDir?: string, includeGit?: boolean): boolean {
+  const roots = projectRootSpellings(projectDir);
+  const candidates = [target, ...target.split("="), ...target.split(":")];
+  if (candidates.some((candidate) => sensitiveSpelling(candidate, roots, includeGit) ||
+      /^\/proc\/(?:self|thread-self|\d+)\/(?:environ|mem)(?:$|\/)/.test(candidate))) return true;
+  let current: string;
+  try { current = path.isAbsolute(target) ? path.parse(target).root : realpathSync(projectDir ?? process.cwd()); }
+  catch { return hasSymlinkTraversal(target, path.resolve(projectDir ?? process.cwd())); }
+  const protectedPath = (candidate: string) => SENSITIVE_PATH.test(protectionSpelling(candidate, includeGit)) ||
+    /^\/proc\/(?:self|thread-self|\d+)\/(?:environ|mem)(?:$|\/)/.test(candidate);
+  if (protectedPath(current)) return true;
+  for (const part of target.split(path.sep).filter(Boolean)) {
+    if (part === ".") continue;
+    current = part === ".." ? path.dirname(current) : path.join(current, part);
+    try { current = realpathSync(current); }
+    catch (error) {
+      // Missing new files are expected; broken aliases and other ambiguous
+      // filesystem errors cannot establish that a protected target is absent.
+      // ENAMETOOLONG is not ambiguous: no such name can exist.
+      try { if (lstatSync(current).isSymbolicLink()) return true; } catch { /* Missing component. */ }
+      if (!ABSENT_COMPONENT.includes((error as NodeJS.ErrnoException).code ?? "")) return true;
+    }
+    if (protectedPath(current)) return true;
+  }
+  return false;
+}
+
+/** A scheme-qualified URL names a remote resource, never a local path. */
+const SCHEME_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+/** `user@host:path` is a remote Git/SCP location rather than a local path. */
+const SCP_URL = /^[^/\\@:]+@[^/\\:]+:/;
+/** `file:` URLs are local reads; every other scheme is remote. */
+const FILE_URL = /^file:(?:\/\/)?([\s\S]*)$/i;
+
+/** Expands the leading home spellings this module can decode without a shell. */
+function expandHome(word: string): string {
+  if (word === "~") return homedir();
+  if (word.startsWith("~/")) return `${homedir()}${word.slice(1)}`;
+  return word.replace(/^\$(?:HOME(?![A-Za-z0-9_])|\{HOME\})/, homedir());
+}
+
+/**
+ * The local path a `file:` URL names, or undefined for any other spelling.
+ *
+ * A URL is not a shell word, so the shell never expands `~`, `$HOME` or
+ * `${HOME}` inside it; they are expanded lexically here. A URL authority that
+ * is a host (`localhost`, an address, a dotted name) is not part of the path,
+ * while a non-host first segment stays in it. Query and fragment are dropped.
+ */
+function fileUrlPath(word: string): string | undefined {
+  const match = FILE_URL.exec(word);
+  if (match === null) return undefined;
+  const rest = expandHome(match[1].split(/[?#]/, 1)[0]);
+  if (rest.startsWith("/")) return rest;
+  const slash = rest.indexOf("/");
+  const authority = slash === -1 ? rest : rest.slice(0, slash);
+  if (slash !== -1 && /^(?:localhost|\[[0-9a-fA-F:.]+\]|[^/]*\.[^/]*)$/.test(authority)) return rest.slice(slash);
+  return `/${rest}`;
+}
+
+/**
+ * The value an option-shaped path operand carries (`-fFILE`, `--file=FILE`).
+ * A plain word is returned unchanged, including a bare `-` or `--`.
+ */
+function operandValue(word: string): string {
+  if (word.length <= 1 || !word.startsWith("-")) return word;
+  const separator = word.indexOf("=");
+  if (separator !== -1) return word.slice(separator + 1);
+  return word.startsWith("--") ? word : word.slice(2);
+}
+
+/**
+ * Protected-path check for an operand a command consumes as a file.
+ *
+ * The command's own grammar has already established that the word names a file
+ * (`cat credentials`), so the bare sensitive names count here even though they
+ * are only data in a pattern position. A word with no separator cannot be more
+ * than one component, so only the explicit names apply: a leading dot is not a
+ * reason to deny `.name`, `.gitignore` or `.cache`. Paths with a separator keep
+ * the full check, including resolved components, symlinks and `file:` URLs.
+ */
+export function isProtectedPathOperand(target: string, projectDir?: string, includeGit?: boolean): boolean {
+  if (!target) return false;
+  const word = operandValue(target);
+  const local = fileUrlPath(word);
+  if (local !== undefined) return isProtected(local, projectDir, includeGit);
+  if (SCHEME_URL.test(word) || SCP_URL.test(word)) return false;
+  return /[/\\]/.test(word) ? isProtected(word, projectDir, includeGit) : SENSITIVE_PATH.test(protectionSpelling(word, includeGit));
+}
+
+/**
+ * Protected-path check for one parsed shell word that the command grammar did
+ * not place in a path or data slot.
+ *
+ * A shell word is often data — a search pattern (`grep -r auth`), a package name
+ * (`npm view auth`), a commit message, or a URL — so bare keywords only count
+ * when the word can name a path: it contains a separator or carries a value in
+ * an option. A separator-less word is matched against the explicit names only,
+ * so `jq .name`, `git add .gitignore` and `echo .foo` stay ordinary words while
+ * `.env`, `.npmrc` and `auth.json` stay protected. Filename-shaped names
+ * (`signing.pem`) stay protected everywhere, and redirect targets are checked
+ * with the full `isProtected` because a redirection always names a file.
+ */
+export function isProtectedShellWord(target: string, projectDir?: string, includeGit?: boolean): boolean {
+  if (!target) return false;
+  const separator = target.startsWith("-") ? target.indexOf("=") : -1;
+  // `--grep=config/auth`, `--format=src/.env` and `--exclude=.env` carry
+  // pattern/format data even when the value is spelled like a path.
+  if (separator !== -1 && isDataOption(target.slice(0, separator))) return false;
+  const local = fileUrlPath(target);
+  if (local !== undefined) return isProtected(local, projectDir, includeGit);
+  if (SCHEME_URL.test(target) || SCP_URL.test(target)) return false;
+  const candidates = [target, ...target.split("="), ...target.split(":")];
+  // A `file:` value is a local path even when it arrives through an option.
+  const files = candidates.map(fileUrlPath).filter((candidate): candidate is string => candidate !== undefined);
+  if (files.length) return files.some((file) => isProtected(file, projectDir, includeGit));
+  // Any other scheme or an SCP-style location is remote, never a local path.
+  if (candidates.some((candidate) => SCHEME_URL.test(candidate) || SCP_URL.test(candidate))) return false;
+  if (target.startsWith("-")) {
+    if (separator === -1) return false;
+    // `--config=credentials.json` and `--file=.env` name files.
+    return isProtectedPathOperand(target.slice(separator + 1), projectDir, includeGit);
+  }
+  // `git show HEAD:.env` names a file after the colon; schemes and SCP
+  // locations were already excluded above.
+  if (!target.includes("=") && target.split(":").slice(1).some((part) => isProtectedPathOperand(part, projectDir, includeGit)))
+    return true;
+  // A separator-less word is only a file reference when it carries a
+  // filename-shaped name; a bare keyword such as `auth` stays data here.
+  return /[/\\]/.test(target) ? isProtected(target, projectDir, includeGit) : SENSITIVE_NAME.test(protectionSpelling(target, includeGit));
+}
 
 export function isInProject(target: string, projectDir: string): boolean {
   const resolved = path.resolve(projectDir, target);
@@ -14,11 +269,39 @@ export function isInProject(target: string, projectDir: string): boolean {
   return resolved === root || resolved.startsWith(`${root}${path.sep}`);
 }
 
-function safeTarget(target: string, projectDir: string): boolean {
+/**
+ * Lexical containment for low-band read operands. Tildes, parameter expansion
+ * and NUL cannot be resolved to a project path here, so they are never low;
+ * callers keep the protected-path and symlink checks separate. Both the spelling
+ * supplied by the caller and the canonical path are accepted, because a scope
+ * discovered with `realpath` may differ from a caller's `/var` vs `/private/var`
+ * spelling on macOS.
+ */
+export function isScopedPath(target: string, locationDir: string, worktreeRoot: string): boolean {
+  if (!target || target.startsWith("~") || /[$`\0]/.test(target)) return false;
+  const directory = path.resolve(locationDir);
+  const root = path.resolve(worktreeRoot);
+  if (isInProject(directory, root) && isInProject(path.resolve(directory, target), root)) return true;
+  try {
+    const canonicalDirectory = realpathSync(directory);
+    const canonicalRoot = realpathSync(root);
+    if (!isInProject(canonicalDirectory, canonicalRoot)) return false;
+    const resolved = path.resolve(canonicalDirectory, target);
+    let canonical = resolved;
+    try { canonical = realpathSync(resolved); } catch { /* New files keep the resolved spelling. */ }
+    return isInProject(resolved, canonicalRoot) || isInProject(canonical, canonicalRoot);
+  } catch { return false; }
+}
+
+export function safeTarget(target: string, locationDir: string, worktreeRoot = projectRoot(locationDir)): boolean {
+  if (target.startsWith("~") || /[$`\0]/.test(target)) return false;
   try {
-    const root = realpathSync(projectDir);
-    const resolved = path.resolve(root, target);
-    if (!isInProject(resolved, root) || SENSITIVE_PATH.test(resolved)) return false;
+    const root = realpathSync(worktreeRoot);
+    const directory = realpathSync(locationDir);
+    if (!lstatSync(root).isDirectory() || !lstatSync(directory).isDirectory() || !isInProject(directory, root)) return false;
+    if (hasSymlinkTraversal(target, directory)) return false;
+    const resolved = path.resolve(directory, target);
+    if (!isInProject(resolved, root) || isProtected(target, directory)) return false;
     const parts = path.relative(root, resolved).split(path.sep);
     let current = root;
     for (const part of parts) {
@@ -33,13 +316,3 @@ function safeTarget(target: string, projectDir: string): boolean {
     return true;
   } catch { return false; }
 }
-
-export function classify(action: string, resources: readonly string[], options?: ClassifyOptions): Classification {
-  if (action === "shell") return classifyShell(resources);
-  if (action === "read" || ((action === "edit" || action === "write") && options?.allowInProjectEdits)) {
-    if (options?.projectDir && resources.length > 0 && resources.every((target) =>
-        target.length > 0 && safeTarget(target, options.projectDir!)))
-      return { tier: "auto-allow", reason: "non-sensitive in-project file operation" };
-  }
-  return { tier: "review", reason: `action '${action}' needs review` };
-}

package/src/tui.tsx

@@ -1,48 +1,58 @@
 /** @jsxImportSource @opentui/solid */
-import { createSignal, Show } from "solid-js";
+import { createEffect, createSignal, Show } from "solid-js";
 import { Plugin } from "@opencode/plugin/tui";
-import { readConfigError, readDecisions } from "./state.js";
-import { isReviewing } from "./tui-state.js";
+import { AutoMode, type AutoModeStatus } from "./rpc.js";
+import { createDecisionNotifier, createDecisionSubscription, createStatusLoader, pillDescription, pillLabel, pillTone, statusLocationKey, type StatusTarget } from "./gui-state.js";
 
-const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const POLL_MS = 1_000;
 
 export default Plugin.define({
   id: "opencode-auto-mode",
-  setup: async (ctx) => {
+  setup: (ctx) => {
     if (ctx.options.tui === false) return;
-    const [reviewing, setReviewing] = createSignal(false);
-    const [configError, setConfigError] = createSignal(false);
-    let announced = false;
-    const update = () => {
+    const [status, setStatus] = createSignal<AutoModeStatus | undefined>(undefined);
+    const refresh = createStatusLoader(
+      (target, signal) => ctx.client.rpc(AutoMode).status({ sessionID: target.sessionID }, {
+        location: target.location, signal,
+      }) as Promise<AutoModeStatus | undefined>,
+      setStatus,
+    );
+    const target = (): StatusTarget | undefined => {
       const route = ctx.ui.router.current();
-      setReviewing(isReviewing(readDecisions(), route.type === "session" ? route.sessionID : undefined));
-      const error = readConfigError(ctx.location?.directory);
-      setConfigError(error !== undefined);
-      if (error === undefined) announced = false;
-      else if (!announced) {
-        announced = true;
-        ctx.ui.toast.show({
-          variant: "error", title: "auto-mode", duration: 10_000,
-          message: "Invalid configuration; automatic approval is disabled.",
-        });
-      }
+      const location = ctx.location ?? ctx.data.location.default();
+      return route.type === "session" && location !== undefined
+        ? { key: statusLocationKey(route.sessionID, location), sessionID: route.sessionID, ownServer: true, location }
+        : undefined;
     };
-    update();
-    const poll = setInterval(update, 250);
+    const receive = createDecisionNotifier(target, (notice) => {
+      ctx.ui.toast.show({ title: "Auto-mode", message: notice.message,
+        variant: notice.kind === "deny" ? "error" : "warning", duration: 5_000 });
+    });
+    const subscription = createDecisionSubscription(receive);
+    const update = () => {
+      const client = ctx.client;
+      subscription.update(client, (handler, signal) => client.rpc(AutoMode).events.on("decision", handler, { signal }));
+      void refresh(target());
+    };
+    const poll = setInterval(update, POLL_MS);
     const dispose = ctx.ui.slot({
-      append: "app",
-      render: () => (
-        <box position="absolute" top={0} right={0} zIndex={10_000} flexDirection="row" gap={1}>
-          <Show when={configError()}>
-            <text fg={ctx.theme.text.feedback.error.base}>auto-mode: invalid config</text>
-          </Show>
-          <Show when={reviewing()}>
-            <spinner frames={SPINNER_FRAMES} interval={120} color={ctx.theme.text.feedback.warning.base} />
-            <text fg={ctx.theme.text.feedback.warning.base}>auto-mode reviewing</text>
+      append: "prompt.footer.status",
+      render: () => {
+        // Router changes refresh immediately, independently of the timer.
+        createEffect(update);
+        const color = () => {
+          const tone = pillTone(status());
+          if (tone === "danger") return ctx.theme.text.feedback.error.base;
+          if (tone === "warning") return ctx.theme.text.feedback.warning.base;
+          return ctx.theme.text.base;
+        };
+        return (
+          <Show when={pillLabel(status())}>
+            <text fg={color()}>auto-mode: {pillDescription(status()) ?? pillLabel(status())}</text>
           </Show>
-        </box>
-      ),
+        );
+      },
     });
-    return () => { clearInterval(poll); dispose(); };
+    return () => { clearInterval(poll); refresh.dispose(); subscription.dispose(); dispose(); };
   },
 });

package/src/user-files.ts

@@ -0,0 +1,75 @@
+import { readFileSync, realpathSync, lstatSync, openSync, fstatSync, closeSync, constants } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { isInProject, projectRoot } from "./tiers.js";
+
+/** Strip JSONC comments and trailing commas without changing quoted strings. */
+export function parseJSONC(input: string): unknown {
+  if (Buffer.byteLength(input) > 1_048_576) throw new Error("JSONC exceeds size limit");
+  let output = "";
+  let quoted = false;
+  for (let i = 0; i < input.length; i++) {
+    const c = input[i];
+    if (quoted) {
+      output += c;
+      if (c === "\\") output += input[++i] ?? "";
+      else if (c === '"') quoted = false;
+    } else if (c === '"') { quoted = true; output += c; }
+    else if (c === "/" && input[i + 1] === "/") {
+      while (i < input.length && input[i] !== "\n") i++;
+      output += "\n";
+    } else if (c === "/" && input[i + 1] === "*") {
+      const end = input.indexOf("*/", i + 2);
+      if (end === -1) throw new Error("Unclosed block comment");
+      output += " "; i = end + 1;
+    } else output += c;
+  }
+  let clean = "";
+  quoted = false;
+  for (let i = 0; i < output.length; i++) {
+    const c = output[i];
+    if (quoted) {
+      clean += c;
+      if (c === "\\") clean += output[++i] ?? "";
+      else if (c === '"') quoted = false;
+    } else {
+      if (c === '"') quoted = true;
+      if (c === "," && /^[\s]*[}\]]/.test(output.slice(i + 1))) continue;
+      clean += c;
+    }
+  }
+  return JSON.parse(clean.replace(/^\uFEFF/, "")) as unknown;
+}
+/** Read policy data without following symlinks or trusting writable parents. */
+export function readUserOwnedFile(filename: string, projectDir?: string, maxBytes = 1_048_576): string {
+  if (!isAbsolute(filename)) throw new Error("Policy file path must be absolute");
+  const lexical = resolve(filename);
+  const canonical = realpathSync(lexical);
+  const root = projectRoot(projectDir ?? process.cwd());
+  let canonicalRoot = root;
+  try { canonicalRoot = realpathSync(root); } catch { /* still enforce lexical root */ }
+  if (isInProject(lexical, root) || isInProject(canonical, canonicalRoot))
+    throw new Error("Policy files must be user-owned outside the repository");
+  const uid = process.getuid?.();
+  let current = lexical;
+  while (true) {
+    const stat = lstatSync(current);
+    if (stat.isSymbolicLink()) throw new Error("Policy paths must not contain symlinks");
+    if ((stat.mode & 0o022) !== 0 && !(stat.isDirectory() && (stat.mode & 0o1000) !== 0))
+      throw new Error("Policy paths must not be writable by other users");
+    if (uid !== undefined && stat.uid !== uid && stat.uid !== 0)
+      throw new Error("Policy paths must be user-owned or system-owned parents");
+    const parent = resolve(current, "..");
+    if (parent === current) break;
+    current = parent;
+  }
+  const descriptor = openSync(lexical, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const stat = fstatSync(descriptor);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > maxBytes ||
+        (uid !== undefined && stat.uid !== uid) || (stat.mode & 0o022) !== 0)
+      throw new Error("Policy file must be user-owned, single-linked and not writable by other users");
+    const input = readFileSync(descriptor, "utf8");
+    if (Buffer.byteLength(input) > maxBytes) throw new Error("Policy file exceeds size limit");
+    return input;
+  } finally { closeSync(descriptor); }
+}

package/src/worktree.ts

@@ -0,0 +1,30 @@
+import { realpathSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+export interface WorktreeScope {
+  /** Canonical location directory: the base for relative request resources. */
+  directory: string;
+  /** Nearest Git working tree, not the shared repository of a linked worktree. */
+  worktreeRoot: string;
+}
+
+/** Stateless discovery: a location move needs no permission mutation or cache invalidation.
+ * Relative native grants follow the location; persisted user grants remain untouched.
+ * Throws for a missing or non-directory location rather than inventing a scope.
+ */
+export function getWorktreeScope(location: string): WorktreeScope {
+  const directory = realpathSync(resolve(location));
+  if (!statSync(directory).isDirectory()) throw new Error("Worktree location must be a directory");
+  let current = directory;
+  while (true) {
+    try {
+      const marker = statSync(join(current, ".git"));
+      if (marker.isFile() || marker.isDirectory()) return { directory, worktreeRoot: realpathSync(current) };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    const parent = dirname(current);
+    if (parent === current) return { directory, worktreeRoot: directory };
+    current = parent;
+  }
+}