@inhuman.tools/policy 0.0.0-stage → 0.2.0

package/src/reasonable-defaults.ts

@@ -0,0 +1,8 @@
+/** Dist floor. Sole home is `reasonable-defaults.json`. The string is the session file body. */
+
+import defaults from "./reasonable-defaults.json" with { type: "json" };
+
+export const reasonableDefaults = defaults;
+
+/** Text of {@link reasonableDefaults} for `policyProgram`. `bindPolicy` takes the object. */
+export const reasonableDefaultsSource: string = JSON.stringify(reasonableDefaults);

package/src/run-authorization.ts

@@ -0,0 +1,23 @@
+import { execState, toJS, type EnvCapability } from "@here.build/arrival";
+
+import { authorizationSource } from "./authorize.js";
+
+export async 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> {
+  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;
+}

package/src/tool-path.ts

@@ -0,0 +1,43 @@
+/**
+ * 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";
+import type { Disposition } from "./types.js";
+
+function slash(text: string): string {
+  return text.replaceAll("\\", "/");
+}
+
+export function normalizeToolPath(raw: string, cwd: string = process.cwd(), home: string = homedir()): string {
+  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: "read" | "write",
+  raw: string,
+  options?: { readonly cwd?: string; readonly home?: string },
+): Disposition {
+  const prepared = normalizeToolPath(raw, options?.cwd, options?.home);
+  const check = operation === "read" ? defaultPolicy.read : defaultPolicy.write;
+  return lattice([check(prepared), check(prepared.toLowerCase())]);
+}

package/src/types.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 function classesOf(verdict: FloorVerdict): readonly ClassId[] {
+  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];
+}

package/src/verdict.ts

@@ -0,0 +1,63 @@
+/**
+ * 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, UnitIdentity } from "./types.js";
+
+const RANK: Readonly<Record<Disposition, number>> = { policyApprove: 0, ask: 1, deny: 2, block: 3 };
+
+export const APPROVE: FloorVerdict = { disposition: "policyApprove", votes: [] };
+
+export function rank(disposition: Disposition): number {
+  return RANK[disposition];
+}
+
+/** A single vote. An approve carries no vote: it names no class. */
+export function cast(
+  disposition: Disposition,
+  cls: ClassId,
+  ruleId: string,
+  extra?: Pick<FloorVote, "unit" | "lift" | "path">,
+): FloorVerdict {
+  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: readonly FloorVerdict[]): FloorVerdict {
+  const joined = joinVotes(verdicts);
+  const seen = mergeSeen(verdicts);
+  return seen === undefined ? joined : { ...joined, seen };
+}
+
+function mergeSeen(verdicts: readonly FloorVerdict[]): readonly UnitIdentity[] | undefined {
+  const out = new Map<string, UnitIdentity>();
+  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: readonly FloorVerdict[]): FloorVerdict {
+  let top: Disposition = "policyApprove";
+  for (const verdict of verdicts) if (rank(verdict.disposition) > rank(top)) top = verdict.disposition;
+  if (top === "policyApprove") return APPROVE;
+  const seen = new Set<string>();
+  const votes: FloorVote[] = [];
+  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: FloorVerdict, unit: FloorVote["unit"]): FloorVerdict {
+  if (unit === undefined || verdict.votes.length === 0) return verdict;
+  return { disposition: verdict.disposition, votes: verdict.votes.map((vote) => ({ unit, ...vote })) };
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.