@passportsign/core 0.1.0

package/src/statement.ts

@@ -0,0 +1,119 @@
+/**
+ * in-toto Statement v1 builder for passportsign attestations.
+ *
+ * The statement's canonical JCS bytes are what gets hashed into the
+ * Rekor entry, so this module is the authoritative source for the
+ * statement shape. Test vectors in
+ * `test/fixtures/canonical-vectors.json` pin the canonicalization
+ * output for representative statements built here.
+ */
+
+export const IN_TOTO_STATEMENT_TYPE = 'https://in-toto.io/Statement/v1' as const;
+export const PASSPORTSIGN_PREDICATE_TYPE =
+  'https://passportsign.dev/personhood/v1' as const;
+
+export type DisclosureLevel = 'personhood' | 'personhood+country';
+
+export interface PassportsignPredicate {
+  /** From the zkPassport SDK — deterministic for (passport, domain, scope). */
+  unique_identifier: string;
+  /** ICAO 3-letter code if disclosed, else null. Pass through as-returned by SDK. */
+  issuing_country: string | null;
+  /** Derived from issuing_country (null → personhood, set → personhood+country). */
+  disclosure_level: DisclosureLevel;
+  /** Lowercase hex SHA-256 of the proof blob bytes. */
+  proof_blob_sha256: string;
+  /** Public gist URL captured at binding time. */
+  gist_url: string;
+  /** Lowercase hex SHA-256 of the gist's content bytes. Also the subject digest. */
+  gist_content_sha256: string;
+  /** zkPassport scope (e.g. "passportsign.dev:nationality-disclose:1"). */
+  scope: string;
+  /** Version string from the zkPassport SDK that produced the proof. */
+  zkpassport_sdk_version: string;
+}
+
+export interface PassportsignStatement {
+  _type: typeof IN_TOTO_STATEMENT_TYPE;
+  subject: Array<{
+    name: string;
+    digest: { sha256: string };
+  }>;
+  predicateType: typeof PASSPORTSIGN_PREDICATE_TYPE;
+  predicate: PassportsignPredicate;
+}
+
+export interface BuildStatementInput {
+  github_username: string;
+  unique_identifier: string;
+  issuing_country: string | null;
+  proof_blob_sha256: string;
+  gist_url: string;
+  gist_content_sha256: string;
+  scope: string;
+  zkpassport_sdk_version: string;
+}
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+function assertSha256Hex(value: string, field: string): void {
+  if (!SHA256_HEX.test(value)) {
+    throw new TypeError(
+      `${field}: expected lowercase 64-char hex SHA-256, got ${JSON.stringify(value)}`,
+    );
+  }
+}
+
+function assertNonEmpty(value: string, field: string): void {
+  if (value.length === 0) {
+    throw new TypeError(`${field}: must be non-empty`);
+  }
+}
+
+/**
+ * Build a passportsign in-toto Statement v1.
+ *
+ * Invariants enforced here (so the canonical bytes are always well-formed):
+ * - `proof_blob_sha256` and `gist_content_sha256` are lowercase 64-char hex.
+ * - `github_username`, `unique_identifier`, `gist_url`, `scope`,
+ *   `zkpassport_sdk_version` are non-empty.
+ * - `subject[0].digest.sha256 === gist_content_sha256` — the subject digest
+ *   is the artifact whose control was demonstrated (the gist content).
+ * - `disclosure_level` is derived from `issuing_country` and is never
+ *   accepted from the caller.
+ * - There is no `bound_at` field — the Rekor inclusion timestamp is the
+ *   authoritative time of binding.
+ */
+export function buildStatement(input: BuildStatementInput): PassportsignStatement {
+  assertSha256Hex(input.proof_blob_sha256, 'proof_blob_sha256');
+  assertSha256Hex(input.gist_content_sha256, 'gist_content_sha256');
+  assertNonEmpty(input.github_username, 'github_username');
+  assertNonEmpty(input.unique_identifier, 'unique_identifier');
+  assertNonEmpty(input.gist_url, 'gist_url');
+  assertNonEmpty(input.scope, 'scope');
+  assertNonEmpty(input.zkpassport_sdk_version, 'zkpassport_sdk_version');
+
+  const disclosure_level: DisclosureLevel =
+    input.issuing_country === null ? 'personhood' : 'personhood+country';
+
+  return {
+    _type: IN_TOTO_STATEMENT_TYPE,
+    subject: [
+      {
+        name: `github.com/${input.github_username}`,
+        digest: { sha256: input.gist_content_sha256 },
+      },
+    ],
+    predicateType: PASSPORTSIGN_PREDICATE_TYPE,
+    predicate: {
+      unique_identifier: input.unique_identifier,
+      issuing_country: input.issuing_country,
+      disclosure_level,
+      proof_blob_sha256: input.proof_blob_sha256,
+      gist_url: input.gist_url,
+      gist_content_sha256: input.gist_content_sha256,
+      scope: input.scope,
+      zkpassport_sdk_version: input.zkpassport_sdk_version,
+    },
+  };
+}

package/src/storage/sqlite.ts

@@ -0,0 +1,185 @@
+/**
+ * SQLite cache mirroring spec §5's `bindings` table.
+ *
+ * The cache is **non-authoritative** by design — losing it is an
+ * availability incident, not a security one. The canonical state lives
+ * in Rekor, and `passportsign rebuild` reconstructs the cache from log
+ * entries.
+ *
+ * Uses Node's built-in `node:sqlite` (experimental but functional in
+ * Node 22.5+; stable enough for our single-user CLI use). Avoids the
+ * `better-sqlite3` native-build dependency, which requires Visual
+ * Studio C++ tools on Windows.
+ *
+ * Usernames are normalized to lowercase on insert and read per spec §10
+ * row 7. Display casing is the caller's responsibility.
+ */
+
+import { DatabaseSync } from 'node:sqlite';
+
+export type Status = 'active' | 'stale' | 'revoked';
+export type DisclosureLevel = 'personhood' | 'personhood+country';
+
+export interface BindingRow {
+  github_username: string;          // lowercase
+  unique_identifier: string;
+  issuing_country: string | null;
+  disclosure_level: DisclosureLevel;
+  scope: string;
+  zkpassport_sdk_ver: string;
+  proof_blob: Uint8Array;
+  gist_url: string;
+  gist_content_sha256: string;
+  bound_at: string;                 // ISO 8601, local-cache only
+  log_entry_hash: string;
+  log_inclusion_proof: unknown;     // serialized as JSON in the DB
+  log_root_at_submission: string;
+  last_checked_at: string;          // ISO 8601
+  status: Status;
+}
+
+export interface PassportsignCache {
+  upsertBinding(row: BindingRow): void;
+  getByUsername(username: string): BindingRow | null;
+  getByUniqueIdentifier(uid: string): BindingRow[];
+  setStatus(username: string, status: Status): void;
+  setLastChecked(username: string, when: Date): void;
+  close(): void;
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS bindings (
+  github_username        TEXT PRIMARY KEY,
+  unique_identifier      TEXT NOT NULL,
+  issuing_country        TEXT,
+  disclosure_level       TEXT NOT NULL CHECK (disclosure_level IN ('personhood','personhood+country')),
+  scope                  TEXT NOT NULL,
+  zkpassport_sdk_ver     TEXT NOT NULL,
+  proof_blob             BLOB NOT NULL,
+  gist_url               TEXT NOT NULL,
+  gist_content_sha256    TEXT NOT NULL,
+  bound_at               TEXT NOT NULL,
+  log_entry_hash         TEXT NOT NULL UNIQUE,
+  log_inclusion_proof    TEXT NOT NULL,
+  log_root_at_submission TEXT NOT NULL,
+  last_checked_at        TEXT NOT NULL,
+  status                 TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','stale','revoked'))
+);
+CREATE INDEX IF NOT EXISTS bindings_unique_identifier ON bindings(unique_identifier);
+`;
+
+interface DbRow {
+  github_username: string;
+  unique_identifier: string;
+  issuing_country: string | null;
+  disclosure_level: DisclosureLevel;
+  scope: string;
+  zkpassport_sdk_ver: string;
+  proof_blob: Uint8Array;
+  gist_url: string;
+  gist_content_sha256: string;
+  bound_at: string;
+  log_entry_hash: string;
+  log_inclusion_proof: string;
+  log_root_at_submission: string;
+  last_checked_at: string;
+  status: Status;
+}
+
+function rowFromDb(r: DbRow): BindingRow {
+  return {
+    github_username: r.github_username,
+    unique_identifier: r.unique_identifier,
+    issuing_country: r.issuing_country,
+    disclosure_level: r.disclosure_level,
+    scope: r.scope,
+    zkpassport_sdk_ver: r.zkpassport_sdk_ver,
+    proof_blob: new Uint8Array(r.proof_blob),
+    gist_url: r.gist_url,
+    gist_content_sha256: r.gist_content_sha256,
+    bound_at: r.bound_at,
+    log_entry_hash: r.log_entry_hash,
+    log_inclusion_proof: JSON.parse(r.log_inclusion_proof),
+    log_root_at_submission: r.log_root_at_submission,
+    last_checked_at: r.last_checked_at,
+    status: r.status,
+  };
+}
+
+export function openCache(path: string): PassportsignCache {
+  const db = new DatabaseSync(path);
+  db.exec('PRAGMA journal_mode = WAL');
+  db.exec(SCHEMA);
+
+  const upsertStmt = db.prepare(`
+    INSERT INTO bindings (
+      github_username, unique_identifier, issuing_country, disclosure_level,
+      scope, zkpassport_sdk_ver, proof_blob, gist_url, gist_content_sha256,
+      bound_at, log_entry_hash, log_inclusion_proof, log_root_at_submission,
+      last_checked_at, status
+    ) VALUES (
+      :github_username, :unique_identifier, :issuing_country, :disclosure_level,
+      :scope, :zkpassport_sdk_ver, :proof_blob, :gist_url, :gist_content_sha256,
+      :bound_at, :log_entry_hash, :log_inclusion_proof, :log_root_at_submission,
+      :last_checked_at, :status
+    )
+    ON CONFLICT(github_username) DO UPDATE SET
+      unique_identifier      = excluded.unique_identifier,
+      issuing_country        = excluded.issuing_country,
+      disclosure_level       = excluded.disclosure_level,
+      scope                  = excluded.scope,
+      zkpassport_sdk_ver     = excluded.zkpassport_sdk_ver,
+      proof_blob             = excluded.proof_blob,
+      gist_url               = excluded.gist_url,
+      gist_content_sha256    = excluded.gist_content_sha256,
+      bound_at               = excluded.bound_at,
+      log_entry_hash         = excluded.log_entry_hash,
+      log_inclusion_proof    = excluded.log_inclusion_proof,
+      log_root_at_submission = excluded.log_root_at_submission,
+      last_checked_at        = excluded.last_checked_at,
+      status                 = excluded.status
+  `);
+  const getByUsernameStmt = db.prepare(`SELECT * FROM bindings WHERE github_username = ?`);
+  const getByUniqueIdStmt = db.prepare(`SELECT * FROM bindings WHERE unique_identifier = ? ORDER BY bound_at`);
+  const setStatusStmt = db.prepare(`UPDATE bindings SET status = ? WHERE github_username = ?`);
+  const setLastCheckedStmt = db.prepare(`UPDATE bindings SET last_checked_at = ? WHERE github_username = ?`);
+
+  return {
+    upsertBinding(row) {
+      upsertStmt.run({
+        github_username: row.github_username.toLowerCase(),
+        unique_identifier: row.unique_identifier,
+        issuing_country: row.issuing_country,
+        disclosure_level: row.disclosure_level,
+        scope: row.scope,
+        zkpassport_sdk_ver: row.zkpassport_sdk_ver,
+        proof_blob: row.proof_blob,
+        gist_url: row.gist_url,
+        gist_content_sha256: row.gist_content_sha256,
+        bound_at: row.bound_at,
+        log_entry_hash: row.log_entry_hash,
+        log_inclusion_proof: JSON.stringify(row.log_inclusion_proof),
+        log_root_at_submission: row.log_root_at_submission,
+        last_checked_at: row.last_checked_at,
+        status: row.status,
+      });
+    },
+    getByUsername(username) {
+      const r = getByUsernameStmt.get(username.toLowerCase()) as unknown as DbRow | undefined;
+      return r ? rowFromDb(r) : null;
+    },
+    getByUniqueIdentifier(uid) {
+      const rows = getByUniqueIdStmt.all(uid) as unknown as DbRow[];
+      return rows.map(rowFromDb);
+    },
+    setStatus(username, status) {
+      setStatusStmt.run(status, username.toLowerCase());
+    },
+    setLastChecked(username, when) {
+      setLastCheckedStmt.run(when.toISOString(), username.toLowerCase());
+    },
+    close() {
+      db.close();
+    },
+  };
+}

package/src/submit.ts

@@ -0,0 +1,54 @@
+/**
+ * Submit a {@link PreparedBinding} to a Rekor log and assemble the
+ * resulting {@link PassportsignBundle}.
+ *
+ * Composes the DSSE envelope step (with ephemeral ECDSA P-256 key)
+ * with a {@link RekorClient}. Day 7 calls this to turn a real-passport
+ * bind into a public-log entry plus a portable bundle.
+ */
+
+import { type PreparedBinding } from './bind.js';
+import {
+  BUNDLE_FORMAT_VERSION,
+  type PassportsignBundle,
+  validateBundle,
+} from './bundle.js';
+import { IN_TOTO_PAYLOAD_TYPE, signEnvelope } from './dsse.js';
+import { type RekorClient, type RekorEntryResponse } from './log/rekor.js';
+
+export interface SubmitBindingDeps {
+  rekor: RekorClient;
+}
+
+export interface SubmitBindingResult {
+  bundle: PassportsignBundle;
+  rekorEntry: RekorEntryResponse;
+}
+
+/**
+ * Sign the canonical statement bytes with an ephemeral ECDSA P-256 key,
+ * submit the in-toto entry to Rekor, and assemble the bundle. Throws
+ * `PassportsignError('log_submission_failed', …)` (from the client) on
+ * any Rekor failure.
+ */
+export async function submitBinding(
+  prepared: PreparedBinding,
+  deps: SubmitBindingDeps,
+): Promise<SubmitBindingResult> {
+  const { envelope } = signEnvelope(prepared.statement_canonical, IN_TOTO_PAYLOAD_TYPE);
+  const rekorEntry = await deps.rekor.submitIntoto(envelope);
+
+  const bundle: PassportsignBundle = {
+    bundle_format_version: BUNDLE_FORMAT_VERSION,
+    statement: Buffer.from(prepared.statement_canonical).toString('hex'),
+    proof_blob: prepared.proof_blob_b64,
+    rekor: {
+      log_entry_hash: rekorEntry.uuid,
+      inclusion_proof: rekorEntry.verification.inclusionProof,
+      log_root_at_submission: rekorEntry.verification.inclusionProof.rootHash,
+    },
+  };
+  validateBundle(bundle);
+
+  return { bundle, rekorEntry };
+}

package/src/truestamp-canonify.d.ts

@@ -0,0 +1,7 @@
+// `@truestamp/canonify`'s package.json defines `exports` but doesn't expose
+// types via a `"types"` condition. NodeNext module resolution can't reach
+// the bundled `dist/mod.d.ts` through the exports map. Declare the surface
+// locally so `tsc --noEmit` passes.
+declare module '@truestamp/canonify' {
+  export default function canonify(object: unknown): string | undefined;
+}

package/src/verifier.ts

@@ -0,0 +1,317 @@
+/**
+ * Bundle verifier — the trust anchor for everyone who is not us.
+ *
+ * Day 6 scope: structural integrity (statement hash matches Rekor's
+ * recorded payloadHash), Merkle inclusion proof against the captured
+ * root, and log-root consistency between the captured root and the
+ * current witnessed root.
+ *
+ * Day 7 scope (deferred): SDK proof verification. Requires a
+ * bundle-schema extension to carry SDK inputs (proofs array,
+ * originalQuery, queryResult). For now `sdk_proof` reports
+ * `'pending_day_7'`.
+ */
+
+import { createHash } from 'node:crypto';
+
+import { type PassportsignBundle, validateBundle } from './bundle.js';
+import { type RekorClient } from './log/rekor.js';
+import { hashLeaf, verifyConsistency, verifyInclusion } from './merkle.js';
+import { unpackSdkPayload } from './sdk-payload.js';
+
+export type CheckResult = 'pass' | 'fail' | 'skipped';
+
+export interface BundleVerifyResult {
+  /**
+   * Statement bytes in the bundle hash to the `payloadHash` Rekor recorded
+   * for the entry.
+   */
+  hash_match: CheckResult;
+  /**
+   * The captured inclusion proof verifies the Rekor entry's leaf hash
+   * against the captured root.
+   */
+  inclusion_proof: CheckResult;
+  /**
+   * The captured root is a prefix of the current witnessed root (the log
+   * has not been rewritten in a way that orphans our entry). Skipped when
+   * no rekor client is provided.
+   */
+  root_consistency: CheckResult;
+  /**
+   * SDK proof verification. `'skipped'` when no SDK verifier is injected.
+   * `'pass'` when the SDK validates the proofs AND the returned
+   * uniqueIdentifier matches the statement's predicate.
+   */
+  sdk_proof: CheckResult;
+  /**
+   * `'pass'` only when every enabled check passes; `'fail'` if any check
+   * fails; `'pending'` when one or more checks are `'skipped'`.
+   */
+  overall: 'pass' | 'fail' | 'pending';
+  errors: string[];
+}
+
+export interface SdkVerifyInput {
+  proofs: unknown[];
+  originalQuery: unknown;
+  queryResult: unknown;
+  scope?: string;
+  devMode?: boolean;
+}
+
+export interface SdkVerifyResult {
+  verified: boolean;
+  uniqueIdentifier: string | undefined;
+}
+
+export interface SdkVerifier {
+  verify(input: SdkVerifyInput): Promise<SdkVerifyResult>;
+}
+
+export interface VerifyBundleDeps {
+  /** Inject a Rekor client to enable hash_match / inclusion / consistency checks. */
+  rekor?: RekorClient;
+  /** Inject a zkPassport SDK verifier to enable the sdk_proof check. */
+  sdkVerifier?: SdkVerifier;
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.substr(i * 2, 2), 16);
+  }
+  return out;
+}
+
+function sha256Hex(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+interface ParsedEntryBody {
+  payloadHashHex: string;
+}
+
+function parseEntryBody(bodyBase64: string): ParsedEntryBody {
+  const bytes = Buffer.from(bodyBase64, 'base64').toString('utf8');
+  const body = JSON.parse(bytes) as Record<string, unknown>;
+  const spec = body['spec'] as Record<string, unknown> | undefined;
+  const content = spec?.['content'] as Record<string, unknown> | undefined;
+  const payloadHash = content?.['payloadHash'] as Record<string, unknown> | undefined;
+  const value = payloadHash?.['value'];
+  if (typeof value !== 'string') {
+    throw new Error('Rekor entry body missing spec.content.payloadHash.value');
+  }
+  return { payloadHashHex: value };
+}
+
+/**
+ * Verify a passportsign bundle. Online checks (hash_match, inclusion_proof,
+ * root_consistency) require a {@link RekorClient}; without one they are
+ * marked `'skipped'`. SDK proof verification is Day 7 work and currently
+ * always returns `'pending_day_7'`.
+ */
+export async function verifyBundle(
+  bundle: PassportsignBundle,
+  deps: VerifyBundleDeps = {},
+): Promise<BundleVerifyResult> {
+  validateBundle(bundle);
+
+  const result: BundleVerifyResult = {
+    hash_match: 'skipped',
+    inclusion_proof: 'skipped',
+    root_consistency: 'skipped',
+    sdk_proof: 'skipped',
+    overall: 'pending',
+    errors: [],
+  };
+
+  // SDK proof verification (independent of rekor) — runs first because
+  // it can be done purely from the bundle.
+  if (deps.sdkVerifier) {
+    result.sdk_proof = await runSdkVerification(bundle, deps.sdkVerifier, result.errors);
+  }
+
+  if (!deps.rekor) {
+    result.overall = computeOverall(result);
+    return result;
+  }
+
+  // 1. Fetch the entry from Rekor (any operator's Rekor mirror would do).
+  let entry;
+  try {
+    entry = await deps.rekor.getEntry(bundle.rekor.log_entry_hash);
+  } catch (err) {
+    result.errors.push(
+      `failed to fetch Rekor entry: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    result.overall = 'fail';
+    result.hash_match = 'fail';
+    result.inclusion_proof = 'fail';
+    result.root_consistency = 'fail';
+    return result;
+  }
+
+  // 2. hash_match: bundle.statement bytes' sha256 must equal entry.body's payloadHash.
+  const statementBytes = hexToBytes(bundle.statement);
+  const expectedPayloadHash = sha256Hex(statementBytes);
+  let entryPayloadHash: string;
+  try {
+    entryPayloadHash = parseEntryBody(entry.body).payloadHashHex;
+  } catch (err) {
+    result.errors.push(
+      `failed to parse Rekor entry body: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    result.hash_match = 'fail';
+    result.inclusion_proof = 'fail';
+    result.root_consistency = 'fail';
+    result.overall = 'fail';
+    return result;
+  }
+  result.hash_match = expectedPayloadHash === entryPayloadHash ? 'pass' : 'fail';
+  if (result.hash_match === 'fail') {
+    result.errors.push(
+      `payloadHash mismatch: bundle says ${expectedPayloadHash}, Rekor entry has ${entryPayloadHash}`,
+    );
+  }
+
+  // 3. inclusion_proof: leaf hash = sha256(0x00 || decoded-body-bytes); verify against captured root.
+  const bodyBytes = new Uint8Array(Buffer.from(entry.body, 'base64'));
+  const leaf = hashLeaf(bodyBytes);
+  const captured = bundle.rekor.inclusion_proof as {
+    hashes: string[];
+    logIndex: number;
+    treeSize: number;
+    rootHash: string;
+  };
+  const proofHashes = captured.hashes.map(hexToBytes);
+  const rootBytes = hexToBytes(captured.rootHash);
+  result.inclusion_proof = verifyInclusion(
+    leaf,
+    captured.logIndex,
+    captured.treeSize,
+    proofHashes,
+    rootBytes,
+  )
+    ? 'pass'
+    : 'fail';
+  if (result.inclusion_proof === 'fail') {
+    result.errors.push('inclusion proof does not verify against captured root');
+  }
+
+  // 4. root_consistency: captured root must be a prefix of current witnessed root.
+  try {
+    const logInfo = await deps.rekor.getLogInfo();
+    if (logInfo.treeSize < captured.treeSize) {
+      result.errors.push(
+        `current tree size ${logInfo.treeSize} is smaller than captured ${captured.treeSize} — log may have been rewound`,
+      );
+      result.root_consistency = 'fail';
+    } else if (logInfo.treeSize === captured.treeSize) {
+      // Same tree, just compare roots
+      result.root_consistency =
+        logInfo.rootHash === captured.rootHash ? 'pass' : 'fail';
+      if (result.root_consistency === 'fail') {
+        result.errors.push(
+          `root mismatch at same treeSize: captured ${captured.rootHash}, current ${logInfo.rootHash}`,
+        );
+      }
+    } else {
+      const proof = await deps.rekor.getConsistencyProof(
+        captured.treeSize,
+        logInfo.treeSize,
+      );
+      const proofBytes = proof.hashes.map(hexToBytes);
+      result.root_consistency = verifyConsistency(
+        captured.treeSize,
+        logInfo.treeSize,
+        rootBytes,
+        hexToBytes(logInfo.rootHash),
+        proofBytes,
+      )
+        ? 'pass'
+        : 'fail';
+      if (result.root_consistency === 'fail') {
+        result.errors.push(
+          'consistency proof does not verify — captured root is not an ancestor of current root',
+        );
+      }
+    }
+  } catch (err) {
+    result.errors.push(
+      `consistency check error: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    result.root_consistency = 'fail';
+  }
+
+  result.overall = computeOverall(result);
+  return result;
+}
+
+async function runSdkVerification(
+  bundle: PassportsignBundle,
+  sdkVerifier: SdkVerifier,
+  errors: string[],
+): Promise<CheckResult> {
+  let payload;
+  try {
+    payload = unpackSdkPayload(bundle.proof_blob);
+  } catch (err) {
+    errors.push(
+      `failed to unpack SDK payload from bundle.proof_blob: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return 'fail';
+  }
+
+  let sdkResult: SdkVerifyResult;
+  try {
+    sdkResult = await sdkVerifier.verify({
+      proofs: payload.proofs,
+      originalQuery: payload.original_query,
+      queryResult: payload.query_result,
+      devMode: payload.dev_mode,
+    });
+  } catch (err) {
+    errors.push(`SDK verify threw: ${err instanceof Error ? err.message : String(err)}`);
+    return 'fail';
+  }
+
+  if (sdkResult.verified !== true) {
+    errors.push(`SDK reported verified=${String(sdkResult.verified)}`);
+    return 'fail';
+  }
+
+  // The returned uniqueIdentifier must match the statement's predicate.
+  let statementUniqueId: string | undefined;
+  try {
+    const statementBytes = Buffer.from(bundle.statement, 'hex').toString('utf8');
+    const parsed = JSON.parse(statementBytes) as {
+      predicate?: { unique_identifier?: string };
+    };
+    statementUniqueId = parsed.predicate?.unique_identifier;
+  } catch {
+    statementUniqueId = undefined;
+  }
+
+  if (!statementUniqueId) {
+    errors.push('could not extract unique_identifier from bundle.statement');
+    return 'fail';
+  }
+  if (sdkResult.uniqueIdentifier !== statementUniqueId) {
+    errors.push(
+      `SDK uniqueIdentifier ${String(sdkResult.uniqueIdentifier)} does not match statement.predicate.unique_identifier ${statementUniqueId}`,
+    );
+    return 'fail';
+  }
+
+  return 'pass';
+}
+
+function computeOverall(r: BundleVerifyResult): 'pass' | 'fail' | 'pending' {
+  const all = [r.hash_match, r.inclusion_proof, r.root_consistency, r.sdk_proof];
+  if (all.some((s) => s === 'fail')) return 'fail';
+  if (all.every((s) => s === 'pass')) return 'pass';
+  return 'pending';
+}