@passportsign/core 0.1.0 → 0.2.0

package/src/lookup.ts

@@ -0,0 +1,175 @@
+/**
+ * Resolve a user's published bindings: index file → Rekor entries →
+ * integrity + sanity checks → state classification.
+ *
+ * This is the shared read pipeline behind `passportsign list` and the
+ * hosted badge service. The index file is user-controlled, so nothing
+ * from it is trusted: every referenced entry is fetched from the log,
+ * its attestation integrity-checked ({@link parseIntotoEntry}), its
+ * inclusion proof verified, and its subject/predicateType checked
+ * against what the index claimed it was.
+ */
+
+import {
+  PASSPORTSIGN_PREDICATE_TYPE,
+  PASSPORTSIGN_REVOCATION_PREDICATE_TYPE,
+} from './statement.js';
+import {
+  classifyBindings,
+  parseIntotoEntry,
+  type ClassifiedBinding,
+  type ParsedIntotoEntry,
+} from './classify.js';
+import { base64ToBytes, hexToBytes } from './encoding.js';
+import { hashLeaf, verifyInclusion } from './merkle.js';
+import { fetchProfileIndex, type ProfileIndex } from './profile-index.js';
+import { type RekorClient, type RekorEntryResponse } from './log/rekor.js';
+
+export interface LookupDeps {
+  rekor: RekorClient;
+  /** Epoch ms for staleness classification; defaults to the current time. */
+  now?: number;
+}
+
+export interface LookupEntryProblem {
+  uuid: string;
+  error: string;
+}
+
+export interface LookupResult {
+  index: ProfileIndex | null;
+  classified: ClassifiedBinding[];
+  /** Entries the log could not return (network, 404). */
+  unreachable: LookupEntryProblem[];
+  /** Entries that failed integrity or sanity checks — treat as hostile index content. */
+  invalid: LookupEntryProblem[];
+}
+
+function verifyEntryInclusion(entry: RekorEntryResponse): boolean {
+  const proof = entry.verification.inclusionProof;
+  const leaf = hashLeaf(base64ToBytes(entry.body));
+  return verifyInclusion(
+    leaf,
+    proof.logIndex,
+    proof.treeSize,
+    proof.hashes.map(hexToBytes),
+    hexToBytes(proof.rootHash),
+  );
+}
+
+interface FetchedSet {
+  parsed: ParsedIntotoEntry[];
+  unreachable: LookupEntryProblem[];
+  invalid: LookupEntryProblem[];
+}
+
+async function fetchAndCheck(
+  uuids: string[],
+  expectedPredicateType: string,
+  githubUsername: string,
+  rekor: RekorClient,
+): Promise<FetchedSet> {
+  const out: FetchedSet = { parsed: [], unreachable: [], invalid: [] };
+  const results = await Promise.allSettled(uuids.map((uuid) => rekor.getEntry(uuid)));
+
+  results.forEach((result, i) => {
+    const uuid = uuids[i]!;
+    if (result.status === 'rejected') {
+      const reason = result.reason;
+      out.unreachable.push({
+        uuid,
+        error: reason instanceof Error ? reason.message : String(reason),
+      });
+      return;
+    }
+    try {
+      const entry = result.value;
+      if (!verifyEntryInclusion(entry)) {
+        out.invalid.push({ uuid, error: 'inclusion proof does not verify' });
+        return;
+      }
+      const parsed = parseIntotoEntry(entry);
+      if (parsed.predicateType !== expectedPredicateType) {
+        out.invalid.push({
+          uuid,
+          error: `predicateType ${parsed.predicateType} != expected ${expectedPredicateType}`,
+        });
+        return;
+      }
+      const subject = parsed.statement.subject[0]?.name ?? '';
+      if (subject.toLowerCase() !== `github.com/${githubUsername}`.toLowerCase()) {
+        out.invalid.push({
+          uuid,
+          error: `subject ${subject} does not match github.com/${githubUsername}`,
+        });
+        return;
+      }
+      out.parsed.push(parsed);
+    } catch (err) {
+      out.invalid.push({ uuid, error: err instanceof Error ? err.message : String(err) });
+    }
+  });
+
+  return out;
+}
+
+/**
+ * Run the lookup pipeline over an already-obtained index (e.g. the
+ * user's file merged with an operator overlay).
+ */
+export async function lookupFromIndex(
+  index: ProfileIndex,
+  deps: LookupDeps,
+): Promise<LookupResult> {
+  const username = index.github_username;
+
+  const [bindings, revocations] = await Promise.all([
+    fetchAndCheck(
+      index.bindings.map((b) => b.rekor_entry_hash),
+      PASSPORTSIGN_PREDICATE_TYPE,
+      username,
+      deps.rekor,
+    ),
+    fetchAndCheck(
+      index.revocations.map((r) => r.rekor_entry_hash),
+      PASSPORTSIGN_REVOCATION_PREDICATE_TYPE,
+      username,
+      deps.rekor,
+    ),
+  ]);
+
+  const classified = classifyBindings({
+    bindings: bindings.parsed,
+    revocations: revocations.parsed,
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  });
+
+  return {
+    index,
+    classified,
+    unreachable: [...bindings.unreachable, ...revocations.unreachable],
+    invalid: [...bindings.invalid, ...revocations.invalid],
+  };
+}
+
+export interface LookupBindingsDeps extends LookupDeps {
+  /** Injectable fetch for the index file request. */
+  fetch?: typeof fetch;
+}
+
+/**
+ * Fetch the user's published `passportsign-index.json` and resolve it.
+ * `index: null` in the result means the user has not published one.
+ */
+export async function lookupBindings(
+  githubUsername: string,
+  deps: LookupBindingsDeps,
+): Promise<LookupResult> {
+  const index = await fetchProfileIndex(githubUsername, {
+    ...(deps.fetch ? { fetch: deps.fetch } : {}),
+  });
+  if (index === null) {
+    return { index: null, classified: [], unreachable: [], invalid: [] };
+  }
+  return lookupFromIndex(index, deps);
+}

package/src/merkle.ts

@@ -1,187 +1,187 @@
-/**
- * RFC 6962 Merkle tree primitives — the math underneath Rekor's
- * inclusion and consistency proofs.
- *
- * Algorithm ported from
- * https://github.com/google/certificate-transparency-go/blob/master/merkle/log_verifier.go
- * (the canonical reference implementation Sigstore tracks).
- *
- * Leaf hash:  sha256(0x00 || leaf-bytes)
- * Inner hash: sha256(0x01 || left-hash || right-hash)
- *
- * A proof of length n+m has n "inner" hashes (siblings along the path
- * from leaf up to the highest common ancestor with the rightmost
- * leaf) followed by m "border" hashes (always left-leaning siblings
- * above that ancestor). The split is determined by bit-decomposition
- * of leafIndex against treeSize - 1.
- */
-
-import { createHash } from 'node:crypto';
-
-export function hashLeaf(data: Uint8Array): Uint8Array {
-  const buf = new Uint8Array(1 + data.length);
-  buf[0] = 0x00;
-  buf.set(data, 1);
-  return new Uint8Array(createHash('sha256').update(buf).digest());
-}
-
-export function hashPair(left: Uint8Array, right: Uint8Array): Uint8Array {
-  const buf = new Uint8Array(1 + left.length + right.length);
-  buf[0] = 0x01;
-  buf.set(left, 1);
-  buf.set(right, 1 + left.length);
-  return new Uint8Array(createHash('sha256').update(buf).digest());
-}
-
-function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
-  if (a.length !== b.length) return false;
-  for (let i = 0; i < a.length; i++) {
-    if (a[i] !== b[i]) return false;
-  }
-  return true;
-}
-
-function bitLength(n: number): number {
-  let len = 0;
-  while (n > 0) {
-    len++;
-    n = Math.floor(n / 2);
-  }
-  return len;
-}
-
-function popcount(n: number): number {
-  let count = 0;
-  while (n > 0) {
-    count += n & 1;
-    n = Math.floor(n / 2);
-  }
-  return count;
-}
-
-function trailingZeros(n: number): number {
-  if (n === 0) return 64;
-  let count = 0;
-  while ((n & 1) === 0) {
-    count++;
-    n = Math.floor(n / 2);
-  }
-  return count;
-}
-
-interface ProofDecomposition {
-  inner: number;
-  border: number;
-}
-
-function decompInclProof(leafIndex: number, treeSize: number): ProofDecomposition {
-  const inner = bitLength(leafIndex ^ (treeSize - 1));
-  const border = popcount(Math.floor(leafIndex / Math.pow(2, inner)));
-  return { inner, border };
-}
-
-function chainInner(seed: Uint8Array, proof: Uint8Array[], leafIndex: number): Uint8Array {
-  let res = seed;
-  for (let i = 0; i < proof.length; i++) {
-    const bit = (Math.floor(leafIndex / Math.pow(2, i))) & 1;
-    res = bit === 0 ? hashPair(res, proof[i]!) : hashPair(proof[i]!, res);
-  }
-  return res;
-}
-
-function chainInnerRight(seed: Uint8Array, proof: Uint8Array[], leafIndex: number): Uint8Array {
-  let res = seed;
-  for (let i = 0; i < proof.length; i++) {
-    const bit = (Math.floor(leafIndex / Math.pow(2, i))) & 1;
-    if (bit === 1) {
-      res = hashPair(proof[i]!, res);
-    }
-  }
-  return res;
-}
-
-function chainBorderRight(seed: Uint8Array, proof: Uint8Array[]): Uint8Array {
-  let res = seed;
-  for (const p of proof) {
-    res = hashPair(p, res);
-  }
-  return res;
-}
-
-/**
- * Verify an RFC 6962 inclusion proof: prove that a leaf with hash
- * `leafHash` at position `leafIndex` is included in a tree of size
- * `treeSize` with root `rootHash`, using the supplied path of
- * sibling hashes.
- */
-export function verifyInclusion(
-  leafHash: Uint8Array,
-  leafIndex: number,
-  treeSize: number,
-  proof: Uint8Array[],
-  rootHash: Uint8Array,
-): boolean {
-  if (leafIndex < 0 || treeSize < 0 || leafIndex >= treeSize) return false;
-
-  const { inner, border } = decompInclProof(leafIndex, treeSize);
-  if (proof.length !== inner + border) return false;
-
-  let res = chainInner(leafHash, proof.slice(0, inner), leafIndex);
-  res = chainBorderRight(res, proof.slice(inner));
-  return bytesEqual(res, rootHash);
-}
-
-/**
- * Verify an RFC 6962 consistency proof: prove that the tree of size
- * `firstSize` with root `firstRoot` is a prefix of the tree of size
- * `secondSize` with root `secondRoot`. Used to detect log rewrites —
- * if our captured root is no longer an ancestor of the current root,
- * the log has been tampered with.
- *
- * Algorithm port of certificate-transparency-go's `VerifyConsistencyProof`.
- */
-export function verifyConsistency(
-  firstSize: number,
-  secondSize: number,
-  firstRoot: Uint8Array,
-  secondRoot: Uint8Array,
-  proof: Uint8Array[],
-): boolean {
-  if (firstSize < 0 || secondSize < firstSize) return false;
-  if (firstSize === secondSize) {
-    return proof.length === 0 && bytesEqual(firstRoot, secondRoot);
-  }
-  if (firstSize === 0) {
-    return proof.length === 0;
-  }
-
-  let { inner, border } = decompInclProof(firstSize - 1, secondSize);
-  const shift = trailingZeros(firstSize);
-  inner -= shift;
-
-  let seed: Uint8Array;
-  let start: number;
-  if ((firstSize & (firstSize - 1)) !== 0) {
-    if (proof.length === 0) return false;
-    seed = proof[0]!;
-    start = 1;
-  } else {
-    seed = firstRoot;
-    start = 0;
-  }
-
-  if (proof.length !== start + inner + border) return false;
-  const subProof = proof.slice(start);
-
-  const mask = Math.floor((firstSize - 1) / Math.pow(2, shift));
-
-  let hash1 = chainInnerRight(seed, subProof.slice(0, inner), mask);
-  hash1 = chainBorderRight(hash1, subProof.slice(inner));
-  if (!bytesEqual(hash1, firstRoot)) return false;
-
-  let hash2 = chainInner(seed, subProof.slice(0, inner), mask);
-  hash2 = chainBorderRight(hash2, subProof.slice(inner));
-  if (!bytesEqual(hash2, secondRoot)) return false;
-
-  return true;
-}
+/**
+ * RFC 6962 Merkle tree primitives — the math underneath Rekor's
+ * inclusion and consistency proofs.
+ *
+ * Algorithm ported from
+ * https://github.com/google/certificate-transparency-go/blob/master/merkle/log_verifier.go
+ * (the canonical reference implementation Sigstore tracks).
+ *
+ * Leaf hash:  sha256(0x00 || leaf-bytes)
+ * Inner hash: sha256(0x01 || left-hash || right-hash)
+ *
+ * A proof of length n+m has n "inner" hashes (siblings along the path
+ * from leaf up to the highest common ancestor with the rightmost
+ * leaf) followed by m "border" hashes (always left-leaning siblings
+ * above that ancestor). The split is determined by bit-decomposition
+ * of leafIndex against treeSize - 1.
+ */
+
+import { sha256Bytes } from './encoding.js';
+
+export function hashLeaf(data: Uint8Array): Uint8Array {
+  const buf = new Uint8Array(1 + data.length);
+  buf[0] = 0x00;
+  buf.set(data, 1);
+  return sha256Bytes(buf);
+}
+
+export function hashPair(left: Uint8Array, right: Uint8Array): Uint8Array {
+  const buf = new Uint8Array(1 + left.length + right.length);
+  buf[0] = 0x01;
+  buf.set(left, 1);
+  buf.set(right, 1 + left.length);
+  return sha256Bytes(buf);
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+function bitLength(n: number): number {
+  let len = 0;
+  while (n > 0) {
+    len++;
+    n = Math.floor(n / 2);
+  }
+  return len;
+}
+
+function popcount(n: number): number {
+  let count = 0;
+  while (n > 0) {
+    count += n & 1;
+    n = Math.floor(n / 2);
+  }
+  return count;
+}
+
+function trailingZeros(n: number): number {
+  if (n === 0) return 64;
+  let count = 0;
+  while ((n & 1) === 0) {
+    count++;
+    n = Math.floor(n / 2);
+  }
+  return count;
+}
+
+interface ProofDecomposition {
+  inner: number;
+  border: number;
+}
+
+function decompInclProof(leafIndex: number, treeSize: number): ProofDecomposition {
+  const inner = bitLength(leafIndex ^ (treeSize - 1));
+  const border = popcount(Math.floor(leafIndex / Math.pow(2, inner)));
+  return { inner, border };
+}
+
+function chainInner(seed: Uint8Array, proof: Uint8Array[], leafIndex: number): Uint8Array {
+  let res = seed;
+  for (let i = 0; i < proof.length; i++) {
+    const bit = (Math.floor(leafIndex / Math.pow(2, i))) & 1;
+    res = bit === 0 ? hashPair(res, proof[i]!) : hashPair(proof[i]!, res);
+  }
+  return res;
+}
+
+function chainInnerRight(seed: Uint8Array, proof: Uint8Array[], leafIndex: number): Uint8Array {
+  let res = seed;
+  for (let i = 0; i < proof.length; i++) {
+    const bit = (Math.floor(leafIndex / Math.pow(2, i))) & 1;
+    if (bit === 1) {
+      res = hashPair(proof[i]!, res);
+    }
+  }
+  return res;
+}
+
+function chainBorderRight(seed: Uint8Array, proof: Uint8Array[]): Uint8Array {
+  let res = seed;
+  for (const p of proof) {
+    res = hashPair(p, res);
+  }
+  return res;
+}
+
+/**
+ * Verify an RFC 6962 inclusion proof: prove that a leaf with hash
+ * `leafHash` at position `leafIndex` is included in a tree of size
+ * `treeSize` with root `rootHash`, using the supplied path of
+ * sibling hashes.
+ */
+export function verifyInclusion(
+  leafHash: Uint8Array,
+  leafIndex: number,
+  treeSize: number,
+  proof: Uint8Array[],
+  rootHash: Uint8Array,
+): boolean {
+  if (leafIndex < 0 || treeSize < 0 || leafIndex >= treeSize) return false;
+
+  const { inner, border } = decompInclProof(leafIndex, treeSize);
+  if (proof.length !== inner + border) return false;
+
+  let res = chainInner(leafHash, proof.slice(0, inner), leafIndex);
+  res = chainBorderRight(res, proof.slice(inner));
+  return bytesEqual(res, rootHash);
+}
+
+/**
+ * Verify an RFC 6962 consistency proof: prove that the tree of size
+ * `firstSize` with root `firstRoot` is a prefix of the tree of size
+ * `secondSize` with root `secondRoot`. Used to detect log rewrites —
+ * if our captured root is no longer an ancestor of the current root,
+ * the log has been tampered with.
+ *
+ * Algorithm port of certificate-transparency-go's `VerifyConsistencyProof`.
+ */
+export function verifyConsistency(
+  firstSize: number,
+  secondSize: number,
+  firstRoot: Uint8Array,
+  secondRoot: Uint8Array,
+  proof: Uint8Array[],
+): boolean {
+  if (firstSize < 0 || secondSize < firstSize) return false;
+  if (firstSize === secondSize) {
+    return proof.length === 0 && bytesEqual(firstRoot, secondRoot);
+  }
+  if (firstSize === 0) {
+    return proof.length === 0;
+  }
+
+  let { inner, border } = decompInclProof(firstSize - 1, secondSize);
+  const shift = trailingZeros(firstSize);
+  inner -= shift;
+
+  let seed: Uint8Array;
+  let start: number;
+  if ((firstSize & (firstSize - 1)) !== 0) {
+    if (proof.length === 0) return false;
+    seed = proof[0]!;
+    start = 1;
+  } else {
+    seed = firstRoot;
+    start = 0;
+  }
+
+  if (proof.length !== start + inner + border) return false;
+  const subProof = proof.slice(start);
+
+  const mask = Math.floor((firstSize - 1) / Math.pow(2, shift));
+
+  let hash1 = chainInnerRight(seed, subProof.slice(0, inner), mask);
+  hash1 = chainBorderRight(hash1, subProof.slice(inner));
+  if (!bytesEqual(hash1, firstRoot)) return false;
+
+  let hash2 = chainInner(seed, subProof.slice(0, inner), mask);
+  hash2 = chainBorderRight(hash2, subProof.slice(inner));
+  if (!bytesEqual(hash2, secondRoot)) return false;
+
+  return true;
+}

package/src/nonce.ts

@@ -1,53 +1,53 @@
-/**
- * Binding nonce per spec §3 step 1: cryptographically random, ≥128 bits,
- * base32-encoded for gist-friendliness, prefixed with the service
- * namespace ("zkm-") and the username for human readability.
- *
- * Format: `zkm-{username}-{base32}`
- * Entropy: 160 bits (20 bytes → 32 base32 chars).
- */
-
-import { randomBytes } from 'node:crypto';
-
-const BASE32_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
-export const NONCE_BYTES = 20;
-export const NONCE_BASE32_LENGTH = 32; // (20 * 8) / 5
-
-/**
- * RFC 4648 base32 (lowercase, no padding) of the input bytes.
- *
- * Uses BigInt to avoid 32-bit overflow when accumulating ≥4 bytes.
- */
-export function base32Encode(bytes: Uint8Array): string {
-  let bits = 0n;
-  let bitCount = 0;
-  let result = '';
-  for (const byte of bytes) {
-    bits = (bits << 8n) | BigInt(byte);
-    bitCount += 8;
-    while (bitCount >= 5) {
-      bitCount -= 5;
-      const idx = Number((bits >> BigInt(bitCount)) & 0x1fn);
-      result += BASE32_ALPHABET[idx];
-    }
-  }
-  if (bitCount > 0) {
-    const idx = Number((bits << BigInt(5 - bitCount)) & 0x1fn);
-    result += BASE32_ALPHABET[idx];
-  }
-  return result;
-}
-
-/**
- * Generate a fresh nonce for a binding session.
- *
- * @param username - GitHub username to embed in the nonce (case preserved).
- * @returns `zkm-<username>-<32 base32 chars>` (length-stable for valid usernames).
- */
-export function generateNonce(username: string): string {
-  if (username.length === 0) {
-    throw new TypeError('generateNonce: username must be non-empty');
-  }
-  const bytes = randomBytes(NONCE_BYTES);
-  return `zkm-${username}-${base32Encode(bytes)}`;
-}
+/**
+ * Binding nonce per spec §3 step 1: cryptographically random, ≥128 bits,
+ * base32-encoded for gist-friendliness, prefixed with the service
+ * namespace ("zkm-") and the username for human readability.
+ *
+ * Format: `zkm-{username}-{base32}`
+ * Entropy: 160 bits (20 bytes → 32 base32 chars).
+ */
+
+import { randomBytes } from './encoding.js';
+
+const BASE32_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+export const NONCE_BYTES = 20;
+export const NONCE_BASE32_LENGTH = 32; // (20 * 8) / 5
+
+/**
+ * RFC 4648 base32 (lowercase, no padding) of the input bytes.
+ *
+ * Uses BigInt to avoid 32-bit overflow when accumulating ≥4 bytes.
+ */
+export function base32Encode(bytes: Uint8Array): string {
+  let bits = 0n;
+  let bitCount = 0;
+  let result = '';
+  for (const byte of bytes) {
+    bits = (bits << 8n) | BigInt(byte);
+    bitCount += 8;
+    while (bitCount >= 5) {
+      bitCount -= 5;
+      const idx = Number((bits >> BigInt(bitCount)) & 0x1fn);
+      result += BASE32_ALPHABET[idx];
+    }
+  }
+  if (bitCount > 0) {
+    const idx = Number((bits << BigInt(5 - bitCount)) & 0x1fn);
+    result += BASE32_ALPHABET[idx];
+  }
+  return result;
+}
+
+/**
+ * Generate a fresh nonce for a binding session.
+ *
+ * @param username - GitHub username to embed in the nonce (case preserved).
+ * @returns `zkm-<username>-<32 base32 chars>` (length-stable for valid usernames).
+ */
+export function generateNonce(username: string): string {
+  if (username.length === 0) {
+    throw new TypeError('generateNonce: username must be non-empty');
+  }
+  const bytes = randomBytes(NONCE_BYTES);
+  return `zkm-${username}-${base32Encode(bytes)}`;
+}