@passportsign/core 0.1.0

package/dist/verifier.js

@@ -0,0 +1,197 @@
+/**
+ * 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 { validateBundle } from './bundle.js';
+import {} from './log/rekor.js';
+import { hashLeaf, verifyConsistency, verifyInclusion } from './merkle.js';
+import { unpackSdkPayload } from './sdk-payload.js';
+function hexToBytes(hex) {
+    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) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function parseEntryBody(bodyBase64) {
+    const bytes = Buffer.from(bodyBase64, 'base64').toString('utf8');
+    const body = JSON.parse(bytes);
+    const spec = body['spec'];
+    const content = spec?.['content'];
+    const payloadHash = content?.['payloadHash'];
+    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, deps = {}) {
+    validateBundle(bundle);
+    const result = {
+        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;
+    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;
+    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, sdkVerifier, errors) {
+    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;
+    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;
+    try {
+        const statementBytes = Buffer.from(bundle.statement, 'hex').toString('utf8');
+        const parsed = JSON.parse(statementBytes);
+        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) {
+    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';
+}
+//# sourceMappingURL=verifier.js.map

package/dist/verifier.js.map

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

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@passportsign/core",
+  "version": "0.1.0",
+  "description": "Core primitives for passportsign: canonical serialization, in-toto Statement v1 builder, binding bundle format, GitHub gist check, Rekor client, RFC 6962 Merkle, DSSE envelope, bundle verifier. Apache-2.0.",
+  "keywords": [
+    "passportsign",
+    "sigstore",
+    "rekor",
+    "in-toto",
+    "zkpassport",
+    "personhood",
+    "attestation",
+    "identity"
+  ],
+  "homepage": "https://passportsign.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/debugmcp/passportsign.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/debugmcp/passportsign/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "JF <https://passportsign.dev>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./storage/sqlite": {
+      "types": "./dist/storage/sqlite.d.ts",
+      "default": "./dist/storage/sqlite.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "dependencies": {
+    "@truestamp/canonify": "1.0.3"
+  },
+  "devDependencies": {},
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/badge.ts

@@ -0,0 +1,113 @@
+/**
+ * Self-contained inline SVG badge generator for passportsign.
+ *
+ * v0 ships without a hosted badge service. Maintainers commit the
+ * generated `passportsign-badge.svg` to a public repo (typically the
+ * `username/username` profile repo) and reference it from their
+ * README. GitHub's image proxy renders the SVG; the badge wraps a
+ * link to the Rekor entry for click-through verification.
+ *
+ * Visual: shields.io-style pill, two segments, ~190-280px wide
+ * depending on text. Renders with the 10x scale + transform=scale(.1)
+ * trick used by shields.io for crisper text rendering.
+ */
+
+export interface BadgeInput {
+  github_username: string;
+  issuing_country: string | null;
+  bound_at: string;            // ISO 8601 timestamp
+  /** Rekor entry UUID for the `<title>` tooltip. */
+  log_entry_hash?: string;
+}
+
+const LABEL = 'passportsign';
+const CHAR_WIDTH_PX = 7;        // Approx Verdana 11pt character width
+const SIDE_PADDING_PX = 8;
+
+function escapeXml(s: string): string {
+  return s.replace(/[<>&"']/g, (c) => {
+    switch (c) {
+      case '<': return '&lt;';
+      case '>': return '&gt;';
+      case '&': return '&amp;';
+      case '"': return '&quot;';
+      case "'": return '&apos;';
+      default: return c;
+    }
+  });
+}
+
+function dateStringFor(isoTimestamp: string): string {
+  // Render as YYYY-MM-DD for the badge.
+  const d = new Date(isoTimestamp);
+  if (Number.isNaN(d.getTime())) return isoTimestamp.slice(0, 10);
+  const y = d.getUTCFullYear();
+  const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(d.getUTCDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+/**
+ * Render the badge SVG. The output is intentionally a string (not a
+ * DOM tree or stream) so callers can write it to disk directly with
+ * `writeFileSync`.
+ */
+export function renderBadgeSvg(input: BadgeInput): string {
+  const date = dateStringFor(input.bound_at);
+  const valueParts = ['verified human'];
+  if (input.issuing_country) valueParts.push(input.issuing_country);
+  valueParts.push(date);
+  const valueText = valueParts.join(' · '); // middle dot ·
+
+  const labelEsc = escapeXml(LABEL);
+  const valueEsc = escapeXml(valueText);
+
+  const labelW = LABEL.length * CHAR_WIDTH_PX + 2 * SIDE_PADDING_PX;
+  const valueW = valueText.length * CHAR_WIDTH_PX + 2 * SIDE_PADDING_PX;
+  const totalW = labelW + valueW;
+
+  const labelCx10 = labelW * 5;          // centre of label segment, scaled x10
+  const valueCx10 = (labelW + valueW / 2) * 10;
+  const ariaLabel = `${labelEsc}: ${valueEsc}`;
+  const tooltipExtra = input.log_entry_hash
+    ? ` (rekor entry ${escapeXml(input.log_entry_hash.slice(0, 16))}…)`
+    : '';
+
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${totalW}" height="20" role="img" aria-label="${ariaLabel}">`,
+    `<title>${ariaLabel}${tooltipExtra}</title>`,
+    `<linearGradient id="s" x2="0" y2="100%">`,
+    `<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>`,
+    `<stop offset="1" stop-opacity=".1"/>`,
+    `</linearGradient>`,
+    `<clipPath id="r"><rect width="${totalW}" height="20" rx="3" fill="#fff"/></clipPath>`,
+    `<g clip-path="url(#r)">`,
+    `<rect width="${labelW}" height="20" fill="#555"/>`,
+    `<rect x="${labelW}" width="${valueW}" height="20" fill="#4c1"/>`,
+    `<rect width="${totalW}" height="20" fill="url(#s)"/>`,
+    `</g>`,
+    `<g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110">`,
+    `<text x="${labelCx10}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)">${labelEsc}</text>`,
+    `<text x="${labelCx10}" y="140" transform="scale(.1)">${labelEsc}</text>`,
+    `<text x="${valueCx10}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)">${valueEsc}</text>`,
+    `<text x="${valueCx10}" y="140" transform="scale(.1)">${valueEsc}</text>`,
+    `</g>`,
+    `</svg>`,
+  ].join('');
+}
+
+/**
+ * Render the Markdown snippet that wraps the badge in a click-through
+ * link to the Rekor entry. Suitable for pasting into a README.
+ */
+export function renderBadgeMarkdown(input: {
+  badge_path: string;            // relative path the user will commit
+  log_entry_hash: string;        // Rekor entry UUID
+  rekor_base_url?: string;       // default: https://rekor.sigstore.dev
+  alt_text?: string;
+}): string {
+  const base = input.rekor_base_url ?? 'https://rekor.sigstore.dev';
+  const url = `${base}/api/v1/log/entries/${input.log_entry_hash}`;
+  const alt = input.alt_text ?? 'passportsign verified';
+  return `[![${alt}](${input.badge_path})](${url})`;
+}

package/src/bind.ts

@@ -0,0 +1,137 @@
+/**
+ * Bind-flow orchestrator (no Rekor yet).
+ *
+ * Composes the pieces from `github.ts`, `statement.ts`, and `canonical.ts`
+ * into a single "given these inputs, produce a ready-to-submit binding"
+ * function. Day 5 will chain this with the Rekor submission and bundle
+ * write to deliver the full `passportsign bind` CLI command.
+ *
+ * Deliberately does **not** call the zkPassport SDK directly — the proof
+ * blob and SDK-derived metadata come in as plain data. The CLI's bind
+ * command is the producer of that data (it drives the SDK + UI),
+ * keeping this module pure and unit-testable without the SDK.
+ */
+
+import { createHash } from 'node:crypto';
+
+import { canonicalize, canonicalSha256Hex } from './canonical.js';
+import { PassportsignError } from './errors.js';
+import { checkGistControl, type GistEvidence } from './github.js';
+import { buildStatement, type PassportsignStatement } from './statement.js';
+
+export interface PrepareBindingInput {
+  github_username: string;
+  /** Base64-encoded zkPassport proof blob (the SDK callback's serialized output). */
+  proof_blob_b64: string;
+  /** From the SDK's `onResult` callback. Deterministic for this passport + scope. */
+  unique_identifier: string;
+  /** ICAO 3-letter code if disclosed, else null. Pass through as-returned by SDK. */
+  issuing_country: string | null;
+  /** Per-binding nonce that was placed in the user's gist for the control check. */
+  nonce: string;
+  /** Full scope string (e.g. "passportsign.dev:nationality-disclose:1"). */
+  scope: string;
+  /** Version string from the zkPassport SDK that produced the proof. */
+  zkpassport_sdk_version: string;
+  /** Optional GitHub token for the gist check (rate limits only — no special access). */
+  github_token?: string;
+}
+
+export interface PrepareBindingInit {
+  /** Init timestamp — gist `updated_at` must be on or after this. */
+  issuedAt: Date;
+  /** Filename to look for in the user's gists. Defaults to `passportsign.txt`. */
+  gistFilename?: string;
+}
+
+export interface PrepareBindingDeps {
+  /** Inject for tests. Defaults to {@link checkGistControl}. */
+  github?: typeof checkGistControl;
+  /** Inject a fetch (forwarded to github). */
+  fetch?: typeof fetch;
+}
+
+export interface PreparedBinding {
+  statement: PassportsignStatement;
+  statement_canonical: Uint8Array;
+  statement_sha256_hex: string;
+  proof_blob_b64: string;
+  proof_blob_sha256_hex: string;
+  gist: GistEvidence;
+}
+
+const DEFAULT_GIST_FILENAME = 'passportsign.txt';
+
+function decodeBase64(b64: string): Uint8Array {
+  return new Uint8Array(Buffer.from(b64, 'base64'));
+}
+
+function sha256Hex(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+/**
+ * Run the GitHub gist control check, then build the in-toto statement and
+ * compute canonical bytes + hashes for the Rekor handoff.
+ *
+ * Throws {@link PassportsignError} with the matching §4 code on any
+ * failure path.
+ */
+export async function prepareBinding(
+  input: PrepareBindingInput,
+  init: PrepareBindingInit,
+  deps: PrepareBindingDeps = {},
+): Promise<PreparedBinding> {
+  const githubImpl = deps.github ?? checkGistControl;
+
+  // 1. GitHub gist control check (throws PassportsignError on any §4 path).
+  const gist = await githubImpl({
+    username: input.github_username,
+    expected_filename: init.gistFilename ?? DEFAULT_GIST_FILENAME,
+    expected_content: input.nonce,
+    not_before: init.issuedAt,
+    ...(input.github_token ? { token: input.github_token } : {}),
+    ...(deps.fetch ? { fetch: deps.fetch } : {}),
+  });
+
+  // 2. Derive proof_blob sha256 from the base64 input.
+  let proofBytes: Uint8Array;
+  try {
+    proofBytes = decodeBase64(input.proof_blob_b64);
+  } catch (err) {
+    throw new PassportsignError(
+      'proof_invalid',
+      `proof_blob_b64 is not valid base64`,
+      err,
+    );
+  }
+  if (proofBytes.length === 0) {
+    throw new PassportsignError('proof_invalid', 'proof_blob_b64 decoded to zero bytes');
+  }
+  const proof_blob_sha256_hex = sha256Hex(proofBytes);
+
+  // 3. Build the in-toto statement (enforces hex / non-empty invariants).
+  const statement = buildStatement({
+    github_username: input.github_username,
+    unique_identifier: input.unique_identifier,
+    issuing_country: input.issuing_country,
+    proof_blob_sha256: proof_blob_sha256_hex,
+    gist_url: gist.url,
+    gist_content_sha256: gist.content_sha256,
+    scope: input.scope,
+    zkpassport_sdk_version: input.zkpassport_sdk_version,
+  });
+
+  // 4. Canonical bytes + sha256 for the Rekor entry.
+  const statement_canonical = canonicalize(statement);
+  const statement_sha256_hex = canonicalSha256Hex(statement);
+
+  return {
+    statement,
+    statement_canonical,
+    statement_sha256_hex,
+    proof_blob_b64: input.proof_blob_b64,
+    proof_blob_sha256_hex,
+    gist,
+  };
+}

package/src/bundle.ts

@@ -0,0 +1,127 @@
+/**
+ * `binding.passportsign.json` bundle format — the portable unit of
+ * verification.
+ *
+ * Rekor stores hashes, not artifacts. To verify a binding, a third party
+ * needs both the Rekor entry (hash + inclusion proof) and the artifacts
+ * that were hashed. The bundle carries both: the canonical statement bytes
+ * (hex), the proof blob (base64), and the Rekor metadata.
+ *
+ * Shape follows the Sigstore verification-bundle pattern. The
+ * `rekor.inclusion_proof` field is intentionally `unknown` for now — its
+ * shape gets pinned in Day 5 after we've smoke-tested the public Sigstore
+ * Rekor response format.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+
+export const BUNDLE_FORMAT_VERSION = 1 as const;
+
+export interface RekorBundleFields {
+  log_entry_hash: string;
+  inclusion_proof: unknown;
+  log_root_at_submission: string;
+}
+
+export interface PassportsignBundle {
+  bundle_format_version: typeof BUNDLE_FORMAT_VERSION;
+  /** Hex-encoded canonical JCS bytes of the in-toto statement. */
+  statement: string;
+  /** Base64-encoded zkPassport proof blob. */
+  proof_blob: string;
+  rekor: RekorBundleFields;
+}
+
+const HEX_EVEN = /^(?:[0-9a-f]{2})+$/;
+// Standard base64: A-Z, a-z, 0-9, +, /, with 0-2 trailing '=' for padding.
+// Length must be multiple of 4.
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+export class BundleValidationError extends Error {
+  constructor(
+    readonly path: string,
+    message: string,
+  ) {
+    super(`${path}: ${message}`);
+    this.name = 'BundleValidationError';
+  }
+}
+
+function fail(path: string, message: string): never {
+  throw new BundleValidationError(path, message);
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Type-guard validator for `PassportsignBundle`. Throws
+ * `BundleValidationError` with a structured path on the first issue.
+ */
+export function validateBundle(value: unknown): asserts value is PassportsignBundle {
+  if (!isObject(value)) fail('$', 'bundle must be a JSON object');
+
+  if (value['bundle_format_version'] !== BUNDLE_FORMAT_VERSION) {
+    fail(
+      '$.bundle_format_version',
+      `expected ${BUNDLE_FORMAT_VERSION}, got ${JSON.stringify(value['bundle_format_version'])}`,
+    );
+  }
+
+  const statement = value['statement'];
+  if (typeof statement !== 'string') fail('$.statement', 'must be a string');
+  if (!HEX_EVEN.test(statement)) {
+    fail('$.statement', 'must be lowercase even-length hex (canonical JCS bytes)');
+  }
+
+  const proofBlob = value['proof_blob'];
+  if (typeof proofBlob !== 'string') fail('$.proof_blob', 'must be a string');
+  if (!BASE64.test(proofBlob)) {
+    fail('$.proof_blob', 'must be standard base64 (A-Z, a-z, 0-9, +, /, = padding)');
+  }
+
+  const rekor = value['rekor'];
+  if (!isObject(rekor)) fail('$.rekor', 'must be an object');
+
+  const logEntryHash = rekor['log_entry_hash'];
+  if (typeof logEntryHash !== 'string' || logEntryHash.length === 0) {
+    fail('$.rekor.log_entry_hash', 'must be a non-empty string');
+  }
+
+  if (!('inclusion_proof' in rekor)) {
+    fail('$.rekor.inclusion_proof', 'is required (shape pinned in Day 5)');
+  }
+
+  const logRootAtSubmission = rekor['log_root_at_submission'];
+  if (typeof logRootAtSubmission !== 'string' || logRootAtSubmission.length === 0) {
+    fail('$.rekor.log_root_at_submission', 'must be a non-empty string');
+  }
+}
+
+/**
+ * Read and validate a `binding.passportsign.json` file. Throws on
+ * invalid JSON or schema violations.
+ */
+export function readBundle(path: string): PassportsignBundle {
+  const raw = readFileSync(path, 'utf8');
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new BundleValidationError(
+      '$',
+      `invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  validateBundle(parsed);
+  return parsed;
+}
+
+/**
+ * Validate and write a `binding.passportsign.json` file (pretty-printed).
+ */
+export function writeBundle(path: string, bundle: PassportsignBundle): void {
+  validateBundle(bundle);
+  writeFileSync(path, JSON.stringify(bundle, null, 2) + '\n', 'utf8');
+}

package/src/canonical.ts

@@ -0,0 +1,33 @@
+import canonify from '@truestamp/canonify';
+import { createHash } from 'node:crypto';
+
+/**
+ * RFC 8785 JCS-canonical UTF-8 bytes for a JSON-serializable value.
+ *
+ * Wraps `@truestamp/canonify` (pinned at exact 1.0.3) and UTF-8 encodes the
+ * resulting string. The fixture-pinned drift test in
+ * `test/canonical.test.ts` guards against silent behavior changes in the
+ * underlying library — JCS implementations have had subtle bugs and this
+ * function's output is the most security-critical artifact in the repo.
+ *
+ * Throws `TypeError` if the value cannot be canonicalized (e.g. undefined,
+ * cycles, non-JSON-serializable types).
+ */
+export function canonicalize(value: unknown): Uint8Array {
+  const canonical = canonify(value);
+  if (canonical === undefined) {
+    throw new TypeError(
+      'canonicalize: value cannot be JCS-canonicalized (undefined / cycle / non-JSON)',
+    );
+  }
+  return new TextEncoder().encode(canonical);
+}
+
+/**
+ * Lowercase-hex SHA-256 of `canonicalize(value)`. Used to derive the
+ * Rekor entry hash for the in-toto statement.
+ */
+export function canonicalSha256Hex(value: unknown): string {
+  const bytes = canonicalize(value);
+  return createHash('sha256').update(bytes).digest('hex');
+}