@passportsign/core 0.1.0 → 0.2.0

package/src/classify.ts

@@ -0,0 +1,165 @@
+/**
+ * Parse Rekor in-toto entries back into statements and classify
+ * binding state (active / stale / revoked).
+ *
+ * This is the read-side counterpart of `statement.ts`/`submit.ts`:
+ * the `list` command and the badge service both consume entries the
+ * profile index points at, and neither may trust the index — every
+ * entry is integrity-checked against the hash Rekor recorded.
+ *
+ * Staleness (spec §10 row 1): a binding moves to `stale` 12 months
+ * after its Rekor inclusion time. `integratedTime` is authoritative;
+ * user-supplied dates in the index are display-only.
+ */
+
+import { base64ToBytes, bytesToUtf8, sha256Hex } from './encoding.js';
+import { type RekorEntryResponse } from './log/rekor.js';
+import {
+  IN_TOTO_STATEMENT_TYPE,
+  PASSPORTSIGN_REVOCATION_PREDICATE_TYPE,
+} from './statement.js';
+
+/** Spec §10 row 1: bindings move to `stale` after 12 months. */
+export const STALENESS_WINDOW_MS = 365 * 24 * 60 * 60 * 1000;
+
+export class EntryParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'EntryParseError';
+  }
+}
+
+/** Generic in-toto Statement v1 shape (predicate left untyped — callers narrow). */
+export interface InTotoStatement {
+  _type: typeof IN_TOTO_STATEMENT_TYPE;
+  subject: Array<{ name: string; digest: Record<string, string> }>;
+  predicateType: string;
+  predicate: unknown;
+}
+
+export interface ParsedIntotoEntry {
+  uuid: string;
+  /** Unix seconds — Rekor's authoritative inclusion time. */
+  integratedTime: number;
+  predicateType: string;
+  statement: InTotoStatement;
+}
+
+function fail(message: string): never {
+  throw new EntryParseError(message);
+}
+
+/**
+ * Decode a Rekor in-toto entry's stored attestation back into its
+ * statement, verifying the attestation bytes hash to the
+ * `payloadHash` Rekor recorded in the entry body. The hash check is
+ * what lets consumers trust an entry fetched via an untrusted index.
+ */
+export function parseIntotoEntry(entry: RekorEntryResponse): ParsedIntotoEntry {
+  const data = entry.attestation?.data;
+  if (typeof data !== 'string' || data.length === 0) {
+    fail(`entry ${entry.uuid}: no stored attestation`);
+  }
+  const decoded = (() => {
+    try {
+      return {
+        attestationBytes: base64ToBytes(data),
+        bodyObj: JSON.parse(bytesToUtf8(base64ToBytes(entry.body))) as unknown,
+      };
+    } catch {
+      fail(`entry ${entry.uuid}: attestation/body is not base64 JSON`);
+    }
+  })();
+  const { attestationBytes, bodyObj } = decoded;
+  const payloadHash = (
+    bodyObj as { spec?: { content?: { payloadHash?: { algorithm?: string; value?: string } } } }
+  )?.spec?.content?.payloadHash;
+  if (payloadHash?.algorithm !== 'sha256' || typeof payloadHash.value !== 'string') {
+    fail(`entry ${entry.uuid}: body has no sha256 payloadHash`);
+  }
+  const computed = sha256Hex(attestationBytes);
+  if (computed !== payloadHash.value) {
+    fail(
+      `entry ${entry.uuid}: attestation hash mismatch (computed ${computed}, recorded ${payloadHash.value})`,
+    );
+  }
+
+  let statement: unknown;
+  try {
+    statement = JSON.parse(bytesToUtf8(attestationBytes));
+  } catch {
+    fail(`entry ${entry.uuid}: attestation is not JSON`);
+  }
+  const s = statement as Partial<InTotoStatement>;
+  if (
+    s?._type !== IN_TOTO_STATEMENT_TYPE ||
+    !Array.isArray(s.subject) ||
+    typeof s.predicateType !== 'string'
+  ) {
+    fail(`entry ${entry.uuid}: attestation is not an in-toto Statement v1`);
+  }
+
+  return {
+    uuid: entry.uuid,
+    integratedTime: entry.integratedTime,
+    predicateType: s.predicateType,
+    statement: s as InTotoStatement,
+  };
+}
+
+export type BindingState = 'active' | 'stale' | 'revoked';
+
+export interface ClassifiedBinding {
+  entry: ParsedIntotoEntry;
+  state: BindingState;
+  /** UUID of the revocation entry that caused `revoked`, when applicable. */
+  revokedBy?: string;
+}
+
+export interface ClassifyBindingsInput {
+  bindings: ParsedIntotoEntry[];
+  revocations: ParsedIntotoEntry[];
+  /** Epoch milliseconds; defaults to the current time. */
+  now?: number;
+}
+
+function predicateField(entry: ParsedIntotoEntry, field: string): string | undefined {
+  const predicate = entry.statement.predicate;
+  if (typeof predicate !== 'object' || predicate === null) return undefined;
+  const value = (predicate as Record<string, unknown>)[field];
+  return typeof value === 'string' ? value : undefined;
+}
+
+/**
+ * Classify each binding:
+ * - `revoked` if a revocation entry (predicateType `…#revocation`)
+ *   carries the same `unique_identifier` and either targets this
+ *   binding's UUID via `revokes_rekor_entry_hash` or has no target
+ *   (revokes all bindings under that identifier);
+ * - else `stale` if older than {@link STALENESS_WINDOW_MS};
+ * - else `active`.
+ */
+export function classifyBindings(input: ClassifyBindingsInput): ClassifiedBinding[] {
+  const now = input.now ?? Date.now();
+  // Exact match, not endsWith — a foreign predicateType that happens to
+  // end in #revocation must never revoke a binding.
+  const revocations = input.revocations.filter(
+    (r) => r.predicateType === PASSPORTSIGN_REVOCATION_PREDICATE_TYPE,
+  );
+
+  return input.bindings.map((entry) => {
+    const uid = predicateField(entry, 'unique_identifier');
+    const revokedBy = revocations.find((r) => {
+      if (predicateField(r, 'unique_identifier') !== uid || uid === undefined) return false;
+      const target = predicateField(r, 'revokes_rekor_entry_hash');
+      return target === undefined || target === entry.uuid;
+    });
+    if (revokedBy) {
+      return { entry, state: 'revoked', revokedBy: revokedBy.uuid };
+    }
+    if (now - entry.integratedTime * 1000 > STALENESS_WINDOW_MS) {
+      return { entry, state: 'stale' };
+    }
+    return { entry, state: 'active' };
+  });
+}

package/src/dsse-common.ts

@@ -0,0 +1,45 @@
+/**
+ * Runtime-neutral DSSE pieces shared by the node signer (`dsse.ts`)
+ * and the WebCrypto signer (`dsse-web.ts`): the envelope shape and the
+ * Pre-Authentication Encoding.
+ */
+
+import { utf8ToBytes } from './encoding.js';
+
+export const DSSE_VERSION = 'DSSEv1';
+export const IN_TOTO_PAYLOAD_TYPE = 'application/vnd.in-toto+json';
+
+export interface DsseSignature {
+  /** Single-base64 of the raw signature bytes. */
+  sig: string;
+  /** PEM-encoded SubjectPublicKeyInfo. */
+  publicKey: string;
+  /** Optional key identifier. Omit (don't pass empty string) when not set. */
+  keyid?: string;
+}
+
+export interface DsseEnvelope {
+  /** Media type of the payload (e.g. `application/vnd.in-toto+json`). */
+  payloadType: string;
+  /** Single-base64 of the raw payload bytes. */
+  payload: string;
+  signatures: DsseSignature[];
+}
+
+/**
+ * DSSE Pre-Authentication Encoding (PAE):
+ *
+ *   "DSSEv1" SP LEN(type) SP type SP LEN(body) SP body
+ *
+ * Where SP is a single 0x20 space, LEN is the ASCII-decimal length of
+ * the following byte string.
+ */
+export function pae(type: string, body: Uint8Array): Uint8Array {
+  const typeBytes = utf8ToBytes(type);
+  const prefix = `${DSSE_VERSION} ${typeBytes.length} ${type} ${body.length} `;
+  const prefixBytes = utf8ToBytes(prefix);
+  const out = new Uint8Array(prefixBytes.length + body.length);
+  out.set(prefixBytes);
+  out.set(body, prefixBytes.length);
+  return out;
+}

package/src/dsse-web.ts

@@ -0,0 +1,97 @@
+/**
+ * WebCrypto variant of the DSSE envelope signer for runtimes without
+ * `node:crypto` sign APIs (browsers, edge workers). Same semantics as
+ * `dsse.ts`'s `signEnvelope`: ephemeral ECDSA P-256 key, discarded
+ * after signing; the signature is a Rekor schema requirement, not a
+ * trust mechanism.
+ *
+ * Two impedance mismatches with what Rekor expects, both handled here:
+ * - WebCrypto emits raw P1363 (`r || s`) signatures; Rekor needs DER.
+ * - WebCrypto exports SPKI as raw bytes; Rekor needs PEM text.
+ *
+ * The drift test in `test/dsse-web.test.ts` verifies output with
+ * `node:crypto.createVerify` so the two signers cannot diverge silently.
+ */
+
+import { bytesToBase64 } from './encoding.js';
+import { pae, type DsseEnvelope } from './dsse-common.js';
+
+export interface SignEnvelopeWebResult {
+  envelope: DsseEnvelope;
+  publicKeyPem: string;
+}
+
+/** Strip leading zero bytes, then re-add one if the high bit is set (DER INTEGER rule). */
+function derInteger(bytes: Uint8Array): Uint8Array {
+  let start = 0;
+  while (start < bytes.length - 1 && bytes[start] === 0) start++;
+  const trimmed = bytes.subarray(start);
+  if (trimmed[0]! & 0x80) {
+    const padded = new Uint8Array(trimmed.length + 1);
+    padded.set(trimmed, 1);
+    return padded;
+  }
+  return trimmed;
+}
+
+/** Convert a P1363 (r||s) ECDSA signature to DER SEQUENCE(INTEGER r, INTEGER s). */
+export function p1363ToDer(sig: Uint8Array): Uint8Array {
+  if (sig.length % 2 !== 0) {
+    throw new TypeError(`p1363ToDer: signature length ${sig.length} is not even`);
+  }
+  const half = sig.length / 2;
+  const r = derInteger(sig.subarray(0, half));
+  const s = derInteger(sig.subarray(half));
+  const body = new Uint8Array(2 + r.length + 2 + s.length);
+  body[0] = 0x02;
+  body[1] = r.length;
+  body.set(r, 2);
+  body[2 + r.length] = 0x02;
+  body[3 + r.length] = s.length;
+  body.set(s, 4 + r.length);
+  // P-256 DER bodies are < 128 bytes, so a single length byte suffices.
+  const out = new Uint8Array(2 + body.length);
+  out[0] = 0x30;
+  out[1] = body.length;
+  out.set(body, 2);
+  return out;
+}
+
+function spkiToPem(spki: Uint8Array): string {
+  const b64 = bytesToBase64(spki);
+  const lines = b64.match(/.{1,64}/g) ?? [];
+  return `-----BEGIN PUBLIC KEY-----\n${lines.join('\n')}\n-----END PUBLIC KEY-----\n`;
+}
+
+/**
+ * Generate an ephemeral ECDSA P-256 keypair via WebCrypto, sign
+ * PAE(payloadType, payload), and return a DSSE envelope. Async because
+ * WebCrypto is; otherwise interchangeable with `signEnvelope`.
+ */
+export async function signEnvelopeWeb(
+  payload: Uint8Array,
+  payloadType: string,
+): Promise<SignEnvelopeWebResult> {
+  const subtle = globalThis.crypto.subtle;
+  const keyPair = await subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, [
+    'sign',
+  ]);
+
+  const paeBytes = pae(payloadType, payload);
+  const rawSig = new Uint8Array(
+    await subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, keyPair.privateKey, paeBytes),
+  );
+  const derSig = p1363ToDer(rawSig);
+
+  const spki = new Uint8Array(await subtle.exportKey('spki', keyPair.publicKey));
+  const publicKeyPem = spkiToPem(spki);
+
+  return {
+    envelope: {
+      payloadType,
+      payload: bytesToBase64(payload),
+      signatures: [{ sig: bytesToBase64(derSig), publicKey: publicKeyPem }],
+    },
+    publicKeyPem,
+  };
+}

package/src/dsse.ts

@@ -1,91 +1,63 @@
-/**
- * DSSE (Dead Simple Signing Envelope) envelope builder.
- *
- * Per-binding ephemeral ECDSA P-256 key — the private key is discarded
- * after signing. The DSSE signature is a Rekor schema requirement, not
- * a trust mechanism. The actual authentication for passportsign comes
- * from the zkPassport proof + GitHub gist evidence carried inside the
- * statement's predicate, not from this signature.
- *
- * Spec: https://github.com/secure-systems-lab/dsse/blob/master/protocol.md
- *
- * Note on key algorithm choice: ECDSA P-256 over SHA-256 is what
- * Rekor's public instance accepts for intoto v0.0.2 entries. Ed25519
- * is in the DSSE spec but the public Rekor's verification path rejected
- * it during the Day 5 smoke test (500 "error generating canonicalized
- * entry"). See `docs/v0-acceptance.md` Day 5 evidence.
- */
-
-import { createSign, generateKeyPairSync } from 'node:crypto';
-
-export const DSSE_VERSION = 'DSSEv1';
-export const IN_TOTO_PAYLOAD_TYPE = 'application/vnd.in-toto+json';
-
-export interface DsseSignature {
-  /** Single-base64 of the raw signature bytes. */
-  sig: string;
-  /** PEM-encoded SubjectPublicKeyInfo. */
-  publicKey: string;
-  /** Optional key identifier. Omit (don't pass empty string) when not set. */
-  keyid?: string;
-}
-
-export interface DsseEnvelope {
-  /** Media type of the payload (e.g. `application/vnd.in-toto+json`). */
-  payloadType: string;
-  /** Single-base64 of the raw payload bytes. */
-  payload: string;
-  signatures: DsseSignature[];
-}
-
-/**
- * DSSE Pre-Authentication Encoding (PAE):
- *
- *   "DSSEv1" SP LEN(type) SP type SP LEN(body) SP body
- *
- * Where SP is a single 0x20 space, LEN is the ASCII-decimal length of
- * the following byte string.
- */
-export function pae(type: string, body: Uint8Array): Uint8Array {
-  const typeBytes = new TextEncoder().encode(type);
-  const prefix = `${DSSE_VERSION} ${typeBytes.length} ${type} ${body.length} `;
-  const prefixBytes = new TextEncoder().encode(prefix);
-  const out = new Uint8Array(prefixBytes.length + body.length);
-  out.set(prefixBytes);
-  out.set(body, prefixBytes.length);
-  return out;
-}
-
-export interface SignEnvelopeResult {
-  envelope: DsseEnvelope;
-  /** PEM of the ephemeral public key (also embedded in envelope.signatures[0].publicKey). */
-  publicKeyPem: string;
-}
-
-/**
- * Generate an ephemeral ECDSA P-256 keypair, sign PAE(payloadType,
- * payload), and return a DSSE envelope. The private key is discarded
- * before return.
- */
-export function signEnvelope(payload: Uint8Array, payloadType: string): SignEnvelopeResult {
-  const { privateKey, publicKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' });
-  const paeBytes = pae(payloadType, payload);
-  const signer = createSign('SHA256');
-  signer.update(Buffer.from(paeBytes));
-  const sigBuf = signer.sign(privateKey);
-  const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }) as string;
-
-  return {
-    envelope: {
-      payloadType,
-      payload: Buffer.from(payload).toString('base64'),
-      signatures: [
-        {
-          sig: sigBuf.toString('base64'),
-          publicKey: publicKeyPem,
-        },
-      ],
-    },
-    publicKeyPem,
-  };
-}
+/**
+ * DSSE (Dead Simple Signing Envelope) envelope builder.
+ *
+ * Per-binding ephemeral ECDSA P-256 key — the private key is discarded
+ * after signing. The DSSE signature is a Rekor schema requirement, not
+ * a trust mechanism. The actual authentication for passportsign comes
+ * from the zkPassport proof + GitHub gist evidence carried inside the
+ * statement's predicate, not from this signature.
+ *
+ * Spec: https://github.com/secure-systems-lab/dsse/blob/master/protocol.md
+ *
+ * Note on key algorithm choice: ECDSA P-256 over SHA-256 is what
+ * Rekor's public instance accepts for intoto v0.0.2 entries. Ed25519
+ * is in the DSSE spec but the public Rekor's verification path rejected
+ * it during the Day 5 smoke test (500 "error generating canonicalized
+ * entry"). See `docs/v0-acceptance.md` Day 5 evidence.
+ */
+
+import { createSign, generateKeyPairSync } from 'node:crypto';
+
+import { pae, type DsseEnvelope } from './dsse-common.js';
+
+export {
+  DSSE_VERSION,
+  IN_TOTO_PAYLOAD_TYPE,
+  pae,
+  type DsseEnvelope,
+  type DsseSignature,
+} from './dsse-common.js';
+
+export interface SignEnvelopeResult {
+  envelope: DsseEnvelope;
+  /** PEM of the ephemeral public key (also embedded in envelope.signatures[0].publicKey). */
+  publicKeyPem: string;
+}
+
+/**
+ * Generate an ephemeral ECDSA P-256 keypair, sign PAE(payloadType,
+ * payload), and return a DSSE envelope. The private key is discarded
+ * before return.
+ */
+export function signEnvelope(payload: Uint8Array, payloadType: string): SignEnvelopeResult {
+  const { privateKey, publicKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' });
+  const paeBytes = pae(payloadType, payload);
+  const signer = createSign('SHA256');
+  signer.update(Buffer.from(paeBytes));
+  const sigBuf = signer.sign(privateKey);
+  const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }) as string;
+
+  return {
+    envelope: {
+      payloadType,
+      payload: Buffer.from(payload).toString('base64'),
+      signatures: [
+        {
+          sig: sigBuf.toString('base64'),
+          publicKey: publicKeyPem,
+        },
+      ],
+    },
+    publicKeyPem,
+  };
+}

package/src/encoding.ts

@@ -0,0 +1,96 @@
+/**
+ * Runtime-neutral byte/string primitives.
+ *
+ * Every module that needs hashing or hex/base64 goes through here so
+ * the rest of core has no `node:crypto` / `Buffer` dependency and runs
+ * unchanged on Node, Cloudflare Workers, and browsers. SHA-256 comes
+ * from `@noble/hashes` (pure JS, synchronous — WebCrypto's async
+ * digest would force async signatures through the whole verify path).
+ */
+
+import { sha256 } from '@noble/hashes/sha256';
+
+const HEX_CHARS = '0123456789abcdef';
+
+export function bytesToHex(bytes: Uint8Array): string {
+  let out = '';
+  for (const b of bytes) {
+    out += HEX_CHARS[b >> 4]! + HEX_CHARS[b & 0x0f]!;
+  }
+  return out;
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(hex)) {
+    throw new TypeError(`hexToBytes: invalid hex string (length ${hex.length})`);
+  }
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+const B64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const B64_LOOKUP: Record<string, number> = {};
+for (let i = 0; i < B64_ALPHABET.length; i++) B64_LOOKUP[B64_ALPHABET[i]!] = i;
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  let out = '';
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i]!;
+    const b1 = i + 1 < bytes.length ? bytes[i + 1]! : 0;
+    const b2 = i + 2 < bytes.length ? bytes[i + 2]! : 0;
+    out += B64_ALPHABET[b0 >> 2]!;
+    out += B64_ALPHABET[((b0 & 0x03) << 4) | (b1 >> 4)]!;
+    out += i + 1 < bytes.length ? B64_ALPHABET[((b1 & 0x0f) << 2) | (b2 >> 6)]! : '=';
+    out += i + 2 < bytes.length ? B64_ALPHABET[b2 & 0x3f]! : '=';
+  }
+  return out;
+}
+
+export function base64ToBytes(b64: string): Uint8Array {
+  if (b64.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(b64)) {
+    throw new TypeError('base64ToBytes: invalid base64 string');
+  }
+  const padding = b64.endsWith('==') ? 2 : b64.endsWith('=') ? 1 : 0;
+  const byteLength = (b64.length / 4) * 3 - padding;
+  const out = new Uint8Array(byteLength);
+  let outIdx = 0;
+  for (let i = 0; i < b64.length; i += 4) {
+    const c0 = B64_LOOKUP[b64[i]!]!;
+    const c1 = B64_LOOKUP[b64[i + 1]!]!;
+    const c2 = b64[i + 2] === '=' ? 0 : B64_LOOKUP[b64[i + 2]!]!;
+    const c3 = b64[i + 3] === '=' ? 0 : B64_LOOKUP[b64[i + 3]!]!;
+    if (outIdx < byteLength) out[outIdx++] = (c0 << 2) | (c1 >> 4);
+    if (outIdx < byteLength) out[outIdx++] = ((c1 & 0x0f) << 4) | (c2 >> 2);
+    if (outIdx < byteLength) out[outIdx++] = ((c2 & 0x03) << 6) | c3;
+  }
+  return out;
+}
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+export function utf8ToBytes(s: string): Uint8Array {
+  return textEncoder.encode(s);
+}
+
+export function bytesToUtf8(bytes: Uint8Array): string {
+  return textDecoder.decode(bytes);
+}
+
+export function sha256Bytes(bytes: Uint8Array): Uint8Array {
+  return sha256(bytes);
+}
+
+export function sha256Hex(bytes: Uint8Array): string {
+  return bytesToHex(sha256(bytes));
+}
+
+/** Cryptographically secure random bytes via the platform's WebCrypto. */
+export function randomBytes(length: number): Uint8Array {
+  const out = new Uint8Array(length);
+  globalThis.crypto.getRandomValues(out);
+  return out;
+}