@dwk/vc 0.1.0-beta.0

package/dist/status-list.d.ts.map

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

package/dist/status-list.js

@@ -0,0 +1,241 @@
+/**
+ * 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 { 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";
+/** Emit a `statusPurpose` as plain data (a mutable array when one was given). */
+function statusPurposeValue(purpose) {
+    return Array.isArray(purpose) ? [...purpose] : purpose;
+}
+/** Whether `purpose` (a `statusPurpose` field) covers `wanted`. */
+function statusPurposeMatches(purpose, wanted) {
+    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, index) {
+    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, index, value) {
+    // 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) {
+    const stream = new Response(input).body.pipeThrough(new CompressionStream("gzip"));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+async function gunzip(input) {
+    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) {
+    return encodeMultibaseBase64url(await gzip(bits));
+}
+/** Decode an `encodedList` (multibase base64url + GZIP) back to its bitstring. */
+export async function decodeBitstring(encodedList) {
+    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, length = DEFAULT_STATUS_LIST_LENGTH) {
+    const bits = new Uint8Array(Math.ceil(length / 8));
+    for (const index of setIndices)
+        setBit(bits, index, true);
+    return encodeBitstring(bits);
+}
+/**
+ * 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) {
+    const subject = {
+        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 = {
+        "@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) {
+    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) {
+    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, statusPurpose) {
+    const status = credential.credentialStatus;
+    const entries = Array.isArray(status)
+        ? status
+        : status === undefined
+            ? []
+            : [status];
+    for (const entry of entries) {
+        if (entry !== null &&
+            typeof entry === "object" &&
+            !Array.isArray(entry) &&
+            statusPurposeMatches(entry.statusPurpose, statusPurpose)) {
+            return entry;
+        }
+    }
+    return undefined;
+}
+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)
+   )`,
+];
+/**
+ * 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) {
+    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 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();
+            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();
+            return (result.results ?? []).map((r) => r.idx);
+        },
+    };
+}
+//# sourceMappingURL=status-list.js.map

package/dist/status-list.js.map

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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@dwk/vc",
+  "version": "0.1.0-beta.0",
+  "description": "did:web identity plus Verifiable Credential (VCDM 2.0) issuance, verification, and Bitstring Status List revocation.",
+  "keywords": [
+    "verifiable-credentials",
+    "vc",
+    "did",
+    "did-web",
+    "data-integrity",
+    "decentralized-identity",
+    "cloudflare-workers"
+  ],
+  "type": "module",
+  "license": "ISC",
+  "author": "David W. Keith <me@dwk.io>",
+  "homepage": "https://github.com/davidwkeith/workers/tree/main/packages/vc#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidwkeith/workers.git",
+    "directory": "packages/vc"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dwk/log": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}

package/src/config.ts

@@ -0,0 +1,158 @@
+/**
+ * Configuration for {@link ./handler.createVc}: the issuer DID and verification
+ * method, the dynamic endpoint URLs, the (optional) status-list policy, and the
+ * delegated authorization and DID-resolution hooks. Per the composition contract
+ * the package never reads the global environment — every tunable arrives here and
+ * signing-key material arrives via a secret binding — so a handler can be
+ * instantiated multiple times and tested in isolation.
+ */
+
+import { noopLogger, noopMetrics, type Logger, type Metrics } from "@dwk/log";
+
+import type { VerificationMethod } from "./data-integrity";
+import { urlToDidWeb } from "./did-web";
+import { DEFAULT_STATUS_LIST_LENGTH, type StatusPurpose } from "./status-list";
+
+/** A mutating operation an {@link AuthorizeOperation} hook can gate. */
+export type VcOperation = "issue" | "status";
+
+/**
+ * Authorization hook for the mutating endpoints (issue, status). Return `true`
+ * to allow. When omitted, requests are allowed through — the composing Worker is
+ * the front door and owns edge token validation (see `spec/architecture.md`);
+ * supply this to enforce authorization inside the package as well.
+ */
+export type AuthorizeOperation = (
+  operation: VcOperation,
+  request: Request,
+) => boolean | Promise<boolean>;
+
+/** Resolve a verification-method id to its key document, or `undefined`. */
+export type DidResolver = (
+  id: string,
+) => VerificationMethod | undefined | Promise<VerificationMethod | undefined>;
+
+/** Status-list policy. */
+export interface StatusConfig {
+  /** Enable the status endpoints and `credentialStatus` issuance. */
+  readonly enabled: boolean;
+  /** The status purpose lists track. Defaults to `"revocation"`. */
+  readonly statusPurpose?: StatusPurpose;
+  /** Bit length of each status list. Defaults to {@link DEFAULT_STATUS_LIST_LENGTH}. */
+  readonly listLength?: number;
+}
+
+/** Configuration passed to {@link ./handler.createVc}. */
+export interface VcConfig {
+  /** The identity root / base URL (e.g. `https://example.com`). */
+  readonly baseUrl: string;
+  /** The issuer DID. Defaults to the `did:web` derived from `baseUrl`. */
+  readonly did?: string;
+  /**
+   * The verification method id used to sign credentials (e.g.
+   * `did:web:example.com#key-0`). Defaults to `${did}#key-0`.
+   */
+  readonly verificationMethod?: string;
+  /** Absolute issuance endpoint. Defaults to `${baseUrl}/credentials/issue`. */
+  readonly issueEndpoint?: string;
+  /** Absolute verification endpoint. Defaults to `${baseUrl}/credentials/verify`. */
+  readonly verifyEndpoint?: string;
+  /** Absolute status-update endpoint. Defaults to `${baseUrl}/credentials/status`. */
+  readonly statusEndpoint?: string;
+  /**
+   * Absolute base URL under which signed status list credentials are served. A
+   * request to `${statusListEndpoint}/<listId>` returns that list. Defaults to
+   * `${baseUrl}/credentials/status-lists`.
+   */
+  readonly statusListEndpoint?: string;
+  /** Status-list policy. Disabled by default. */
+  readonly status?: StatusConfig;
+  /** Authorization hook for issue/status (see {@link AuthorizeOperation}). */
+  readonly authorize?: AuthorizeOperation;
+  /**
+   * Verification-method resolver used during verification. Defaults to a
+   * `did:web` resolver over the global `fetch`.
+   */
+  readonly resolveDid?: DidResolver;
+  /** Logger; defaults to a no-op. */
+  readonly logger?: Logger;
+  /** Metrics sink; defaults to a no-op. */
+  readonly metrics?: Metrics;
+}
+
+/** Fully resolved configuration with defaults applied and URLs parsed. */
+export interface ResolvedVcConfig {
+  readonly did: string;
+  readonly verificationMethod: string;
+  readonly issueEndpoint: string;
+  readonly verifyEndpoint: string;
+  readonly statusEndpoint: string;
+  readonly statusListEndpoint: string;
+  readonly issuePath: string;
+  readonly verifyPath: string;
+  readonly statusPath: string;
+  readonly statusListPath: string;
+  readonly statusEnabled: boolean;
+  readonly statusPurpose: StatusPurpose;
+  readonly statusListLength: number;
+  readonly authorize: AuthorizeOperation;
+  readonly resolveDid?: DidResolver;
+  readonly logger: Logger;
+  readonly metrics: Metrics;
+}
+
+function pathOf(absoluteUrl: string, label: string): string {
+  try {
+    return new URL(absoluteUrl).pathname;
+  } catch {
+    throw new Error(`@dwk/vc: ${label} is not a valid URL`);
+  }
+}
+
+/**
+ * Resolve user config into a {@link ResolvedVcConfig}: derive the issuer DID and
+ * verification method from `baseUrl` when omitted, default each endpoint URL, and
+ * pre-compute pathnames for routing. Throws if `baseUrl` (or any explicitly
+ * supplied endpoint URL) is not a valid URL, or if status is enabled without a
+ * status-list endpoint resolvable from `baseUrl`.
+ */
+export function resolveConfig(config: VcConfig): ResolvedVcConfig {
+  let base: URL;
+  try {
+    base = new URL(config.baseUrl);
+  } catch {
+    throw new Error("@dwk/vc: `baseUrl` is not a valid URL");
+  }
+  const origin = base.origin;
+
+  const did = config.did ?? urlToDidWeb(config.baseUrl);
+  const verificationMethod = config.verificationMethod ?? `${did}#key-0`;
+
+  const issueEndpoint = config.issueEndpoint ?? `${origin}/credentials/issue`;
+  const verifyEndpoint =
+    config.verifyEndpoint ?? `${origin}/credentials/verify`;
+  const statusEndpoint =
+    config.statusEndpoint ?? `${origin}/credentials/status`;
+  const statusListEndpoint =
+    config.statusListEndpoint ?? `${origin}/credentials/status-lists`;
+
+  return {
+    did,
+    verificationMethod,
+    issueEndpoint,
+    verifyEndpoint,
+    statusEndpoint,
+    statusListEndpoint,
+    issuePath: pathOf(issueEndpoint, "issueEndpoint"),
+    verifyPath: pathOf(verifyEndpoint, "verifyEndpoint"),
+    statusPath: pathOf(statusEndpoint, "statusEndpoint"),
+    statusListPath: pathOf(statusListEndpoint, "statusListEndpoint"),
+    statusEnabled: config.status?.enabled ?? false,
+    statusPurpose: config.status?.statusPurpose ?? "revocation",
+    statusListLength: config.status?.listLength ?? DEFAULT_STATUS_LIST_LENGTH,
+    authorize: config.authorize ?? (() => true),
+    resolveDid: config.resolveDid,
+    logger: config.logger ?? noopLogger,
+    metrics: config.metrics ?? noopMetrics,
+  };
+}

package/src/credential.ts

@@ -0,0 +1,188 @@
+/**
+ * Verifiable Credential Data Model 2.0 shapes and structural validation.
+ *
+ * Plain-data helpers: assemble an unsigned credential, validate the required VCDM
+ * 2.0 members before signing or after verifying, and evaluate the validity
+ * window. No Web Crypto, no runtime — the proof lives in {@link ./data-integrity}.
+ *
+ * @see https://www.w3.org/TR/vc-data-model-2.0/
+ */
+
+import { isValidXsdDateTimeStamp, toXsdDateTime } from "./datetime";
+import type { JcsValue } from "./jcs";
+import type { JsonObject } from "./data-integrity";
+
+/** The base VCDM 2.0 context, which MUST be the first `@context` entry. */
+export const VC_CONTEXT_V2 = "https://www.w3.org/ns/credentials/v2";
+
+/** The base credential type every verifiable credential carries. */
+export const VERIFIABLE_CREDENTIAL_TYPE = "VerifiableCredential";
+
+/** An issuer reference: a URL string or an object with an `id`. */
+export type Issuer = string | (JsonObject & { id: string });
+
+/** A credential prior to having a proof attached. */
+export interface UnsignedCredential extends JsonObject {
+  "@context": JcsValue;
+  type: JcsValue;
+  issuer: Issuer;
+  credentialSubject: JcsValue;
+}
+
+/** Inputs to {@link buildCredential}. */
+export interface BuildCredentialOptions {
+  /** Extra credential types beyond `VerifiableCredential`. */
+  readonly type?: string | readonly string[];
+  /** Extra `@context` entries beyond the base VCDM 2.0 context. */
+  readonly context?: string | readonly string[];
+  /** The credential id (a URL), if any. */
+  readonly id?: string;
+  readonly issuer: Issuer;
+  readonly credentialSubject: JcsValue;
+  /** `validFrom` (XSD dateTime). Defaults to now when omitted. */
+  readonly validFrom?: Date | string;
+  /** `validUntil` (XSD dateTime). */
+  readonly validUntil?: Date | string;
+  /** A `credentialStatus` entry (e.g. a Bitstring Status List reference). */
+  readonly credentialStatus?: JsonObject | readonly JsonObject[];
+}
+
+function dedupePrepend(
+  base: string,
+  extra: string | readonly string[] | undefined,
+): string[] {
+  const out = [base];
+  if (extra === undefined) return out;
+  const list = typeof extra === "string" ? [extra] : extra;
+  for (const item of list) {
+    if (!out.includes(item)) out.push(item);
+  }
+  return out;
+}
+
+/**
+ * Assemble an unsigned VCDM 2.0 credential, guaranteeing the base context comes
+ * first and the base `VerifiableCredential` type is present. The result is ready
+ * for {@link ./data-integrity.addProof}.
+ */
+export function buildCredential(
+  options: BuildCredentialOptions,
+): UnsignedCredential {
+  const credential: UnsignedCredential = {
+    "@context": dedupePrepend(VC_CONTEXT_V2, options.context),
+    type: dedupePrepend(VERIFIABLE_CREDENTIAL_TYPE, options.type),
+    issuer: options.issuer,
+    credentialSubject: options.credentialSubject,
+  };
+  if (options.id !== undefined) credential.id = options.id;
+  credential.validFrom = toXsdDateTime(options.validFrom ?? new Date());
+  if (options.validUntil !== undefined) {
+    credential.validUntil = toXsdDateTime(options.validUntil);
+  }
+  if (options.credentialStatus !== undefined) {
+    credential.credentialStatus = Array.isArray(options.credentialStatus)
+      ? [...options.credentialStatus]
+      : (options.credentialStatus as JsonObject);
+  }
+  return credential;
+}
+
+function hasType(type: JcsValue | undefined, expected: string): boolean {
+  if (type === expected) return true;
+  return Array.isArray(type) && type.includes(expected);
+}
+
+function firstContext(context: JcsValue | undefined): JcsValue | undefined {
+  if (Array.isArray(context)) return context[0];
+  return context;
+}
+
+/**
+ * Validate the structural VCDM 2.0 requirements of a credential, returning a
+ * list of problems (empty when valid). Checks the base context ordering, the
+ * `VerifiableCredential` type, and the presence/typing of `issuer` and
+ * `credentialSubject`. Does not check the proof — that is
+ * {@link ./data-integrity.verifyProof}.
+ */
+export function validateCredential(credential: JsonObject): string[] {
+  const errors: string[] = [];
+
+  if (firstContext(credential["@context"]) !== VC_CONTEXT_V2) {
+    errors.push(`@context must begin with "${VC_CONTEXT_V2}"`);
+  }
+  if (!hasType(credential.type, VERIFIABLE_CREDENTIAL_TYPE)) {
+    errors.push(`type must include "${VERIFIABLE_CREDENTIAL_TYPE}"`);
+  }
+
+  const issuer = credential.issuer;
+  const issuerOk =
+    typeof issuer === "string"
+      ? issuer.length > 0
+      : issuer !== null &&
+        typeof issuer === "object" &&
+        !Array.isArray(issuer) &&
+        typeof (issuer as JsonObject).id === "string";
+  if (!issuerOk) {
+    errors.push("issuer must be a URL string or an object with a string id");
+  }
+
+  const subject = credential.credentialSubject;
+  const subjectOk =
+    subject !== null &&
+    subject !== undefined &&
+    typeof subject === "object" &&
+    (!Array.isArray(subject) || subject.length > 0);
+  if (!subjectOk) {
+    errors.push("credentialSubject must be an object or a non-empty array");
+  }
+
+  if (credential.id !== undefined && typeof credential.id !== "string") {
+    errors.push("id, when present, must be a string");
+  }
+
+  return errors;
+}
+
+/** The issuer id of a credential, whether `issuer` is a string or an object. */
+export function issuerId(credential: JsonObject): string | undefined {
+  const issuer = credential.issuer;
+  if (typeof issuer === "string") return issuer;
+  if (issuer !== null && typeof issuer === "object" && !Array.isArray(issuer)) {
+    const id = (issuer as JsonObject).id;
+    return typeof id === "string" ? id : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Evaluate a credential's validity window against `now` (epoch ms). Returns a
+ * reason when the credential is not yet valid or has expired, else `null`.
+ *
+ * A present-but-malformed bound fails **closed**: an unparseable `validFrom` is
+ * treated as not-yet-valid and an unparseable `validUntil` as expired, rather
+ * than silently dropping the bound (which would let a credential with a garbled
+ * expiry verify as if it never expires).
+ */
+export function checkValidityPeriod(
+  credential: JsonObject,
+  now: number = Date.now(),
+): "not_yet_valid" | "expired" | null {
+  const validFrom = credential.validFrom;
+  if (validFrom !== undefined) {
+    if (typeof validFrom !== "string" || !isValidXsdDateTimeStamp(validFrom)) {
+      return "not_yet_valid";
+    }
+    if (now < Date.parse(validFrom)) return "not_yet_valid";
+  }
+  const validUntil = credential.validUntil;
+  if (validUntil !== undefined) {
+    if (
+      typeof validUntil !== "string" ||
+      !isValidXsdDateTimeStamp(validUntil)
+    ) {
+      return "expired";
+    }
+    if (now > Date.parse(validUntil)) return "expired";
+  }
+  return null;
+}