@dwk/vc 0.1.0-beta.0

package/src/log.ts

@@ -0,0 +1,35 @@
+/**
+ * `@dwk/vc` — structured observability event taxonomy.
+ *
+ * Credential issuance and status changes are the security-relevant moments here:
+ * an unauthorized issue attempt, a verification that fails its proof, or a
+ * revocation are exactly what an operator wants a signal for. Logging and metrics
+ * are opt-in via an injected {@link Logger} and {@link Metrics} (see `@dwk/log`)
+ * and **share this one vocabulary**: the same dotted event name is passed to the
+ * logger and the metrics sink so a log line and its counter line up.
+ *
+ * Fields follow the redaction policy: never the credential subject, claims, the
+ * signing key, or a `proofValue` — only stable reason codes, a credential `type`
+ * count or list, the issuer host, and the status purpose/outcome.
+ *
+ * @packageDocumentation
+ */
+
+/** Stable event names emitted by `@dwk/vc`. */
+export const VcLogEvent = {
+  /** A credential was issued (signed). Fields: `cryptosuite`. */
+  Issued: "vc.issued",
+  /** A credential was verified. Fields: `verified` (boolean). */
+  Verified: "vc.verified",
+  /** A credential's status was changed. Fields: `statusPurpose`, `value`. */
+  StatusChanged: "vc.status.changed",
+  /**
+   * A request was rejected before completing. Field: `reason`
+   * (`method_not_allowed`, `unauthorized`, `malformed_request`,
+   * `unsupported`, `status_disabled`, `not_found`).
+   */
+  Rejected: "vc.rejected",
+} as const;
+
+/** Union of the event-name string literals in {@link VcLogEvent}. */
+export type VcLogEvent = (typeof VcLogEvent)[keyof typeof VcLogEvent];

package/src/multibase.ts

@@ -0,0 +1,189 @@
+/**
+ * Multibase / Multikey encoding primitives used by Verifiable Credential proofs
+ * and DID documents.
+ *
+ * Data Integrity proof values are **multibase base58-btc** strings (a leading
+ * `z`), and a `Multikey` verification method publishes its public key as a
+ * multibase base58-btc string over a **multicodec**-prefixed raw key. Status
+ * lists are **multibase base64url** (a leading `u`). These helpers are pure
+ * byte/string transforms with no Web Crypto or runtime dependency, so they
+ * unit-test in isolation.
+ *
+ * @see https://www.w3.org/TR/controller-document/#multikey
+ * @see https://github.com/multiformats/multibase
+ */
+
+const BASE58_ALPHABET =
+  "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+
+// Reverse lookup: code point → value, built once.
+const BASE58_LOOKUP: Readonly<Record<string, number>> = (() => {
+  const map: Record<string, number> = {};
+  for (let i = 0; i < BASE58_ALPHABET.length; i++) {
+    map[BASE58_ALPHABET[i]!] = i;
+  }
+  return map;
+})();
+
+/** Multibase prefix characters this module understands. */
+export const MULTIBASE_BASE58BTC = "z";
+export const MULTIBASE_BASE64URL = "u";
+
+/**
+ * Multicodec varint prefixes for the key types published as a `Multikey`.
+ * Encoded as unsigned LEB128 varints (the on-disk multicodec form).
+ */
+export const MULTICODEC_ED25519_PUB = Uint8Array.of(0xed, 0x01);
+
+/** Encode raw bytes as base58-btc (no multibase prefix). */
+export function base58btcEncode(bytes: Uint8Array): string {
+  if (bytes.length === 0) return "";
+
+  // Count and preserve leading zero bytes as leading '1's.
+  let zeros = 0;
+  while (zeros < bytes.length && bytes[zeros] === 0) zeros++;
+
+  // Convert the base-256 big-endian integer to base-58 via repeated division.
+  const digits: number[] = [];
+  for (let i = zeros; i < bytes.length; i++) {
+    let carry = bytes[i]!;
+    for (let j = 0; j < digits.length; j++) {
+      carry += digits[j]! << 8;
+      digits[j] = carry % 58;
+      carry = (carry / 58) | 0;
+    }
+    while (carry > 0) {
+      digits.push(carry % 58);
+      carry = (carry / 58) | 0;
+    }
+  }
+
+  let out = "1".repeat(zeros);
+  for (let i = digits.length - 1; i >= 0; i--) {
+    out += BASE58_ALPHABET[digits[i]!];
+  }
+  return out;
+}
+
+/** Decode a base58-btc string (no multibase prefix) to raw bytes. */
+export function base58btcDecode(input: string): Uint8Array {
+  if (input.length === 0) return new Uint8Array(0);
+
+  let zeros = 0;
+  while (zeros < input.length && input[zeros] === "1") zeros++;
+
+  const bytes: number[] = [];
+  for (let i = zeros; i < input.length; i++) {
+    const value = BASE58_LOOKUP[input[i]!];
+    if (value === undefined) {
+      throw new Error(`@dwk/vc: invalid base58 character "${input[i]}"`);
+    }
+    let carry = value;
+    for (let j = 0; j < bytes.length; j++) {
+      carry += bytes[j]! * 58;
+      bytes[j] = carry & 0xff;
+      carry >>= 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 0xff);
+      carry >>= 8;
+    }
+  }
+
+  const out = new Uint8Array(zeros + bytes.length);
+  for (let i = 0; i < bytes.length; i++) {
+    out[zeros + bytes.length - 1 - i] = bytes[i]!;
+  }
+  return out;
+}
+
+/** Base64url-encode bytes without padding. */
+export function base64urlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+/** Decode a base64url string (padded or not) to bytes. */
+export function base64urlDecode(input: string): Uint8Array {
+  const b64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded =
+    b64.length % 4 === 0 ? b64 : b64 + "=".repeat(4 - (b64.length % 4));
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** Encode bytes as a multibase base58-btc string (`z…`). */
+export function encodeMultibaseBase58btc(bytes: Uint8Array): string {
+  return MULTIBASE_BASE58BTC + base58btcEncode(bytes);
+}
+
+/** Encode bytes as a multibase base64url string (`u…`). */
+export function encodeMultibaseBase64url(bytes: Uint8Array): string {
+  return MULTIBASE_BASE64URL + base64urlEncode(bytes);
+}
+
+/**
+ * Decode a multibase string, dispatching on its prefix. Supports base58-btc
+ * (`z`) and base64url (`u`) — the two encodings the VC suite emits.
+ */
+export function decodeMultibase(input: string): Uint8Array {
+  if (input.length === 0) {
+    throw new Error("@dwk/vc: empty multibase value");
+  }
+  const prefix = input[0];
+  const rest = input.slice(1);
+  if (prefix === MULTIBASE_BASE58BTC) return base58btcDecode(rest);
+  if (prefix === MULTIBASE_BASE64URL) return base64urlDecode(rest);
+  throw new Error(`@dwk/vc: unsupported multibase prefix "${prefix ?? ""}"`);
+}
+
+/**
+ * Encode a raw Ed25519 public key (32 bytes) as a `Multikey`
+ * `publicKeyMultibase` value: multibase base58-btc over the
+ * multicodec-prefixed key.
+ */
+export function encodeEd25519Multikey(rawPublicKey: Uint8Array): string {
+  if (rawPublicKey.length !== 32) {
+    throw new Error(
+      `@dwk/vc: Ed25519 public key must be 32 bytes, got ${rawPublicKey.length}`,
+    );
+  }
+  const prefixed = new Uint8Array(
+    MULTICODEC_ED25519_PUB.length + rawPublicKey.length,
+  );
+  prefixed.set(MULTICODEC_ED25519_PUB, 0);
+  prefixed.set(rawPublicKey, MULTICODEC_ED25519_PUB.length);
+  return encodeMultibaseBase58btc(prefixed);
+}
+
+/** The raw key bytes and key type recovered from a `publicKeyMultibase`. */
+export interface DecodedMultikey {
+  readonly keyType: "Ed25519";
+  readonly rawPublicKey: Uint8Array;
+}
+
+/**
+ * Decode a `Multikey` `publicKeyMultibase` value into its raw key bytes,
+ * validating the multicodec prefix. Only Ed25519 is supported as a Multikey;
+ * other key types are published as `publicKeyJwk` instead.
+ */
+export function decodeMultikey(publicKeyMultibase: string): DecodedMultikey {
+  const bytes = decodeMultibase(publicKeyMultibase);
+  if (
+    bytes.length === MULTICODEC_ED25519_PUB.length + 32 &&
+    bytes[0] === MULTICODEC_ED25519_PUB[0] &&
+    bytes[1] === MULTICODEC_ED25519_PUB[1]
+  ) {
+    return {
+      keyType: "Ed25519",
+      rawPublicKey: bytes.slice(MULTICODEC_ED25519_PUB.length),
+    };
+  }
+  throw new Error("@dwk/vc: unsupported or malformed Multikey prefix");
+}

package/src/status-list.ts

@@ -0,0 +1,356 @@
+/**
+ * Bitstring Status List support: the encoded-list codec, credential/entry
+ * builders, and a D1-backed authority for flipping a credential's status.
+ *
+ * A status list is a GZIP-compressed bitstring, multibase base64url-encoded,
+ * published inside a `BitstringStatusListCredential`. A credential opts in by
+ * carrying a `BitstringStatusListEntry` that points at a list and an index;
+ * verifiers read the bit at that index. Flipping a bit (revoking, suspending) is
+ * stateful and security-sensitive, so the authoritative bits live in **D1** — a
+ * strongly-consistent store — never KV (see `spec/non-functional-requirements.md`).
+ *
+ * The codec and builders are pure (GZIP via `CompressionStream`, available under
+ * both Node and workerd); only {@link createVcStatusStore} touches a binding.
+ *
+ * @see https://www.w3.org/TR/vc-bitstring-status-list/
+ */
+
+import { toXsdDateTime } from "./datetime";
+import type { JcsValue } from "./jcs";
+import type { JsonObject } from "./data-integrity";
+import { decodeMultibase, encodeMultibaseBase64url } from "./multibase";
+
+/**
+ * The minimum bitstring length the spec mandates (131,072 bits / 16 KB), chosen
+ * so an individual entry's index does not leak which credential it refers to.
+ */
+export const DEFAULT_STATUS_LIST_LENGTH = 131072;
+
+export const BITSTRING_STATUS_LIST_CREDENTIAL_TYPE =
+  "BitstringStatusListCredential";
+export const BITSTRING_STATUS_LIST_ENTRY_TYPE = "BitstringStatusListEntry";
+export const BITSTRING_STATUS_LIST_SUBJECT_TYPE = "BitstringStatusList";
+
+/** A status purpose. `revocation` is permanent; `suspension` is reversible. */
+export type StatusPurpose = "revocation" | "suspension" | (string & {});
+
+/**
+ * A `statusPurpose` value as it appears on a credential or entry. The Bitstring
+ * Status List spec allows "one or more" purposes, so a single purpose or an
+ * array of them are both valid.
+ */
+export type StatusPurposeValue = StatusPurpose | readonly StatusPurpose[];
+
+/** Emit a `statusPurpose` as plain data (a mutable array when one was given). */
+function statusPurposeValue(purpose: StatusPurposeValue): JcsValue {
+  return Array.isArray(purpose) ? [...purpose] : (purpose as StatusPurpose);
+}
+
+/** Whether `purpose` (a `statusPurpose` field) covers `wanted`. */
+function statusPurposeMatches(
+  purpose: JcsValue | undefined,
+  wanted: StatusPurpose,
+): boolean {
+  return Array.isArray(purpose) ? purpose.includes(wanted) : purpose === wanted;
+}
+
+/** Get the bit at `index` in a most-significant-bit-first bitstring. */
+export function getBit(bits: Uint8Array, index: number): boolean {
+  if (index < 0) return false;
+  const byteIndex = index >> 3;
+  if (byteIndex >= bits.length) return false;
+  const bit = 7 - (index & 7);
+  return ((bits[byteIndex]! >> bit) & 1) === 1;
+}
+
+/** Set the bit at `index` in a most-significant-bit-first bitstring. */
+export function setBit(bits: Uint8Array, index: number, value: boolean): void {
+  // A negative index shifts to a negative byteIndex, which would slip past the
+  // upper-bound check, so guard both ends explicitly.
+  const byteIndex = index >> 3;
+  if (index < 0 || byteIndex >= bits.length) {
+    throw new Error(`@dwk/vc: status index ${index} is out of range`);
+  }
+  const bit = 7 - (index & 7);
+  if (value) {
+    bits[byteIndex]! |= 1 << bit;
+  } else {
+    bits[byteIndex]! &= ~(1 << bit);
+  }
+}
+
+async function gzip(input: Uint8Array): Promise<Uint8Array> {
+  const stream = new Response(input).body!.pipeThrough(
+    new CompressionStream("gzip"),
+  );
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+async function gunzip(input: Uint8Array): Promise<Uint8Array> {
+  const stream = new Response(input).body!.pipeThrough(
+    new DecompressionStream("gzip"),
+  );
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+/** GZIP-compress a bitstring and multibase base64url-encode it (`encodedList`). */
+export async function encodeBitstring(bits: Uint8Array): Promise<string> {
+  return encodeMultibaseBase64url(await gzip(bits));
+}
+
+/** Decode an `encodedList` (multibase base64url + GZIP) back to its bitstring. */
+export async function decodeBitstring(
+  encodedList: string,
+): Promise<Uint8Array> {
+  return gunzip(decodeMultibase(encodedList));
+}
+
+/**
+ * Build an `encodedList` of `length` bits with the given indices set to 1.
+ * `length` is the bit count (rounded up to whole bytes).
+ */
+export async function buildEncodedList(
+  setIndices: Iterable<number>,
+  length: number = DEFAULT_STATUS_LIST_LENGTH,
+): Promise<string> {
+  const bits = new Uint8Array(Math.ceil(length / 8));
+  for (const index of setIndices) setBit(bits, index, true);
+  return encodeBitstring(bits);
+}
+
+/** Options for {@link buildStatusListCredential}. */
+export interface StatusListCredentialOptions {
+  /** The status list credential's id (a URL). */
+  readonly id: string;
+  /** The status purpose(s) this list tracks (one or more). */
+  readonly statusPurpose: StatusPurposeValue;
+  /** The pre-built `encodedList` value. */
+  readonly encodedList: string;
+  /** The issuer (string or object with id). */
+  readonly issuer: string | (JsonObject & { id: string });
+  /** `validFrom` (XSD dateTime). Defaults to now when omitted. */
+  readonly validFrom?: Date | string;
+  /**
+   * `validUntil` (XSD dateTime). Bounds how long a verifier may treat the
+   * cached status as authoritative.
+   */
+  readonly validUntil?: Date | string;
+  /**
+   * Cache time-to-live in milliseconds, advertised on both the credential and
+   * its status-list subject so verifiers can bound status caching.
+   */
+  readonly ttl?: number;
+}
+
+/**
+ * Assemble an **unsigned** `BitstringStatusListCredential`. The caller signs it
+ * with {@link ./data-integrity.addProof} before publishing.
+ *
+ * Per the Bitstring Status List spec, `validFrom`/`validUntil`/`ttl` bound how
+ * long the published status may be cached; `validUntil` and `ttl` are emitted on
+ * the credential (and `ttl` also on the subject) when supplied.
+ */
+export function buildStatusListCredential(
+  options: StatusListCredentialOptions,
+): JsonObject {
+  const subject: JsonObject = {
+    id: `${options.id}#list`,
+    type: BITSTRING_STATUS_LIST_SUBJECT_TYPE,
+    statusPurpose: statusPurposeValue(options.statusPurpose),
+    encodedList: options.encodedList,
+  };
+  if (options.ttl !== undefined) subject.ttl = options.ttl;
+  const credential: JsonObject = {
+    "@context": ["https://www.w3.org/ns/credentials/v2"],
+    id: options.id,
+    type: ["VerifiableCredential", BITSTRING_STATUS_LIST_CREDENTIAL_TYPE],
+    issuer: options.issuer,
+    validFrom: toXsdDateTime(options.validFrom ?? new Date()),
+    credentialSubject: subject,
+  };
+  if (options.validUntil !== undefined) {
+    credential.validUntil = toXsdDateTime(options.validUntil);
+  }
+  if (options.ttl !== undefined) credential.ttl = options.ttl;
+  return credential;
+}
+
+/** Build a `credentialStatus` entry referencing a list index. */
+export function buildStatusEntry(options: {
+  readonly statusListCredential: string;
+  readonly statusListIndex: number;
+  readonly statusPurpose: StatusPurposeValue;
+  readonly id?: string;
+}): JsonObject {
+  return {
+    id:
+      options.id ??
+      `${options.statusListCredential}#${options.statusListIndex}`,
+    type: BITSTRING_STATUS_LIST_ENTRY_TYPE,
+    statusPurpose: statusPurposeValue(options.statusPurpose),
+    statusListIndex: String(options.statusListIndex),
+    statusListCredential: options.statusListCredential,
+  };
+}
+
+/** Read a `statusListIndex` from a credential's `credentialStatus` entry. */
+export function statusEntryIndex(entry: JsonObject): number | undefined {
+  const raw = entry.statusListIndex;
+  const value = typeof raw === "string" ? Number(raw) : raw;
+  return typeof value === "number" && Number.isInteger(value) && value >= 0
+    ? value
+    : undefined;
+}
+
+/** Locate a `credentialStatus` entry for a purpose on a credential. */
+export function findStatusEntry(
+  credential: JsonObject,
+  statusPurpose: StatusPurpose,
+): JsonObject | undefined {
+  const status = credential.credentialStatus;
+  const entries: JcsValue[] = Array.isArray(status)
+    ? status
+    : status === undefined
+      ? []
+      : [status];
+  for (const entry of entries) {
+    if (
+      entry !== null &&
+      typeof entry === "object" &&
+      !Array.isArray(entry) &&
+      statusPurposeMatches((entry as JsonObject).statusPurpose, statusPurpose)
+    ) {
+      return entry as JsonObject;
+    }
+  }
+  return undefined;
+}
+
+/** Cloudflare bindings required by the D1-backed status store. */
+export interface VcStatusStoreEnv {
+  /** D1 database holding per-list status bits and index allocations. */
+  readonly VC_STATUS_DB: D1Database;
+}
+
+/** Authoritative store for credential status bits, backed by D1. */
+export interface VcStatusStore {
+  /** Create the schema if absent. Idempotent. */
+  init(): Promise<void>;
+  /** Allocate and return the next unused index for a list + purpose. */
+  allocateIndex(listId: string, statusPurpose: StatusPurpose): Promise<number>;
+  /** Set the status bit at an index (e.g. revoke). */
+  setStatus(
+    listId: string,
+    statusPurpose: StatusPurpose,
+    index: number,
+    value: boolean,
+  ): Promise<void>;
+  /** Read the status bit at an index (defaults to `false`/unset). */
+  getStatus(
+    listId: string,
+    statusPurpose: StatusPurpose,
+    index: number,
+  ): Promise<boolean>;
+  /** The set (value-1) indices for a list + purpose, ascending. */
+  setIndices(listId: string, statusPurpose: StatusPurpose): Promise<number[]>;
+}
+
+const SCHEMA = [
+  `CREATE TABLE IF NOT EXISTS status_entries (
+     list_id TEXT NOT NULL,
+     status_purpose TEXT NOT NULL,
+     idx INTEGER NOT NULL,
+     value INTEGER NOT NULL DEFAULT 0,
+     PRIMARY KEY (list_id, status_purpose, idx)
+   )`,
+  `CREATE TABLE IF NOT EXISTS status_allocations (
+     list_id TEXT NOT NULL,
+     status_purpose TEXT NOT NULL,
+     next_index INTEGER NOT NULL,
+     PRIMARY KEY (list_id, status_purpose)
+   )`,
+] as const;
+
+/**
+ * Create the D1-backed {@link VcStatusStore}. Fails loudly if the required
+ * `VC_STATUS_DB` binding is missing — no silent degradation (composition
+ * contract).
+ */
+export function createVcStatusStore(env: VcStatusStoreEnv): VcStatusStore {
+  if (!env.VC_STATUS_DB) {
+    throw new Error("@dwk/vc: missing required D1 binding `VC_STATUS_DB`");
+  }
+  const db = env.VC_STATUS_DB;
+
+  return {
+    async init() {
+      for (const ddl of SCHEMA) await db.prepare(ddl).run();
+    },
+
+    async allocateIndex(listId, statusPurpose) {
+      // Atomically bump the per-list counter and read it back, so concurrent
+      // allocations never hand out the same index.
+      const row = await db
+        .prepare(
+          `INSERT INTO status_allocations (list_id, status_purpose, next_index)
+             VALUES (?, ?, 1)
+           ON CONFLICT (list_id, status_purpose)
+             DO UPDATE SET next_index = next_index + 1
+           RETURNING next_index`,
+        )
+        .bind(listId, statusPurpose)
+        .first<{ next_index: number }>();
+      // next_index now points past the allocated slot; the slot is one below.
+      return (row?.next_index ?? 1) - 1;
+    },
+
+    async setStatus(listId, statusPurpose, index, value) {
+      // Only set (value-1) bits are stored; clearing a bit deletes the row so the
+      // table stays sparse (one row per set bit) rather than accumulating
+      // value-0 tombstones. `getStatus`/`setIndices` already treat a missing row
+      // as unset.
+      if (value) {
+        await db
+          .prepare(
+            `INSERT INTO status_entries (list_id, status_purpose, idx, value)
+               VALUES (?, ?, ?, 1)
+             ON CONFLICT (list_id, status_purpose, idx)
+               DO UPDATE SET value = 1`,
+          )
+          .bind(listId, statusPurpose, index)
+          .run();
+      } else {
+        await db
+          .prepare(
+            `DELETE FROM status_entries
+             WHERE list_id = ? AND status_purpose = ? AND idx = ?`,
+          )
+          .bind(listId, statusPurpose, index)
+          .run();
+      }
+    },
+
+    async getStatus(listId, statusPurpose, index) {
+      const row = await db
+        .prepare(
+          `SELECT value FROM status_entries
+           WHERE list_id = ? AND status_purpose = ? AND idx = ?`,
+        )
+        .bind(listId, statusPurpose, index)
+        .first<{ value: number }>();
+      return row?.value === 1;
+    },
+
+    async setIndices(listId, statusPurpose) {
+      const result = await db
+        .prepare(
+          `SELECT idx FROM status_entries
+           WHERE list_id = ? AND status_purpose = ? AND value = 1
+           ORDER BY idx ASC`,
+        )
+        .bind(listId, statusPurpose)
+        .all<{ idx: number }>();
+      return (result.results ?? []).map((r) => r.idx);
+    },
+  };
+}