@memnox/interceptors 0.1.1

package/dist/shell-cli.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+import {
+  buildAuthorizer,
+  buildHold,
+  buildLeases,
+  log
+} from "./chunk-SB27OD2T.js";
+
+// src/shell-cli.ts
+import { spawn } from "child_process";
+
+// src/shell-seam.ts
+import {
+  DECISION_EFFECT,
+  digest,
+  isAllowed as holdAllowed,
+  leasePathFor,
+  leaseScopeFor,
+  proceeds,
+  resolveShellLine,
+  takesLease
+} from "@memnox/core";
+var SHELL_ACTION = "shell.execute";
+var SHELL_EXIT_OK = 0;
+var SHELL_EXIT_WITHHELD = 77;
+var SEVERITY = {
+  [DECISION_EFFECT.ALLOW]: 0,
+  [DECISION_EFFECT.ASK]: 1,
+  [DECISION_EFFECT.DENY]: 2
+};
+function worse(a, b) {
+  return (SEVERITY[b.effect] ?? 0) > (SEVERITY[a.effect] ?? 0) ? b : a;
+}
+var ShellSeam = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  async gate(command) {
+    if (command.length === 0) {
+      return { message: "no command to run", exitCode: SHELL_EXIT_WITHHELD };
+    }
+    const line = command.join(" ");
+    let verdict = await this.deps.authorizer.authorize(
+      this.requestFor(SHELL_ACTION, line)
+    );
+    for (const resolved of resolveShellLine(line, this.deps.env ?? {}).actions) {
+      if (resolved.action === SHELL_ACTION) continue;
+      const request = this.requestFor(resolved.action, resolved.target ?? line);
+      verdict = worse(verdict, await this.deps.authorizer.authorize(request));
+    }
+    if (verdict.effect === DECISION_EFFECT.ASK) {
+      const answered = await this.askAbout(line, verdict);
+      if (answered !== null) return answered;
+    } else if (verdict.effect !== DECISION_EFFECT.ALLOW) {
+      return { message: describe(verdict), exitCode: SHELL_EXIT_WITHHELD };
+    }
+    const held = await this.claim(line);
+    if (held !== null) return held;
+    return { run: command, exitCode: SHELL_EXIT_OK };
+  }
+  /**
+   * Puts an ASK to a person. Null when it was allowed and the line may proceed.
+   *
+   * Withheld rather than run when nobody answers: a walk-away must not become a yes,
+   * and a timeout is said differently from a refusal so the two read differently.
+   */
+  async askAbout(line, verdict) {
+    const hold = this.deps.hold;
+    if (hold === void 0) {
+      return {
+        message: `${describe(verdict)}
+Nobody could be asked, so it was withheld. Run the agent under "memnox run".`,
+        exitCode: SHELL_EXIT_WITHHELD
+      };
+    }
+    const result = await hold.hold({
+      sessionId: this.deps.sessionId ?? "ses_local",
+      agent: "an agent",
+      operation: SHELL_ACTION,
+      fingerprint: digest(line),
+      reason: verdict.reason,
+      command: line
+    });
+    if (holdAllowed(result)) return null;
+    return { message: describe(verdict), exitCode: SHELL_EXIT_WITHHELD };
+  }
+  /**
+   * Takes the paths this line writes, or answers with who is already on them. Reads
+   * never reach the register: `takesLease` decides that here, so there is no path
+   * through this seam that can make a reader wait.
+   */
+  async claim(line) {
+    const leases = this.deps.leases;
+    if (leases === void 0) return null;
+    for (const resolved of resolveShellLine(line, this.deps.env ?? {}).actions) {
+      if (!takesLease(String(resolved.class))) continue;
+      const path = leasePathFor(
+        resolved.target,
+        leases.repositoryRoot,
+        this.deps.workingDirectory ?? leases.repositoryRoot
+      );
+      if (path === null) continue;
+      const scope = leaseScopeFor(path, leases.isDirectory);
+      const verdict = await leases.gate.claim(
+        scope,
+        leases.holder,
+        `${resolved.action} ${resolved.target ?? ""}`.trim()
+      );
+      if (proceeds(verdict)) continue;
+      return {
+        message: verdict.message ?? `${scope} is held by another agent.`,
+        exitCode: SHELL_EXIT_WITHHELD
+      };
+    }
+    return null;
+  }
+  requestFor(action, target) {
+    return {
+      action,
+      target,
+      // LOCAL ONLY. The SDK strips this before anything reaches the runtime.
+      arguments: { command: target },
+      ...this.deps.sessionId === void 0 ? {} : { sessionId: this.deps.sessionId },
+      ...this.deps.workingDirectory === void 0 ? {} : { workingDirectory: this.deps.workingDirectory }
+    };
+  }
+};
+function describe(verdict) {
+  const parts = [verdict.reason];
+  if (verdict.alternative !== void 0) {
+    const target = verdict.alternative.resource === void 0 ? "" : ` ${verdict.alternative.resource}`;
+    parts.push(
+      `Instead: ${verdict.alternative.action}${target} \u2014 ${verdict.alternative.note}`
+    );
+  }
+  if (verdict.approvalId !== void 0) {
+    parts.push(`Ask a person: memnox approvals resolve ${verdict.approvalId} --by <you>`);
+  }
+  if (verdict.decisionId !== void 0)
+    parts.push(`Why: memnox why ${verdict.decisionId}`);
+  return parts.join(" ");
+}
+
+// src/shell-invocation.ts
+import { basename } from "path";
+var SHELL_MODE = {
+  /** `-c "<line>"`: the POSIX contract, and the only form an agent actually uses. */
+  COMMAND: "command",
+  /** `-- cmd args`: how a person or a test drives the wrapper directly. */
+  ARGV: "argv",
+  /** No command at all. Hand the terminal to the real shell rather than refuse it. */
+  INTERACTIVE: "interactive"
+};
+function commandFlag(argument) {
+  return /^-[a-z]*c$/.test(argument);
+}
+function shellInvocation(argv) {
+  const separator = argv.indexOf("--");
+  if (separator !== -1) {
+    return { mode: SHELL_MODE.ARGV, argv: [...argv.slice(separator + 1)], flags: [] };
+  }
+  const flags = [];
+  for (const [index, argument] of argv.entries()) {
+    if (commandFlag(argument)) {
+      const line = argv[index + 1];
+      if (line === void 0) break;
+      return { mode: SHELL_MODE.COMMAND, line, flags };
+    }
+    if (argument.startsWith("-")) {
+      flags.push(argument);
+      continue;
+    }
+    return { mode: SHELL_MODE.ARGV, argv: [...argv.slice(index)], flags };
+  }
+  return { mode: SHELL_MODE.INTERACTIVE, flags };
+}
+var REAL_SHELL_VAR = "MEMNOX_REAL_SHELL";
+var FALLBACK_SHELL = "/bin/sh";
+function realShell(env, self) {
+  const named = env[REAL_SHELL_VAR];
+  if (named !== void 0 && named !== "" && basename(named) !== basename(self)) {
+    return named;
+  }
+  const inherited = env["SHELL"];
+  if (inherited !== void 0 && inherited !== "" && basename(inherited) !== basename(self)) {
+    return inherited;
+  }
+  return FALLBACK_SHELL;
+}
+
+// src/shell-cli.ts
+var USAGE = `Usage: memnox-shell -c "<command line>"
+       memnox-shell -- <command...>
+
+Gates what was asked against policy, then runs it unchanged through the real shell.
+A refusal names an alternative where the rule gave one, and nothing is ever rewritten.`;
+var SHELL_NAME = "memnox-shell";
+function commandOf(invocation) {
+  if (invocation.mode === SHELL_MODE.COMMAND) return [invocation.line ?? ""];
+  return invocation.argv ?? [];
+}
+function run(executable, args) {
+  const child = spawn(executable, args, { stdio: "inherit" });
+  child.on("exit", (code, signal) => {
+    process.exitCode = code === null ? signal === null ? SHELL_EXIT_WITHHELD : 128 : code;
+  });
+  child.on("error", (err) => {
+    log(`could not run the command: ${String(err)}`);
+    process.exitCode = SHELL_EXIT_WITHHELD;
+  });
+}
+async function main() {
+  const invocation = shellInvocation(process.argv.slice(2));
+  const shell = realShell(process.env, SHELL_NAME);
+  if (invocation.mode === SHELL_MODE.INTERACTIVE) {
+    if (process.stdin.isTTY !== true) {
+      process.stderr.write(`${USAGE}
+`);
+      process.exitCode = SHELL_EXIT_WITHHELD;
+      return;
+    }
+    run(shell, invocation.flags);
+    return;
+  }
+  const command = commandOf(invocation);
+  if (command.length === 0 || command[0] === "") {
+    process.stderr.write(`${USAGE}
+`);
+    process.exitCode = SHELL_EXIT_WITHHELD;
+    return;
+  }
+  const leases = buildLeases();
+  const seam = new ShellSeam({
+    authorizer: await buildAuthorizer(),
+    workingDirectory: process.cwd(),
+    env: process.env,
+    hold: buildHold(),
+    ...leases === void 0 ? {} : { leases }
+  });
+  const outcome = await seam.gate(command);
+  if (outcome.message !== void 0) log(outcome.message);
+  if (outcome.run === void 0) {
+    process.exitCode = outcome.exitCode;
+    return;
+  }
+  if (invocation.mode === SHELL_MODE.COMMAND) {
+    run(shell, [...invocation.flags, "-c", invocation.line ?? ""]);
+    return;
+  }
+  const [executable, ...args] = outcome.run;
+  if (executable === void 0) return;
+  run(executable, args);
+}
+main().catch((err) => {
+  log(`shell seam failed, ruling on nothing: ${String(err)}`);
+  process.exitCode = SHELL_EXIT_WITHHELD;
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@memnox/interceptors",
+  "version": "0.1.1",
+  "description": "The local seams — a PreToolUse hook, a shell wrapper, a git credential helper, an egress proxy and a Docker socket gate — that route what an agent does through Memnox before it happens.",
+  "keywords": [
+    "hooks",
+    "claude-code",
+    "seam",
+    "ai-agents",
+    "security"
+  ],
+  "license": "Apache-2.0",
+  "author": "Memnox",
+  "homepage": "https://github.com/Memnox/memnox/tree/main/packages/interceptors#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Memnox/memnox.git",
+    "directory": "packages/interceptors"
+  },
+  "bugs": {
+    "url": "https://github.com/Memnox/memnox/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./interceptor-cli": "./dist/interceptor-cli.js",
+    "./shell-cli": "./dist/shell-cli.js",
+    "./git-credential-cli": "./dist/git-credential-cli.js",
+    "./egress-cli": "./dist/egress-cli.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@memnox/core": "0.1.1"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}