qredential 0.2.0 → 0.3.1

package/README.md

@@ -8,6 +8,9 @@
 
 Verify a digital credential from a QR code with **no network connection**.
 
+Someone shows you a code. You need to know one thing about them, and you need to know it is true.
+This library reads the code, checks the signature, and answers, without asking anybody.
+
 ```ts
 import { verify } from 'qredential'
 
@@ -19,6 +22,38 @@ No server call. No lookup. No account. The proof travels inside the QR code itse
 
 ---
 
+## What this actually does
+
+If you have not worked with digital credentials before, this section is for you. Nothing here
+assumes you have.
+
+A credential is a statement somebody signed. "This person is over 18." "This person may drive a
+car." The signature is what makes it worth anything: it says an authority stands behind the
+statement, and that nobody edited it afterwards.
+
+On paper, and in a PDF, one signature covers the whole document. To prove a single line of it you
+hand over all of it. Show a driving licence to prove your age and the other person also learns your
+address, your licence number and your exact date of birth. They never asked for any of that. They
+have it now anyway.
+
+Selective disclosure breaks that trade. The issuer signs each fact separately, and the credential
+carries only a fingerprint of each one. You choose which facts to reveal, and the rest stay
+fingerprints that say nothing about their contents. The signature still checks out, because it was
+never a signature over one indivisible blob.
+
+All of it fits inside the code the verifier scans: the signature, the fingerprints, and the facts
+you chose to share. Nothing is fetched while verifying, so a door, a bus, a rural clinic or an
+aeroplane at cruising altitude can check a credential with no network at all.
+
+There is one last piece, and it is the one people forget. Anything you can scan, you can photograph.
+So the person presenting also has to sign a fresh challenge with a private key that never leaves
+their device. Without that step, a screenshot of somebody else's credential would pass. This library
+refuses any presentation that lacks it, and the section on [proving the
+holder](#proving-the-holder-not-just-the-credential) explains how.
+
+The format is SD-JWT, standardised as [RFC 9901](https://www.rfc-editor.org/rfc/rfc9901.html) in
+November 2025. It is what the European digital identity wallets and the OpenID specifications use.
+
 ## Why this exists
 
 I built the eCNH, Brazil's digital driver's licence, used by more than 40 million people. The part
@@ -92,9 +127,16 @@ ones to reveal, and the signature still checks out on what is left:
 ```ts
 // The credential contains name, address, birth date, document number.
 // The bar only gets to see one thing.
-const presentation = await present(credential, { disclose: ['over_18'] })
+const presentation = await present(credential, {
+  disclose: ['over_18'],
+  keyBinding: { key: holderPrivateJwk, audience: 'https://bar.example/door', nonce: challenge },
+})
 
-const result = await verify(presentation, { trust })
+const result = await verify(presentation, {
+  trust,
+  nonce: challenge,
+  audience: 'https://bar.example/door',
+})
 result.claims          // { over_18: true }
 result.claims.address  // undefined, and it was never transmitted
 ```
@@ -172,6 +214,18 @@ If the cached list is too old, you get `result.ok === false` with
 `result.reason === 'status_list_stale'` rather than a false yes. Deciding what to do when you cannot
 be sure is your call, and the library refuses to make it quietly for you.
 
+## Examples
+
+Runnable scenarios, each a single file with no setup beyond `npm run build`:
+[a door checking somebody is over 18](examples/age-check-at-the-door.mjs), [issuing a
+credential](examples/issue-a-credential.mjs), [revoking one that is already in somebody's
+pocket](examples/revoke-a-credential.mjs), and [what a credential costs in QR
+characters](examples/sizes.mjs). CI runs all of them, so they cannot quietly stop working.
+
+[examples/README.md](examples/README.md) has the index and two findings the prose does not make:
+a presentation with key binding is larger than the credential it came from, and a revocation list
+covering a million credentials is about 600 characters.
+
 ## API
 
 Four functions. That is the whole surface.

package/dist/crypto.d.ts

@@ -1,4 +1,4 @@
-import type { Alg, Jwk } from './types.js';
+import type { Alg, Jwk, SdAlg } from './types.js';
 export declare function importPrivateKey(jwk: Jwk, alg: Alg): Promise<CryptoKey>;
 export declare function importPublicKey(jwk: Jwk, alg: Alg): Promise<CryptoKey>;
 export declare function sign(data: string, key: CryptoKey, alg: Alg): Promise<Uint8Array>;
@@ -10,4 +10,8 @@ export declare function verifySignature(data: string, signature: string, key: Cr
  * only be used one way here and guessing wrong fails loudly at import rather than quietly.
  */
 export declare function algForJwk(jwk: Jwk): Alg;
+export declare function isSupportedSdAlg(alg: string): alg is SdAlg;
+/** Map an IANA Named Information Hash Algorithm name to its WebCrypto digest algorithm name. */
+export declare function webCryptoDigestAlg(sdAlg: string): AlgorithmIdentifier;
+export declare function digestHash(data: Uint8Array, sdAlg?: string): Promise<Uint8Array>;
 export declare function sha256(data: Uint8Array): Promise<Uint8Array>;

package/dist/crypto.js

@@ -66,7 +66,26 @@ export function algForJwk(jwk) {
         return 'EdDSA';
     throw new QredentialError('unsupported_alg', `cannot tell which algorithm this key is for: kty ${String(jwk.kty)}, crv ${String(jwk.crv)}`);
 }
-export async function sha256(data) {
-    const buf = await crypto.subtle.digest('SHA-256', data);
+const SD_ALG_MAP = {
+    'sha-256': 'SHA-256',
+    'sha-384': 'SHA-384',
+    'sha-512': 'SHA-512',
+};
+export function isSupportedSdAlg(alg) {
+    return alg === 'sha-256' || alg === 'sha-384' || alg === 'sha-512';
+}
+/** Map an IANA Named Information Hash Algorithm name to its WebCrypto digest algorithm name. */
+export function webCryptoDigestAlg(sdAlg) {
+    if (isSupportedSdAlg(sdAlg)) {
+        return SD_ALG_MAP[sdAlg];
+    }
+    throw new QredentialError('unsupported_alg', `unsupported _sd_alg: ${sdAlg}`);
+}
+export async function digestHash(data, sdAlg = 'sha-256') {
+    const algName = webCryptoDigestAlg(sdAlg);
+    const buf = await crypto.subtle.digest(algName, data);
     return new Uint8Array(buf);
 }
+export async function sha256(data) {
+    return digestHash(data, 'sha-256');
+}

package/dist/index.js

@@ -4,7 +4,8 @@ import { seconds, nowSeconds } from './duration.js';
 import { pack, unpack, isEnvelope } from './envelope.js';
 import { parseStatusList, readStatus, isStale } from './status.js';
 import { REGISTERED_CLAIMS, digest, sdHash, makeDisclosure, splitCombined, joinCombined, disclosureLocations, reconstructClaims, } from './sdjwt.js';
-import { QredentialError } from './errors.js';
+import { isSupportedSdAlg } from './crypto.js';
+import { isQredentialError, QredentialError } from './errors.js';
 export { QredentialError, isQredentialError } from './errors.js';
 /**
  * Turn a rejected result into a thrown {@link QredentialError}, for callers who would rather use
@@ -75,8 +76,12 @@ export async function issue(options) {
     if (reserved.length > 0) {
         throw new QredentialError('invalid_option', `these claim names describe the token, not the subject, and cannot be made disclosable: ${reserved.join(', ')}`);
     }
+    const sdAlg = options.sdAlg ?? 'sha-256';
+    if (!isSupportedSdAlg(sdAlg)) {
+        throw new QredentialError('unsupported_alg', `unsupported _sd_alg: ${sdAlg}`);
+    }
     const disclosures = disclosable.map((name) => makeDisclosure(name, options.claims[name]));
-    const digests = shuffle(await Promise.all(disclosures.map((d) => digest(d.raw))));
+    const digests = shuffle(await Promise.all(disclosures.map((d) => digest(d.raw, sdAlg))));
     const payload = { iss: options.issuer, iat };
     for (const [key, value] of Object.entries(options.claims)) {
         if (!disclosable.includes(key))
@@ -105,7 +110,7 @@ export async function issue(options) {
     }
     if (digests.length > 0) {
         payload['_sd'] = digests;
-        payload['_sd_alg'] = 'sha-256';
+        payload['_sd_alg'] = sdAlg;
     }
     const header = { alg, typ: 'dc+sd-jwt', kid: options.kid };
     const signingInput = `${b64urlJson(header)}.${b64urlJson(payload)}`;
@@ -162,13 +167,14 @@ export async function present(credential, options) {
     if (bound === null) {
         throw new QredentialError('invalid_option', 'this credential has no cnf claim, so the issuer never bound a holder key and a proof would mean nothing');
     }
+    const sdAlg = readSdAlg(jwt);
     const alg = options.keyBinding.alg ?? algForJwk(options.keyBinding.key);
     const kbPayload = {
         iat: nowSeconds(),
         aud: options.keyBinding.audience,
         nonce: options.keyBinding.nonce,
         // Commits to exactly this set of disclosures, so a relay cannot add or strip one afterwards.
-        sd_hash: await sdHash(jwt, kept),
+        sd_hash: await sdHash(jwt, kept, sdAlg),
     };
     const kbInput = `${b64urlJson({ alg, typ: 'kb+jwt' })}.${b64urlJson(kbPayload)}`;
     const holderKey = await importPrivateKey(options.keyBinding.key, alg);
@@ -189,6 +195,19 @@ function readHolderKey(jwt) {
         return null;
     }
 }
+/** Pull _sd_alg out of a credential's payload, defaulting to sha-256 per RFC 9901. */
+function readSdAlg(jwt) {
+    const segments = jwt.split('.');
+    if (segments.length !== 3)
+        return 'sha-256';
+    try {
+        const payload = unb64urlJson(segments[1]);
+        return payload['_sd_alg'] ?? 'sha-256';
+    }
+    catch {
+        return 'sha-256';
+    }
+}
 export async function verify(input, options) {
     const now = options.now ?? nowSeconds();
     const skew = options.clockSkew ?? 60;
@@ -273,6 +292,9 @@ export async function verify(input, options) {
         withheld = rebuilt.withheld;
     }
     catch (error) {
+        if (isQredentialError(error) && error.code === 'unsupported_alg') {
+            return reject('unsupported_alg', error.message);
+        }
         return reject('digest_mismatch', error.message);
     }
     let revocationChecked = false;
@@ -436,7 +458,20 @@ async function checkHolderProof(input) {
             holderVerified: false,
         };
     }
-    const expected = await sdHash(jwt, disclosures);
+    const sdAlg = payload['_sd_alg'] ?? 'sha-256';
+    let expected;
+    try {
+        expected = await sdHash(jwt, disclosures, sdAlg);
+    }
+    catch (error) {
+        if (isQredentialError(error) && error.code === 'unsupported_alg') {
+            return {
+                rejected: reject('unsupported_alg', error.message),
+                holderVerified: false,
+            };
+        }
+        throw error;
+    }
     if (kbPayload['sd_hash'] !== expected) {
         return {
             rejected: reject('holder_proof_invalid', 'the holder proof commits to a different set of disclosures than the one presented'),

package/dist/sdjwt.d.ts

@@ -1,3 +1,4 @@
+import type { SdAlg } from './types.js';
 export declare const SEPARATOR = "~";
 /**
  * Registered claims that describe the token rather than the subject.
@@ -27,9 +28,9 @@ export declare function parseDisclosure(raw: string): Disclosure;
  * signature covers exactly this set of disclosures. Without it a relay could strip or add
  * disclosures after the holder signed, and the proof would still check out.
  */
-export declare function sdHash(jwt: string, disclosures: string[]): Promise<string>;
+export declare function sdHash(jwt: string, disclosures: string[], alg?: string): Promise<string>;
 /** Digest of a disclosure exactly as transmitted. Hashing a re-serialised copy would not match. */
-export declare function digest(raw: string): Promise<string>;
+export declare function digest(raw: string, alg?: string): Promise<string>;
 export declare function splitCombined(combined: string): {
     jwt: string;
     disclosures: string[];
@@ -44,6 +45,16 @@ export declare function joinCombined(jwt: string, disclosures: string[], keyBind
  * skipped: a verifier that silently ignores an injected claim is the bug that makes the format
  * pointless.
  */
+/**
+ * The hash a credential says its digests were made with, validated.
+ *
+ * RFC 9901 section 4.1.1 requires sha-256 and allows any name from the IANA Named Information Hash
+ * Algorithm Registry. These three are the ones WebCrypto computes in every runtime this targets;
+ * anything else is refused by name rather than guessed at. Reading it in one place is what keeps
+ * the digest map, the claim reconstruction and the path resolver from disagreeing about which hash
+ * a credential uses, which is the kind of disagreement that makes a claim silently unreachable.
+ */
+export declare function resolveSdAlg(payload: Record<string, unknown>): SdAlg;
 /**
  * Rebuild the claim set, following the processing model in RFC 9901 section 7.1.
  *

package/dist/sdjwt.js

@@ -1,5 +1,5 @@
 import { b64url, b64urlJson, unb64urlJson, randomBytes, utf8 } from './bytes.js';
-import { sha256 } from './crypto.js';
+import { digestHash, isSupportedSdAlg } from './crypto.js';
 import { QredentialError } from './errors.js';
 export const SEPARATOR = '~';
 /**
@@ -55,12 +55,12 @@ export function parseDisclosure(raw) {
  * signature covers exactly this set of disclosures. Without it a relay could strip or add
  * disclosures after the holder signed, and the proof would still check out.
  */
-export async function sdHash(jwt, disclosures) {
-    return b64url(await sha256(utf8(joinCombined(jwt, disclosures))));
+export async function sdHash(jwt, disclosures, alg = 'sha-256') {
+    return b64url(await digestHash(utf8(joinCombined(jwt, disclosures)), alg));
 }
 /** Digest of a disclosure exactly as transmitted. Hashing a re-serialised copy would not match. */
-export async function digest(raw) {
-    return b64url(await sha256(utf8(raw)));
+export async function digest(raw, alg = 'sha-256') {
+    return b64url(await digestHash(utf8(raw), alg));
 }
 export function splitCombined(combined) {
     const parts = combined.split(SEPARATOR);
@@ -102,6 +102,22 @@ export function joinCombined(jwt, disclosures, keyBinding) {
  * skipped: a verifier that silently ignores an injected claim is the bug that makes the format
  * pointless.
  */
+/**
+ * The hash a credential says its digests were made with, validated.
+ *
+ * RFC 9901 section 4.1.1 requires sha-256 and allows any name from the IANA Named Information Hash
+ * Algorithm Registry. These three are the ones WebCrypto computes in every runtime this targets;
+ * anything else is refused by name rather than guessed at. Reading it in one place is what keeps
+ * the digest map, the claim reconstruction and the path resolver from disagreeing about which hash
+ * a credential uses, which is the kind of disagreement that makes a claim silently unreachable.
+ */
+export function resolveSdAlg(payload) {
+    const alg = payload['_sd_alg'] ?? 'sha-256';
+    if (!isSupportedSdAlg(alg)) {
+        throw new QredentialError('unsupported_alg', `unsupported _sd_alg: ${alg}`);
+    }
+    return alg;
+}
 /**
  * Rebuild the claim set, following the processing model in RFC 9901 section 7.1.
  *
@@ -116,12 +132,10 @@ export function joinCombined(jwt, disclosures, keyBinding) {
  * verifier that silently ignores any of those is the bug that makes the format pointless.
  */
 export async function reconstructClaims(payload, disclosures) {
-    const sdAlg = payload['_sd_alg'] ?? 'sha-256';
-    if (sdAlg !== 'sha-256')
-        throw new QredentialError('unsupported_alg', `unsupported _sd_alg: ${sdAlg}`);
+    const sdAlg = resolveSdAlg(payload);
     const byDigest = new Map();
     for (const raw of disclosures) {
-        const dig = await digest(raw);
+        const dig = await digest(raw, sdAlg);
         // Keying by digest would quietly swallow a repeat, and a presentation that sends the same
         // disclosure twice is malformed however harmless it looks.
         if (byDigest.has(dig)) {
@@ -261,9 +275,10 @@ function elementDigest(item) {
  * meaning what it said.
  */
 export async function disclosureLocations(payload, disclosures) {
+    const sdAlg = resolveSdAlg(payload);
     const byDigest = new Map();
     for (const raw of disclosures) {
-        byDigest.set(await digest(raw), { raw, parsed: parseDisclosure(raw) });
+        byDigest.set(await digest(raw, sdAlg), { raw, parsed: parseDisclosure(raw) });
     }
     const found = new Map();
     const walk = (node, path, ancestors) => {

package/dist/types.d.ts

@@ -1,4 +1,9 @@
 export type Alg = 'ES256' | 'EdDSA';
+/**
+ * Hashing algorithms supported for SD-JWT selective disclosure (RFC 9901 section 4.1.1).
+ * From the IANA Named Information Hash Algorithm Registry.
+ */
+export type SdAlg = 'sha-256' | 'sha-384' | 'sha-512';
 export interface Jwk {
     kty: string;
     crv?: string;
@@ -38,6 +43,11 @@ export interface IssueOptions {
     key: Jwk;
     kid: string;
     alg?: Alg;
+    /**
+     * Hashing algorithm for selective disclosure and key binding sd_hash.
+     * Defaults to 'sha-256' (RFC 9901).
+     */
+    sdAlg?: SdAlg;
     claims: Record<string, unknown>;
     /** Claim names the holder may withhold at presentation time. Everything else is always visible. */
     disclose?: string[];

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "qredential",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Verify a digital credential from a QR code with no network connection. SD-JWT selective disclosure, offline revocation, zero dependencies.",
   "homepage": "https://qredential.js.org/",
   "bugs": {
     "url": "https://github.com/george-veras/qredential/issues"
   },
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -20,11 +21,16 @@
     "README.md",
     "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
+    "coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
+    "lint": "oxlint src test scripts",
     "build:site": "node scripts/build-site.mjs",
     "check:site": "node scripts/build-site.mjs && git diff --exit-code docs/",
     "prepack": "npm run build",
@@ -34,6 +40,7 @@
     "build:og": "node scripts/build-og.mjs",
     "check:playground": "node scripts/check-playground.mjs",
     "check:seo": "node scripts/check-seo.mjs",
+    "check:docs": "node scripts/check-docs.mjs",
     "check:a11y": "node scripts/check-a11y.mjs"
   },
   "keywords": [
@@ -64,18 +71,20 @@
     "node": ">=20"
   },
   "devDependencies": {
-    "@sd-jwt/core": "^0.19.0",
+    "@sd-jwt/core": "^0.21.0",
     "@sd-jwt/crypto-nodejs": "^0.19.0",
-    "@types/node": "^22.10.0",
+    "@types/node": "^26.6.2",
     "@vitest/browser": "^5.0.1",
     "@vitest/browser-playwright": "^5.0.1",
+    "@vitest/coverage-v8": "^5.0.1",
     "axe-core": "^4.13.0",
     "esbuild": "^0.28.2",
-    "fast-check": "^3.23.2",
-    "marked": "^15.0.12",
+    "fast-check": "^4.10.1",
+    "marked": "^18.0.13",
+    "oxlint": "^1.85.0",
     "playwright": "^1.63.0",
-    "qrcode-generator": "^1.5.2",
-    "typescript": "^5.7.0",
+    "qrcode-generator": "^2.0.4",
+    "typescript": "^7.0.2",
     "vitest": "^5.0.1"
   }
 }