@primust/verifier 1.0.0

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * primust-verify — Types for offline verifier.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/upstream_resolver.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Default upstream-VPEC root resolver for the offline verifier (Follow-7).
+ *
+ * The verifier's parent-root resolution path (Follow-6) accepts a
+ * synchronous `(vpecId) => string | null` resolver so verification can
+ * stay single-threaded and offline. This module provides two
+ * compositions:
+ *
+ *  - **Envelopes Map** — caller supplies a Map<vpec_id, root> (typical
+ *    test path or in-memory verification of a known bundle).
+ *  - **SqliteStore lookup** — caller supplies `dbPath` and the resolver
+ *    reads `vpec_commitment_roots` directly via better-sqlite3, mirroring
+ *    `SqliteStore.getUpstreamVpecRoot` semantics (vpec row first, fall
+ *    through to run row).
+ *
+ * Both paths are checked in order (envelopes first). Returning `null`
+ * signals "no upstream root cached" — the verifier then falls back to
+ * the generic governance witness rather than fabricating a vacuous root.
+ *
+ * SI-1: this resolver only reads the public `commitment_root_poseidon2`
+ * value. It never reaches into raw envelope content or check records.
+ */
+export declare function __resetSqliteMissingWarnedForTesting(): void;
+export 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>;
+}
+import type { UpstreamRootResolver } from './types';
+export type { UpstreamRootResolver };
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare function closeResolver(resolver: UpstreamRootResolver): void;
+//# sourceMappingURL=upstream_resolver.d.ts.map

package/dist/upstream_resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream_resolver.d.ts","sourceRoot":"","sources":["../src/upstream_resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AASH,wBAAgB,oCAAoC,IAAI,IAAI,CAE3D;AAcD,MAAM,WAAW,uBAAuB;IACtC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAID,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAkDrC;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,uBAAuB,GAC5B,oBAAoB,CAkCtB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAMlE"}

package/dist/upstream_resolver.js

@@ -0,0 +1,126 @@
+/**
+ * Default upstream-VPEC root resolver for the offline verifier (Follow-7).
+ *
+ * The verifier's parent-root resolution path (Follow-6) accepts a
+ * synchronous `(vpecId) => string | null` resolver so verification can
+ * stay single-threaded and offline. This module provides two
+ * compositions:
+ *
+ *  - **Envelopes Map** — caller supplies a Map<vpec_id, root> (typical
+ *    test path or in-memory verification of a known bundle).
+ *  - **SqliteStore lookup** — caller supplies `dbPath` and the resolver
+ *    reads `vpec_commitment_roots` directly via better-sqlite3, mirroring
+ *    `SqliteStore.getUpstreamVpecRoot` semantics (vpec row first, fall
+ *    through to run row).
+ *
+ * Both paths are checked in order (envelopes first). Returning `null`
+ * signals "no upstream root cached" — the verifier then falls back to
+ * the generic governance witness rather than fabricating a vacuous root.
+ *
+ * SI-1: this resolver only reads the public `commitment_root_poseidon2`
+ * value. It never reaches into raw envelope content or check records.
+ */
+import { createRequire } from 'node:module';
+// Module-level guard: warn at most once per process when the optional
+// better-sqlite3 peer dep is missing, then fail-open by returning a
+// resolver that yields `null` for every vpec id. Exported (with `__`
+// prefix) only so tests can reset between cases.
+let _sqliteMissingWarned = false;
+export function __resetSqliteMissingWarnedForTesting() {
+    _sqliteMissingWarned = false;
+}
+function warnSqliteMissingOnce(err) {
+    if (_sqliteMissingWarned)
+        return;
+    _sqliteMissingWarned = true;
+    // eslint-disable-next-line no-console
+    console.warn('@primust/verifier: better-sqlite3 not installed in this environment; ' +
+        'upstream root resolver via SqliteStore is disabled and resolution ' +
+        'falls back to the envelopes Map (or null when none provided). ' +
+        'Install with: npm install better-sqlite3', err instanceof Error ? err.message : err);
+}
+function openDbHandle(dbPath) {
+    // Dynamic require so verifier package doesn't take a static dep on
+    // better-sqlite3 — declared as an OPTIONAL peerDependency. If the dep
+    // is missing we emit a single explicit warning per process and the
+    // resolver fail-opens (returns null for every vpec id).
+    let Database;
+    try {
+        const require_ = createRequire(import.meta.url);
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        Database = require_('better-sqlite3');
+    }
+    catch (err) {
+        warnSqliteMissingOnce(err);
+        return null;
+    }
+    try {
+        const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+        return {
+            vpecStmt: db.prepare(`SELECT root FROM vpec_commitment_roots WHERE key = ? AND kind = 'vpec'`),
+            runStmt: db.prepare(`SELECT root FROM vpec_commitment_roots WHERE key = ? AND kind = 'run'`),
+            close: () => db.close(),
+        };
+    }
+    catch (err) {
+        console.warn('[primust-verify] upstream resolver: cannot open SQLite store at', dbPath, err);
+        return null;
+    }
+}
+/**
+ * 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.
+ */
+export function createUpstreamRootResolver(opts) {
+    const envelopes = opts.envelopes ?? null;
+    let dbHandle;
+    // dbHandle is `undefined` until first use, `null` after a failed open.
+    return function resolveUpstreamRoot(vpecId) {
+        if (!vpecId)
+            return null;
+        if (envelopes) {
+            const fromMap = envelopes.get(vpecId);
+            if (fromMap)
+                return fromMap;
+        }
+        if (opts.dbPath) {
+            if (dbHandle === undefined) {
+                dbHandle = openDbHandle(opts.dbPath);
+            }
+            if (dbHandle) {
+                try {
+                    const vpecRow = dbHandle.vpecStmt.get(vpecId);
+                    if (vpecRow?.root)
+                        return vpecRow.root;
+                    const runRow = dbHandle.runStmt.get(vpecId);
+                    if (runRow?.root)
+                        return runRow.root;
+                }
+                catch (err) {
+                    console.warn(`[primust-verify] upstream resolver: query failed for ${vpecId}:`, err);
+                }
+            }
+        }
+        return null;
+    };
+}
+/**
+ * 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.
+ */
+export function closeResolver(resolver) {
+    // The handle is encapsulated in the closure; we intentionally do
+    // nothing here in v1. The hook exists so the public surface is stable
+    // when we move to a returned `{ resolver, close }` shape. See
+    // CIRCUITS_TODO Follow-7 for the rollout plan.
+    void resolver;
+}
+//# sourceMappingURL=upstream_resolver.js.map

package/dist/upstream_resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream_resolver.js","sourceRoot":"","sources":["../src/upstream_resolver.ts"],"names":[],"mappings":"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"}

package/dist/v29-envelope.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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).
+ */
+export type PubkeyResolver = (kid: string) => Uint8Array;
+export declare const ENVELOPE_VERSION = "v0.1";
+export declare const ALLOWED_KINDS: Set<string>;
+export declare const ALLOWED_TRUST_EDGES: Set<string>;
+export declare const PROOF_TIER_HIERARCHY: readonly ["attestation", "witnessed", "execution", "operator_bound", "verifiable_inference", "mathematical"];
+export type ProofTier = (typeof PROOF_TIER_HIERARCHY)[number];
+export interface V29VerifyResult {
+    ok: boolean;
+    reasonCode: string | null;
+    detail?: string;
+}
+export declare const v29Pass: () => V29VerifyResult;
+export declare const v29Fail: (code: string, detail?: string) => V29VerifyResult;
+export declare function canonicalJson(value: unknown): string;
+export declare function canonicalHash(value: unknown): string;
+export declare function validateEnvelopeShape(envelope: unknown): V29VerifyResult;
+export declare function reproduceAggregations(records: Array<Record<string, unknown>>): Record<string, unknown>;
+export declare function validateAggregations(envelope: Record<string, unknown>): V29VerifyResult;
+export declare function reproduceTierCeiling(harnessManifest: Record<string, unknown>, surface: string, tierClaimed: string): {
+    effective_tier: string;
+    tier_ceiling_applied: string | null;
+};
+export declare function validateRecordsAgainstHarness(records: Array<Record<string, unknown>>, harnessManifest: Record<string, unknown> | null): V29VerifyResult;
+export declare function validateRuntimeBindingHash(binding: Record<string, unknown>): V29VerifyResult;
+export declare function reproduceManifestCanonicalHash(manifest: Record<string, unknown>, manifestKind: "agent" | "harness"): string;
+export declare function validateManifestCanonicalHash(manifest: Record<string, unknown>, manifestKind: "agent" | "harness"): V29VerifyResult;
+export declare function validateRuntimeBindingSignature(binding: Record<string, unknown>, pubkeyResolver: PubkeyResolver | null): V29VerifyResult;
+export declare function validateManifestSignature(manifest: Record<string, unknown>, manifestKind: "agent" | "harness", pubkeyResolver: PubkeyResolver | null): V29VerifyResult;
+export 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;
+//# sourceMappingURL=v29-envelope.d.ts.map

package/dist/v29-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v29-envelope.d.ts","sourceRoot":"","sources":["../src/v29-envelope.ts"],"names":[],"mappings":"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"}