@passportsign/core 0.1.0 → 0.2.0

package/src/bind.ts

@@ -1,137 +1,128 @@
-/**
- * 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,
-  };
-}
+/**
+ * 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 { canonicalize, canonicalSha256Hex } from './canonical.js';
+import { base64ToBytes, sha256Hex } from './encoding.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';
+
+/**
+ * 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 = base64ToBytes(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-fs.ts

@@ -0,0 +1,40 @@
+/**
+ * Node-only file I/O for `binding.passportsign.json` bundles. Kept out
+ * of `bundle.ts` so the validation logic stays runtime-neutral (the
+ * `./web` subpath exports validation but not these).
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+
+import {
+  BundleValidationError,
+  validateBundle,
+  type PassportsignBundle,
+} from './bundle.js';
+
+/**
+ * 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/bundle.ts

@@ -1,127 +1,138 @@
-/**
- * `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');
-}
+/**
+ * `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 { bytesToHex } from './encoding.js';
+import { type RekorEntryResponse } from './log/rekor.js';
+
+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');
+  }
+}
+
+// readBundle / writeBundle live in `bundle-fs.ts` (node:fs) so this
+// module stays runtime-neutral; the main index re-exports both.
+
+/**
+ * What bundle assembly needs from a prepared statement — satisfied by
+ * both `PreparedBinding` and `PreparedRevocation`. The statement kind
+ * doesn't matter; Rekor sees canonical bytes either way.
+ */
+export interface SubmittableStatement {
+  statement_canonical: Uint8Array;
+  proof_blob_b64: string;
+}
+
+/**
+ * Assemble (and validate) the portable bundle from a prepared
+ * statement and the Rekor entry it produced. Pure — used by the node
+ * `submitBinding` path and by runtimes that sign with
+ * `signEnvelopeWeb` and submit through the Rekor client themselves.
+ */
+export function assembleBundle(
+  prepared: SubmittableStatement,
+  rekorEntry: RekorEntryResponse,
+): PassportsignBundle {
+  const bundle: PassportsignBundle = {
+    bundle_format_version: BUNDLE_FORMAT_VERSION,
+    statement: bytesToHex(prepared.statement_canonical),
+    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;
+}

package/src/canonical.ts

@@ -1,33 +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');
-}
+import canonify from '@truestamp/canonify';
+
+import { sha256Hex, utf8ToBytes } from './encoding.js';
+
+/**
+ * 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 utf8ToBytes(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 {
+  return sha256Hex(canonicalize(value));
+}