harnery 0.41.0 → 0.43.0

package/src/lib/guarded-remove.ts

@@ -0,0 +1,376 @@
+import { spawnSync } from "node:child_process";
+import { lstatSync, readdirSync, readlinkSync, realpathSync, rmSync, type Stats } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, parse, relative, resolve, sep } from "node:path";
+
+export interface RemoveOptions {
+  root: string;
+  recursive?: boolean;
+  yes?: boolean;
+  dryRun?: boolean;
+  /**
+   * Protected paths (Git metadata, credentials, Harnery state, SSH or GnuPG
+   * keys, a bare repository) the caller names for removal, one exact path
+   * each. A protected path that is not named is still refused.
+   */
+  allowProtected?: string[];
+  /** Directories whose own Git metadata and Harnery state may never be allowed (the live workspace). */
+  liveRoots?: string[];
+}
+
+export interface RemovalLink {
+  path: string;
+  /** What the link points to. It is removed as a link and never followed. */
+  target: string;
+}
+
+export interface RemovalReport {
+  schema: "harnery.removal/v1";
+  applied: boolean;
+  root: string;
+  targets: string[];
+  entries: number;
+  bytes: number;
+  /** Protected paths removed because the caller named them with allowProtected. */
+  protected: string[];
+  /** Symbolic links inside recursive targets, removed as links. */
+  links: RemovalLink[];
+}
+
+const protectedNames = new Set([".git", ".harnery", ".credentials", ".ssh", ".gnupg"]);
+const MAX_ENTRIES = 10_000;
+
+/** Permanent removal is deliberately limited to inspected, untracked local outputs. */
+export function guardedRemove(
+  paths: string[],
+  options: RemoveOptions,
+  checkClaims: (targets: string[]) => void = () => {},
+): RemovalReport {
+  const cwd = realpathSync(process.cwd());
+  const root = checkedPath(options.root, new Set(), true);
+  const allowed = allowedProtected(options.allowProtected ?? [], root, options.liveRoots ?? []);
+  const rootStat = lstatSync(root);
+  const rootFingerprint = fingerprint(rootStat);
+  if (!rootStat.isDirectory()) throw new Error("--root must be a directory");
+  if (root === parse(root).root || root === realpathSync(homedir()))
+    throw new Error("--root cannot be a filesystem root or home directory");
+  if (paths.length === 0 || paths.length > 100) throw new Error("Supply 1-100 explicit targets");
+  const targets = paths.map((path) => checkedPath(path, allowed));
+  const snapshots = new Map<string, string>();
+  const removedProtected = new Set<string>();
+  const links: RemovalLink[] = [];
+  const gitDirs = new Set<string>();
+  let bytes = 0;
+  const devices = new Set<number>();
+
+  for (const target of targets) {
+    const home = realpathSync(homedir());
+    if (target === home || strictlyInside(target, home))
+      throw new Error(`Cannot remove the home directory or its ancestor: ${target}`);
+    const systemRoots =
+      process.platform === "win32"
+        ? [
+            process.env.SystemRoot,
+            process.env.ProgramFiles,
+            process.env["ProgramFiles(x86)"],
+          ].filter((value): value is string => Boolean(value))
+        : [
+            "/etc",
+            "/usr",
+            "/boot",
+            "/dev",
+            "/proc",
+            "/sys",
+            "/bin",
+            "/sbin",
+            "/lib",
+            "/lib64",
+            "/run",
+          ];
+    if (
+      systemRoots.some(
+        (system) =>
+          target === resolve(system) ||
+          strictlyInside(resolve(system), target) ||
+          strictlyInside(target, resolve(system)),
+      )
+    )
+      throw new Error(`System files are protected: ${target}`);
+    if (!strictlyInside(root, target))
+      throw new Error(`Target must be strictly inside --root: ${target}`);
+    if (target === cwd || strictlyInside(target, cwd))
+      throw new Error(`Cannot remove the working directory or its ancestor: ${target}`);
+    if (
+      targets.some((other) => other !== target && strictlyInside(other, target)) ||
+      targets.filter((other) => other === target).length > 1
+    )
+      throw new Error("Targets must not duplicate or contain one another");
+    const stat = lstatSync(target);
+    if (stat.dev !== rootStat.dev) throw new Error(`Target crosses a mount boundary: ${target}`);
+    if (stat.isDirectory() && !options.recursive)
+      throw new Error(`Directory removal requires --recursive: ${target}`);
+    const device = stat.dev;
+    devices.add(device);
+    const pending = [target];
+    while (pending.length) {
+      const path = pending.pop()!;
+      const info = lstatSync(path);
+      if (basename(path) === ARTIFACT_RECORD && insideArtifactWorkspace(path, null))
+        throw new Error(`An artifact's record is managed by the artifact commands: ${path}`);
+      if (protectedNames.has(basename(path).toLowerCase())) {
+        if (!allowed.has(path)) throw new Error(protectedMessage(path));
+        removedProtected.add(path);
+      }
+      if (info.isSymbolicLink()) {
+        // A link inside the tree is removed as a link; its target is never
+        // read, followed, or counted. (The target itself and its ancestors
+        // were already refused if they were links, in checkedPath.)
+        if (path === target) throw new Error(`Path contains a symlink: ${path}`);
+        if (snapshots.size >= MAX_ENTRIES)
+          throw new Error(
+            `Removal exceeds the ${MAX_ENTRIES}-entry limit; use the owning cleanup command`,
+          );
+        snapshots.set(path, fingerprint(info));
+        links.push({ path, target: readlinkSync(path) });
+        continue;
+      }
+      if (info.dev !== device || (!info.isDirectory() && !info.isFile()))
+        throw new Error(`Mount boundary or special file cannot be removed: ${path}`);
+      if (snapshots.size >= MAX_ENTRIES)
+        throw new Error(
+          `Removal exceeds the ${MAX_ENTRIES}-entry limit; use the owning cleanup command`,
+        );
+      snapshots.set(path, fingerprint(info));
+      if (info.isFile()) bytes += info.size;
+      else {
+        const names = readdirSync(path);
+        if (
+          names.includes("HEAD") &&
+          names.includes("objects") &&
+          names.includes("config") &&
+          !insideAllowed(path, allowed)
+        )
+          throw new Error(
+            `Repository metadata cannot be removed: ${path}. To remove it on purpose, name it with --allow-protected ${path}`,
+          );
+        if (allowed.has(path)) removedProtected.add(path);
+        if (isRepositoryMetadata(path)) gitDirs.add(path);
+        for (const name of names) pending.push(resolve(path, name));
+      }
+    }
+    assertUntracked(target);
+  }
+  if (devices.size > 1) throw new Error("Targets must be on one filesystem");
+  for (const path of allowed)
+    if (!removedProtected.has(path))
+      throw new Error(`--allow-protected names a path no target removes: ${path}`);
+  for (const dir of gitDirs) assertNoUnpushedHistory(dir);
+  checkClaims(targets);
+  const report: RemovalReport = {
+    schema: "harnery.removal/v1",
+    applied: false,
+    root,
+    targets,
+    entries: snapshots.size,
+    bytes,
+    protected: [...removedProtected].sort(),
+    links,
+  };
+  if (!options.yes || options.dryRun) return report;
+
+  // Recheck the entire batch before its first mutation. Filesystem changes after
+  // these checks remain possible; this is a guard, not a transactional filesystem.
+  if (
+    checkedPath(options.root, new Set(), true) !== root ||
+    fingerprint(lstatSync(root)) !== rootFingerprint
+  )
+    throw new Error("Allowed root changed during inspection");
+  for (const target of targets) {
+    checkedPath(target, allowed);
+    assertUntracked(target);
+  }
+  for (const dir of gitDirs) assertNoUnpushedHistory(dir);
+  checkClaims(targets);
+  for (const [path, previous] of snapshots) {
+    if (fingerprint(lstatSync(path)) !== previous)
+      throw new Error(`Target changed during inspection: ${path}`);
+  }
+  for (const target of targets)
+    rmSync(target, { recursive: Boolean(options.recursive), force: false });
+  return { ...report, applied: true };
+}
+
+/** The metadata file the artifact commands keep in each artifact workspace. */
+const ARTIFACT_RECORD = ".harnery-artifact.json";
+
+/**
+ * True when `path` lies strictly inside one artifact workspace,
+ * <dir>/.harnery/artifacts/<id>/..., under the `.harnery` component `state`
+ * (any `.harnery` when null). Artifact workspaces hold local outputs, so their
+ * contents may be removed; the workspace itself, its record file, and the rest
+ * of Harnery state stay protected and follow the artifact commands. `orSelf`
+ * accepts the workspace directory itself (used for --root, which is never removed).
+ */
+function insideArtifactWorkspace(path: string, state: string | null, orSelf = false): boolean {
+  const parts = path.split(sep);
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i]!.toLowerCase() !== ".harnery") continue;
+    if (state !== null && parts.slice(0, i + 1).join(sep) !== state) continue;
+    // .harnery / artifacts / <id> / <something>
+    return (
+      parts[i + 1] === "artifacts" && Boolean(parts[i + 2]) && parts.length >= i + (orSelf ? 3 : 4)
+    );
+  }
+  return false;
+}
+
+function protectedMessage(path: string): string {
+  return `Protected state cannot be removed: ${path}. To remove it on purpose, name it with --allow-protected ${path}`;
+}
+
+function insideAllowed(path: string, allowed: ReadonlySet<string>): boolean {
+  for (const entry of allowed) if (path === entry || strictlyInside(entry, path)) return true;
+  return false;
+}
+
+/**
+ * Resolves the caller's --allow-protected paths. Each must be one exact
+ * protected path strictly inside the root, reached without symlinks, and
+ * never the Git metadata or Harnery state of a live workspace root.
+ */
+function allowedProtected(paths: string[], root: string, liveRoots: string[]): Set<string> {
+  const allowed = new Set<string>();
+  const live = liveRoots.map((dir) => resolve(dir));
+  for (const input of paths) {
+    if (!input?.trim() || /[\0\r\n*?[\]$]/.test(input))
+      throw new Error("Use a nonempty explicit --allow-protected path without wildcards");
+    const path = resolve(input);
+    let cursor = dirname(path);
+    while (true) {
+      if (lstatSync(cursor).isSymbolicLink())
+        throw new Error(`--allow-protected path contains a symlink: ${cursor}`);
+      const parent = dirname(cursor);
+      if (parent === cursor) break;
+      cursor = parent;
+    }
+    const info = lstatSync(path);
+    if (info.isSymbolicLink()) throw new Error(`--allow-protected path is a symlink: ${path}`);
+    if (!strictlyInside(root, path))
+      throw new Error(`--allow-protected path must be strictly inside --root: ${path}`);
+    const named = protectedNames.has(basename(path).toLowerCase());
+    if (!named && !(info.isDirectory() && isRepositoryMetadata(path)))
+      throw new Error(`--allow-protected must name a protected path itself: ${path}`);
+    for (const dir of live) {
+      const own = [".git", ".harnery"].map((name) => resolve(dir, name));
+      if (
+        path === dir ||
+        strictlyInside(path, dir) ||
+        own.some((state) => path === state || strictlyInside(state, path))
+      )
+        throw new Error(`The live workspace's own state cannot be allowed: ${path}`);
+    }
+    allowed.add(realpathSync(path));
+  }
+  return allowed;
+}
+
+function isRepositoryMetadata(dir: string): boolean {
+  const names = readdirSync(dir);
+  return names.includes("HEAD") && names.includes("objects") && names.includes("config");
+}
+
+/**
+ * Removing a repository's metadata loses any commit that exists nowhere
+ * else. An allowed Git directory must have no branch or tag commit missing
+ * from its remotes; anything that cannot be checked is refused.
+ */
+function assertNoUnpushedHistory(gitDir: string): void {
+  const result = spawnSync(
+    "git",
+    [
+      "--git-dir",
+      gitDir,
+      "rev-list",
+      "--max-count=1",
+      "--branches",
+      "--tags",
+      "--not",
+      "--remotes",
+    ],
+    {
+      encoding: "utf8",
+      timeout: 10_000,
+      env: { ...process.env, LC_ALL: "C", GIT_DIR: undefined, GIT_WORK_TREE: undefined },
+    },
+  );
+  if (result.error || result.status !== 0)
+    throw new Error(`Cannot confirm ${gitDir} holds no unpushed history`);
+  if (result.stdout.trim()) throw new Error(`Repository has commits not on any remote: ${gitDir}`);
+}
+
+function strictlyInside(parent: string, child: string): boolean {
+  const rel = relative(parent, child);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+function checkedPath(
+  input: string,
+  allowed: ReadonlySet<string> = new Set(),
+  isRoot = false,
+): string {
+  if (!input?.trim() || /[\0\r\n*?[\]$]/.test(input))
+    throw new Error("Use a nonempty explicit path without wildcards or unresolved variables");
+  const path = resolve(input);
+  let cursor = path;
+  while (true) {
+    if (
+      protectedNames.has(basename(cursor).toLowerCase()) &&
+      !allowed.has(cursor) &&
+      !insideArtifactWorkspace(path, cursor, isRoot)
+    )
+      throw new Error(
+        cursor === path ? protectedMessage(path) : `Protected state contains this path: ${cursor}`,
+      );
+    const info = lstatSync(cursor);
+    if (info.isSymbolicLink()) throw new Error(`Path contains a symlink: ${cursor}`);
+    const parent = dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return realpathSync(path);
+}
+
+function fingerprint(stat: Stats): string {
+  return [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+}
+
+function assertUntracked(target: string): void {
+  const git = (args: string[]) =>
+    spawnSync("git", ["-C", dirname(target), ...args], {
+      encoding: "utf8",
+      timeout: 10_000,
+      maxBuffer: 4 * 1024 * 1024,
+      env: {
+        ...process.env,
+        LC_ALL: "C",
+        GIT_LITERAL_PATHSPECS: "1",
+        GIT_DIR: undefined,
+        GIT_WORK_TREE: undefined,
+        GIT_INDEX_FILE: undefined,
+      },
+    });
+  const detected = git(["rev-parse", "--show-toplevel"]);
+  if (detected.error) throw new Error(`Cannot check Git ownership: ${detected.error.message}`);
+  if (detected.status !== 0) {
+    if (detected.status === 128 && detected.stderr.startsWith("fatal: not a git repository"))
+      return;
+    throw new Error(`Cannot check Git ownership: ${detected.stderr.trim()}`);
+  }
+  const repo = detected.stdout.trim();
+  const tracked = git(["ls-files", "--cached", "-z", "--full-name", "--", target]);
+  if (tracked.error || tracked.status !== 0) throw new Error(`Cannot inspect Git index in ${repo}`);
+  if (tracked.stdout.length)
+    throw new Error(
+      `Tracked files are protected; use git rm for intentional source removal: ${target}`,
+    );
+}

package/src/lib/instructions/templates.ts

@@ -89,8 +89,7 @@ export function renderInstructionsBlock(
   return `## harnery coordination
 
 This project runs [harnery](https://harnery.com) for multi-agent coordination.
-You share this checkout with other agents; the surfaces below keep you oriented
-and out of each other's way, and let you dispatch a team of your own when a job
+You share this checkout with other agents; the surfaces below keep you oriented and out of each other's way, and let you dispatch a team of your own when a job
 is bigger than one session. Run \`${b} <command> --help\` for any command's full
 surface. ${deeper}
 
@@ -103,8 +102,7 @@ widely-shared files.
 **Task lifecycle.** Beside the activity peers already see, declare whether your
 objective is still open: \`${b} agents lifecycle blocked --reason "<why>"\` when
 it cannot proceed, \`${b} agents lifecycle done\` when it is complete, and
-\`${b} agents lifecycle active\` to reopen. \`done\` requires a current task and
-a passing Git finalization check (dirty or unpushed work refuses, and nothing is
+\`${b} agents lifecycle active\` to reopen. \`done\` requires a current task and a passing Git finalization check (dirty or unpushed work refuses, and nothing is
 written). Ordinary \`set-task\` calls never change lifecycle, and a transition
 that re-mints the session title tells you the new name to copy. ${endPointer}
 
@@ -129,8 +127,7 @@ It reclaims an abandoned namesake (no live process) and refuses only when anothe
 live process still holds the name; never hand-edit Harnery's history, heartbeat,
 or derived identity cache.
 
-**Declare intent on shell commands.** Every command you run is captured to the
-coordination ledger (\`.harnery/ledgers/v3/\`). Lead a shell command with a
+**Declare intent on shell commands.** Every command you run is captured to the coordination ledger (\`.harnery/ledgers/v3/\`). Lead a shell command with a
 \`# intent: <why>\` comment (or set the tool's description) so the recorded event
 carries a reason instead of \`(no intent)\`; the [tool-intent
 guide](https://harnery.com/guides/tool-intent/) owns the details.
@@ -154,6 +151,10 @@ After review, use \`${b} artifacts discard <id> --reason "<why no longer needed>
 Do not create a repo-root temp directory; \`${b} artifacts clean\` previews
 expired cleanup and requires \`--yes\` to delete anything.
 
+**Removing local outputs.** Use \`${b} rm --root <directory> <paths...>\` instead of shell \`rm\`, which skips resolved-path, Git ownership, and peer-claim checks. Preview
+is the default; \`--yes\` deletes permanently and \`--recursive\` permits directories.
+Use \`git rm\` for tracked source and the artifact commands for managed evidence.
+
 **Local file links.** When the operator should open a local repo file, mint the
 URL with \`${b} files url <repo-relative-path>\` instead of guessing it. HTML opens
 as a real page with working scripts and relative assets; other files open in the
@@ -164,8 +165,7 @@ can't resolve from the repo, file it instead. \`${b} decision file "<question>"\
 records it and lets you proceed on a stated default; \`${b} decision search "<terms>"\`
 surfaces prior decisions, so check for precedent before re-deciding. ${decidePointer}
 
-**Councils.** For a hard or contested decision, convene a council of agents.
-\`${b} council create "<objective>"\` runs structured rounds toward a decision. ${councilPointer}`;
+**Councils.** For a hard or contested decision, convene a council of agents. \`${b} council create "<objective>"\` runs structured rounds toward a decision. ${councilPointer}`;
 }
 
 // ── Skills ──────────────────────────────────────────────────────────────────

package/src/lib/tunnel/allowlist.ts

@@ -0,0 +1,208 @@
+// Address allowlist for the tunnel gate: exact addresses and CIDR ranges, IPv4
+// and IPv6. Pure functions with no I/O, shared by the gate worker (matching)
+// and the `tunnel allow` commands (validation + canonical spelling).
+//
+// An IPv6 phone and laptop on one Wi-Fi network have different addresses but
+// share a /64 prefix, so a range entry such as `2601:db8:1:2::/64` admits both.
+// An entry without a prefix length is a single address (/32 or /128).
+//
+// IPv4-mapped IPv6 addresses (`::ffff:203.0.113.8`) are IPv4 addresses reached
+// through a dual-stack socket, so they parse and match as IPv4.
+
+import { isIPv4, isIPv6 } from "node:net";
+
+export type IpFamily = 4 | 6;
+
+export interface ParsedIp {
+  family: IpFamily;
+  value: bigint;
+}
+
+export interface AllowEntry extends ParsedIp {
+  /** Prefix length in bits (32 or 128 for a single address). */
+  prefix: number;
+}
+
+const FULL_BITS: Record<IpFamily, number> = { 4: 32, 6: 128 };
+
+function parseIpv4(text: string): bigint | null {
+  if (!isIPv4(text)) return null;
+  let value = 0n;
+  for (const part of text.split(".")) value = (value << 8n) | BigInt(Number(part));
+  return value;
+}
+
+function parseIpv6(text: string): bigint | null {
+  if (!isIPv6(text)) return null;
+  let rest = text;
+  // A trailing dotted quad (`::ffff:1.2.3.4`, `64:ff9b::1.2.3.4`) is two groups.
+  const dotted = rest.match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/);
+  if (dotted) {
+    const v4 = parseIpv4(dotted[2] as string);
+    if (v4 === null) return null;
+    rest = `${dotted[1]}${(v4 >> 16n).toString(16)}:${(v4 & 0xffffn).toString(16)}`;
+  }
+  const halves = rest.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? (halves[0] as string).split(":") : [];
+  const tail = halves.length === 2 && halves[1] ? (halves[1] as string).split(":") : [];
+  const missing = 8 - head.length - tail.length;
+  if (halves.length === 1 ? missing !== 0 : missing < 1) return null;
+  const groups = [
+    ...head,
+    ...Array.from({ length: halves.length === 2 ? missing : 0 }, () => "0"),
+    ...tail,
+  ];
+  if (groups.length !== 8) return null;
+  let value = 0n;
+  for (const group of groups) {
+    if (!/^[0-9a-f]{1,4}$/i.test(group)) return null;
+    value = (value << 16n) | BigInt(Number.parseInt(group, 16));
+  }
+  return value;
+}
+
+/**
+ * Parse one address. Returns null for anything that is not an IP literal. A
+ * zone id (`fe80::1%en0`) is dropped, and an IPv4-mapped IPv6 address is
+ * reported as the IPv4 address it carries.
+ */
+export function parseIp(raw: string): ParsedIp | null {
+  let text = raw.trim();
+  if (text.startsWith("[") && text.endsWith("]")) text = text.slice(1, -1);
+  const zone = text.indexOf("%");
+  if (zone !== -1) text = text.slice(0, zone);
+  if (!text) return null;
+  const v4 = parseIpv4(text);
+  if (v4 !== null) return { family: 4, value: v4 };
+  const v6 = parseIpv6(text);
+  if (v6 === null) return null;
+  if (v6 >> 32n === 0xffffn) return { family: 4, value: v6 & 0xffffffffn };
+  return { family: 6, value: v6 };
+}
+
+function maskFor(family: IpFamily, prefix: number): bigint {
+  const bits = BigInt(FULL_BITS[family]);
+  const host = bits - BigInt(prefix);
+  return ((1n << bits) - 1n) ^ ((1n << host) - 1n);
+}
+
+/**
+ * Parse an allowlist entry: `203.0.113.8`, `203.0.113.0/24`, `2601:db8::1`, or
+ * `2601:db8:1:2::/64`. Host bits below the prefix are cleared, so
+ * `203.0.113.77/24` means the network `203.0.113.0/24`. Returns null when the
+ * entry is not a valid address or its prefix length is out of range.
+ */
+export function parseAllowEntry(raw: string): AllowEntry | null {
+  const text = raw.trim();
+  const slash = text.indexOf("/");
+  const address = parseIp(slash === -1 ? text : text.slice(0, slash));
+  if (!address) return null;
+  let prefix = FULL_BITS[address.family];
+  if (slash !== -1) {
+    const lengthText = text.slice(slash + 1);
+    if (!/^\d{1,3}$/.test(lengthText)) return null;
+    prefix = Number(lengthText);
+    // A prefix on an IPv4-mapped IPv6 entry counts from the IPv6 start, so
+    // `::ffff:1.2.3.0/120` is the IPv4 /24. Anything shorter is not an IPv4 range.
+    if (address.family === 4 && /:/.test(text.slice(0, slash))) {
+      if (prefix < 96 || prefix > 128) return null;
+      prefix -= 96;
+    }
+    if (prefix > FULL_BITS[address.family]) return null;
+  }
+  return { ...address, prefix, value: address.value & maskFor(address.family, prefix) };
+}
+
+function compress(groups: number[]): string {
+  // RFC 5952: collapse the longest run of two or more zero groups (first wins).
+  let bestStart = -1;
+  let bestLen = 0;
+  for (let i = 0; i < 8; ) {
+    if (groups[i] !== 0) {
+      i++;
+      continue;
+    }
+    let j = i;
+    while (j < 8 && groups[j] === 0) j++;
+    if (j - i > bestLen) {
+      bestStart = i;
+      bestLen = j - i;
+    }
+    i = j;
+  }
+  if (bestLen < 2) return groups.map((g) => g.toString(16)).join(":");
+  const left = groups.slice(0, bestStart).map((g) => g.toString(16));
+  const right = groups.slice(bestStart + bestLen).map((g) => g.toString(16));
+  return `${left.join(":")}::${right.join(":")}`;
+}
+
+/** Canonical text of an address (dotted quad, or compressed lowercase IPv6). */
+export function formatIp(ip: ParsedIp): string {
+  if (ip.family === 4) {
+    return [24n, 16n, 8n, 0n].map((shift) => Number((ip.value >> shift) & 0xffn)).join(".");
+  }
+  const groups: number[] = [];
+  for (let i = 7; i >= 0; i--) groups.push(Number((ip.value >> BigInt(i * 16)) & 0xffffn));
+  return compress(groups);
+}
+
+/** Canonical text of an entry; a single address carries no `/len` suffix. */
+export function formatAllowEntry(entry: AllowEntry): string {
+  const address = formatIp(entry);
+  return entry.prefix === FULL_BITS[entry.family] ? address : `${address}/${entry.prefix}`;
+}
+
+/**
+ * Canonical spelling of an allowlist entry, or null when invalid. Two spellings
+ * of one address or range (`2601:DB8:0:0::1`, `2601:db8::1`) normalize equal.
+ */
+export function normalizeAllowEntry(raw: string): string | null {
+  const entry = parseAllowEntry(raw);
+  return entry ? formatAllowEntry(entry) : null;
+}
+
+export interface Allowlist {
+  entries: AllowEntry[];
+  /** Entries that could not be parsed; they never match anything. */
+  invalid: string[];
+}
+
+export function compileAllowlist(rawEntries: readonly string[]): Allowlist {
+  const entries: AllowEntry[] = [];
+  const invalid: string[] = [];
+  for (const raw of rawEntries) {
+    const text = raw.trim();
+    if (!text) continue;
+    const entry = parseAllowEntry(text);
+    if (entry) entries.push(entry);
+    else invalid.push(text);
+  }
+  return { entries, invalid };
+}
+
+/** True when `ip` lies inside any entry. A missing or malformed address never matches. */
+export function allowlistMatches(list: Allowlist, ip: string): boolean {
+  const address = parseIp(ip);
+  if (!address) return false;
+  for (const entry of list.entries) {
+    if (entry.family !== address.family) continue;
+    const mask = maskFor(entry.family, entry.prefix);
+    if ((address.value & mask) === entry.value) return true;
+  }
+  return false;
+}
+
+/** The IPv6 /64 network prefix of an address, as a canonical `…/64` entry. */
+export function ipv6Slash64(address: string): string | null {
+  const ip = parseIp(address);
+  if (!ip || ip.family !== 6) return null;
+  return formatAllowEntry({ ...ip, prefix: 64, value: ip.value & maskFor(6, 64) });
+}
+
+/** A single IPv4 address as a `/32` entry. */
+export function ipv4Slash32(address: string): string | null {
+  const ip = parseIp(address);
+  if (!ip || ip.family !== 4) return null;
+  return `${formatIp(ip)}/32`;
+}