@moonglade/provenance 0.0.0-stage → 2.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moonglade AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,9 @@
+# Dependency and fixture notices
+
+This package uses the MIT license. Its direct runtime dependencies are PKI.js 3.4.1 and ASN1.js 3.0.10, both BSD-3-Clause. The locked runtime dependency tree also includes @noble/hashes (MIT), bytestreamjs (BSD-3-Clause), pvtsutils (MIT), pvutils (MIT) and tslib (0BSD).
+
+Each dependency retains its own copyright and license files when installed. No dependency code is vendored in this package.
+
+Timestamp tests generate synthetic certificates and ephemeral keys with PKI.js and Node WebCrypto. Merkle and canonicalization vectors are project test data. The historical FreeTSA fixture and unreviewed TSA anchors are excluded.
+
+The Moonglade name identifies the project. The MIT license does not grant additional trademark permission. The exported root certificate deliberately contains the release maintainer's public signer identity. It is not an artifact verification key and does not grant agents architect authority.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @moonglade/provenance 2.6.0
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ed25519 signatures, canonical file hashes, RFC 3161 timestamp checks and Merkle inclusion proofs for Node 22 and 24.
+
+## Build from source
+
+Run these commands from the repository root:
+
+```sh
+npm ci
+npm test
+```
+
+The npm package can be installed after a release is authorized. This candidate has not been published.
+
+## Sign and verify
+
+```js
+const { ProvenanceEngine } = require('@moonglade/provenance');
+// Supply your own Ed25519 keys. Never use the release root key for artifacts.
+async function example(file, privateKey, publicKey, root) {
+  await ProvenanceEngine.sealDocument(file, privateKey, 'example-signer', 'local', { vaultRoot: root });
+  return ProvenanceEngine.verifyDocument(file, publicKey, {
+    expectedScope: ProvenanceEngine.scopeFor(file, root),
+    requiredSigners: ['example-signer']
+  });
+}
+```
+
+Get trusted public keys through a channel you trust. An editable sidecar cannot establish a signer's identity. A valid signature establishes possession of a key and integrity of the signed payload. It does not prove the content is correct, identify its actual author, or grant the signer authority.
+
+Supply `expectedScope` to bind verification to an expected location or namespace. Use `requiredSigners` when particular signatures are required. The low-level verifier does not infer either policy.
+
+## Canonicalization
+
+For text, the engine removes one leading UTF-8 BOM, converts CRLF to LF and applies Unicode NFC. Bare CR is preserved. Invalid UTF-8 is rejected.
+
+Known binary formats keep their exact bytes. For unknown extensions, a NUL in the first 1024 bytes selects binary handling; otherwise the engine requires valid UTF-8 text. Text integrity follows these normalization rules rather than raw byte identity.
+
+## Verification results
+
+`SEALED` requires a verified Ed25519 signature. With no key, a matching recorded hash is shown in amber as `HASH-ONLY`. The sidecar is editable, so that result provides no signature assurance. Malformed sidecars cannot produce a seal.
+
+Timestamp results are separate: `ABSENT`, `INVALID`, `INTEGRITY_ONLY` or `ANCHORED`. Time comes from the verified token, never an unsigned sidecar field. `ANCHORED` requires caller-supplied CA certificates, chain validation at token time, ESSCertIDv2 and a critical timestamp-only EKU. Certificate revocation is not checked. Without anchors, a valid self-signed TSA token can provide integrity-only evidence. Network or host-clock observations without tokens do not become RFC 3161 attestations.
+
+## CLI
+
+The installed names are `provenance`, `provenance-artifact` and `provenance-gate`. The last starts the MCP server. CLI commands are:
+
+```text
+provenance --help
+provenance --version
+provenance verify <file>
+provenance badge <file>
+provenance observe <file>
+provenance seal-provisional <file>
+provenance move <source> <destination>
+provenance test [--json]
+```
+
+Set `MOONGLADE_PUBLIC_KEY_PEM` for verification. Provisional sealing requires `MOONGLADE_PRIVATE_KEY_PEM` and `MOONGLADE_SIGNER`. The verification root is `MOONGLADE_ROOT`, or the current directory when unset. `MOONGLADE_REQUIRED_SIGNERS` is an optional comma-separated list.
+
+Failed verification and refused sealing return a nonzero exit code. Move refuses destination collisions and any source sidecar. To relocate an attested artifact, copy it, explicitly reseal and verify the destination, then retire the original separately. Existing signatures keep their original scope.
+
+## MCP and filesystem access
+
+The read-only MCP server exposes `verify_artifact_provenance`, `audit_vault_merkle_root` and `assert_gate_status`. It has no signing or hook tools. Each supplied path authorizes a local read under the operator's filesystem permissions. The process is not a sandbox. Connect it only to principals allowed that access.
+
+Gate assertions check the supplied signature and policy; they do not establish human approval or signer authority. Input frames are limited to 1 MiB. File reads reject symlinks and have a 64 MiB limit; sidecars are limited to 1 MiB, and timestamp tokens and responses to 512 KiB. Protect workspace permissions. Concurrent hostile filesystem writers are outside the supported trust model.
+
+## API and limits
+
+`dist/index.d.ts` declares the public exports: the engine, vault, verification policy, canonicalization and bounded reads; Merkle helpers; timestamp parsing, verification and acquisition; badge helpers; artifact and envelope utilities; read-only MCP tools and self-test.
+
+The built-in verifier returns `INDETERMINATE` for OpenPGP and SSHSIG attestations. The legacy library OpenPGP signing helper is not covered by the default test suite; its keyring selection is caller-controlled. Default hooks, platform keystores, the hook CLI and sibling packages are excluded.
+
+See [SPEC.md](SPEC.md), [TIMESTAMP.md](TIMESTAMP.md), [NOTICE.md](NOTICE.md) and [trust/README.md](trust/README.md). GPG checks the OpenPGP release identity separately. Artifact verification uses raw Ed25519 SPKI PEM keys. Candidate documentation is intentionally unsealed. The root release key is not an agent key.

package/SPEC.md

@@ -0,0 +1,176 @@
+# Attestation Bundle v3 (Extended): Generic Claims, Dual-Hash Binding & Multi-Party Countersigning
+
+**Status:** Implemented in `@moonglade/provenance` v2.6.0+ / v3-Extended Engine  
+**Author:** Marc Ottley (Moonglade AI)  
+**Supersedes:** Bundle v2 Specification (`SPEC.md`)  
+
+---
+
+## 1. Motivation & Design Intent
+
+Attestation Bundle v2 solved field binding and domain separation for local-first document attestation:
+```text
+moonglade-provenance/v2\n
+scope:<scope>\n
+sha256:<sha256 of canonical bytes>\n
+signer:<identity>\n
+```
+
+While v2 securely bound the document's content hash to its repository scope and signer, real-world systems require attaching **rich, structured domain metadata** that must also be tamper-evident:
+- **Photography & Generative Media:** EXIF camera telemetry, focal length, color space, creator royalty splits, and Creative Commons / commercial licensing terms.
+- **Enterprise PDF & Legal Documents:** Contract identifiers, governing jurisdictions, classification levels, and counterparty entities.
+- **Forensic Science & Chain of Custody:** Evidence acquisition timestamps, laboratory operator IDs, case numbers, and forensic instrument serial numbers.
+- **Agentic AI Governance:** Model version, generation prompt hash, hallucination audit logs, and parent artifact DAG pointers.
+
+Attestation Bundle v3 introduces **Generic Signed Claims** with **Dual-Hash Cryptographic Preimage Binding** and **Multi-Party Countersigning**, preserving 100% backward compatibility with v2 bundles.
+
+---
+
+## 2. Generic Claims Architecture
+
+### 2.1 Arbitrary Datatype Support
+Claims are not restricted to predefined strings. Any valid JSON data structure can be used as a claim key or value:
+- **Primitive types:** Strings, numbers (safe integers only; carry a decimal as a string or a scaled integer), booleans, null.
+- **Structured types:** Arrays, nested objects, associative lookup tables.
+
+### 2.2 Deterministic Canonicalization (RFC 8785 JCS)
+To ensure that claims serialize identically across different programming languages and runtimes (Node.js, Python, Rust, Go, browser extensions):
+1. **Object Key Sorting:** All object keys are sorted lexicographically by UTF-16 code units.
+2. **Whitespace Stripping:** No whitespace is permitted between keys, colons, commas, or values.
+3. **Number Formatting:** Numbers MUST be IEEE 754 integers within -(2^53-1) to 2^53-1, judged by value (draft -03 section 3.3): `1.0` and `1e2` are accepted and written `1` and `100`, `-0` is written `0`. Non-integral numbers (such as `1.5`), values beyond the safe range, `NaN` and `Infinity` are rejected by the TypeScript, Python and Rust engines alike.
+4. **String Escaping:** Characters below `0x20` are escaped using standard escape sequences (`\\n`, `\\r`, `\\t`) or `\\u00xx`.
+5. **Undefined Exclusion:** Undefined object properties are omitted from serialization.
+
+Formally:
+$$\\text{ClaimsHash} = \\text{SHA-256}(\\text{JCS}(\\text{claims}))$$
+
+---
+
+## 3. The 5-Line Signing Preimage Framing
+
+### 3.1 Framing Specification
+The digital signature covers an unambiguous, newline-delimited framing payload that binds both the artifact bytes and the claims:
+
+```text
+moonglade-provenance/v3\n
+scope:<scope-uri>\n
+target-sha256:<64-hex of canonical artifact bytes>\n
+signer:<signer-identity>\n
+claims-sha256:<64-hex of JCS canonical claims map>\n
+```
+
+### 3.2 ABNF Definition
+
+```abnf
+V3-Payload      = "moonglade-provenance/v3" LF
+                  "scope:" Scope-URI LF
+                  "target-sha256:" 64HEXDIG LF
+                  "signer:" Identity-String LF
+                  "claims-sha256:" 64HEXDIG LF
+
+Scope-URI       = 1*(ALPHA / DIGIT / "-" / "_" / "." / "/" / ":")
+Identity-String = 1*(VCHAR)
+64HEXDIG        = 64HEXDIG
+LF              = %x0A
+```
+
+### 3.3 Security Invariants
+1. **Domain Separation:** The header `"moonglade-provenance/v3\n"` guarantees that v3 signatures cannot be replayed or downgraded to v2 or v1 formats.
+2. **Dual-Hash Binding:** The signature cryptographically binds the canonical artifact bytes (`target-sha256`) and the claims payload (`claims-sha256`) into a single atomic assertion. Tampering with either the artifact OR the claims invalidates the signature.
+3. **Control Character Rejection:** Control characters (`0x00` through `0x1F` and `0x7F`) in any field abort signing immediately, preventing delimiter injection attacks.
+
+---
+
+## 4. Sidecar Schema (v3)
+
+```json
+{
+  "standard": "Moonglade Provenance Attestation Bundle v3",
+  "artifact": "bathsheba_twilight_raw.jpg",
+  "claims": {
+    "photographer": "Marc Ottley",
+    "focal_length_mm": 85,
+    "camera_make": "Sony",
+    "camera_model": "ILCE-7RM5",
+    "iso": 100,
+    "aperture": "1.8",
+    "shutter_speed": "1/250",
+    "license": "CC-BY-NC-ND-4.0",
+    "royalty_split": {
+      "photographer_pct": 70,
+      "gallery_fund_pct": 30
+    },
+    "tags": ["bathsheba", "east-coast", "golden-hour", "raw"]
+  },
+  "claims_sha256": "3c89b27e8d1a49f5...",
+  "attestations": [
+    {
+      "method": "moonglade-ed25519-v3",
+      "signer": "marc.ottley@moongladeai.net",
+      "scope": "moonglade:vault:gallery/bathsheba_twilight_raw.jpg",
+      "target_sha256": "9f83a2...",
+      "claims_sha256": "3c89b27e8d1a49f5...",
+      "created": "2026-09-14T14:35:00Z",
+      "git_commit": "c4d2e1f",
+      "signature": "base64-ed25519-sig..."
+    },
+    {
+      "method": "moonglade-ed25519-v3",
+      "signer": "gallery.curator@moongladeai.net",
+      "scope": "moonglade:vault:gallery/bathsheba_twilight_raw.jpg",
+      "target_sha256": "9f83a2...",
+      "claims_sha256": "3c89b27e8d1a49f5...",
+      "created": "2026-09-14T14:40:00Z",
+      "git_commit": "c4d2e1f",
+      "signature": "base64-ed25519-countersig..."
+    },
+    {
+      "method": "rfc3161",
+      "tier": "L1_CRYPTO_PRIMARY",
+      "tsa": "https://freetsa.org/tsr",
+      "tsa_time": "2026-09-14T14:35:03Z",
+      "token_b64": "MIIB..."
+    }
+  ],
+  "sha256_at_last_write": "9f83a2...",
+  "updated": "2026-09-14T14:40:00Z",
+  "status": "canonical"
+}
+```
+
+---
+
+## 5. Multi-Party Countersigning Protocol
+
+In distributed workflows (e.g. Creator to Publisher, Laboratory Analyst to Quality Inspector):
+1. **Primary Seal:** The creator seals the artifact with their private key, attaching the canonical claims.
+2. **Review & Countersign:**
+   - The countersigner reads `<artifact>.provenance.json`.
+   - The engine validates that `target_sha256` matches the artifact bytes and `claims_sha256` matches the JCS-canonicalized claims.
+   - The countersigner executes `countersignDocument()`:
+     $$\\text{Sig}_{\\text{counter}} = \\text{Sign}_{K_{\\text{counter}}}(\\text{V3-Payload})$$
+   - Appends the countersignature to `attestations`.
+3. **Independent Keyring Verification:**
+   - Recipients pass a keyring mapping signer identities to public keys:
+     ```typescript
+     const keyring = {
+       "marc.ottley@moongladeai.net": marcPublicKeyPem,
+       "gallery.curator@moongladeai.net": galleryPublicKeyPem
+     };
+     const result = await ProvenanceEngine.verifyDocument(path, keyring);
+     ```
+   - Every signature in the bundle must verify against its corresponding key. If any key is missing or forged, the verification fails closed.
+
+---
+
+## 6. Threat Model & Verification Guarantees
+
+| Attack Vector | Detection Mechanism | Result |
+| :--- | :--- | :--- |
+| **Artifact Byte Mutation** | Target hash mismatch | `Hash mismatch: Document has been mutated` |
+| **Claims Value Tampering** | Recomputed JCS hash mismatch | `Claims hash mismatch: claims payload has been mutated` |
+| **Claims Substitution** | Preimage `claims-sha256` mismatch | `Signature validation failed` |
+| **Scope Smuggling** | Strict POSIX relative URI binding | `Attestation records a different hash / scope mismatch` |
+| **Signature Downgrade** | Version header framing (`moonglade-provenance/v3`) | Legacy v1/v2 parsers fail closed on version string |
+| **Forged Countersignature** | Keyring verification fails on invalid signature | `Signature validation failed for signer` |
+| **Timestamp Forgery** | RFC 3161 X.509 cert chain and ASN.1 message imprint | `Timestamp token verification failed` |\n

package/TIMESTAMP.md

@@ -0,0 +1,21 @@
+# Timestamp verification in 2.6.0
+
+## Token verification
+
+`verifyTimeStampToken` checks the CMS signature over signed attributes, signed content type, TSTInfo digest, SHA-256 document imprint, one TSA signer, ESS certificate binding, certificate validity at token generation time and critical timestamp-only EKU. If KeyUsage is present it must permit signatures. SHA-256/384/512 CMS digests and RSA PKCS#1 v1.5 or ECDSA signatures are supported. Other algorithms fail closed. Legacy ESSCertID is supported for integrity-only checks; anchored policy requires ESSCertIDv2.
+
+## Trust anchors
+
+Without caller-supplied `trustAnchors`, a token can earn INTEGRITY_ONLY, including self-signed tokens. Supplying CA trustAnchors requires successful PKI.js certificate path validation at the token generation time and yields ANCHORED. An empty anchor list is an error. Sidecar-supplied anchors are ignored. No OCSP/CRL revocation lookup is performed and no revocation assurance is claimed. No public TSA anchor is installed implicitly.
+
+## Acquisition and response checks
+
+`validateTimeStampResp` checks response structure; it does not verify signatures. It parses the actual TSTInfo imprint/nonce rather than searching bytes. verifyTimeStampToken establishes cryptographic integrity and optional trust. probeTsa performs both response/nonce checking and token signature/imprint validation. queryTsa limits responses to 512 KiB and imposes an absolute deadline. Acquisition routing labels L1/L2 on probes describe selected endpoint pools only; returned token results are INTEGRITY_ONLY, never trusted by routing. Network HTTP Date and host-clock fallbacks are unauthenticated observations, not timestamp attestations. No host-time substitute is inserted into a token result.
+
+## Public functions
+
+Public functions: encodeDerLength, encodeDerSequence, decodeDerLength, parsePkiStatus, validateTimeStampResp, verifyTimeStampToken, buildTimeStampReq, extractGenTime, queryTsa, probeTsa, probeNetworkTime and concurrentDegradingTimestamp. EndpointCircuitBreaker and exported endpoint/policy constants provide acquisition scheduling. extractGenTime is a legacy unauthenticated diagnostic parser, never used for a verified timestamp verdict.
+
+## Test coverage
+
+Tests generate ephemeral synthetic CA/TSA keys in memory. No private fixture key or third-party TSA token ships. Live TSA behavior and revocation are outside the hermetic tests. Services are used under their own terms and are not endorsed by this package. Sources: [PKI.js certificate validation](https://pkijs.org/docs/api/classes/CertificateChainValidationEngine/), [RFC 5816](https://www.rfc-editor.org/rfc/rfc5816).

package/dist/artifact-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/artifact-cli.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+const artifactHook_1 = require("./artifactHook");
+const self_test_1 = require("./self-test");
+const badge_1 = require("./badge");
+async function main() {
+    const [, , action, file, dest] = process.argv;
+    if (action === '--help' || action === '-h') {
+        console.log('provenance <verify|badge|observe|seal-provisional|move|test> <file> [dest]. Keys: MOONGLADE_PUBLIC_KEY_PEM / MOONGLADE_PRIVATE_KEY_PEM. Verification root: MOONGLADE_ROOT or current directory.');
+        return;
+    }
+    if (action === '--version') {
+        console.log(require('../package.json').version);
+        return;
+    }
+    if (action === 'verify') {
+        if (!file || !process.env.MOONGLADE_PUBLIC_KEY_PEM)
+            throw new Error('verify requires a file and MOONGLADE_PUBLIC_KEY_PEM');
+        const expectedScope = index_1.ProvenanceEngine.scopeFor(file, process.env.MOONGLADE_ROOT || process.cwd());
+        const requiredSigners = process.env.MOONGLADE_REQUIRED_SIGNERS?.split(',');
+        const result = await index_1.ProvenanceEngine.verifyDocument(file, process.env.MOONGLADE_PUBLIC_KEY_PEM, { expectedScope, requiredSigners });
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.verified)
+            process.exitCode = 1;
+        return;
+    }
+    if (action === 'test' || action === 'self-test') {
+        const isJson = process.argv.includes('--json');
+        const report = await (0, self_test_1.runSelfTests)();
+        if (isJson) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            (0, self_test_1.printSelfTestReport)(report);
+        }
+        if (!report.passed)
+            process.exitCode = 1;
+        return;
+    }
+    if (action === 'badge') {
+        if (!file) {
+            console.error('usage: provenance badge <file> [--format=text|markdown|json|shields] [--short]');
+            process.exitCode = 2;
+            return;
+        }
+        const isJson = process.argv.includes('--json') || process.argv.includes('--format=json');
+        const isText = process.argv.includes('--format=text');
+        const isShields = process.argv.includes('--format=shields') || process.argv.includes('--format=shields-url');
+        const isHtml = process.argv.includes('--format=html') || process.argv.includes('--html');
+        const isColor = process.argv.includes('--color') || process.argv.includes('-c');
+        const isShort = process.argv.includes('--short');
+        const badgeInfo = await (0, badge_1.getArtifactBadge)(file, {
+            style: isShort ? 'short' : 'detailed',
+            color: isColor ? 'ansi' : false,
+            publicKeyPem: process.env.MOONGLADE_PUBLIC_KEY_PEM,
+            requiredScope: process.env.MOONGLADE_PUBLIC_KEY_PEM ? index_1.ProvenanceEngine.scopeFor(file, process.env.MOONGLADE_ROOT || process.cwd()) : undefined
+        });
+        if (isJson) {
+            console.log(JSON.stringify(badgeInfo, null, 2));
+        }
+        else if (isHtml) {
+            console.log(badgeInfo.html ?? badgeInfo.badgeText);
+        }
+        else if (isShields) {
+            console.log(badgeInfo.shieldsUrl);
+        }
+        else if (isText) {
+            console.log(isColor ? (badgeInfo.ansiText ?? badgeInfo.badgeText) : badgeInfo.badgeText);
+        }
+        else {
+            console.log(isColor ? `${badgeInfo.markdown.replace(badgeInfo.badgeText, badgeInfo.ansiText ?? badgeInfo.badgeText)}` : badgeInfo.markdown);
+        }
+        if (badgeInfo.status === 'MUTATED' || badgeInfo.status === 'INVALID_SIGNATURE' || badgeInfo.status === 'NOT_FOUND') {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (!action || !file || !['observe', 'seal-provisional', 'move'].includes(action)) {
+        console.error('usage: provenance <observe|seal-provisional|move|test|badge> <file> [dest]');
+        process.exitCode = 2;
+        return;
+    }
+    if (action === 'move') {
+        if (!dest) {
+            console.error('usage: provenance-artifact move <source> <dest>');
+            process.exitCode = 2;
+            return;
+        }
+        const result = await (0, artifactHook_1.moveArtifactWithAttestation)(file, dest);
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const common = {
+        vaultRoot: process.cwd(),
+        signerIdentity: process.env.MOONGLADE_SIGNER,
+        generator: {
+            agent: process.env.MOONGLADE_AGENT ?? 'unknown',
+            model: process.env.MOONGLADE_MODEL
+        }
+    };
+    const result = await (0, artifactHook_1.processArtifact)(file, { ...common, action: action, privateKeyPem: process.env.MOONGLADE_PRIVATE_KEY_PEM });
+    if (result.skipped)
+        process.exitCode = 1;
+    console.log(JSON.stringify(result, null, 2));
+}
+main().catch(error => { console.error(error.message); process.exitCode = 1; });

package/dist/artifactEnvelope.d.ts

@@ -0,0 +1,38 @@
+export declare const ARTIFACT_ENVELOPE_FORMAT = "moonglade-artifact-envelope-v1";
+export type ArtifactType = 'markdown' | 'image' | '3d-scene' | 'memory' | 'model-output' | 'release' | 'other';
+export type ArtifactLifecycle = 'unverified' | 'observed' | 'signed' | 'published' | 'revoked';
+export interface ArtifactEvidence {
+    integrity: 'unknown' | 'valid' | 'failed';
+    signature: 'none' | 'provisional' | 'valid' | 'failed';
+    timestamp: 'none' | 'indeterminate' | 'valid' | 'failed';
+    scope: 'unknown' | 'valid' | 'failed';
+}
+export interface ArtifactEnvelope {
+    format: typeof ARTIFACT_ENVELOPE_FORMAT;
+    artifact_id: string;
+    artifact_type: ArtifactType;
+    canonical_bytes: string;
+    source_uri?: string;
+    scope?: string;
+    created_at: string;
+    parents: string[];
+    attestations: Array<{
+        method: string;
+        signer?: string;
+        fingerprint?: string;
+        status?: string;
+        signature?: string;
+    }>;
+    status: ArtifactLifecycle;
+    evidence: ArtifactEvidence;
+    generator?: {
+        agent?: string;
+        model?: string;
+        session?: string;
+    };
+}
+export declare function artifactId(canonicalBytes: Buffer): string;
+export declare function createArtifactEnvelope(input: Omit<ArtifactEnvelope, 'format' | 'artifact_id'> & {
+    bytes: Buffer;
+}): ArtifactEnvelope;
+export declare function validateArtifactEnvelope(value: unknown): value is ArtifactEnvelope;

package/dist/artifactEnvelope.js

@@ -0,0 +1,61 @@
+"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.ARTIFACT_ENVELOPE_FORMAT = void 0;
+exports.artifactId = artifactId;
+exports.createArtifactEnvelope = createArtifactEnvelope;
+exports.validateArtifactEnvelope = validateArtifactEnvelope;
+const crypto = __importStar(require("crypto"));
+exports.ARTIFACT_ENVELOPE_FORMAT = 'moonglade-artifact-envelope-v1';
+function artifactId(canonicalBytes) {
+    return `sha256:${crypto.createHash('sha256').update(canonicalBytes).digest('hex')}`;
+}
+function createArtifactEnvelope(input) {
+    const { bytes, ...rest } = input;
+    return { format: exports.ARTIFACT_ENVELOPE_FORMAT, artifact_id: artifactId(bytes), ...rest };
+}
+function validateArtifactEnvelope(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return v.format === exports.ARTIFACT_ENVELOPE_FORMAT && typeof v.artifact_id === 'string' && /^sha256:[0-9a-f]{64}$/.test(v.artifact_id)
+        && typeof v.canonical_bytes === 'string' && typeof v.created_at === 'string'
+        && Array.isArray(v.parents) && Array.isArray(v.attestations)
+        && ['unverified', 'observed', 'signed', 'published', 'revoked'].includes(v.status ?? '')
+        && !!v.evidence && ['unknown', 'valid', 'failed'].includes(v.evidence.integrity ?? '')
+        && ['none', 'provisional', 'valid', 'failed'].includes(v.evidence.signature ?? '')
+        && ['none', 'indeterminate', 'valid', 'failed'].includes(v.evidence.timestamp ?? '')
+        && ['unknown', 'valid', 'failed'].includes(v.evidence.scope ?? '');
+}

package/dist/artifactHook.d.ts

@@ -0,0 +1,30 @@
+import { ProvenanceSidecar } from './index';
+export type ArtifactAction = 'observe' | 'seal-provisional';
+export interface ArtifactHookOptions {
+    action?: ArtifactAction;
+    vaultRoot?: string;
+    privateKeyPem?: string;
+    signerIdentity?: string;
+    generator?: {
+        agent: string;
+        model?: string;
+        session?: string;
+    };
+    parents?: string[];
+    gitCommit?: string;
+}
+export interface ArtifactHookResult {
+    path: string;
+    action: ArtifactAction;
+    skipped: boolean;
+    reason?: string;
+    sidecar?: ProvenanceSidecar;
+}
+export interface ArtifactMoveResult {
+    artifactPath: string;
+    attestationPath: string;
+    attestationMoved: boolean;
+}
+export declare function processArtifact(filePath: string, opts?: ArtifactHookOptions): Promise<ArtifactHookResult>;
+/** Move an artifact and its adjacent attestation as one atomic logical unit. */
+export declare function moveArtifactWithAttestation(sourcePath: string, destinationPath: string): Promise<ArtifactMoveResult>;