@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/template-pins.js

@@ -0,0 +1,115 @@
+/**
+ * Re-pinning records after template parameters are substituted (#2549, #2627).
+ *
+ * A template's decision records may pin a file of the template by hash. When
+ * `chant init --from` or `chant workspace upgrade` fills that file's
+ * `{{chant:<name>}}` placeholders, the copy's bytes differ from the
+ * template's, and every copy would report the pin as drifted on day one. So
+ * after substitution, each pin that held in the template and names a
+ * substituted file gets the hash of the substituted content.
+ *
+ * A record is any Markdown file whose front matter has an `evidence` list
+ * with path pins. Its paths resolve from the nearest directory above it that
+ * holds a workspace declaration, as `chant workspace records` resolves them.
+ * A pin that did not hold in the template stays as it is: re-pinning follows
+ * the substitution and never hides drift the template already had. Only the
+ * `sha256` value on the pin's line changes; the rest of the file is kept byte
+ * for byte.
+ */
+import { sha256Hex } from "../content-digest.js";
+import { pinEntries } from "./record-assets.js";
+import { parseFrontMatter } from "./records.js";
+const DECLARATIONS = ["chant.workspace.json", "chant.workspace.jsonc"];
+const EVIDENCE = "evidence";
+const dirOf = (path) => (path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "");
+/** The nearest directory at or above `dir` holding a workspace declaration in `files`, or "" for the root. */
+function workspaceRootOf(files, dir) {
+    for (let d = dir;; d = dirOf(d)) {
+        if (DECLARATIONS.some((name) => files.has(d === "" ? name : `${d}/${name}`)))
+            return d;
+        if (d === "")
+            return "";
+    }
+}
+/**
+ * Rewrite, in `substituted`, the pins of every record that name a file in
+ * `changed` and held against `original`. Returns the files with the records
+ * rewritten, and which records were.
+ */
+export function repinSubstituted(original, substituted, changed) {
+    const files = new Map(substituted);
+    const repinned = [];
+    if (changed.length === 0)
+        return { files, repinned };
+    const changedSet = new Set(changed);
+    for (const [recordPath, data] of [...substituted].sort(([a], [b]) => a.localeCompare(b))) {
+        if (!recordPath.endsWith(".md"))
+            continue;
+        const text = data.toString("utf-8");
+        const fm = parseFrontMatter(text);
+        if (!fm.ok)
+            continue;
+        const root = workspaceRootOf(substituted, dirOf(recordPath));
+        const full = (p) => (root === "" ? p : `${root}/${p}`);
+        const updates = new Map();
+        for (const pin of pinEntries(fm.value, EVIDENCE)) {
+            const file = full(pin.path);
+            if (!changedSet.has(file))
+                continue;
+            const before = original.get(file);
+            const after = substituted.get(file);
+            if (!before || !after || sha256Hex(before) !== pin.sha256)
+                continue;
+            updates.set(pin.path, { from: pin.sha256, to: sha256Hex(after) });
+        }
+        if (updates.size === 0)
+            continue;
+        const rewritten = rewritePins(text, updates);
+        // Only a rewrite that reads back with every update applied is kept.
+        const check = parseFrontMatter(rewritten);
+        const pins = check.ok ? pinEntries(check.value, EVIDENCE) : [];
+        if (![...updates].every(([path, u]) => pins.some((p) => p.path === path && p.sha256 === u.to)))
+            continue;
+        files.set(recordPath, Buffer.from(rewritten, "utf-8"));
+        repinned.push({ record: recordPath, paths: [...updates.keys()].sort() });
+    }
+    return { files, repinned };
+}
+/**
+ * Replace the `sha256` of each updated pin in the front matter. A pin is a
+ * list entry, from its `- ` line to the next one at the same indentation or
+ * less, holding both `path: "<path>"` and `sha256: "<old>"`.
+ */
+function rewritePins(text, updates) {
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const lines = text.split(eol);
+    const end = lines.indexOf("---", 1);
+    if (lines[0] !== "---" || end < 0)
+        return text;
+    const starts = [];
+    for (let i = 1; i < end; i++)
+        if (/^\s*- /.test(lines[i]))
+            starts.push(i);
+    for (let s = 0; s < starts.length; s++) {
+        const from = starts[s];
+        const indent = lines[from].search(/-/);
+        let to = end;
+        for (let i = from + 1; i < end; i++) {
+            const lead = lines[i].search(/\S/);
+            if (lead >= 0 && lead <= indent) {
+                to = i;
+                break;
+            }
+        }
+        const entry = lines.slice(from, to).join("\n");
+        const path = entry.match(/(?:^|\n)\s*(?:- )?path: "([^"]*)"/)?.[1];
+        const update = path !== undefined ? updates.get(path) : undefined;
+        if (!update)
+            continue;
+        for (let i = from; i < to; i++) {
+            if (new RegExp(`^(\\s*(?:- )?sha256: )"${update.from}"\\s*$`).test(lines[i]))
+                lines[i] = lines[i].replace(update.from, update.to);
+        }
+    }
+    return lines.join(eol);
+}

package/dist/workspace/trailer-joins.js

@@ -0,0 +1,65 @@
+/**
+ * Joining a commit through chant's own trailers (#3149, ws-075), for `graph
+ * --intent` and `graph --intent --record`.
+ *
+ * A plugin's `commitJoins` reads a kind's own trailers (`intent-joins.ts`).
+ * These are core's: a `Chant-Record` names a record by kind and id, and a
+ * `Chant-Lease` names a work lease by its fencing token, which the lease
+ * histories on `chant/lifecycle` turn into the work item it was taken on.
+ * Both read the local branch and never fetch.
+ */
+import { execFileSync } from "node:child_process";
+import { parseLeaseHistory } from "../lifecycle/work-lease.js";
+import { readChantTrailers } from "./trailers.js";
+/** The branch the lease histories are on. */
+const LEDGER_BRANCH = "refs/heads/chant/lifecycle";
+function git(top, args) {
+    try {
+        return execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The work item each lease token names, from the lease histories
+ * (`_leases/<item>.jsonl`, any member's) on the local `chant/lifecycle`
+ * branch. A token no history names is left out. Never fetches.
+ */
+export function leaseItemsByToken(top, tokens) {
+    const out = new Map();
+    const wanted = [...new Set(tokens.filter((t) => t !== ""))];
+    if (wanted.length === 0 || git(top, ["rev-parse", "--verify", "--quiet", LEDGER_BRANCH]) === undefined)
+        return out;
+    const listed = git(top, ["grep", "-l", "-F", ...wanted.flatMap((t) => ["-e", t]), LEDGER_BRANCH, "--", ":(glob)**/_leases/*.jsonl"]);
+    for (const line of (listed ?? "").split("\n")) {
+        const path = line.startsWith(`${LEDGER_BRANCH}:`) ? line.slice(LEDGER_BRANCH.length + 1) : "";
+        const m = path.match(/(?:^|\/)_leases\/([^/]+)\.jsonl$/);
+        if (!m)
+            continue;
+        const text = git(top, ["show", `${LEDGER_BRANCH}:${path}`]);
+        for (const r of parseLeaseHistory(text ?? "").records)
+            if (wanted.includes(r.token) && r.item === m[1] && !out.has(r.token))
+                out.set(r.token, r.item);
+    }
+    return out;
+}
+/** Read chant's trailers from each commit, and the work items their lease tokens name. */
+export function readTrailerJoins(top, commits) {
+    const read = commits.map((c) => ({ sha: c.sha, trailers: readChantTrailers(c.trailers) }));
+    const items = leaseItemsByToken(top, read.map((r) => r.trailers.lease).filter((t) => t !== null));
+    const out = new Map();
+    for (const { sha, trailers } of read) {
+        out.set(sha, {
+            trailers,
+            joins: {
+                agent: trailers.agent,
+                lease: trailers.lease === null ? null : { token: trailers.lease, item: items.get(trailers.lease) ?? null },
+                run: trailers.run,
+                records: trailers.records.map((r) => ({ kind: r.kind, id: r.id, node: null })),
+                applied: trailers.applied,
+            },
+        });
+    }
+    return out;
+}

package/dist/workspace/trailers.js

@@ -0,0 +1,111 @@
+/**
+ * chant's commit trailers (#3149, ws-075): the vocabulary a commit uses to
+ * name the lease, the agent run, the records and the apply behind it.
+ *
+ * A trailer is how a commit points at a fact kept elsewhere: a work lease on
+ * `chant/lifecycle`, an agent run in the run ledger (#3033), a record in the
+ * working tree. Provenance is keyed to those ids, never to commit SHAs, so a
+ * commit that keeps its message through a rebase or a cherry-pick keeps its
+ * joins (#3037). chant never writes a commit itself (ws-074): whoever makes
+ * the commit adds the trailers, and chant reads them back in `graph
+ * --intent`, `graph --intent --record` and `workspace runs`.
+ *
+ * | Trailer | Value | Names |
+ * |---|---|---|
+ * | `Chant-Agent` | an agent session | the session that wrote the commit (ws-067) |
+ * | `Chant-Lease` | a fencing token | the work lease the commit was made under |
+ * | `Chant-Run` | a run id | the agent run that made the commit (#3033) |
+ * | `Chant-Record` | `<kind>:<id>` | a record the commit carries out or changes; repeatable |
+ * | `Chant-Applied-By` | a principal | who applied a leased branch, on the apply commit |
+ * | `Chant-Applied-At` | ISO 8601 | when it was applied |
+ * | `Chant-Applied-Commit` | a commit id | the tip of the branch that was applied |
+ *
+ * Every other trailer is a plugin's, and core gives it no meaning; a kind's
+ * `commitJoins` may (`intent-joins.ts`).
+ */
+import { trailerValue, trailerValues } from "./intent-joins.js";
+/** The agent session that wrote a commit (ws-067). */
+export const AGENT_TRAILER = "Chant-Agent";
+/** The fencing token of the work lease a commit was made under. */
+export const LEASE_TRAILER = "Chant-Lease";
+/** The agent run that made a commit (#3033). */
+export const RUN_TRAILER = "Chant-Run";
+/** A record a commit carries out or changes, as `<kind>:<id>`. Repeatable. */
+export const RECORD_TRAILER = "Chant-Record";
+/** Who applied a leased branch, on the commit that applied it. */
+export const APPLIED_BY_TRAILER = "Chant-Applied-By";
+/** When the branch was applied, ISO 8601. */
+export const APPLIED_AT_TRAILER = "Chant-Applied-At";
+/** The tip of the branch that was applied. */
+export const APPLIED_COMMIT_TRAILER = "Chant-Applied-Commit";
+/** Every trailer key core reads, in the order a writer should add them. */
+export const CHANT_TRAILERS = [AGENT_TRAILER, LEASE_TRAILER, RUN_TRAILER, RECORD_TRAILER, APPLIED_BY_TRAILER, APPLIED_AT_TRAILER, APPLIED_COMMIT_TRAILER];
+/** A record kind's name, as a kind file's `recordKind.name` gives it. */
+const KIND_NAME = /^[a-z][a-z0-9-]*$/;
+/** A record id, as the record kinds allocate them and as a work lease keys them. */
+const RECORD_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const COMMIT_ID = /^[0-9a-f]{40,64}$/;
+/** Parse one `Chant-Record` value, `<kind>:<id>`, or undefined when it is not one. */
+export function parseRecordRef(value) {
+    const colon = value.indexOf(":");
+    if (colon <= 0)
+        return undefined;
+    const kind = value.slice(0, colon).trim();
+    const id = value.slice(colon + 1).trim();
+    return KIND_NAME.test(kind) && RECORD_ID.test(id) ? { kind, id } : undefined;
+}
+/** Read chant's own trailers from a commit's parsed trailers. Keys compare without case, as git's do. */
+export function readChantTrailers(trailers) {
+    const records = [];
+    for (const v of trailerValues(trailers, RECORD_TRAILER)) {
+        const ref = parseRecordRef(v);
+        if (ref && !records.some((r) => r.kind === ref.kind && r.id === ref.id))
+            records.push(ref);
+    }
+    const by = trailerValue(trailers, APPLIED_BY_TRAILER) ?? null;
+    const commit = trailerValue(trailers, APPLIED_COMMIT_TRAILER) ?? null;
+    return {
+        agent: trailerValue(trailers, AGENT_TRAILER) ?? null,
+        lease: trailerValue(trailers, LEASE_TRAILER) ?? null,
+        run: trailerValue(trailers, RUN_TRAILER) ?? null,
+        records,
+        applied: by === null ? null : { by, at: trailerValue(trailers, APPLIED_AT_TRAILER) ?? null, commit: commit !== null && COMMIT_ID.test(commit) ? commit : null },
+    };
+}
+/** Whether a commit carries any of chant's own trailers. */
+export function hasChantTrailers(t) {
+    return t.agent !== null || t.lease !== null || t.run !== null || t.records.length > 0 || t.applied !== null;
+}
+/**
+ * The trailer lines for a commit message, in {@link CHANT_TRAILERS} order.
+ * Throws when a value holds a line break or a record ref is malformed, since
+ * either would write a trailer git parses differently.
+ */
+export function formatChantTrailers(input) {
+    const lines = [];
+    const add = (key, value) => {
+        if (value === undefined)
+            return;
+        const v = value.trim();
+        if (v === "" || /[\r\n]/.test(v))
+            throw new Error(`${key} takes one line of text, not ${JSON.stringify(value)}`);
+        lines.push(`${key}: ${v}`);
+    };
+    add(AGENT_TRAILER, input.agent);
+    add(LEASE_TRAILER, input.lease);
+    add(RUN_TRAILER, input.run);
+    for (const r of input.records ?? []) {
+        const ref = typeof r === "string" ? parseRecordRef(r) : r;
+        if (!ref || !KIND_NAME.test(ref.kind) || !RECORD_ID.test(ref.id))
+            throw new Error(`${RECORD_TRAILER} takes <kind>:<id>, not ${JSON.stringify(r)}`);
+        add(RECORD_TRAILER, `${ref.kind}:${ref.id}`);
+    }
+    if (input.applied) {
+        add(APPLIED_BY_TRAILER, input.applied.by);
+        add(APPLIED_AT_TRAILER, input.applied.at);
+        if (input.applied.commit !== undefined && !COMMIT_ID.test(input.applied.commit))
+            throw new Error(`${APPLIED_COMMIT_TRAILER} takes a full commit id, not ${JSON.stringify(input.applied.commit)}`);
+        add(APPLIED_COMMIT_TRAILER, input.applied.commit);
+    }
+    return lines;
+}

package/dist/workspace/tree.js

@@ -0,0 +1,136 @@
+/**
+ * The files a workspace read looks at: the working tree, or one commit's git
+ * objects (`--at <rev>`, #2524 D15). Reading a revision needs no checkout and
+ * no network; the whole tree is listed once from the local object store.
+ *
+ * Paths are relative to the tree's root, `/`-separated, and `""` is the root.
+ */
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+/** Join tree-relative path parts, leaving out `""` and `"."`. */
+export function joinPath(...parts) {
+    return parts.filter((p) => p !== "" && p !== ".").join("/");
+}
+/** The working tree under `root`. */
+export function workingTree(root) {
+    return {
+        label: "",
+        stat(path) {
+            try {
+                const s = statSync(join(root, path));
+                return s.isDirectory() ? "dir" : s.isFile() ? "file" : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        list(path) {
+            let dirents;
+            try {
+                dirents = readdirSync(join(root, path), { withFileTypes: true });
+            }
+            catch {
+                return undefined;
+            }
+            const out = [];
+            for (const d of dirents) {
+                let type = d.isDirectory() ? "dir" : d.isFile() ? "file" : undefined;
+                if (!type && d.isSymbolicLink()) {
+                    try {
+                        const s = statSync(join(root, path, d.name));
+                        type = s.isDirectory() ? "dir" : s.isFile() ? "file" : undefined;
+                    }
+                    catch {
+                        // A dangling link is no entry.
+                    }
+                }
+                if (type)
+                    out.push({ name: d.name, type });
+            }
+            return out;
+        },
+        read(path) {
+            return readFileSync(join(root, path), "utf-8");
+        },
+        bytes(path) {
+            return readFileSync(join(root, path));
+        },
+    };
+}
+function git(cwd, args) {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 512 * 1024 * 1024 });
+}
+/** The top of the git repository holding `cwd`, or undefined outside one. */
+export function gitTop(cwd) {
+    try {
+        return git(cwd, ["rev-parse", "--show-toplevel"]).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The full commit id `rev` names in the repository at `top`, or undefined. */
+export function resolveCommit(top, rev) {
+    if (rev.startsWith("-"))
+        return undefined;
+    try {
+        return git(top, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`]).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The tree of `commit` in the repository at `top`, rooted at `prefix` (a
+ * directory relative to `top`, `""` for the top itself).
+ */
+export function gitTree(top, commit, prefix = "") {
+    const entries = new Map([["", "dir"]]);
+    const children = new Map([["", []]]);
+    const out = git(top, ["ls-tree", "-r", "-t", "-z", "--full-tree", commit]);
+    for (const line of out.split("\0")) {
+        if (!line)
+            continue;
+        const tab = line.indexOf("\t");
+        const type = line.slice(0, tab).split(" ")[1];
+        const full = line.slice(tab + 1);
+        let path;
+        if (prefix === "")
+            path = full;
+        else if (full.startsWith(`${prefix}/`))
+            path = full.slice(prefix.length + 1);
+        else
+            continue;
+        const kind = type === "tree" ? "dir" : type === "blob" ? "file" : undefined;
+        if (!kind)
+            continue;
+        entries.set(path, kind);
+        const slash = path.lastIndexOf("/");
+        const parent = slash < 0 ? "" : path.slice(0, slash);
+        if (!children.has(parent))
+            children.set(parent, []);
+        children.get(parent).push({ name: path.slice(slash + 1), type: kind });
+        if (kind === "dir" && !children.has(path))
+            children.set(path, []);
+    }
+    return {
+        label: ` at ${commit.slice(0, 8)}`,
+        stat: (path) => entries.get(path),
+        list: (path) => (entries.get(path) === "dir" ? [...(children.get(path) ?? [])] : undefined),
+        read(path) {
+            if (entries.get(path) !== "file")
+                throw new Error(`${path} is not a file${` at ${commit.slice(0, 8)}`}`);
+            return git(top, ["cat-file", "blob", `${commit}:${joinPath(prefix, path)}`]);
+        },
+        bytes(path) {
+            if (entries.get(path) !== "file")
+                throw new Error(`${path} is not a file${` at ${commit.slice(0, 8)}`}`);
+            return execFileSync("git", ["cat-file", "blob", `${commit}:${joinPath(prefix, path)}`], { cwd: top, stdio: ["ignore", "pipe", "pipe"], maxBuffer: 512 * 1024 * 1024 });
+        },
+    };
+}
+/** Directory names a workspace walk never enters. */
+export function skippedDir(name) {
+    return name === "node_modules" || name.startsWith(".");
+}

package/dist/workspace/trust/attestor.js

@@ -0,0 +1,63 @@
+/**
+ * Attestors and provenance levels (#2524 D5).
+ *
+ * An attestor answers one question about a commit: does it carry an
+ * attestation that the policy read at base accepts? Concrete attestors are
+ * plugins. Core ships the contract and the first one, ssh-signed commits
+ * (./ssh-commit.ts). Plugin attestors will arrive the way kinds do, through
+ * `workspaceKinds` (#2525 rule 5), once the declaration can name them (#2534,
+ * #2535); until then {@link registerAttestor} is the entry point.
+ *
+ * What counts as proof: a signature the attestor checked against a key the
+ * base policy lists. Never a trailer, a typed-in name, an author field or an
+ * environment variable.
+ */
+import { UNATTESTED_APPROVER } from "../../lifecycle/gate-origin.js";
+/**
+ * How far a record's authorship is established. The list is closed and
+ * ordered from strongest to weakest; a gate may require `attested`.
+ *
+ * - `attested`: an attestor verified a signature by a signer the base policy lists.
+ * - `attested-unverifiable-here`: there is a signature, but nothing here can
+ *   check it (a signature format no attestor handles, or a missing tool).
+ * - `adopted`: not attested, but inside a commit range the base policy admits.
+ * - `unattested`: none of the above. The same word, with the same meaning, as
+ *   the approver a gate resolution records when its channel cannot attest to a
+ *   name (#2384, {@link UNATTESTED_APPROVER}); D5 keeps that meaning.
+ */
+export const PROVENANCE_LEVELS = ["attested", "attested-unverifiable-here", "adopted", UNATTESTED_APPROVER];
+const registered = [];
+/** Add an attestor. Later registrations are asked after earlier ones. */
+export function registerAttestor(attestor) {
+    if (!registered.some((a) => a.name === attestor.name))
+        registered.push(attestor);
+}
+/** Remove every attestor registered by {@link registerAttestor}. For tests. */
+export function resetAttestors() {
+    registered.length = 0;
+}
+/**
+ * Ask each attestor in turn. The first `attested` answer wins; otherwise
+ * `attested-unverifiable-here` beats `unattested`, so a signature nobody here
+ * can check is still reported as there.
+ */
+export function attestCommit(ctx, commit, attestors) {
+    let best;
+    for (const a of attestors) {
+        const r = a.attestCommit(ctx, commit);
+        if (r.level === "attested")
+            return r;
+        if (!best || (best.level === "unattested" && r.level === "attested-unverifiable-here"))
+            best = r;
+    }
+    return best ?? { level: "unattested", attestor: "none", reason: "no attestor is registered" };
+}
+/** {@link attestCommit} for a raw commit object, asking only the attestors that judge one. */
+export function attestRawCommit(ctx, raw, attestors) {
+    return attestCommit(ctx, "", attestors.filter((a) => a.attestRaw).map((a) => ({ name: a.name, attestCommit: (c) => a.attestRaw(c, raw) })));
+}
+/** The attestors in use: the built-in ones first, then any registered. */
+export async function activeAttestors() {
+    const { sshCommitAttestor } = await import("./ssh-commit.js");
+    return [sshCommitAttestor, ...registered.filter((a) => a.name !== sshCommitAttestor.name)];
+}

package/dist/workspace/trust/dsse.js

@@ -0,0 +1,108 @@
+/**
+ * DSSE envelopes (https://github.com/secure-systems-lab/dsse, v1) signed with
+ * Ed25519 runner keys (#2553).
+ *
+ * The signature covers the pre-authentication encoding (PAE) of the payload
+ * type and the payload, never the payload alone, so an envelope cannot be
+ * replayed under another type. Everything here runs offline: verifying needs
+ * the envelope and the public key, nothing else.
+ *
+ * Public keys are written the way ssh writes them (`ssh-ed25519 AAAA...`), so
+ * the runner keys in `.chant/trust.json` read like the signers file beside
+ * them, and a key id is the key's ssh fingerprint (`SHA256:...`).
+ */
+import { createHash, createPrivateKey, createPublicKey, sign, verify } from "node:crypto";
+export const IN_TOTO_PAYLOAD_TYPE = "application/vnd.in-toto+json";
+/** DSSE v1 pre-authentication encoding. Lengths are byte lengths in ASCII decimal. */
+export function pae(payloadType, payload) {
+    const type = Buffer.from(payloadType, "utf8");
+    return Buffer.concat([Buffer.from(`DSSEv1 ${type.length} `, "utf8"), type, Buffer.from(` ${payload.length} `, "utf8"), payload]);
+}
+// ── ssh-ed25519 public keys ──────────────────────────────────────────────────
+function sshString(buf, at) {
+    if (at + 4 > buf.length)
+        throw new Error("truncated key");
+    const len = buf.readUInt32BE(at);
+    if (at + 4 + len > buf.length)
+        throw new Error("truncated key");
+    return { value: buf.subarray(at + 4, at + 4 + len), next: at + 4 + len };
+}
+/** The 32 raw bytes of an `ssh-ed25519 <base64>` public key. */
+export function ed25519FromSsh(line) {
+    const [type, b64] = line.trim().split(/\s+/);
+    if (type !== "ssh-ed25519" || !b64)
+        throw new Error("runner keys must be ssh-ed25519 public keys");
+    const blob = Buffer.from(b64, "base64");
+    const t = sshString(blob, 0);
+    if (t.value.toString("utf8") !== "ssh-ed25519")
+        throw new Error("the key blob is not ssh-ed25519");
+    const k = sshString(blob, t.next);
+    if (k.value.length !== 32 || k.next !== blob.length)
+        throw new Error("not a 32-byte ed25519 key");
+    return Buffer.from(k.value);
+}
+/** An `ssh-ed25519 <base64>` line for 32 raw public key bytes. */
+export function sshFromEd25519(raw) {
+    const part = (b) => {
+        const len = Buffer.alloc(4);
+        len.writeUInt32BE(b.length);
+        return Buffer.concat([len, b]);
+    };
+    return `ssh-ed25519 ${Buffer.concat([part(Buffer.from("ssh-ed25519")), part(raw)]).toString("base64")}`;
+}
+/** The ssh fingerprint of a public key line: `SHA256:` and unpadded base64. */
+export function sshFingerprint(line) {
+    const blob = Buffer.from(line.trim().split(/\s+/)[1] ?? "", "base64");
+    return `SHA256:${createHash("sha256").update(blob).digest("base64").replace(/=+$/, "")}`;
+}
+function publicKeyObject(line) {
+    return createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: ed25519FromSsh(line).toString("base64url") }, format: "jwk" });
+}
+/** A private Ed25519 key from PEM (PKCS#8), and its public half as an ssh line. */
+export function loadRunnerKey(pem) {
+    const key = createPrivateKey(pem);
+    if (key.asymmetricKeyType !== "ed25519")
+        throw new Error(`runner keys must be Ed25519, not ${key.asymmetricKeyType}`);
+    const jwk = createPublicKey(key).export({ format: "jwk" });
+    return { key, publicKey: sshFromEd25519(Buffer.from(jwk.x, "base64url")) };
+}
+// ── Sign and verify ──────────────────────────────────────────────────────────
+export function signEnvelope(payloadType, payload, key, publicKey) {
+    const sig = sign(null, pae(payloadType, payload), key);
+    return { payloadType, payload: payload.toString("base64"), signatures: [{ keyid: sshFingerprint(publicKey), sig: sig.toString("base64") }] };
+}
+/** Verify an envelope against `trusted`. One valid signature by a trusted key is enough. */
+export function verifyEnvelope(envelope, trusted) {
+    if (!isEnvelope(envelope))
+        return { ok: false, code: "envelope-invalid", reason: "not a DSSE envelope: it needs payloadType, payload and signatures" };
+    const payload = Buffer.from(envelope.payload, "base64");
+    if (payload.toString("base64") !== envelope.payload)
+        return { ok: false, code: "envelope-invalid", reason: "the payload is not canonical base64" };
+    const message = pae(envelope.payloadType, payload);
+    const byId = new Map(trusted.map((t) => [sshFingerprint(t.key), t]));
+    for (const s of envelope.signatures) {
+        const t = byId.get(s.keyid);
+        if (!t)
+            continue;
+        let good = false;
+        try {
+            good = verify(null, message, publicKeyObject(t.key), Buffer.from(s.sig, "base64"));
+        }
+        catch {
+            good = false;
+        }
+        if (good)
+            return { ok: true, principal: t.principal, keyid: s.keyid, payloadType: envelope.payloadType, payload };
+    }
+    const ids = envelope.signatures.map((s) => s.keyid).join(", ") || "none";
+    return { ok: false, code: "envelope-untrusted", reason: `no signature verifies against a runner key the policy at base lists (key ids: ${ids})` };
+}
+function isEnvelope(v) {
+    if (v === null || typeof v !== "object")
+        return false;
+    const e = v;
+    return (typeof e.payloadType === "string" &&
+        typeof e.payload === "string" &&
+        Array.isArray(e.signatures) &&
+        e.signatures.every((s) => s !== null && typeof s === "object" && typeof s.keyid === "string" && typeof s.sig === "string"));
+}