@inhuman.tools/policy 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@inhuman.tools/policy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "JSON floor and the authorization program. The caller supplies the decide capability.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./floor": {
+      "types": "./dist/floor.d.ts",
+      "import": "./dist/floor.js",
+      "default": "./dist/floor.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "authorize.scm",
+    "!**/__tests__"
+  ],
+  "dependencies": {
+    "@here.build/arrival": "^0.10.2",
+    "minimatch": "10.2.6",
+    "zod": "^4.4.3",
+    "@inhuman.tools/error-with-invariant": "^0.1.0",
+    "@inhuman.tools/policy-bash-disassembler": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "eslint": "9.39.2",
+    "typescript": "6.0.2",
+    "vitest": "4.1.0",
+    "@-internal-/eslint-configs": "0.0.0",
+    "@inhuman.tools/env-capability-decision-structured": "^0.0.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/here-build/inhuman-harness.git",
+    "directory": "packages-policy/policy"
+  },
+  "browserslist": [
+    "last 2 chrome versions",
+    "last 2 firefox versions",
+    "last 2 safari versions",
+    "ios_saf >= 16.4",
+    "node >= 22"
+  ],
+  "author": "Merkle Bonsai",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "tsc -p tsconfig.json --noEmit && vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }

package/src/acknowledge.ts

@@ -0,0 +1,206 @@
+/**
+ * `needsAcknowledgement` for the adapters. One place for the flag schema, the matcher and the texts;
+ * an adapter only asks "does this call need an acknowledgement" and translates the answer into its
+ * host's confirmation mechanism.
+ *
+ * A flag forces a request for a call that would otherwise run (floor approve, judge allow, any
+ * resolution to allow). It never turns a block or a denial into anything. Flags only tighten:
+ * the effective set is the union of the user and project layers, so a project file can add and
+ * can never remove a user flag. The dist ships none.
+ *
+ * Adapters have no `modes` of their own, so `modes` is accepted (the schema is the daemon's) and
+ * ignored: a flag applies in every adapter.
+ *
+ * `class` matches the classes of the floor votes (`classesOf`). An approve has no classes, so a
+ * class flag only matches a call whose floor tier is ask or deny. `command` matches a prefix of
+ * `[argv0, ...spine, ...familyArgs]` of any shell unit in `verdict.seen`, so approved calls match.
+ */
+import { z } from "zod";
+
+import { defaultPolicy } from "./bind.js";
+import { CLASS_IDS, type ClassId } from "./classes.js";
+import { lattice } from "./lift.js";
+import { normalizeToolPath } from "./tool-path.js";
+import { classesOf, type FloorVerdict } from "./types.js";
+import { join } from "./verdict.js";
+
+const classIdSchema = z.enum(CLASS_IDS);
+
+const matchSchema = z.union([
+  z.strictObject({ class: classIdSchema }),
+  z.strictObject({ mcp: z.string().min(1), account: z.string().min(1).optional(), tool: z.string().min(1).optional() }),
+  z.strictObject({ tool: z.string().min(1) }),
+  z.strictObject({ command: z.array(z.string().min(1)).min(1) }),
+]);
+
+const flagSchema = z.strictObject({
+  match: matchSchema,
+  why: z.string().max(200).optional(),
+  modes: z.array(z.enum(["manual", "auto", "yolo"])).optional(),
+});
+
+export type AckMatch =
+  | { readonly class: ClassId }
+  | { readonly mcp: string; readonly account?: string; readonly tool?: string }
+  | { readonly tool: string }
+  | { readonly command: readonly string[] };
+
+export type AckFlag = {
+  readonly match: AckMatch;
+  readonly why?: string;
+  readonly modes?: readonly ("manual" | "auto" | "yolo")[];
+};
+
+/** Throws a readable error for an invalid block; `undefined` is no flags. */
+export function parseAcknowledge(value: unknown): readonly AckFlag[] {
+  if (value === undefined) return [];
+  const parsed = z.array(flagSchema).safeParse(value);
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    throw new Error(
+      `invalid acknowledge config: ${issue === undefined ? "bad shape" : `${issue.path.join(".") || "(root)"}: ${issue.message}`}`,
+    );
+  }
+  return parsed.data as readonly AckFlag[];
+}
+
+/** A config file's text: a JSON array of flags, or an object with an `acknowledge` array. Empty text is none. */
+export function parseAcknowledgeText(text: string | undefined): readonly AckFlag[] {
+  if (text === undefined || text.trim() === "") return [];
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    throw new Error("invalid acknowledge config: not json");
+  }
+  if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+    return parseAcknowledge((raw as Record<string, unknown>).acknowledge);
+  }
+  return parseAcknowledge(raw);
+}
+
+/** Layer rule: the union. Project can add; nothing in it removes a user flag. */
+export function mergeAcknowledge(...layers: readonly (readonly AckFlag[] | undefined)[]): readonly AckFlag[] {
+  const out = new Map<string, AckFlag>();
+  for (const layer of layers) for (const flag of layer ?? []) out.set(JSON.stringify([flag.match, flag.why]), flag);
+  return [...out.values()];
+}
+
+/** `mcp__server__tool` is the common MCP tool-name shape; hosts that spell it differently pass `mcp` themselves. */
+export function mcpOf(toolName: string): { readonly server: string; readonly tool: string } | undefined {
+  const found = /^mcp__(.+?)__(.+)$/.exec(toolName);
+  return found?.[1] === undefined || found[2] === undefined ? undefined : { server: found[1], tool: found[2] };
+}
+
+export type AckSubject = {
+  readonly tool?: string;
+  readonly mcp?: { readonly server: string; readonly account?: string; readonly tool?: string };
+  readonly verdict?: FloorVerdict;
+};
+
+export type AckRequirement = {
+  readonly labels: readonly string[];
+  readonly why: readonly string[];
+};
+
+export function labelOf(match: AckMatch): string {
+  if ("class" in match) return `class ${match.class}`;
+  if ("command" in match) return `command ${match.command.join(" ")}`;
+  if ("mcp" in match) {
+    return `mcp ${[match.mcp, match.tool].filter((part) => part !== undefined).join("/")}`;
+  }
+  return `tool ${match.tool}`;
+}
+
+function matches(match: AckMatch, subject: AckSubject): boolean {
+  if ("class" in match) return subject.verdict !== undefined && classesOf(subject.verdict).includes(match.class);
+  if ("command" in match) {
+    const units = subject.verdict?.seen ?? [];
+    return units.some((unit) => {
+      const identity = [unit.argv0, ...unit.spine, ...unit.familyArgs];
+      return match.command.length <= identity.length && match.command.every((word, i) => identity[i] === word);
+    });
+  }
+  const mcp = subject.mcp ?? (subject.tool === undefined ? undefined : mcpOf(subject.tool));
+  if ("mcp" in match) {
+    return (
+      mcp !== undefined &&
+      mcp.server === match.mcp &&
+      (match.tool === undefined || mcp.tool === match.tool) &&
+      (match.account === undefined || ("account" in mcp && mcp.account === match.account))
+    );
+  }
+  return subject.tool === match.tool || (mcp !== undefined && mcp.tool === match.tool);
+}
+
+/** Null when no flag matches. */
+export function acknowledgeRequirement(flags: readonly AckFlag[], subject: AckSubject): AckRequirement | null {
+  const labels: string[] = [];
+  const why: string[] = [];
+  for (const flag of flags) {
+    if (!matches(flag.match, subject)) continue;
+    const label = labelOf(flag.match);
+    if (!labels.includes(label)) labels.push(label);
+    if (flag.why !== undefined && !why.includes(flag.why)) why.push(flag.why);
+  }
+  return labels.length === 0 ? null : { labels, why };
+}
+
+/** Strictest floor verdict for a call, with the host path preparation the adapters use. */
+export function floorVerdictOf(
+  call:
+    | { readonly kind: "bash"; readonly command: string; readonly cwd?: string }
+    | {
+        readonly kind: "read" | "write";
+        readonly path: string;
+        readonly cwd?: string;
+      },
+): FloorVerdict {
+  if (call.kind === "bash") return defaultPolicy.explainBash(call.command, undefined);
+  const prepared = normalizeToolPath(call.path, call.cwd);
+  const explain = call.kind === "read" ? defaultPolicy.explainRead : defaultPolicy.explainWrite;
+  const first = explain(prepared);
+  const second = explain(prepared.toLowerCase());
+  const top = lattice([first.disposition, second.disposition]);
+  return join([first, second].filter((verdict) => verdict.disposition === top));
+}
+
+export function blockReason(requirement: AckRequirement): string {
+  return `needs acknowledgement: ${requirement.labels.join(", ")}`;
+}
+
+export type AckRequest = { readonly summary: string; readonly detail: string; readonly why?: string };
+export type Acknowledger = (request: AckRequest) => Promise<boolean>;
+
+const DETAIL_LIMIT = 500;
+
+/** `text` is what the agent wrote (a command, a path, arguments). It is JSON-encoded and truncated. */
+export function acknowledgeRequest(requirement: AckRequirement, tool: string, text: string): AckRequest {
+  const encoded = JSON.stringify(text);
+  const detail = encoded.length > DETAIL_LIMIT ? `${encoded.slice(0, DETAIL_LIMIT)}...` : encoded;
+  const why = requirement.why.length === 0 ? undefined : requirement.why.join("; ");
+  return {
+    summary: `Acknowledge ${tool}: ${requirement.labels.join(", ")}`,
+    detail,
+    ...(why === undefined ? {} : { why }),
+  };
+}
+
+/**
+ * Ask the host. Undefined means acknowledged and the call may run; a string is the denial reason.
+ * No `acknowledger` is the degraded path: the reason is `needs acknowledgement: <label>`.
+ */
+export async function requestAcknowledgement(
+  requirement: AckRequirement,
+  tool: string,
+  text: string,
+  acknowledger: Acknowledger | undefined,
+): Promise<string | undefined> {
+  if (acknowledger === undefined) return blockReason(requirement);
+  try {
+    const accepted = await acknowledger(acknowledgeRequest(requirement, tool, text));
+    return accepted ? undefined : `acknowledgement declined: ${requirement.labels.join(", ")}`;
+  } catch {
+    return `acknowledgement failed: ${requirement.labels.join(", ")}`;
+  }
+}

package/src/authorize.ts

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ErrorWithInvariant } from "@inhuman.tools/error-with-invariant";
+
+export class DecideError extends ErrorWithInvariant {
+  override readonly name = "DecideError";
+}
+
+const programPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "../authorize.scm");
+
+let cached: string | undefined;
+
+export function authorizationProgram(): string {
+  if (cached !== undefined) return cached;
+  cached = readFileSync(programPath, "utf8");
+  return cached;
+}
+
+/** A set `POLICY_AUTHORIZE` that cannot be read is an error, not the dist script. */
+export function authorizationSource(override?: string, env?: NodeJS.ProcessEnv): string {
+  const inline = override?.trim();
+  if (inline) return inline;
+  const file = env?.POLICY_AUTHORIZE?.trim();
+  if (file === undefined || file === "") return authorizationProgram();
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (error) {
+    const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+    if (code === "ENOENT") throw new DecideError(`authorization program not found: ${file}`);
+    throw error;
+  }
+  const source = text.trim();
+  if (source === "") throw new DecideError("authorization program is empty");
+  return text;
+}

package/src/bind.ts

@@ -0,0 +1,58 @@
+import { explainBash } from "./check.js";
+import { compilePolicy, PolicyAssumeError } from "./compile.js";
+import type { Which } from "./identity.js";
+import { explainPath, writeRemainderKind } from "./path-policy.js";
+import { reasonableDefaults } from "./reasonable-defaults.js";
+import { classesOf, type FloorVerdict, type Policy } from "./types.js";
+import { cast } from "./verdict.js";
+
+const unresolved: Which = () => undefined;
+
+export function bindPolicy(document: unknown, which: Which = unresolved): Policy {
+  const compiled = compilePolicy(document);
+  const clusters = { read: compiled.read, write: compiled.write };
+  const bash = (command: string, cwd?: string): FloorVerdict =>
+    compiled.bash === undefined
+      ? cast("ask", "unmodelled", "bash:no-policy")
+      : explainBash(compiled.bash, command, clusters, which, cwd);
+  for (const smoke of compiled.assume) {
+    const verdict = bash(smoke.command);
+    const actual = verdict.disposition;
+    PolicyAssumeError.invariant(
+      actual === smoke.expect,
+      `assume: expected ${smoke.expect}, got ${actual}: ${smoke.command}`,
+      {
+        expected: smoke.expect,
+        actual,
+        command: smoke.command,
+      },
+    );
+    if (smoke.expectClass !== undefined) {
+      const classes = classesOf(verdict);
+      PolicyAssumeError.invariant(
+        classes.includes(smoke.expectClass),
+        `assume: expected class ${smoke.expectClass}, got ${classes.join(",") || "none"}: ${smoke.command}`,
+        { expected: smoke.expect, actual, command: smoke.command },
+      );
+    }
+  }
+  const path = (cluster: "read" | "write") => {
+    const term = cluster === "read" ? compiled.read : compiled.write;
+    return (raw: string): FloorVerdict =>
+      term === undefined ? cast("ask", "unmodelled", `${cluster}:no-policy`) : explainPath(term, raw);
+  };
+  const explainRead = path("read");
+  const explainWrite = path("write");
+  return {
+    bash: (command: string, cwd?: string) => bash(command, cwd).disposition,
+    explainBash: bash,
+    read: (raw: string) => explainRead(raw).disposition,
+    explainRead,
+    write: (raw: string) => explainWrite(raw).disposition,
+    explainWrite,
+    writeKind: (raw: string) => (compiled.write === undefined ? null : writeRemainderKind(compiled.write, raw)),
+  };
+}
+
+/** Dist floor. A path-form argv0 stays a path: this binding has no `which`. */
+export const defaultPolicy: Policy = bindPolicy(reasonableDefaults);