@moonglade/provenance 0.0.0-stage → 2.6.1

package/dist/artifactHook.js

@@ -0,0 +1,114 @@
+"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.processArtifact = processArtifact;
+exports.moveArtifactWithAttestation = moveArtifactWithAttestation;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const index_1 = require("./index");
+const artifactEnvelope_1 = require("./artifactEnvelope");
+const UNSAFE_NAMES = new Set(['.env', '.env.local', 'id_rsa', 'id_ed25519', 'id_dsa', 'id_ecdsa', '.npmrc', 'credentials', 'secrets.json']);
+const UNSAFE_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '__pycache__']);
+function isUnsafe(filePath) {
+    const parts = path.resolve(filePath).split(path.sep);
+    if (parts.some(part => UNSAFE_DIRS.has(part)))
+        return 'path is inside an excluded directory';
+    if (UNSAFE_NAMES.has(path.basename(filePath).toLowerCase()))
+        return 'filename is excluded';
+    if (/\.(pem|key|p12|pfx|asc|kdbx)$/i.test(filePath))
+        return 'private-key or certificate material is excluded';
+    return undefined;
+}
+async function processArtifact(filePath, opts = {}) {
+    const resolved = path.resolve(filePath);
+    const unsafe = isUnsafe(resolved);
+    if (unsafe)
+        return { path: resolved, action: opts.action ?? 'observe', skipped: true, reason: unsafe };
+    const action = opts.action ?? 'observe';
+    if (action === 'observe') {
+        const bytes = await (0, index_1.readRegularFile)(resolved, index_1.MAX_ARTIFACT_BYTES);
+        const hash = (await Promise.resolve().then(() => __importStar(require('crypto')))).createHash('sha256').update(bytes).digest('hex');
+        const envelope = (0, artifactEnvelope_1.createArtifactEnvelope)({ artifact_type: 'other', canonical_bytes: `sha256:${hash}`, created_at: new Date().toISOString(), parents: [], attestations: [], status: 'observed', evidence: { integrity: 'valid', signature: 'none', timestamp: 'none', scope: 'unknown' }, bytes });
+        return { path: resolved, action, skipped: false, sidecar: {
+                standard: 'Moonglade Provenance Observation v1', artifact: path.basename(resolved), attestations: [],
+                sha256_at_last_write: hash, updated: new Date().toISOString(), envelope
+            } };
+    }
+    if (!opts.privateKeyPem || !opts.signerIdentity)
+        throw new Error('seal-provisional requires privateKeyPem and signerIdentity');
+    const sidecar = await index_1.ProvenanceEngine.sealDocument(resolved, opts.privateKeyPem, opts.signerIdentity, opts.gitCommit ?? 'unknown', { vaultRoot: opts.vaultRoot, timestamp: false });
+    sidecar.status = 'provisional';
+    sidecar.generator = opts.generator ?? { agent: 'unknown' };
+    sidecar.parents = opts.parents ?? [];
+    sidecar.envelope = (0, artifactEnvelope_1.createArtifactEnvelope)({ artifact_type: 'other', canonical_bytes: `sha256:${sidecar.sha256_at_last_write}`, created_at: sidecar.updated, parents: opts.parents ?? [], attestations: sidecar.attestations.map(a => ({ method: a.method, signer: a.signer, status: a.method === 'moonglade-ed25519-v2' ? 'provisional' : 'indeterminate', signature: a.signature })), status: 'signed', evidence: { integrity: 'valid', signature: 'provisional', timestamp: 'none', scope: 'valid' }, generator: opts.generator, bytes: await (0, index_1.readRegularFile)(resolved, index_1.MAX_ARTIFACT_BYTES) });
+    await (0, index_1.writeSidecar)(`${resolved}.provenance.json`, sidecar);
+    return { path: resolved, action, skipped: false, sidecar };
+}
+/** Move an artifact and its adjacent attestation as one atomic logical unit. */
+async function moveArtifactWithAttestation(sourcePath, destinationPath) {
+    const source = path.resolve(sourcePath);
+    const destination = path.resolve(destinationPath);
+    const sourceAttestation = `${source}.provenance.json`;
+    const destinationAttestation = `${destination}.provenance.json`;
+    for (const file of [destination, destinationAttestation]) {
+        try {
+            await fs.lstat(file);
+            throw new Error('Move destination already exists');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    try {
+        await fs.lstat(sourceAttestation);
+        throw new Error('Attested move refused: copy and explicitly reseal at the destination before retiring the source');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    await (0, index_1.readRegularFile)(source, index_1.MAX_ARTIFACT_BYTES);
+    // Exclusive link creation avoids rename-overwrite races. Cross-device moves fail safely.
+    await fs.link(source, destination);
+    try {
+        await fs.unlink(source);
+    }
+    catch (error) {
+        await fs.unlink(destination);
+        throw error;
+    }
+    return { artifactPath: destination, attestationPath: destinationAttestation, attestationMoved: false };
+}

package/dist/badge.d.ts

@@ -0,0 +1,83 @@
+export type ProvenanceBadgeStatus = 'HASH_ONLY' | 'SEALED' | 'LIVING' | 'SCRATCH' | 'MUTATED' | 'INVALID_SIGNATURE' | 'NOT_FOUND';
+export interface BadgeColorDefinition {
+    hex: string;
+    ansi: string;
+    bgHex: string;
+    bgAnsi: string;
+    resetAnsi: string;
+}
+export declare const BADGE_COLORS: Record<ProvenanceBadgeStatus, BadgeColorDefinition>;
+export declare function getStatusColor(status: ProvenanceBadgeStatus): BadgeColorDefinition;
+export interface BadgeOptions {
+    format?: 'text' | 'markdown' | 'markdown-link' | 'shields-url' | 'html' | 'json';
+    color?: boolean | 'ansi' | 'html';
+    shortHashLen?: number;
+    style?: 'short' | 'detailed';
+    targetUrl?: string;
+    publicKeyPem?: string;
+    requiredScope?: string;
+}
+export interface BadgeInfo {
+    status: ProvenanceBadgeStatus;
+    badgeText: string;
+    ansiText?: string;
+    html?: string;
+    colorHex: string;
+    markdown: string;
+    shieldsUrl: string;
+    filePath: string;
+    artifactName: string;
+    signer?: string;
+    shortHash?: string;
+    fullHash?: string;
+    tier?: string;
+    timestamp?: string;
+    error?: string;
+}
+/**
+ * Clean signer identifier for badge display (e.g. 'Synthetic (Fixture)...' -> 'Synthetic').
+ */
+export declare function extractShortSigner(signer?: string): string | undefined;
+/**
+ * Generate a Shields.io badge URL for a given status.
+ */
+export declare function getShieldsBadgeUrl(status: ProvenanceBadgeStatus, details?: {
+    signer?: string;
+    shortHash?: string;
+}): string;
+/**
+ * Format an ANSI color-coded badge string for terminal display.
+ */
+export declare function formatAnsiBadge(status: ProvenanceBadgeStatus, details?: {
+    signer?: string;
+    hash?: string;
+    tier?: string;
+}, options?: BadgeOptions): string;
+/**
+ * Format an inline HTML badge element for web apps, Astro, or rich markdown docs.
+ */
+export declare function formatHtmlBadge(status: ProvenanceBadgeStatus, details?: {
+    signer?: string;
+    hash?: string;
+    tier?: string;
+}, options?: BadgeOptions): string;
+/**
+ * Format a badge string given status and metadata.
+ */
+export declare function formatBadge(status: ProvenanceBadgeStatus, details?: {
+    signer?: string;
+    hash?: string;
+    tier?: string;
+}, options?: BadgeOptions): string;
+/**
+ * Format a complete markdown link with the badge adjacent.
+ */
+export declare function formatMarkdownLink(filePath: string, badgeInfo: BadgeInfo, options?: {
+    label?: string;
+    urlPrefix?: string;
+    targetUrl?: string;
+}): string;
+/**
+ * Inspect an artifact and its sidecar to produce a complete Provenance BadgeInfo.
+ */
+export declare function getArtifactBadge(filePath: string, options?: BadgeOptions): Promise<BadgeInfo>;

package/dist/badge.js

@@ -0,0 +1,403 @@
+"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.BADGE_COLORS = void 0;
+exports.getStatusColor = getStatusColor;
+exports.extractShortSigner = extractShortSigner;
+exports.getShieldsBadgeUrl = getShieldsBadgeUrl;
+exports.formatAnsiBadge = formatAnsiBadge;
+exports.formatHtmlBadge = formatHtmlBadge;
+exports.formatBadge = formatBadge;
+exports.formatMarkdownLink = formatMarkdownLink;
+exports.getArtifactBadge = getArtifactBadge;
+const fsSync = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const index_1 = require("./index");
+exports.BADGE_COLORS = {
+    HASH_ONLY: { hex: '#d97706', ansi: '\x1b[1;33m', bgHex: 'rgba(217,119,6,0.15)', bgAnsi: '\x1b[43;30m', resetAnsi: '\x1b[0m' },
+    SEALED: {
+        hex: '#2ea44f',
+        ansi: '\x1b[1;32m',
+        bgHex: 'rgba(46,164,79,0.15)',
+        bgAnsi: '\x1b[42;30m',
+        resetAnsi: '\x1b[0m'
+    },
+    LIVING: {
+        hex: '#0969da',
+        ansi: '\x1b[1;34m',
+        bgHex: 'rgba(9,105,218,0.15)',
+        bgAnsi: '\x1b[44;37m',
+        resetAnsi: '\x1b[0m'
+    },
+    SCRATCH: {
+        hex: '#d97706',
+        ansi: '\x1b[1;33m',
+        bgHex: 'rgba(217,119,6,0.15)',
+        bgAnsi: '\x1b[43;30m',
+        resetAnsi: '\x1b[0m'
+    },
+    MUTATED: {
+        hex: '#cf222e',
+        ansi: '\x1b[1;31m',
+        bgHex: 'rgba(207,34,46,0.15)',
+        bgAnsi: '\x1b[41;37m',
+        resetAnsi: '\x1b[0m'
+    },
+    INVALID_SIGNATURE: {
+        hex: '#cf222e',
+        ansi: '\x1b[1;31m',
+        bgHex: 'rgba(207,34,46,0.15)',
+        bgAnsi: '\x1b[41;37m',
+        resetAnsi: '\x1b[0m'
+    },
+    NOT_FOUND: {
+        hex: '#6e7781',
+        ansi: '\x1b[90m',
+        bgHex: 'rgba(110,119,129,0.15)',
+        bgAnsi: '\x1b[47;30m',
+        resetAnsi: '\x1b[0m'
+    }
+};
+function getStatusColor(status) {
+    return exports.BADGE_COLORS[status] || exports.BADGE_COLORS.NOT_FOUND;
+}
+/**
+ * Clean signer identifier for badge display (e.g. 'Synthetic (Fixture)...' -> 'Synthetic').
+ */
+function extractShortSigner(signer) {
+    if (!signer)
+        return undefined;
+    const match = signer.match(/^([^<(\s]+)/);
+    return match ? match[1] : signer;
+}
+/**
+ * Generate a Shields.io badge URL for a given status.
+ */
+function getShieldsBadgeUrl(status, details) {
+    let label = 'provenance';
+    let message = 'unknown';
+    let color = 'lightgrey';
+    switch (status) {
+        case 'HASH_ONLY': return 'https://img.shields.io/badge/provenance-hash%20only-d97706?style=flat-square';
+        case 'SEALED': {
+            const parts = ['sealed'];
+            if (details?.signer)
+                parts.push(encodeURIComponent(details.signer));
+            if (details?.shortHash)
+                parts.push(details.shortHash);
+            message = parts.join('%20%C2%B7%20'); // URL-encoded middle dot
+            color = '2ea44f'; // Green
+            break;
+        }
+        case 'LIVING':
+            message = 'unsealed%20%C2%B7%20living';
+            color = '0969da'; // Blue
+            break;
+        case 'SCRATCH':
+            message = 'ephemeral%20%C2%B7%20scratch';
+            color = 'd97706'; // Amber
+            break;
+        case 'MUTATED':
+            message = 'mutated%20%C2%B7%20mismatch';
+            color = 'cf222e'; // Red
+            break;
+        case 'INVALID_SIGNATURE':
+            message = 'invalid%20signature';
+            color = 'cf222e'; // Red
+            break;
+        case 'NOT_FOUND':
+            message = 'not%20found';
+            color = 'grey';
+            break;
+    }
+    return `https://img.shields.io/badge/${label}-${message}-${color}?style=flat-square`;
+}
+/**
+ * Format an ANSI color-coded badge string for terminal display.
+ */
+function formatAnsiBadge(status, details, options = {}) {
+    const colorDef = getStatusColor(status);
+    const plain = formatBadge(status, details, { ...options, color: false });
+    // Match the inner bracketed text: e.g. "🛡️ [SEALED · Synthetic · 9df0af4d]"
+    const match = plain.match(/^(\S+)\s*\[(.*)\]$/);
+    if (!match) {
+        return `${colorDef.ansi}${plain}${colorDef.resetAnsi}`;
+    }
+    const emoji = match[1];
+    const inner = match[2];
+    return `${emoji} [${colorDef.ansi}${inner}${colorDef.resetAnsi}]`;
+}
+/**
+ * Format an inline HTML badge element for web apps, Astro, or rich markdown docs.
+ */
+function formatHtmlBadge(status, details, options = {}) {
+    const colorDef = getStatusColor(status);
+    const plain = formatBadge(status, details, { ...options, format: 'text', color: false });
+    const match = plain.match(/^(\S+)\s*\[(.*)\]$/);
+    if (!match) {
+        return `<span class="provenance-badge provenance-badge-${status.toLowerCase()}" style="color:${colorDef.hex};font-weight:600;font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;font-size:0.85em;">${plain}</span>`;
+    }
+    const emoji = match[1];
+    const innerText = match[2].replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+    return `${emoji} <span class="provenance-badge-status" style="color:${colorDef.hex};font-weight:600;font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;font-size:0.85em;">[${innerText}]</span>`;
+}
+/**
+ * Format a badge string given status and metadata.
+ */
+function formatBadge(status, details, options = {}) {
+    if (options.color === true || options.color === 'ansi' || options.format === 'text' && options.color) {
+        return formatAnsiBadge(status, details, { ...options, color: false });
+    }
+    if (options.color === 'html' || options.format === 'html') {
+        return formatHtmlBadge(status, details, options);
+    }
+    const shortHashLen = options.shortHashLen ?? 8;
+    const shortHash = details?.hash ? details.hash.slice(0, shortHashLen) : undefined;
+    const shortSigner = options.style === 'short'
+        ? undefined
+        : extractShortSigner(details?.signer);
+    switch (status) {
+        case 'HASH_ONLY': return '⚠️ [HASH-ONLY · UNVERIFIED]';
+        case 'SEALED': {
+            const parts = ['SEALED'];
+            if (shortSigner)
+                parts.push(shortSigner);
+            if (shortHash)
+                parts.push(shortHash);
+            return `🛡️ [${parts.join(' · ')}]`;
+        }
+        case 'LIVING':
+            return '📝 [UNSEALED · LIVING]';
+        case 'SCRATCH':
+            return '⚡ [EPHEMERAL · SCRATCH]';
+        case 'MUTATED':
+            return '🚨 [MUTATED · HASH MISMATCH]';
+        case 'INVALID_SIGNATURE':
+            return '🚨 [INVALID SIGNATURE]';
+        case 'NOT_FOUND':
+            return '❌ [NOT FOUND]';
+    }
+}
+/**
+ * Format a complete markdown link with the badge adjacent.
+ */
+function formatMarkdownLink(filePath, badgeInfo, options = {}) {
+    const label = options.label || path.basename(filePath);
+    let fileUrl = options.targetUrl;
+    if (!fileUrl) {
+        const normalized = path.resolve(filePath).replace(/\\/g, '/');
+        fileUrl = options.urlPrefix
+            ? `${options.urlPrefix}/${path.basename(filePath)}`
+            : `file:///${normalized.startsWith('/') ? normalized.slice(1) : normalized}`;
+    }
+    return `[${label}](${fileUrl}) ${badgeInfo.badgeText}`;
+}
+/**
+ * Inspect an artifact and its sidecar to produce a complete Provenance BadgeInfo.
+ */
+async function getArtifactBadge(filePath, options = {}) {
+    const resolved = path.resolve(filePath);
+    const artifactName = path.basename(resolved);
+    const isScratch = resolved.includes(`${path.sep}scratch${path.sep}`) ||
+        resolved.includes('/scratch/') ||
+        resolved.includes(`${path.sep}tmp${path.sep}`) ||
+        resolved.includes('/tmp/');
+    if (!fsSync.existsSync(resolved)) {
+        const badgeText = formatBadge('NOT_FOUND', {}, options);
+        const colorDef = getStatusColor('NOT_FOUND');
+        const ansiText = formatAnsiBadge('NOT_FOUND', {}, options);
+        const html = formatHtmlBadge('NOT_FOUND', {}, options);
+        return {
+            status: 'NOT_FOUND',
+            badgeText,
+            ansiText,
+            html,
+            colorHex: colorDef.hex,
+            markdown: `[${artifactName}] ${badgeText}`,
+            shieldsUrl: getShieldsBadgeUrl('NOT_FOUND'),
+            filePath: resolved,
+            artifactName,
+            error: `File not found: ${resolved}`
+        };
+    }
+    // Canonicalize and compute SHA-256 hash
+    const canonicalBytes = await index_1.ProvenanceEngine.canonicalizeFile(resolved);
+    const currentHash = crypto.createHash('sha256').update(canonicalBytes).digest('hex');
+    const shortHash = currentHash.slice(0, options.shortHashLen ?? 8);
+    // Locate companion sidecar
+    let sidecarPath = `${resolved}.provenance.json`;
+    if (!fsSync.existsSync(sidecarPath)) {
+        // Special check for package.json -> package.provenance.json in same directory
+        if (artifactName === 'package.json') {
+            const alt = path.join(path.dirname(resolved), 'package.provenance.json');
+            if (fsSync.existsSync(alt)) {
+                sidecarPath = alt;
+            }
+        }
+    }
+    // Case 1: No sidecar present
+    if (!fsSync.existsSync(sidecarPath)) {
+        const status = isScratch ? 'SCRATCH' : 'LIVING';
+        const badgeText = formatBadge(status, { hash: currentHash }, options);
+        const colorDef = getStatusColor(status);
+        const ansiText = formatAnsiBadge(status, { hash: currentHash }, options);
+        const html = formatHtmlBadge(status, { hash: currentHash }, options);
+        const badgeInfo = {
+            status,
+            badgeText,
+            ansiText,
+            html,
+            colorHex: colorDef.hex,
+            markdown: '',
+            shieldsUrl: getShieldsBadgeUrl(status, { shortHash }),
+            filePath: resolved,
+            artifactName,
+            shortHash,
+            fullHash: currentHash
+        };
+        badgeInfo.markdown = formatMarkdownLink(resolved, badgeInfo, { targetUrl: options.targetUrl });
+        return badgeInfo;
+    }
+    // Case 2: Sidecar present - parse and verify
+    try {
+        const sidecarRaw = (await (0, index_1.readRegularFile)(sidecarPath, index_1.MAX_SIDECAR_BYTES)).toString('utf8');
+        const sidecar = JSON.parse(sidecarRaw);
+        (0, index_1.validateSidecar)(sidecar);
+        // Hash check
+        if (sidecar.sha256_at_last_write && sidecar.sha256_at_last_write !== currentHash) {
+            const badgeText = formatBadge('MUTATED', { hash: currentHash }, options);
+            const colorDef = getStatusColor('MUTATED');
+            const ansiText = formatAnsiBadge('MUTATED', { hash: currentHash }, options);
+            const html = formatHtmlBadge('MUTATED', { hash: currentHash }, options);
+            const badgeInfo = {
+                status: 'MUTATED',
+                badgeText,
+                ansiText,
+                html,
+                colorHex: colorDef.hex,
+                markdown: '',
+                shieldsUrl: getShieldsBadgeUrl('MUTATED', { shortHash }),
+                filePath: resolved,
+                artifactName,
+                shortHash,
+                fullHash: currentHash,
+                error: `Sidecar recorded hash ${sidecar.sha256_at_last_write.slice(0, 12)}... does not match computed hash ${shortHash}...`
+            };
+            badgeInfo.markdown = formatMarkdownLink(resolved, badgeInfo, { targetUrl: options.targetUrl });
+            return badgeInfo;
+        }
+        // Extract signer information
+        const firstAtt = sidecar.attestations?.[0] || sidecar.envelope?.attestations?.[0];
+        const rawSigner = firstAtt?.signer || sidecar.generator?.agent;
+        const cleanSigner = extractShortSigner(rawSigner);
+        let verifiedTimestamp;
+        let verifiedTier;
+        // Cryptographic signature check if public key provided
+        if (options.publicKeyPem) {
+            const verifyRes = await index_1.ProvenanceEngine.verifyDocument(resolved, options.publicKeyPem, { expectedScope: options.requiredScope });
+            verifiedTimestamp = verifyRes.timestamp;
+            verifiedTier = verifyRes.timestampTier;
+            if (!verifyRes.verified) {
+                const badgeText = formatBadge('INVALID_SIGNATURE', { hash: currentHash, signer: cleanSigner }, options);
+                const colorDef = getStatusColor('INVALID_SIGNATURE');
+                const ansiText = formatAnsiBadge('INVALID_SIGNATURE', { hash: currentHash, signer: cleanSigner }, options);
+                const html = formatHtmlBadge('INVALID_SIGNATURE', { hash: currentHash, signer: cleanSigner }, options);
+                const badgeInfo = {
+                    status: 'INVALID_SIGNATURE',
+                    badgeText,
+                    ansiText,
+                    html,
+                    colorHex: colorDef.hex,
+                    markdown: '',
+                    shieldsUrl: getShieldsBadgeUrl('INVALID_SIGNATURE', { signer: cleanSigner, shortHash }),
+                    filePath: resolved,
+                    artifactName,
+                    signer: rawSigner,
+                    shortHash,
+                    fullHash: currentHash,
+                    error: verifyRes.error
+                };
+                badgeInfo.markdown = formatMarkdownLink(resolved, badgeInfo, { targetUrl: options.targetUrl });
+                return badgeInfo;
+            }
+        }
+        const status = options.publicKeyPem ? 'SEALED' : 'HASH_ONLY';
+        const badgeText = formatBadge(status, { hash: currentHash, signer: cleanSigner }, options);
+        const colorDef = getStatusColor(status);
+        const ansiText = formatAnsiBadge(status, { hash: currentHash, signer: cleanSigner }, options);
+        const html = formatHtmlBadge(status, { hash: currentHash, signer: cleanSigner }, options);
+        const badgeInfo = {
+            status: status,
+            badgeText,
+            ansiText,
+            html,
+            colorHex: colorDef.hex,
+            markdown: '',
+            shieldsUrl: getShieldsBadgeUrl(status, { signer: cleanSigner, shortHash }),
+            filePath: resolved,
+            artifactName,
+            signer: rawSigner,
+            shortHash,
+            fullHash: currentHash,
+            tier: verifiedTier,
+            timestamp: verifiedTimestamp
+        };
+        badgeInfo.markdown = formatMarkdownLink(resolved, badgeInfo, { targetUrl: options.targetUrl });
+        return badgeInfo;
+    }
+    catch (err) {
+        const badgeText = formatBadge('MUTATED', { hash: currentHash }, options);
+        const colorDef = getStatusColor('MUTATED');
+        const ansiText = formatAnsiBadge('MUTATED', { hash: currentHash }, options);
+        const html = formatHtmlBadge('MUTATED', { hash: currentHash }, options);
+        const badgeInfo = {
+            status: 'MUTATED',
+            badgeText,
+            ansiText,
+            html,
+            colorHex: colorDef.hex,
+            markdown: '',
+            shieldsUrl: getShieldsBadgeUrl('MUTATED', { shortHash }),
+            filePath: resolved,
+            artifactName,
+            shortHash,
+            fullHash: currentHash,
+            error: `Failed to parse sidecar: ${err.message}`
+        };
+        badgeInfo.markdown = formatMarkdownLink(resolved, badgeInfo, { targetUrl: options.targetUrl });
+        return badgeInfo;
+    }
+}

package/dist/hookInstaller.d.ts

@@ -0,0 +1,75 @@
+export interface HookSelection {
+    preCommit: boolean;
+    mcpVerifyRead: boolean;
+    mcpAutoSeal: boolean;
+}
+export interface InstallOptions extends HookSelection {
+    cwd?: string;
+    /** Replace a hook that was not installed by this tool, after backing it up. */
+    force?: boolean;
+}
+export interface HookResult {
+    path: string;
+    action: 'created' | 'unchanged' | 'updated' | 'replaced';
+    backup?: string;
+}
+export interface InstallResult {
+    /** What the manifest now records (selected options merged with earlier recorded state). */
+    selection: HookSelection;
+    hooksDir: string | null;
+    hook: HookResult | null;
+    manifestPath: string;
+    manifestBackup?: string;
+}
+/** Marker line (line 2 of the generated hook). A hook is ours only if its whole content equals a known generated version. */
+export declare const HOOK_MARKER = "# moonglade-provenance-hook v1";
+export declare class HookConflictError extends Error {
+    readonly hookPath: string;
+    constructor(hookPath: string);
+}
+export declare function findGitRoot(startDir?: string): Promise<string | null>;
+/**
+ * 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.
+ */
+export declare function resolveHooksDir(cwd?: string): Promise<string | null>;
+/**
+ * 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.
+ */
+export declare const PRE_COMMIT_SCRIPT = "#!/usr/bin/env bash\n# moonglade-provenance-hook v1\n# Moonglade Provenance - Git Pre-Commit Verification Gate (requires bash)\n# Blocks the commit when a staged artifact that has a provenance sidecar no longer matches it.\n\necho \"Moonglade Provenance: Verifying staged artifacts...\"\n\nTMP_LIST=$(mktemp) || exit 1\ntrap 'rm -f \"$TMP_LIST\"' EXIT\nif ! git diff --cached --name-only -z --diff-filter=ACMR > \"$TMP_LIST\"; then\n  echo \"Moonglade Provenance: could not list staged files; commit aborted.\"\n  exit 1\nfi\n\nFAILED=0\nwhile IFS= read -r -d '' FILE; do\n  case \"$FILE\" in\n    *.provenance.json|*.provenance-registry.json) continue ;;\n    *.md|*.csv|*.json|*.sql|*.yml|*.yaml) ;;\n    *) continue ;;\n  esac\n  [ -f \"$FILE\" ] || continue\n  [ -f \"$FILE.provenance.json\" ] || continue\n  TARGET=\"$FILE\"\n  case \"$TARGET\" in -*) TARGET=\"./$TARGET\" ;; esac\n  if ! npx --no-install @moonglade/provenance badge \"$TARGET\" --short < /dev/null > /dev/null 2>&1; then\n    echo \"[PROVENANCE DRIFT] $FILE has mutated or failed verification!\"\n    FAILED=1\n  fi\ndone < \"$TMP_LIST\"\n\nif [ \"$FAILED\" -ne 0 ]; then\n  echo \"\"\n  echo \"Commit aborted by Moonglade Provenance Gate.\"\n  echo \"Please re-seal mutated artifacts before committing:\"\n  echo \"  npx @moonglade/provenance seal-provisional <file>\"\n  echo \"\"\n  exit 1\nfi\n\necho \"All staged artifacts verified.\"\nexit 0\n";
+/**
+ * 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.
+ */
+export declare function installGitHook(hooksDir: string, hookName: string, scriptContent: string, opts?: {
+    force?: boolean;
+    known?: string[];
+}): Promise<HookResult>;
+/**
+ * Write the manifest. An existing manifest that is not exactly in the shape this tool writes is backed up first.
+ */
+export declare function writeProvenanceConfig(dir: string, selection: HookSelection): Promise<{
+    path: string;
+    backup?: string;
+}>;
+/**
+ * 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.
+ */
+export declare function installHooks(opts: InstallOptions): Promise<InstallResult>;
+export declare const HOOK_FLAGS: readonly ["--pre-commit", "--mcp-verify-read", "--mcp-auto-seal", "--force"];
+export declare const HOOK_USAGE: string;
+/** CLI entry. Returns the process exit code. */
+export declare function runInstallHooksCli(args: string[], cwd?: string, io?: PromptIo): Promise<number>;
+interface PromptIo {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    /** Force interactive (true) or non-interactive (false) mode; default is whether stdin and stdout are terminals. */
+    interactive?: boolean;
+}
+export {};