@inhuman.tools/policy 0.0.0-stage → 0.2.0

package/dist/run-authorization.d.ts

@@ -0,0 +1,8 @@
+import { type EnvCapability } from "@here.build/arrival";
+export declare function authorize(document: string, options: {
+    readonly capability: EnvCapability;
+    readonly config?: Readonly<Record<string, unknown>>;
+    readonly program?: string;
+    readonly env?: NodeJS.ProcessEnv;
+}): Promise<"allow" | "deny" | null>;
+//# sourceMappingURL=run-authorization.d.ts.map

package/dist/run-authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-authorization.d.ts","sourceRoot":"","sources":["../src/run-authorization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAI1E,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IACP,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC,GACA,OAAO,CAAC,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC,CAUlC"}

package/dist/run-authorization.js

@@ -0,0 +1,16 @@
+import { execState, toJS } from "@here.build/arrival";
+import { authorizationSource } from "./authorize.js";
+export async function authorize(document, options) {
+    const state = await execState(authorizationSource(options.program, options.env), {
+        capabilities: [options.capability],
+        config: { ...options.config, document },
+    });
+    const value = state.values.at(0);
+    if (value === undefined)
+        return null;
+    const decided = toJS(value);
+    if (decided === "allow" || decided === "deny")
+        return decided;
+    return null;
+}
+//# sourceMappingURL=run-authorization.js.map

package/dist/run-authorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-authorization.js","sourceRoot":"","sources":["../src/run-authorization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAsB,MAAM,qBAAqB,CAAC;AAE1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,OAKC;IAED,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,mBAAmB,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE;QAC/E,YAAY,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC;QAClC,MAAM,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE;KACxC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,OAAO,CAAC;IAC9D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/tool-path.d.ts

@@ -0,0 +1,8 @@
+import type { Disposition } from "./types.js";
+export declare function normalizeToolPath(raw: string, cwd?: string, home?: string): string;
+/** Strictest dist-floor answer for a model-supplied path, after host normalisation. */
+export declare function checkToolPath(operation: "read" | "write", raw: string, options?: {
+    readonly cwd?: string;
+    readonly home?: string;
+}): Disposition;
+//# sourceMappingURL=tool-path.d.ts.map

package/dist/tool-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-path.d.ts","sourceRoot":"","sources":["../src/tool-path.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM9C,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAU5G;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,GAAG,OAAO,EAC3B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D,WAAW,CAIb"}

package/dist/tool-path.js

@@ -0,0 +1,38 @@
+/**
+ * Host path preparation for the file floor, for hosts that hand the model's path
+ * string straight to the adapter. Mirrors the harness's `workspacePath`: resolve
+ * against the working directory, collapse `.` / `..`, make in-root paths relative,
+ * leave extra-root paths absolute (so a miss is `deny`, never `..` ask).
+ * Lexical only: no realpath, so a symlink inside the tree is not followed.
+ * The floor matches case-sensitively, so `checkToolPath` also asks about the
+ * lower-cased path and keeps the stricter answer (`.GIT/hooks` is `.git/hooks`
+ * on APFS and NTFS).
+ */
+import { homedir } from "node:os";
+import path from "node:path";
+import { defaultPolicy } from "./bind.js";
+import { lattice } from "./lift.js";
+function slash(text) {
+    return text.replaceAll("\\", "/");
+}
+export function normalizeToolPath(raw, cwd = process.cwd(), home = homedir()) {
+    let written = slash(raw.trim() === "" ? "." : raw.trim());
+    if (written === "~" || written.startsWith("~/"))
+        written = `${slash(home)}${written.slice(1)}`;
+    const root = path.posix.normalize(slash(cwd.startsWith("/") || /^[a-z]:/i.test(cwd) ? cwd : `/${cwd}`));
+    const resolved = path.posix.normalize(written.startsWith("/") ? written : path.posix.join(root, written));
+    const trimmed = resolved.length > 1 && resolved.endsWith("/") ? resolved.slice(0, -1) : resolved;
+    const rel = path.posix.relative(root, trimmed);
+    if (rel === "")
+        return ".";
+    if (rel === ".." || rel.startsWith("../") || rel.startsWith("/"))
+        return trimmed;
+    return rel;
+}
+/** Strictest dist-floor answer for a model-supplied path, after host normalisation. */
+export function checkToolPath(operation, raw, options) {
+    const prepared = normalizeToolPath(raw, options?.cwd, options?.home);
+    const check = operation === "read" ? defaultPolicy.read : defaultPolicy.write;
+    return lattice([check(prepared), check(prepared.toLowerCase())]);
+}
+//# sourceMappingURL=tool-path.js.map

package/dist/tool-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-path.js","sourceRoot":"","sources":["../src/tool-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,SAAS,KAAK,CAAC,IAAY;IACzB,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE,EAAE,OAAe,OAAO,EAAE;IAClG,IAAI,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1D,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/F,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC;IACxG,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1G,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IACjG,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC/C,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,GAAG,CAAC;IAC3B,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IACjF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,aAAa,CAC3B,SAA2B,EAC3B,GAAW,EACX,OAA2D;IAE3D,MAAM,QAAQ,GAAG,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACrE,MAAM,KAAK,GAAG,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC;IAC9E,OAAO,OAAO,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Floor carriers. `policyApprove` is the positive vote. Stored `approve` and `allow` parse as it.
+ * `block` is unliftable. `deny` is overridable by descending arms.
+ * File effects (`read_path` / `write_path`) join on their own lattice, apart from bash
+ * shape — they cannot lift `ask`.
+ */
+import type { ClassId } from "./classes.js";
+export type Disposition = "policyApprove" | "ask" | "deny" | "block";
+/** Write-deny remainder intern. Null when the floor is not deny. */
+export type WriteRemainderKind = "protected" | "outside" | "risky";
+export type ArgType = "read_path" | "write_path";
+/** Why an approve became ask without a rule saying so. A lifted vote is never grantable. */
+export type LiftKind = "env" | "xargs" | "nonliteral" | "unparsed" | "overflow" | "readings";
+/** Grant family of one shell unit: program, recognized subcommand spine, `family_args` positionals. */
+export type UnitIdentity = {
+    readonly argv0: string;
+    readonly spine: readonly string[];
+    readonly familyArgs: readonly string[];
+};
+/** One rule's vote, with the class that says why it voted. Only votes at the call's tier are reported. */
+export type FloorVote = {
+    readonly disposition: Disposition;
+    readonly class: ClassId;
+    /** Stable rule identity: `bash:git/push[--force]`, `write_block:.git/hooks`, `lift:env`. */
+    readonly ruleId: string;
+    /** Shell votes only: the unit that voted. Absent for path and host votes. */
+    readonly unit?: UnitIdentity;
+    readonly lift?: LiftKind;
+    /** Path votes only: the prepared path and the cluster it was judged in. */
+    readonly path?: {
+        readonly cluster: "read" | "write";
+        readonly path: string;
+    };
+};
+/** The tier and the votes that decided it. `votes` is empty for `policyApprove`. */
+export type FloorVerdict = {
+    readonly disposition: Disposition;
+    readonly votes: readonly FloorVote[];
+    /**
+     * Every shell unit the call runs, at any tier (an approve names none in `votes`). Only a shell verdict
+     * has it. An acknowledgement flag on a command family needs it to see an approved call.
+     */
+    readonly seen?: readonly UnitIdentity[];
+};
+export type Policy = {
+    /** `cwd`: workspace-relative directory the shell runs in; relative path words re-base on it. */
+    readonly bash: (command: string, cwd?: string) => Disposition;
+    readonly explainBash: (command: string, cwd?: string) => FloorVerdict;
+    readonly read: (path: string) => Disposition;
+    readonly explainRead: (path: string) => FloorVerdict;
+    readonly write: (path: string) => Disposition;
+    readonly explainWrite: (path: string) => FloorVerdict;
+    /** Write-deny remainder intern. Null when the floor is not deny. */
+    readonly writeKind: (path: string) => WriteRemainderKind | null;
+};
+export type FlagConstraint = {
+    readonly names: readonly string[];
+    readonly vals: readonly string[];
+    readonly takesValue: boolean;
+};
+export type Matcher = {
+    readonly class?: ClassId;
+    readonly flags: Readonly<Record<string, FlagConstraint>>;
+    readonly globs: readonly string[];
+    readonly toks: readonly string[];
+    readonly matchers: readonly Matcher[];
+    readonly policy?: Disposition;
+};
+export type CommandNode = {
+    readonly policy?: Disposition;
+    /** Why this node votes what it votes. Inherited from the nearest ancestor that names one. */
+    readonly class?: ClassId;
+    /** Leading positionals (after the spine) that belong to the grant family. Does not affect the tier. */
+    readonly familyArgs: number;
+    readonly argTypes: readonly ArgType[];
+    readonly argRestType?: ArgType;
+    readonly matchers: readonly Matcher[];
+    /** Option whose value is a path (`--output=F`, glued `-oF`). Long names carry their prefixes. */
+    readonly flagPaths: Readonly<Record<string, ArgType>>;
+    /** Named argument guards (see guards.ts) for what flags and positionals cannot express. */
+    readonly guards: readonly string[];
+    readonly dash?: CommandNode;
+    readonly subcommands: Readonly<Record<string, CommandNode>>;
+};
+/** Classes of the votes that decided the tier. A tier with no voting rule is `unmodelled`. */
+export declare function classesOf(verdict: FloorVerdict): readonly ClassId[];
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * Floor carriers. `policyApprove` is the positive vote. Stored `approve` and `allow` parse as it.
+ * `block` is unliftable. `deny` is overridable by descending arms.
+ * File effects (`read_path` / `write_path`) join on their own lattice, apart from bash
+ * shape — they cannot lift `ask`.
+ */
+/** Classes of the votes that decided the tier. A tier with no voting rule is `unmodelled`. */
+export function classesOf(verdict) {
+    if (verdict.disposition === "policyApprove")
+        return [];
+    const classes = new Set(verdict.votes.filter((vote) => vote.disposition === verdict.disposition).map((vote) => vote.class));
+    return classes.size === 0 ? ["unmodelled"] : [...classes];
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyFH,8FAA8F;AAC9F,MAAM,UAAU,SAAS,CAAC,OAAqB;IAC7C,IAAI,OAAO,CAAC,WAAW,KAAK,eAAe;QAAE,OAAO,EAAE,CAAC;IACvD,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CACnG,CAAC;IACF,OAAO,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC;AAC5D,CAAC"}

package/dist/verdict.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Votes on the strict lattice. `join` is `lattice` that keeps the rules which decided the tier:
+ * the result is the strictest disposition and the union of the votes at exactly that disposition.
+ */
+import type { ClassId } from "./classes.js";
+import type { Disposition, FloorVerdict, FloorVote } from "./types.js";
+export declare const APPROVE: FloorVerdict;
+export declare function rank(disposition: Disposition): number;
+/** A single vote. An approve carries no vote: it names no class. */
+export declare function cast(disposition: Disposition, cls: ClassId, ruleId: string, extra?: Pick<FloorVote, "unit" | "lift" | "path">): FloorVerdict;
+/** Strictest of the verdicts, with the votes at that tier (deduplicated by rule, class and unit). */
+export declare function join(verdicts: readonly FloorVerdict[]): FloorVerdict;
+/** Same verdict with every vote stamped with a unit (shell units only). */
+export declare function withUnit(verdict: FloorVerdict, unit: FloorVote["unit"]): FloorVerdict;
+//# sourceMappingURL=verdict.d.ts.map

package/dist/verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.d.ts","sourceRoot":"","sources":["../src/verdict.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAgB,MAAM,YAAY,CAAC;AAIrF,eAAO,MAAM,OAAO,EAAE,YAA0D,CAAC;AAEjF,wBAAgB,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAErD;AAED,oEAAoE;AACpE,wBAAgB,IAAI,CAClB,WAAW,EAAE,WAAW,EACxB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,GAChD,YAAY,CAGd;AAED,qGAAqG;AACrG,wBAAgB,IAAI,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,CAIpE;AA2BD,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,YAAY,CAGrF"}

package/dist/verdict.js

@@ -0,0 +1,55 @@
+const RANK = { policyApprove: 0, ask: 1, deny: 2, block: 3 };
+export const APPROVE = { disposition: "policyApprove", votes: [] };
+export function rank(disposition) {
+    return RANK[disposition];
+}
+/** A single vote. An approve carries no vote: it names no class. */
+export function cast(disposition, cls, ruleId, extra) {
+    if (disposition === "policyApprove")
+        return APPROVE;
+    return { disposition, votes: [{ disposition, class: cls, ruleId, ...extra }] };
+}
+/** Strictest of the verdicts, with the votes at that tier (deduplicated by rule, class and unit). */
+export function join(verdicts) {
+    const joined = joinVotes(verdicts);
+    const seen = mergeSeen(verdicts);
+    return seen === undefined ? joined : { ...joined, seen };
+}
+function mergeSeen(verdicts) {
+    const out = new Map();
+    for (const verdict of verdicts)
+        for (const unit of verdict.seen ?? [])
+            out.set(JSON.stringify(unit), unit);
+    return out.size === 0 ? undefined : [...out.values()];
+}
+function joinVotes(verdicts) {
+    let top = "policyApprove";
+    for (const verdict of verdicts)
+        if (rank(verdict.disposition) > rank(top))
+            top = verdict.disposition;
+    if (top === "policyApprove")
+        return APPROVE;
+    const seen = new Set();
+    const votes = [];
+    for (const verdict of verdicts) {
+        if (verdict.disposition !== top)
+            continue;
+        for (const vote of verdict.votes) {
+            if (vote.disposition !== top)
+                continue;
+            const key = JSON.stringify([vote.ruleId, vote.class, vote.unit, vote.lift, vote.path]);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            votes.push(vote);
+        }
+    }
+    return { disposition: top, votes };
+}
+/** Same verdict with every vote stamped with a unit (shell units only). */
+export function withUnit(verdict, unit) {
+    if (unit === undefined || verdict.votes.length === 0)
+        return verdict;
+    return { disposition: verdict.disposition, votes: verdict.votes.map((vote) => ({ unit, ...vote })) };
+}
+//# sourceMappingURL=verdict.js.map

package/dist/verdict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.js","sourceRoot":"","sources":["../src/verdict.ts"],"names":[],"mappings":"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"}

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.2.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.2.0",
+    "@inhuman.tools/policy-bash-disassembler": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "eslint": "9.39.2",
+    "typescript": "6.0.2",
+    "vitest": "4.1.0",
+    "@inhuman.tools/env-capability-decision-structured": "^0.0.1",
+    "@-internal-/eslint-configs": "0.0.0"
+  },
+  "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;
+}