@moonglade/provenance 0.0.0-stage → 2.6.1

package/dist/hookInstaller.js

@@ -0,0 +1,410 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_USAGE = exports.HOOK_FLAGS = exports.PRE_COMMIT_SCRIPT = exports.HookConflictError = exports.HOOK_MARKER = void 0;
+exports.findGitRoot = findGitRoot;
+exports.resolveHooksDir = resolveHooksDir;
+exports.installGitHook = installGitHook;
+exports.writeProvenanceConfig = writeProvenanceConfig;
+exports.installHooks = installHooks;
+exports.runInstallHooksCli = runInstallHooksCli;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
+const child_process_1 = require("child_process");
+/** Marker line (line 2 of the generated hook). A hook is ours only if its whole content equals a known generated version. */
+exports.HOOK_MARKER = '# moonglade-provenance-hook v1';
+class HookConflictError extends Error {
+    hookPath;
+    constructor(hookPath) {
+        super(`${hookPath} already exists and is not an unmodified hook generated by Moonglade Provenance (it may be foreign or edited). It was left unchanged. Re-run with --force to back it up and replace it.`);
+        this.hookPath = hookPath;
+        this.name = 'HookConflictError';
+    }
+}
+exports.HookConflictError = HookConflictError;
+function git(cwd, args) {
+    return new Promise(resolve => {
+        (0, child_process_1.execFile)('git', args, { cwd, windowsHide: true }, (err, stdout) => {
+            if (err)
+                resolve({ ok: false, missing: err.code === 'ENOENT', out: '' });
+            else
+                resolve({ ok: true, missing: false, out: String(stdout).trim() });
+        });
+    });
+}
+async function findGitRoot(startDir = process.cwd()) {
+    let curr = path.resolve(startDir);
+    while (true) {
+        try {
+            const stat = await fs.stat(path.join(curr, '.git'));
+            if (stat.isDirectory())
+                return curr;
+        }
+        catch {
+            // not in this dir
+        }
+        const parent = path.dirname(curr);
+        if (parent === curr)
+            return null;
+        curr = parent;
+    }
+}
+/**
+ * Hooks directory as git itself resolves it (`git rev-parse --git-path hooks`), so linked worktrees,
+ * submodules and core.hooksPath work. Falls back to a `.git` directory only when git is not installed.
+ * Returns null when cwd is not inside a repository.
+ */
+async function resolveHooksDir(cwd = process.cwd()) {
+    const r = await git(cwd, ['rev-parse', '--git-path', 'hooks']);
+    if (r.ok)
+        return path.resolve(cwd, r.out);
+    if (r.missing) {
+        const root = await findGitRoot(cwd);
+        return root ? path.join(root, '.git', 'hooks') : null;
+    }
+    return null;
+}
+async function resolveTopLevel(cwd) {
+    const r = await git(cwd, ['rev-parse', '--show-toplevel']);
+    return r.ok ? path.resolve(cwd, r.out) : path.resolve(cwd);
+}
+/**
+ * The generated pre-commit hook. Written for bash (not POSIX sh): it reads NUL-delimited names (`read -d ''`)
+ * so file names with spaces, non-ASCII characters (git would quote them otherwise) or newlines are all checked.
+ * Fail closed: if the staged list cannot be read, the commit is blocked.
+ */
+exports.PRE_COMMIT_SCRIPT = `#!/usr/bin/env bash
+${exports.HOOK_MARKER}
+# Moonglade Provenance - Git Pre-Commit Verification Gate (requires bash)
+# Blocks the commit when a staged artifact that has a provenance sidecar no longer matches it.
+
+echo "Moonglade Provenance: Verifying staged artifacts..."
+
+TMP_LIST=$(mktemp) || exit 1
+trap 'rm -f "$TMP_LIST"' EXIT
+if ! git diff --cached --name-only -z --diff-filter=ACMR > "$TMP_LIST"; then
+  echo "Moonglade Provenance: could not list staged files; commit aborted."
+  exit 1
+fi
+
+FAILED=0
+while IFS= read -r -d '' FILE; do
+  case "$FILE" in
+    *.provenance.json|*.provenance-registry.json) continue ;;
+    *.md|*.csv|*.json|*.sql|*.yml|*.yaml) ;;
+    *) continue ;;
+  esac
+  [ -f "$FILE" ] || continue
+  [ -f "$FILE.provenance.json" ] || continue
+  TARGET="$FILE"
+  case "$TARGET" in -*) TARGET="./$TARGET" ;; esac
+  if ! npx --no-install @moonglade/provenance badge "$TARGET" --short < /dev/null > /dev/null 2>&1; then
+    echo "[PROVENANCE DRIFT] $FILE has mutated or failed verification!"
+    FAILED=1
+  fi
+done < "$TMP_LIST"
+
+if [ "$FAILED" -ne 0 ]; then
+  echo ""
+  echo "Commit aborted by Moonglade Provenance Gate."
+  echo "Please re-seal mutated artifacts before committing:"
+  echo "  npx @moonglade/provenance seal-provisional <file>"
+  echo ""
+  exit 1
+fi
+
+echo "All staged artifacts verified."
+exit 0
+`;
+/** Generated hook contents this tool has shipped. A hook is ours only if its content equals one of these exactly. */
+const KNOWN_GENERATED_HOOKS = [exports.PRE_COMMIT_SCRIPT];
+function backupStamp() {
+    return new Date().toISOString().replace(/\.\d+Z$/, 'Z').replace(/[-:]/g, '');
+}
+/** Copy a file to `<file>.bak-<UTC timestamp>` (exclusive create, counter suffix on collision). */
+async function backupFile(file) {
+    const stamp = backupStamp();
+    for (let i = 0;; i++) {
+        const candidate = `${file}.bak-${stamp}${i ? '-' + i : ''}`;
+        try {
+            await fs.copyFile(file, candidate, 1 /* COPYFILE_EXCL */);
+            return candidate;
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+        }
+    }
+}
+/**
+ * Install one hook script. An existing hook is replaced only if its content equals a known generated version
+ * (`known`, default: the shipped hook). Anything else, including our own hook with an edit or a foreign hook
+ * that merely mentions the marker, is refused unless `force`, and a forced replace is backed up first.
+ */
+async function installGitHook(hooksDir, hookName, scriptContent, opts = {}) {
+    await fs.mkdir(hooksDir, { recursive: true });
+    const hookPath = path.join(hooksDir, hookName);
+    const known = opts.known ?? KNOWN_GENERATED_HOOKS;
+    let existing = null;
+    try {
+        existing = await fs.readFile(hookPath, 'utf8');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    let action = 'created';
+    let backup;
+    if (existing !== null) {
+        if (existing === scriptContent) {
+            action = 'unchanged';
+        }
+        else if (known.includes(existing)) {
+            action = 'updated';
+        }
+        else {
+            if (!opts.force)
+                throw new HookConflictError(hookPath);
+            action = 'replaced';
+            backup = await backupFile(hookPath);
+        }
+    }
+    if (action !== 'unchanged') {
+        await fs.writeFile(hookPath, scriptContent, { mode: 0o755 });
+    }
+    await fs.chmod(hookPath, 0o755);
+    return backup ? { path: hookPath, action, backup } : { path: hookPath, action };
+}
+function manifestPayload(selection) {
+    const payload = {
+        standard: MANIFEST_STANDARD,
+        hooks: selection
+    };
+    if (selection.mcpVerifyRead || selection.mcpAutoSeal) {
+        payload.mcpServer = { command: 'npx', args: ['-y', '@moonglade/provenance', 'provenance-gate'] };
+    }
+    return payload;
+}
+/** Previously recorded choices from an existing manifest, or null when absent or unreadable. */
+async function readRecordedHooks(file) {
+    let raw;
+    try {
+        raw = await fs.readFile(file, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { parsed: null, raw: null };
+        throw e;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return { parsed: parsed && typeof parsed === 'object' ? parsed : null, raw };
+    }
+    catch {
+        return { parsed: null, raw };
+    }
+}
+const MANIFEST_STANDARD = 'Moonglade Provenance Hook Manifest v1';
+/** True only for a manifest of exactly the shape this tool writes. Anything else (user keys, other standard, bad JSON) is backed up before a rewrite. */
+function isOurManifest(parsed) {
+    if (!parsed || parsed.standard !== MANIFEST_STANDARD)
+        return false;
+    const allowed = new Set(['standard', 'installedAt', 'hooks', 'mcpServer']);
+    if (!Object.keys(parsed).every(k => allowed.has(k)))
+        return false;
+    const hooks = parsed.hooks;
+    if (!hooks || typeof hooks !== 'object')
+        return false;
+    const hk = new Set(['preCommit', 'mcpVerifyRead', 'mcpAutoSeal']);
+    return Object.keys(hooks).every(k => hk.has(k) && typeof hooks[k] === 'boolean');
+}
+/**
+ * Write the manifest. An existing manifest that is not exactly in the shape this tool writes is backed up first.
+ */
+async function writeProvenanceConfig(dir, selection) {
+    const configPath = path.join(dir, '.provenance-hooks.json');
+    const payload = manifestPayload(selection);
+    const { parsed, raw } = await readRecordedHooks(configPath);
+    let backup;
+    if (raw !== null && !isOurManifest(parsed))
+        backup = await backupFile(configPath);
+    const out = { standard: payload.standard, installedAt: new Date().toISOString(), ...payload };
+    await fs.writeFile(configPath, JSON.stringify(out, null, 2) + '\n', 'utf8');
+    return backup ? { path: configPath, backup } : { path: configPath };
+}
+/**
+ * Install exactly the selected gates. Nothing is enabled that was not selected. The manifest records the
+ * selected options merged with earlier recorded MCP choices (never switched off silently) and with reality:
+ * preCommit is true when an unmodified generated pre-commit hook is installed.
+ */
+async function installHooks(opts) {
+    const cwd = path.resolve(opts.cwd ?? process.cwd());
+    const selected = {
+        preCommit: opts.preCommit === true,
+        mcpVerifyRead: opts.mcpVerifyRead === true,
+        mcpAutoSeal: opts.mcpAutoSeal === true
+    };
+    let hooksDir = null;
+    let hook = null;
+    if (selected.preCommit) {
+        hooksDir = await resolveHooksDir(cwd);
+        if (!hooksDir)
+            throw new Error(`pre-commit hook requested but ${cwd} is not inside a git repository`);
+        hook = await installGitHook(hooksDir, 'pre-commit', exports.PRE_COMMIT_SCRIPT, { force: opts.force });
+    }
+    else {
+        hooksDir = await resolveHooksDir(cwd);
+    }
+    const top = await resolveTopLevel(cwd);
+    const recorded = (await readRecordedHooks(path.join(top, '.provenance-hooks.json'))).parsed?.hooks;
+    let installed = false;
+    if (hooksDir) {
+        try {
+            installed = KNOWN_GENERATED_HOOKS.includes(await fs.readFile(path.join(hooksDir, 'pre-commit'), 'utf8'));
+        }
+        catch { /* no hook */ }
+    }
+    const selection = {
+        preCommit: selected.preCommit || installed,
+        mcpVerifyRead: selected.mcpVerifyRead || recorded?.mcpVerifyRead === true,
+        mcpAutoSeal: selected.mcpAutoSeal || recorded?.mcpAutoSeal === true
+    };
+    const manifest = await writeProvenanceConfig(top, selection);
+    return { selection, hooksDir, hook, manifestPath: manifest.path, manifestBackup: manifest.backup };
+}
+exports.HOOK_FLAGS = ['--pre-commit', '--mcp-verify-read', '--mcp-auto-seal', '--force'];
+exports.HOOK_USAGE = 'usage: provenance install-hooks [--pre-commit] [--mcp-verify-read] [--mcp-auto-seal] [--force]\n' +
+    '  --pre-commit        install the git pre-commit verification gate\n' +
+    '  --mcp-verify-read   record the fail-closed verify-on-read MCP option\n' +
+    '  --mcp-auto-seal     record the provisional auto-seal-on-agent-write MCP option\n' +
+    '  --force             replace an existing hook that is not ours, after backing it up to <hook>.bak-<UTC timestamp>\n' +
+    'With no choice flag, the command asks about each option when run in a terminal and does nothing otherwise.';
+/** CLI entry. Returns the process exit code. */
+async function runInstallHooksCli(args, cwd = process.cwd(), io = {}) {
+    const unknown = args.filter(a => !exports.HOOK_FLAGS.includes(a));
+    if (unknown.length) {
+        console.error(`unknown argument: ${unknown.join(' ')}\n${exports.HOOK_USAGE}`);
+        return 2;
+    }
+    const has = (f) => args.includes(f);
+    let selection = { preCommit: has('--pre-commit'), mcpVerifyRead: has('--mcp-verify-read'), mcpAutoSeal: has('--mcp-auto-seal') };
+    if (!selection.preCommit && !selection.mcpVerifyRead && !selection.mcpAutoSeal) {
+        const interactive = io.interactive ?? (Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY));
+        if (!interactive) {
+            console.error(`no option selected and no terminal to ask.\n${exports.HOOK_USAGE}`);
+            return 2;
+        }
+        try {
+            selection = await askInteractively(io);
+        }
+        catch (e) {
+            if (e instanceof PromptCancelled) {
+                console.error(`install-hooks ${e.message}.`);
+                return 1;
+            }
+            throw e;
+        }
+    }
+    try {
+        const r = await installHooks({ cwd, ...selection, force: has('--force') });
+        if (r.hook) {
+            console.log(`${r.hook.action}: ${r.hook.path}`);
+            if (r.hook.backup)
+                console.log(`backup of previous hook: ${r.hook.backup}`);
+        }
+        console.log(`manifest: ${r.manifestPath}`);
+        if (r.manifestBackup)
+            console.log(`backup of previous manifest: ${r.manifestBackup}`);
+        console.log(`enabled: ${JSON.stringify(r.selection)}`);
+        if (selection.mcpVerifyRead || selection.mcpAutoSeal) {
+            console.log('MCP configuration snippet:');
+            console.log(JSON.stringify({ mcpServers: { 'provenance-gate': { command: 'npx', args: ['-y', '@moonglade/provenance', 'provenance-gate'] } } }, null, 2));
+        }
+        return 0;
+    }
+    catch (e) {
+        console.error(e.message);
+        return 1;
+    }
+}
+class PromptCancelled extends Error {
+    constructor() {
+        super('cancelled, nothing changed');
+        this.name = 'PromptCancelled';
+    }
+}
+async function askInteractively(io = {}) {
+    const rl = readline.createInterface({ input: io.input ?? process.stdin, output: io.output ?? process.stdout });
+    // Queue lines from the start so piped input delivered in one chunk is not lost; end of input cancels.
+    const lines = [];
+    let waiter = null;
+    let closed = false;
+    rl.on('line', l => { if (waiter) {
+        const w = waiter;
+        waiter = null;
+        w.resolve(l);
+    }
+    else
+        lines.push(l); });
+    rl.on('close', () => { closed = true; if (waiter) {
+        const w = waiter;
+        waiter = null;
+        w.reject(new PromptCancelled());
+    } });
+    const nextLine = () => new Promise((resolve, reject) => {
+        if (lines.length)
+            return resolve(lines.shift());
+        if (closed)
+            return reject(new PromptCancelled());
+        waiter = { resolve, reject };
+    });
+    const ask = async (q, def) => {
+        rl.setPrompt(`${q} (${def ? 'Y/n' : 'y/N'}): `);
+        rl.prompt();
+        const t = (await nextLine()).trim().toLowerCase();
+        return t === '' ? def : t === 'y' || t === 'yes';
+    };
+    try {
+        return {
+            preCommit: await ask('Install the git pre-commit verification gate?', true),
+            mcpVerifyRead: await ask('Record the fail-closed verify-on-read MCP option?', false),
+            mcpAutoSeal: await ask('Record the provisional auto-seal-on-agent-write MCP option?', false)
+        };
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,228 @@
+import * as crypto from 'crypto';
+import { InclusionProof, ArtifactMap } from './merkle';
+import { DTAResult, DTAOptions } from './timestamp';
+import { ArtifactEnvelope } from './artifactEnvelope';
+/**
+ * Moonglade Provenance Engine (TypeScript Implementation)
+ * Provides Ed25519 micro-signatures, RFC 3161 timestamps, and Merkle root macro-provenance.
+ */
+export interface ProvenanceSidecar {
+    standard: string;
+    artifact: string;
+    claims?: Record<string, any>;
+    claims_sha256?: string;
+    attestations: Array<{
+        method: string;
+        signer?: string;
+        scope?: string;
+        sha256?: string;
+        target_sha256?: string;
+        claims_sha256?: string;
+        created?: string;
+        git_commit?: string;
+        signature?: string;
+        tier?: string;
+        tsa?: string;
+        tsa_time?: string;
+        token_b64?: string;
+        probes?: any[];
+    }>;
+    sha256_at_last_write: string;
+    updated: string;
+    status?: 'provisional' | 'canonical' | 'revoked';
+    generator?: {
+        agent: string;
+        model?: string;
+        session?: string;
+    };
+    parents?: string[];
+    envelope?: ArtifactEnvelope;
+}
+export interface VerificationResult {
+    verified: boolean;
+    status?: 'VERIFIED' | 'INDETERMINATE';
+    documentSignatureVerified?: boolean;
+    timestampStatus?: 'ABSENT' | 'INVALID' | 'INTEGRITY_ONLY' | 'ANCHORED';
+    signer?: string;
+    timestamp?: string;
+    timestampTier?: string;
+    timestampVerified?: boolean;
+    timestampSigner?: string;
+    error?: string;
+    /** How many signature attestations were checked. Zero means an empty bundle. */
+    attestationsChecked?: number;
+    /** Methods present that this version cannot verify. Reported, never ignored. */
+    unknownMethods?: string[];
+    /**
+     * The scope covered by the verified signature. Returned so a caller can compare it
+     * with the location or namespace it expected: the signature binds the scope string,
+     * but nothing in this library binds that string to where the file actually is.
+     * A caller that does not compare it has not enforced scope.
+     */
+    scope?: string;
+    /** Standard markdown provenance badge representation of this artifact verdict. */
+    badge?: string;
+    claims?: Record<string, any>;
+    claimsSha256?: string;
+}
+export declare const TEXT_EXTENSIONS: Set<string>;
+export declare const BINARY_EXTENSIONS: Set<string>;
+/**
+ * Checks if a filename or byte buffer represents text rather than binary data.
+ */
+export declare function isTextContent(filename: string, bytes: Buffer | Uint8Array): boolean;
+/**
+ * Deterministic JSON Canonicalization Scheme (RFC 8785 subset for generic claims, draft -03 section 3.3).
+ * Sorts object keys lexicographically by UTF-16 code units with no whitespace. Numbers must be safe
+ * integers; floats, NaN, Infinity and lone surrogates are rejected, exactly as in the Python and Rust engines.
+ */
+export declare function canonicalizeJson(value: any): string;
+export interface VerificationPolicy {
+    expectedScope?: string;
+    requiredSigners?: string[];
+    timestampTrustAnchors?: string[];
+}
+export declare const BUNDLE_V2 = "Moonglade Provenance Attestation Bundle v2";
+export declare const BUNDLE_V3 = "Moonglade Provenance Attestation Bundle v3";
+export declare const MAX_ARTIFACT_BYTES: number;
+export declare const MAX_SIDECAR_BYTES: number;
+/** Reject links and oversized inputs. This local tool assumes no concurrent hostile filesystem writer. */
+export declare function readRegularFile(file: string, limit: number): Promise<Buffer>;
+export declare function writeSidecar(file: string, value: ProvenanceSidecar): Promise<void>;
+export declare function validateSidecar(sidecar: any): asserts sidecar is ProvenanceSidecar;
+export declare class ProvenanceEngine {
+    /**
+     * Canonicalizes an in-memory buffer according to Moonglade Provenance rules.
+     * Text documents: strips UTF-8 BOM, normalizes CRLF to LF, and applies Unicode NFC.
+     * Binary documents (PDFs, images, binaries): preserves exact byte fidelity.
+     */
+    static canonicalizeBytes(raw: Buffer, filename?: string): Buffer;
+    /**
+     * Canonicalize a file's bytes deterministically:
+     * For text documents, normalize CRLF to LF, strip UTF-8 BOM, and apply Unicode NFC.
+     * For binary documents (PDFs, images, binaries), preserve byte-exact fidelity.
+     *
+     * This exists so a git checkout on Windows does not invalidate text signatures
+     * in the repository, while ensuring binary structures (like PDF xref tables)
+     * remain completely untouched.
+     */
+    static canonicalizeFile(filePath: string): Promise<Buffer>;
+    /**
+     * Generates an Ed25519 keypair for testing/local identities if none exists.
+     */
+    static generateEd25519KeyPair(): crypto.KeyPairSyncResult<string, string>;
+    /**
+     * The bytes that are actually signed.
+     *
+     * Until v2 the signature covered the document bytes alone, which meant the
+     * scope, the signer identity and the timestamp were unauthenticated JSON
+     * sitting beside it. Anyone could rewrite the scope in a sidecar and the
+     * signature still verified - so the stated property, that a signature made
+     * for one scope will not verify under another, was not true here.
+     *
+     * v2 signs a structured claim instead. Three properties matter:
+     *
+     *   1. Domain separation - the version string is inside the payload, so a
+     *      signature over one payload type cannot be replayed as another.
+     *   2. Field binding - scope, artifact hash and signer are all covered.
+     *   3. Unambiguous framing - newlines delimit fields, and fields are
+     *      validated to contain none, so a crafted scope cannot smuggle in a
+     *      forged signer line.
+     */
+    static readonly PAYLOAD_VERSION = "moonglade-provenance/v2";
+    static readonly PAYLOAD_VERSION_V3 = "moonglade-provenance/v3";
+    static buildSigningPayload(fields: {
+        scope: string;
+        sha256: string;
+        signer: string;
+    }): Buffer;
+    static buildSigningPayloadV3(fields: {
+        scope: string;
+        targetSha256: string;
+        signer: string;
+        claimsSha256: string;
+    }): Buffer;
+    /**
+     * Build the attestation scope for an artifact.
+     *
+     * Scope isolation is the stated security property: a signature made for one
+     * scope must not be presentable for another. Until 2026-08-30 this used
+     * `path.basename(filePath)`, which gave every README.md in the tree the same
+     * scope - a collision in any repository with repeated filenames, which is all
+     * of them.
+     *
+     * It is now the path relative to `vaultRoot`, matching the Python
+     * implementation's `namespace_for()`.
+     *
+     * Separators are forced to POSIX. `path.relative` yields backslashes on
+     * Windows and forward slashes elsewhere, so without this the same file signed
+     * on two machines would carry two different scopes. That is the same class of
+     * defect canonicalizeFile exists to prevent for line endings, and it would be
+     * careless to fix one and not the other.
+     */
+    static scopeFor(filePath: string, vaultRoot?: string, explicit?: string): string;
+    /**
+     * Sign a document and generate the .provenance.json sidecar.
+     * Supports both v2 standard bundles and v3 extended bundles with generic claims.
+     */
+    static sealDocument(filePath: string, privateKeyPem: string, signerIdentity: string, gitCommit?: string, opts?: {
+        vaultRoot?: string;
+        scope?: string;
+        timestamp?: boolean | DTAOptions;
+        claims?: Record<string, any>;
+        version?: 'v2' | 'v3';
+    }): Promise<ProvenanceSidecar>;
+    /**
+     * Countersign an existing document and append the attestation to the sidecar.
+     */
+    static countersignDocument(filePath: string, privateKeyPem: string, signerIdentity: string, gitCommit?: string, opts?: {
+        vaultRoot?: string;
+        scope?: string;
+        verificationKeys?: string | Record<string, string>;
+        policy?: VerificationPolicy;
+    }): Promise<ProvenanceSidecar>;
+    /**
+     * Attest RFC 3161 timestamping for an artifact via Concurrent Multi-Source DTA.
+     */
+    static attestTimestamp(filePath: string, opts?: DTAOptions): Promise<DTAResult>;
+    /**
+     * Verify a document against its sidecar.
+     * Supports both v2 and v3 attestation bundles.
+     */
+    static verifyDocument(filePath: string, publicKeyPem: string | Record<string, string>, policy?: VerificationPolicy): Promise<VerificationResult>;
+}
+/**
+ * Vault Macro-Provenance: Merkle Tree Hash Registry
+ */
+export declare class ProvenanceVault {
+    rootPath: string;
+    salt: string;
+    constructor(rootPath: string, salt?: string);
+    private walk;
+    /**
+     * Hash every file under the root and build a real Merkle tree over them.
+     *
+     * Until v2 this returned a flat SHA-256 over the concatenated hashes. That
+     * detected change and nothing else - it could not produce an inclusion proof,
+     * which is the only reason to use a tree. See merkle.ts.
+     *
+     * Paths are POSIX-normalised before hashing, so a vault scanned on Windows and
+     * on Linux yields the same root. Without that the two would silently disagree,
+     * which is the same defect canonicalizeFile prevents for line endings.
+     */
+    scanAndAudit(): Promise<{
+        merkleRoot: string;
+        algorithm: string;
+        fileCount: number;
+        artifacts: ArtifactMap;
+    }>;
+    /** Audit path for one artifact, by its POSIX path relative to the root. */
+    proveInclusion(relPath: string): Promise<InclusionProof | null>;
+}
+export * from './merkle';
+export * from './timestamp';
+export * from './mcp';
+export * from './artifactHook';
+export * from './artifactEnvelope';
+export * from './self-test';
+export * from './badge';