@primust/verifier 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,13 +1,335 @@
-export { verify } from './verifier';
-export type { UpstreamRootResolver, VerifyOptions, VerificationResult, RekorStatus, } from './types';
-export { generateVerifyHtml } from './verify-html-template';
-export { seedKeyCache } from './key-cache';
-export { REASONS, buildMerkleRoot, canonicalJson, canonicalJsonString, canonicalNumber, verifyBoundedTrace, } from './bounded-trace';
-export type { BoundedTraceResult, ReasonCode } from './bounded-trace';
-export { SCOPED_REASONS, verifyScopedCertificates, } from './scoped';
-export type { ScopedCertificatesResult, ScopedReason } from './scoped';
-export { createUpstreamRootResolver, closeResolver, } from './upstream_resolver';
-export type { UpstreamResolverOptions } from './upstream_resolver';
-export { ENVELOPE_VERSION, ALLOWED_KINDS, ALLOWED_TRUST_EDGES, PROOF_TIER_HIERARCHY, canonicalJson as canonicalJsonV29, canonicalHash as canonicalHashV29, validateEnvelopeShape, reproduceAggregations, validateAggregations, reproduceTierCeiling, validateRecordsAgainstHarness, validateRuntimeBindingHash, reproduceManifestCanonicalHash, validateManifestCanonicalHash, verifyV29, } from './v29-envelope';
-export type { V29VerifyResult, ProofTier } from './v29-envelope';
-//# sourceMappingURL=index.d.ts.map
+import { ProofLevel, ProofDistribution, Coverage } from '@primust/artifact-core';
+
+/**
+ * primust-verify — Types for offline verifier.
+ */
+
+type RekorStatus = 'active' | 'not_found' | 'revoked' | 'unavailable' | 'skipped';
+/**
+ * Synchronous resolver that returns the parent VPEC's
+ * `commitment_root_poseidon2` (canonical "poseidon2:<hex>" form) for a
+ * given upstream VPEC envelope ID, or null if the parent's root is not
+ * locally available.
+ *
+ * Implementations typically wrap `SqliteStore.getUpstreamVpecRoot(vpecId)`.
+ * The verifier core deliberately avoids a SqliteStore dependency to
+ * preserve its zero-runtime-deps invariant — callers inject this resolver
+ * when they have local store context (CLI / dashboard verifier paths).
+ *
+ * Returning null is offline-tolerant: the verifier surfaces a warning
+ * (`upstream_vpec_proof_no_anchor_root_in_artifact`) rather than a hard
+ * mismatch, so cross-org chains still verify at boundaries.
+ */
+type UpstreamRootResolver = (vpecId: string) => string | null | undefined;
+interface VerifyOptions {
+    /** Reject test_mode: true artifacts. */
+    production?: boolean;
+    /** Skip Rekor check — fully offline mode. */
+    skip_network?: boolean;
+    /** Path to custom public key PEM (for enterprise self-hosting). */
+    trust_root?: string;
+}
+interface VerificationResult {
+    vpec_id: string;
+    valid: boolean;
+    schema_version: string;
+    proof_level: ProofLevel | string;
+    proof_distribution: ProofDistribution | Record<string, unknown>;
+    org_id: string;
+    workflow_id: string;
+    process_context_hash: string | null;
+    partial: boolean;
+    test_mode: boolean;
+    signer_id: string;
+    kid: string;
+    signed_at: string;
+    timestamp_anchor_valid: boolean | null;
+    rekor_status: RekorStatus;
+    zk_proof_valid: boolean | null;
+    commitment_root_valid: boolean | null;
+    manifest_hashes: Record<string, string>;
+    gaps: Array<{
+        gap_id: string;
+        gap_type: string;
+        severity: string;
+    }>;
+    coverage: Coverage | Record<string, unknown>;
+    violations_present: boolean;
+    violation_count: number;
+    errors: string[];
+    warnings: string[];
+}
+
+/**
+ * primust-verify — Offline VPEC artifact verifier.
+ *
+ * ZERO runtime dependencies on Primust infrastructure after initial
+ * public key fetch. Must verify a VPEC produced today in 10 years.
+ *
+ * Verification steps (in order):
+ * 1. Schema validation
+ * 2. SHA-256 integrity + Ed25519 signature (combined)
+ * 3. Kid resolution
+ * 4. Signer status check (Rekor — stubbed in v1)
+ * 5. RFC 3161 timestamp verification (stubbed in v1)
+ * 6. Proof level integrity
+ * 7. Manifest hash audit
+ * 8. ZK proof verification (stubbed in v1)
+ * 9. test_mode check
+ */
+
+/**
+ * Verify a VPEC artifact.
+ *
+ * @param artifact               - Parsed artifact JSON (Record<string, unknown>)
+ * @param options                - Verification options
+ * @param upstreamRootResolver   - Optional synchronous resolver returning
+ *   the PARENT VPEC's `commitment_root_poseidon2` for a given upstream
+ *   VPEC envelope ID. When provided, governance_upstream_vpec_inclusion
+ *   proofs are anchored to `Poseidon2(lineage_commitment(child_run_id,
+ *   upstream_vpec_ids), parentRoot)` — the same reduction
+ *   `PolicySnapshotService.openRun` performs at issuance. When omitted,
+ *   the verifier falls back to anchoring against the artifact's own
+ *   `commitment_root_poseidon2` (legacy behavior — preserves backward
+ *   compat for callers that lack upstream-store context).
+ * @returns VerificationResult with errors/warnings
+ */
+declare function verify(artifact: Record<string, unknown>, options?: VerifyOptions, upstreamRootResolver?: UpstreamRootResolver): Promise<VerificationResult>;
+
+/**
+ * verify.html template generator for Evidence Pack output.
+ *
+ * Generates a self-contained HTML file that:
+ * 1. Embeds the Ed25519 public key
+ * 2. Pre-loads the Evidence Pack summary
+ * 3. Verifies using WebCrypto API on page load
+ * 4. Works completely offline
+ * 5. Shows chain of VPECs with verification status
+ */
+interface VerifyHtmlOptions {
+    publicKeyB64: string;
+    packData: {
+        pack_id: string;
+        org_id: string;
+        period_start: string;
+        period_end: string;
+        vpec_count: number;
+        vpecs: Array<{
+            vpec_id: string;
+            proof_level_floor: string;
+            provable_surface: number;
+            gap_count: number;
+            issued_at: string;
+            environment: string;
+            signature: string;
+            signed_payload: string;
+        }>;
+        provable_surface_summary: {
+            mathematical: number;
+            execution: number;
+            witnessed: number;
+            attestation: number;
+        };
+        upstream_vpecs?: Array<{
+            vpec_id: string;
+            org_id: string;
+            proof_level_floor: string;
+            signature: string;
+            signed_payload: string;
+        }>;
+    };
+}
+declare function generateVerifyHtml(options: VerifyHtmlOptions): string;
+
+/**
+ * Public key cache for VPEC signature verification.
+ *
+ * Fetches public keys from trust anchor URLs and caches by key ID.
+ * Supports pinned trust roots for offline/air-gapped verification.
+ *
+ * SI-3: untrusted public_key_url values from the artifact are NOT honored.
+ * Without a caller-supplied trust_root, the URL host must be on the
+ * built-in allowlist. Otherwise an attacker can mint a VPEC pointing at
+ * their own key-server and `verify()` would return valid.
+ */
+/**
+ * Resolve a public key by key ID.
+ *
+ * @param kid - Key identifier from VPEC signature field
+ * @param publicKeyUrl - URL to fetch the PEM/base64url key
+ * @param trustRoot - Optional local PEM file path or content for offline mode
+ */
+/**
+ * Pre-seed the in-memory key cache. Used by evidence-pack assembler
+ * to inject the signer's public key before verification runs.
+ */
+declare function seedKeyCache(kid: string, publicKey: string): void;
+
+/**
+ * Reference TypeScript interpreter for bounded_trace_v1 verification.
+ *
+ * This is the canonical second-opinion verifier described in PRIMUST_V27 §20.2,
+ * ported from verifier-py/src/primust_verify/bounded_trace.py. It is
+ * intentionally small and obviously-correct: consumes a BoundedTraceV1 payload
+ * plus a ProfileRecord and produces one of the §16.3 canonical downgrade
+ * reason codes (or "ok" on success).
+ *
+ * Crypto used: SHA-256 with RFC 6962-style domain-separated leaves (0x00)
+ * and nodes (0x01). Canonical JSON follows RFC 8785 + ECMAScript 7.1.12.1
+ * number serialization for cross-language parity.
+ *
+ * SI-3 (VPEC verifiability): this module's output MUST match the Python
+ * reference byte-for-byte across the shared conformance fixture corpus at
+ * packages/verifier-py/tests/fixtures/bounded_trace_v1/. The conformance
+ * runner in scripts/lane_a_conformance.* enforces this.
+ *
+ * Zero runtime dependencies besides node:crypto.
+ */
+declare function canonicalNumber(x: number): string;
+/**
+ * Canonical JSON serialization:
+ *   - object keys sorted lexicographically
+ *   - UTF-8
+ *   - separators ",":":",  no whitespace
+ *   - numbers via canonicalNumber
+ *   - strings via JSON.stringify (same escape rules as Python json with ensure_ascii=False)
+ */
+declare function canonicalJson$1(obj: unknown): Uint8Array;
+declare function canonicalJsonString(obj: unknown): string;
+declare function buildMerkleRoot(leaves: Uint8Array[]): string;
+interface BoundedTraceResult {
+    valid: boolean;
+    proof_level: "operator_bound" | "execution";
+    reason: string;
+    disclosed_operator_count: number;
+    verified_merkle_paths: number;
+    details: Record<string, unknown>;
+}
+declare const REASONS: readonly ["profile_not_found", "profile_signature_invalid", "profile_not_empirical", "profile_expired", "profile_revoked", "profile_no_freshness_window", "profile_trace_mismatch", "runtime_not_supported", "trace_schema_unknown", "missing_merkle_root", "merkle_inclusion_failed", "threshold_violation", "runtime_section_missing", "retrieval_section_missing", "closed_api_pre_cohort", "closed_api_pre_promote", "closed_api_v2_promoted", "profile_deprecated", "unknown_lifecycle_state"];
+type ReasonCode = (typeof REASONS)[number] | "thresholds_verified";
+declare function verifyBoundedTrace(trace: Record<string, unknown>, profile: Record<string, unknown>, options?: {
+    now?: Date;
+}): BoundedTraceResult;
+
+/**
+ * Reference TypeScript verifier for the `scoped_certificates` VPEC section.
+ *
+ * Ported from verifier-py/src/primust_verify/scoped.py. Validates the
+ * top-level `scoped_certificates` array + matching
+ * `scoped_certificates_commitment` emitted by the SDK's
+ * `primust.scoped.bundle` module (SCOPED_CERT_SPEC_v27 §14).
+ *
+ * Trust-chain scope:
+ *   1. Every entry carries a known `certificate_type` discriminator.
+ *   2. Every entry has the required structural fields for its type.
+ *   3. The array is in canonical order: lexicographic by
+ *      (certificate_type, canonical_sha256(payload)).
+ *   4. The declared commitment byte-matches the recomputed Merkle root
+ *      over the ordered canonical-JSON leaves. Empty bundle uses the
+ *      well-known `sha256(canonical({scoped_certificates: []}))`.
+ *
+ * SI-3 (VPEC verifiability): this module's output MUST agree with the
+ * Python reference (`primust_verify.scoped`) byte-for-byte across the
+ * shared fixture corpus at
+ * packages/verifier-py/tests/fixtures/scoped_v1/. The conformance runner
+ * in scripts/scoped_conformance.py gates that in CI.
+ */
+
+declare const SCOPED_REASONS: readonly ["ok", "missing_section", "malformed_section", "missing_commitment", "malformed_commitment", "missing_discriminator", "unknown_certificate_type", "schema_validation_failed", "ordering_violation", "commitment_mismatch"];
+type ScopedReason = (typeof SCOPED_REASONS)[number];
+interface ScopedCertificatesResult {
+    valid: boolean;
+    reason: ScopedReason;
+    entry_count: number;
+    details: Record<string, unknown>;
+}
+declare function verifyScopedCertificates(vpecLike: Record<string, unknown>): ScopedCertificatesResult;
+
+interface UpstreamResolverOptions {
+    /**
+     * Optional path to the runtime-core SqliteStore database. When provided,
+     * the resolver opens a read-only handle on first use and queries
+     * `vpec_commitment_roots` for `kind='vpec'` first, then `kind='run'`
+     * (matches `SqliteStore.getUpstreamVpecRoot`). Resolver close is the
+     * caller's responsibility — see `closeResolver`.
+     */
+    dbPath?: string;
+    /**
+     * Optional in-memory map of `vpec_id` → `'poseidon2:<64-hex>'`. Useful
+     * for tests, deterministic offline verification of a bundle, and air-
+     * gapped flows that inline the upstream commitment alongside the VPEC.
+     */
+    envelopes?: Map<string, string>;
+}
+
+/**
+ * Build a synchronous resolver that maps a vpec_id to its cached
+ * `commitment_root_poseidon2` value, or null if no row is cached.
+ *
+ * Lookup order: envelopes Map → SqliteStore vpec row → SqliteStore run
+ * row. This mirrors `SqliteStore.getUpstreamVpecRoot` so SDK and verifier
+ * never disagree about which root applies to a given lineage edge.
+ */
+declare function createUpstreamRootResolver(opts: UpstreamResolverOptions): UpstreamRootResolver;
+/**
+ * Best-effort close hook for resolvers that opened a SQLite handle.
+ *
+ * The resolver is closure-scoped, so we expose a static helper instead
+ * of returning an object. Callers may also let the handle be GC'd —
+ * better-sqlite3 closes on finalizer — but explicit close is safer in
+ * long-running CLI batches.
+ */
+declare function closeResolver(resolver: UpstreamRootResolver): void;
+
+/**
+ * v29 ProofCheck envelope + manifest + runtime-binding conformance.
+ *
+ * Mirror of packages/verifier-py/src/primust_verify/v29_envelope.py.
+ * The Py↔TS parity contract: canonicalJson(x) MUST produce byte-identical
+ * output for identical inputs across both languages, and every reproduction
+ * function MUST return the same value.
+ *
+ * Per docs/v29-draft/PROOFCHECK_ENVELOPE_SPEC_v0_1.md, AGENT_MANIFEST_SPEC,
+ * HARNESS_MANIFEST_SPEC, RUNTIME_BINDING_SPEC.
+ *
+ * Pure functions only. No DB, no network, no KMS.
+ */
+/**
+ * Resolve a key id to its raw 32-byte Ed25519 public key. Sync to keep
+ * the verifier pure / pluggable; relying parties typically wire this to
+ * an embedded trust root (e.g. a JSON map of pinned kids).
+ */
+type PubkeyResolver = (kid: string) => Uint8Array;
+declare const ENVELOPE_VERSION = "v0.1";
+declare const ALLOWED_KINDS: Set<string>;
+declare const ALLOWED_TRUST_EDGES: Set<string>;
+declare const PROOF_TIER_HIERARCHY: readonly ["attestation", "witnessed", "execution", "operator_bound", "verifiable_inference", "mathematical"];
+type ProofTier = (typeof PROOF_TIER_HIERARCHY)[number];
+interface V29VerifyResult {
+    ok: boolean;
+    reasonCode: string | null;
+    detail?: string;
+}
+declare function canonicalJson(value: unknown): string;
+declare function canonicalHash(value: unknown): string;
+declare function validateEnvelopeShape(envelope: unknown): V29VerifyResult;
+declare function reproduceAggregations(records: Array<Record<string, unknown>>): Record<string, unknown>;
+declare function validateAggregations(envelope: Record<string, unknown>): V29VerifyResult;
+declare function reproduceTierCeiling(harnessManifest: Record<string, unknown>, surface: string, tierClaimed: string): {
+    effective_tier: string;
+    tier_ceiling_applied: string | null;
+};
+declare function validateRecordsAgainstHarness(records: Array<Record<string, unknown>>, harnessManifest: Record<string, unknown> | null): V29VerifyResult;
+declare function validateRuntimeBindingHash(binding: Record<string, unknown>): V29VerifyResult;
+declare function reproduceManifestCanonicalHash(manifest: Record<string, unknown>, manifestKind: "agent" | "harness"): string;
+declare function validateManifestCanonicalHash(manifest: Record<string, unknown>, manifestKind: "agent" | "harness"): V29VerifyResult;
+declare function verifyV29(opts: {
+    envelope: Record<string, unknown>;
+    runtimeBinding?: Record<string, unknown>;
+    agentManifest?: Record<string, unknown>;
+    harnessManifest?: Record<string, unknown>;
+    pubkeyResolver?: PubkeyResolver | null;
+    requireSignatures?: boolean;
+}): V29VerifyResult;
+
+export { ALLOWED_KINDS, ALLOWED_TRUST_EDGES, type BoundedTraceResult, ENVELOPE_VERSION, PROOF_TIER_HIERARCHY, type ProofTier, REASONS, type ReasonCode, type RekorStatus, SCOPED_REASONS, type ScopedCertificatesResult, type ScopedReason, type UpstreamResolverOptions, type UpstreamRootResolver, type V29VerifyResult, type VerificationResult, type VerifyOptions, buildMerkleRoot, canonicalHash as canonicalHashV29, canonicalJson$1 as canonicalJson, canonicalJsonString, canonicalJson as canonicalJsonV29, canonicalNumber, closeResolver, createUpstreamRootResolver, generateVerifyHtml, reproduceAggregations, reproduceManifestCanonicalHash, reproduceTierCeiling, seedKeyCache, validateAggregations, validateEnvelopeShape, validateManifestCanonicalHash, validateRecordsAgainstHarness, validateRuntimeBindingHash, verify, verifyBoundedTrace, verifyScopedCertificates, verifyV29 };