@moonglade/provenance 0.0.0-stage → 2.6.0

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';