qredential 0.2.0

package/dist/qr.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Character capacity of a QR code in alphanumeric mode, versions 1 to 40, per ISO/IEC 18004.
+ *
+ * base45 output is alphanumeric-safe by construction, which is the reason to use it. Worth being
+ * precise about what that buys, because the folklore overstates it: base45 in alphanumeric mode
+ * costs about 8.25 bits per original byte, against 10.67 for base64 in byte mode, and 8 flat for
+ * raw binary in byte mode. So it beats base64 clearly and loses slightly to raw bytes. Raw bytes
+ * are given up on purpose: byte mode carries charset ambiguity, and plenty of scanners hand back a
+ * mangled string. A credential that survives being copied, pasted and logged is worth a 3% size
+ * penalty.
+ */
+declare const CAPACITY: {
+    readonly L: readonly [25, 47, 77, 114, 154, 195, 224, 279, 335, 395, 468, 535, 619, 667, 758, 854, 938, 1046, 1153, 1249, 1352, 1460, 1588, 1704, 1853, 1990, 2132, 2223, 2369, 2520, 2677, 2840, 3009, 3183, 3351, 3537, 3729, 3927, 4087, 4296];
+    readonly M: readonly [20, 38, 61, 90, 122, 154, 178, 221, 262, 311, 366, 419, 483, 528, 600, 656, 734, 816, 909, 970, 1035, 1134, 1248, 1326, 1451, 1542, 1637, 1732, 1839, 1994, 2113, 2238, 2369, 2506, 2632, 2780, 2894, 3054, 3220, 3391];
+    readonly Q: readonly [16, 29, 47, 67, 87, 108, 125, 157, 189, 221, 259, 296, 352, 376, 426, 470, 531, 574, 644, 702, 742, 823, 890, 963, 1041, 1094, 1172, 1263, 1322, 1429, 1499, 1618, 1700, 1787, 1867, 1966, 2071, 2181, 2298, 2420];
+    readonly H: readonly [10, 20, 35, 50, 64, 84, 93, 122, 143, 174, 200, 227, 259, 283, 321, 365, 408, 452, 493, 557, 587, 640, 672, 744, 779, 864, 910, 958, 1016, 1080, 1150, 1226, 1307, 1394, 1431, 1530, 1591, 1658, 1774, 1852];
+};
+export type ErrorCorrection = keyof typeof CAPACITY;
+export interface FitResult {
+    chars: number;
+    /** Smallest QR version that holds the payload, or null when nothing does. */
+    version: number | null;
+    capacity: number | null;
+    /** True when it fits at a version that scans reliably on a phone in bad light. */
+    comfortable: boolean;
+    errorCorrection: ErrorCorrection;
+    advice: string;
+}
+/**
+ * Check a payload against real QR limits before you design a credential you cannot print.
+ *
+ * Error correction level M is the default because that is what almost every real deployment uses:
+ * L looks generous on paper and then fails on a scuffed printed card.
+ */
+export declare function fits(payload: string, errorCorrection?: ErrorCorrection): FitResult;
+export {};

package/dist/qr.js

@@ -0,0 +1,59 @@
+/**
+ * Character capacity of a QR code in alphanumeric mode, versions 1 to 40, per ISO/IEC 18004.
+ *
+ * base45 output is alphanumeric-safe by construction, which is the reason to use it. Worth being
+ * precise about what that buys, because the folklore overstates it: base45 in alphanumeric mode
+ * costs about 8.25 bits per original byte, against 10.67 for base64 in byte mode, and 8 flat for
+ * raw binary in byte mode. So it beats base64 clearly and loses slightly to raw bytes. Raw bytes
+ * are given up on purpose: byte mode carries charset ambiguity, and plenty of scanners hand back a
+ * mangled string. A credential that survives being copied, pasted and logged is worth a 3% size
+ * penalty.
+ */
+const CAPACITY = {
+    L: [25, 47, 77, 114, 154, 195, 224, 279, 335, 395, 468, 535, 619, 667, 758, 854, 938, 1046, 1153, 1249, 1352, 1460, 1588, 1704, 1853, 1990, 2132, 2223, 2369, 2520, 2677, 2840, 3009, 3183, 3351, 3537, 3729, 3927, 4087, 4296],
+    M: [20, 38, 61, 90, 122, 154, 178, 221, 262, 311, 366, 419, 483, 528, 600, 656, 734, 816, 909, 970, 1035, 1134, 1248, 1326, 1451, 1542, 1637, 1732, 1839, 1994, 2113, 2238, 2369, 2506, 2632, 2780, 2894, 3054, 3220, 3391],
+    Q: [16, 29, 47, 67, 87, 108, 125, 157, 189, 221, 259, 296, 352, 376, 426, 470, 531, 574, 644, 702, 742, 823, 890, 963, 1041, 1094, 1172, 1263, 1322, 1429, 1499, 1618, 1700, 1787, 1867, 1966, 2071, 2181, 2298, 2420],
+    H: [10, 20, 35, 50, 64, 84, 93, 122, 143, 174, 200, 227, 259, 283, 321, 365, 408, 452, 493, 557, 587, 640, 672, 744, 779, 864, 910, 958, 1016, 1080, 1150, 1226, 1307, 1394, 1431, 1530, 1591, 1658, 1774, 1852],
+};
+/** Above this version the modules get small enough that cheap cameras and cracked screens struggle. */
+const COMFORTABLE_VERSION = 20;
+/**
+ * Check a payload against real QR limits before you design a credential you cannot print.
+ *
+ * Error correction level M is the default because that is what almost every real deployment uses:
+ * L looks generous on paper and then fails on a scuffed printed card.
+ */
+export function fits(payload, errorCorrection = 'M') {
+    const table = CAPACITY[errorCorrection];
+    const chars = payload.length;
+    let version = null;
+    let capacity = null;
+    for (let i = 0; i < table.length; i++) {
+        if (chars <= table[i]) {
+            version = i + 1;
+            capacity = table[i];
+            break;
+        }
+    }
+    if (version === null) {
+        return {
+            chars,
+            version: null,
+            capacity: null,
+            comfortable: false,
+            errorCorrection,
+            advice: `${chars} characters does not fit in any QR code at level ${errorCorrection}. Move claims out of the credential or make them selectively disclosable.`,
+        };
+    }
+    const comfortable = version <= COMFORTABLE_VERSION;
+    return {
+        chars,
+        version,
+        capacity,
+        comfortable,
+        errorCorrection,
+        advice: comfortable
+            ? `Fits QR version ${version} at level ${errorCorrection}, with ${capacity - chars} characters to spare.`
+            : `Fits QR version ${version}, which is dense enough that scanning gets unreliable on worn cards and cheap cameras. Aim for version ${COMFORTABLE_VERSION} or below.`,
+    };
+}

package/dist/sdjwt.d.ts

@@ -0,0 +1,85 @@
+export declare const SEPARATOR = "~";
+/**
+ * Registered claims that describe the token rather than the subject.
+ *
+ * They are kept out of `claims` because every one of them is already surfaced as a typed field on
+ * the result. Leaving them mixed in means `Object.keys(result.claims)` hands a caller `iat` and
+ * `status` alongside `over_18`, which makes the obvious loop over a person's attributes wrong.
+ */
+export declare const REGISTERED_CLAIMS: Set<string>;
+export interface Disclosure {
+    /** The transmitted string. The digest is taken over exactly these characters. */
+    raw: string;
+    salt: string;
+    /** Present for an object property, absent for an array element. */
+    name?: string;
+    value: unknown;
+    kind: 'property' | 'element';
+}
+export declare function makeDisclosure(name: string, value: unknown): Disclosure;
+/** RFC 9901 section 4.2.2: an array element disclosure carries no claim name. */
+export declare function makeElementDisclosure(value: unknown): Disclosure;
+export declare function parseDisclosure(raw: string): Disclosure;
+/**
+ * The hash a key binding JWT commits to.
+ *
+ * Taken over the whole presentation up to and including the final separator, so the holder's
+ * 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>;
+/** 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 splitCombined(combined: string): {
+    jwt: string;
+    disclosures: string[];
+    keyBinding?: string;
+};
+export declare function joinCombined(jwt: string, disclosures: string[], keyBinding?: string): string;
+/**
+ * Rebuild the claim set from the always visible payload plus whichever disclosures travelled.
+ *
+ * Every disclosure has to match a digest the issuer signed. A disclosure that does not is an
+ * attempt to add a claim after the fact, so it fails the whole credential rather than being
+ * skipped: a verifier that silently ignores an injected claim is the bug that makes the format
+ * pointless.
+ */
+/**
+ * Rebuild the claim set, following the processing model in RFC 9901 section 7.1.
+ *
+ * Two shapes of embedded digest exist and both are resolved here, at any depth:
+ *
+ *   - an object with an `_sd` array, whose digests stand for properties of that object
+ *   - an array element shaped `{"...": digest}`, which stands for the element itself
+ *
+ * Resolution is recursive, because a disclosed value can itself contain either shape. The rules
+ * that reject rather than skip are the ones that matter: a disclosure the issuer never signed, one
+ * used twice, one naming a reserved or already-present claim, or one left over at the end. A
+ * verifier that silently ignores any of those is the bug that makes the format pointless.
+ */
+export declare function reconstructClaims(payload: Record<string, unknown>, disclosures: string[]): Promise<{
+    claims: Record<string, unknown>;
+    disclosed: string[];
+    withheld: number;
+}>;
+export interface DisclosureLocation {
+    /** Where this disclosure's value lands, as a path: `address.locality`, `nationalities[0]`. */
+    path: string;
+    /** Disclosures that must travel with it, because its digest only appears once they are resolved. */
+    requires: string[];
+}
+/**
+ * Work out where each disclosure sits in the credential.
+ *
+ * A nested disclosure's path does not exist until its parent is resolved: the digest for
+ * `address.locality` lives inside the value of the `address` disclosure, so the walk has to resolve
+ * as it goes, exactly the way a verifier does. That is also why each location carries its ancestors.
+ * RFC 9901 section 4.2.6 is explicit that sending a nested disclosure without the one containing it
+ * is illegal, so a holder who asks for `address.locality` has to send `address` too, and this is
+ * what lets present() work that out rather than making the caller do it.
+ *
+ * Array indices are positions in the credential as issued. They stay stable whatever the holder
+ * decides to withhold, which is the only way a selector written against the credential can keep
+ * meaning what it said.
+ */
+export declare function disclosureLocations(payload: Record<string, unknown>, disclosures: string[]): Promise<Map<string, DisclosureLocation>>;

package/dist/sdjwt.js

@@ -0,0 +1,310 @@
+import { b64url, b64urlJson, unb64urlJson, randomBytes, utf8 } from './bytes.js';
+import { sha256 } from './crypto.js';
+import { QredentialError } from './errors.js';
+export const SEPARATOR = '~';
+/**
+ * Registered claims that describe the token rather than the subject.
+ *
+ * They are kept out of `claims` because every one of them is already surfaced as a typed field on
+ * the result. Leaving them mixed in means `Object.keys(result.claims)` hands a caller `iat` and
+ * `status` alongside `over_18`, which makes the obvious loop over a person's attributes wrong.
+ */
+export const REGISTERED_CLAIMS = new Set([
+    'iss', 'iat', 'exp', 'nbf', 'sub', 'vct', 'status', 'cnf', '_sd', '_sd_alg',
+]);
+export function makeDisclosure(name, value) {
+    const salt = b64url(randomBytes(16));
+    // The array form and its ordering are fixed by RFC 9901: [salt, claim name, claim value].
+    const raw = b64urlJson([salt, name, value]);
+    return { raw, salt, name, value, kind: 'property' };
+}
+/** RFC 9901 section 4.2.2: an array element disclosure carries no claim name. */
+export function makeElementDisclosure(value) {
+    const salt = b64url(randomBytes(16));
+    const raw = b64urlJson([salt, value]);
+    return { raw, salt, value, kind: 'element' };
+}
+export function parseDisclosure(raw) {
+    let parsed;
+    try {
+        parsed = unb64urlJson(raw);
+    }
+    catch (error) {
+        throw new QredentialError('malformed_credential', 'disclosure is not readable', { cause: error });
+    }
+    if (!Array.isArray(parsed) || (parsed.length !== 2 && parsed.length !== 3)) {
+        throw new QredentialError('malformed_credential', 'disclosure must be an array of two elements (array member) or three (object property)');
+    }
+    const salt = parsed[0];
+    if (typeof salt !== 'string') {
+        throw new QredentialError('malformed_credential', 'disclosure salt must be a string');
+    }
+    if (parsed.length === 2) {
+        return { raw, salt, value: parsed[1], kind: 'element' };
+    }
+    const name = parsed[1];
+    if (typeof name !== 'string') {
+        throw new QredentialError('malformed_credential', 'disclosure claim name must be a string');
+    }
+    return { raw, salt, name, value: parsed[2], kind: 'property' };
+}
+/**
+ * The hash a key binding JWT commits to.
+ *
+ * Taken over the whole presentation up to and including the final separator, so the holder's
+ * 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))));
+}
+/** 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 function splitCombined(combined) {
+    const parts = combined.split(SEPARATOR);
+    // A bare JWT is not a combined form. The separator is mandatory even with no disclosures, and
+    // accepting its absence is the same leniency the empty segment check below exists to stop.
+    if (parts.length < 2) {
+        throw new QredentialError('malformed_credential', 'credential is missing the ~ separator that ends every SD-JWT combined form');
+    }
+    const jwt = parts[0] ?? '';
+    const rest = parts.slice(1);
+    // The combined form ends with a separator when there is no key binding JWT, which leaves a
+    // trailing empty segment. A non-empty final segment is a key binding JWT.
+    let keyBinding;
+    if (rest.length > 0) {
+        const last = rest[rest.length - 1];
+        if (last === '')
+            rest.pop();
+        else {
+            keyBinding = last;
+            rest.pop();
+        }
+    }
+    // Everything still in `rest` is a disclosure, and an empty one is not a disclosure. Accepting it
+    // quietly would mean this parser and a stricter one disagree about whether the same bytes are a
+    // valid credential, which is exactly how parser differentials start.
+    if (rest.some((d) => d === '')) {
+        throw new QredentialError('malformed_credential', 'credential contains an empty disclosure segment');
+    }
+    return { jwt, disclosures: rest, keyBinding };
+}
+export function joinCombined(jwt, disclosures, keyBinding) {
+    return [jwt, ...disclosures, keyBinding ?? ''].join(SEPARATOR);
+}
+/**
+ * Rebuild the claim set from the always visible payload plus whichever disclosures travelled.
+ *
+ * Every disclosure has to match a digest the issuer signed. A disclosure that does not is an
+ * attempt to add a claim after the fact, so it fails the whole credential rather than being
+ * skipped: a verifier that silently ignores an injected claim is the bug that makes the format
+ * pointless.
+ */
+/**
+ * Rebuild the claim set, following the processing model in RFC 9901 section 7.1.
+ *
+ * Two shapes of embedded digest exist and both are resolved here, at any depth:
+ *
+ *   - an object with an `_sd` array, whose digests stand for properties of that object
+ *   - an array element shaped `{"...": digest}`, which stands for the element itself
+ *
+ * Resolution is recursive, because a disclosed value can itself contain either shape. The rules
+ * that reject rather than skip are the ones that matter: a disclosure the issuer never signed, one
+ * used twice, one naming a reserved or already-present claim, or one left over at the end. A
+ * 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 byDigest = new Map();
+    for (const raw of disclosures) {
+        const dig = await digest(raw);
+        // 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)) {
+            throw new QredentialError('malformed_credential', 'the same disclosure was sent more than once');
+        }
+        byDigest.set(dig, parseDisclosure(raw));
+    }
+    const used = new Set();
+    const seen = new Set();
+    const disclosed = [];
+    let withheld = 0;
+    /** Record a digest the payload embeds, rejecting a second sighting of the same one. */
+    const note = (dig) => {
+        if (seen.has(dig)) {
+            throw new QredentialError('malformed_credential', 'the same digest appears more than once in this credential');
+        }
+        seen.add(dig);
+    };
+    const resolveObject = (node, path) => {
+        const sd = node['_sd'];
+        delete node['_sd'];
+        if (sd !== undefined) {
+            if (!Array.isArray(sd) || sd.some((d) => typeof d !== 'string')) {
+                throw new QredentialError('malformed_credential', '_sd must be an array of strings');
+            }
+            for (const dig of sd) {
+                note(dig);
+                const found = byDigest.get(dig);
+                // A digest with no disclosure is a claim the holder withheld. It is ignored on purpose:
+                // that is what withholding looks like from here.
+                if (!found) {
+                    withheld++;
+                    continue;
+                }
+                if (found.kind !== 'property' || found.name === undefined) {
+                    throw new QredentialError('malformed_credential', 'a digest under _sd resolved to an array element disclosure');
+                }
+                if (found.name === '_sd' || found.name === '...') {
+                    throw new QredentialError('malformed_credential', `disclosure uses the reserved claim name "${found.name}"`);
+                }
+                if (REGISTERED_CLAIMS.has(found.name)) {
+                    throw new QredentialError('malformed_credential', `disclosure tries to set the registered claim "${found.name}"`);
+                }
+                if (Object.prototype.hasOwnProperty.call(node, found.name)) {
+                    throw new QredentialError('malformed_credential', `disclosure for "${found.name}" collides with a claim already in the payload`);
+                }
+                used.add(dig);
+                node[found.name] = found.value;
+                disclosed.push([...path, found.name].join('.'));
+                walk(found.value, [...path, found.name]);
+            }
+        }
+        for (const [key, value] of Object.entries(node)) {
+            walk(value, [...path, key]);
+        }
+    };
+    const resolveArray = (node, path) => {
+        const kept = [];
+        for (let i = 0; i < node.length; i++) {
+            const item = node[i];
+            const dig = elementDigest(item);
+            if (dig === null) {
+                walk(item, [...path, `[${i}]`]);
+                kept.push(item);
+                continue;
+            }
+            note(dig);
+            const found = byDigest.get(dig);
+            // Section 7.1 step d: an element whose digest has no disclosure is removed, not left behind
+            // as a placeholder for the caller to trip over.
+            if (!found) {
+                withheld++;
+                continue;
+            }
+            if (found.kind !== 'element') {
+                throw new QredentialError('malformed_credential', 'an array element digest resolved to an object property disclosure');
+            }
+            used.add(dig);
+            const at = `${path.join('.')}[${kept.length}]`;
+            disclosed.push(at);
+            walk(found.value, [...path, `[${kept.length}]`]);
+            kept.push(found.value);
+        }
+        node.length = 0;
+        node.push(...kept);
+    };
+    const walk = (node, path) => {
+        if (Array.isArray(node))
+            return resolveArray(node, path);
+        if (node !== null && typeof node === 'object') {
+            return resolveObject(node, path);
+        }
+    };
+    const claims = {};
+    for (const [key, value] of Object.entries(payload)) {
+        if (REGISTERED_CLAIMS.has(key))
+            continue;
+        claims[key] = structuredClone(value);
+    }
+    // The top level `_sd` lives on the payload, so it is copied in for the walk and stripped after.
+    const root = { ...claims };
+    if (payload['_sd'] !== undefined)
+        root['_sd'] = structuredClone(payload['_sd']);
+    resolveObject(root, []);
+    // Section 7.1 step 5: anything the payload never referenced is an attempt to add a claim after
+    // the fact, and fails the whole credential rather than being skipped.
+    const orphan = [...byDigest.entries()].find(([dig]) => !used.has(dig));
+    if (orphan) {
+        const [, d] = orphan;
+        const what = d.name !== undefined ? `"${d.name}"` : 'an array element';
+        throw new QredentialError('malformed_credential', `disclosure for ${what} does not match any digest signed by the issuer`);
+    }
+    return { claims: root, disclosed, withheld };
+}
+/** An array element stands for a hidden value when it is exactly `{"...": "<digest>"}`. */
+function elementDigest(item) {
+    if (item === null || typeof item !== 'object' || Array.isArray(item))
+        return null;
+    const keys = Object.keys(item);
+    if (keys.length !== 1 || keys[0] !== '...')
+        return null;
+    const value = item['...'];
+    return typeof value === 'string' ? value : null;
+}
+/**
+ * Work out where each disclosure sits in the credential.
+ *
+ * A nested disclosure's path does not exist until its parent is resolved: the digest for
+ * `address.locality` lives inside the value of the `address` disclosure, so the walk has to resolve
+ * as it goes, exactly the way a verifier does. That is also why each location carries its ancestors.
+ * RFC 9901 section 4.2.6 is explicit that sending a nested disclosure without the one containing it
+ * is illegal, so a holder who asks for `address.locality` has to send `address` too, and this is
+ * what lets present() work that out rather than making the caller do it.
+ *
+ * Array indices are positions in the credential as issued. They stay stable whatever the holder
+ * decides to withhold, which is the only way a selector written against the credential can keep
+ * meaning what it said.
+ */
+export async function disclosureLocations(payload, disclosures) {
+    const byDigest = new Map();
+    for (const raw of disclosures) {
+        byDigest.set(await digest(raw), { raw, parsed: parseDisclosure(raw) });
+    }
+    const found = new Map();
+    const walk = (node, path, ancestors) => {
+        if (Array.isArray(node)) {
+            for (let i = 0; i < node.length; i++) {
+                const at = `${path}[${i}]`;
+                const dig = elementDigest(node[i]);
+                if (dig === null) {
+                    walk(node[i], at, ancestors);
+                    continue;
+                }
+                const hit = byDigest.get(dig);
+                if (!hit)
+                    continue;
+                found.set(hit.raw, { path: at, requires: [...ancestors] });
+                walk(hit.parsed.value, at, [...ancestors, hit.raw]);
+            }
+            return;
+        }
+        if (node === null || typeof node !== 'object')
+            return;
+        const object = node;
+        const sd = object['_sd'];
+        if (Array.isArray(sd)) {
+            for (const dig of sd) {
+                if (typeof dig !== 'string')
+                    continue;
+                const hit = byDigest.get(dig);
+                if (!hit || hit.parsed.name === undefined)
+                    continue;
+                const at = path ? `${path}.${hit.parsed.name}` : hit.parsed.name;
+                found.set(hit.raw, { path: at, requires: [...ancestors] });
+                walk(hit.parsed.value, at, [...ancestors, hit.raw]);
+            }
+        }
+        for (const [key, value] of Object.entries(object)) {
+            if (key === '_sd' || key === '_sd_alg')
+                continue;
+            walk(value, path ? `${path}.${key}` : key, ancestors);
+        }
+    };
+    walk(payload, '', []);
+    return found;
+}

package/dist/status.d.ts

@@ -0,0 +1,49 @@
+import type { Alg, Jwk } from './types.js';
+export type StatusValue = 'valid' | 'invalid' | 'suspended' | 'unknown';
+export interface StatusListToken {
+    issuer: string;
+    uri?: string;
+    issuedAt?: number;
+    expiresAt?: number;
+    bits: number;
+    bytes: Uint8Array;
+}
+/**
+ * Parse a Token Status List JWT that the verifier already has on disk.
+ *
+ * Signature checking happens in verify(), against the same trust list as the credential, because a
+ * status list from an unverified source is worse than no status list: it lets an attacker clear a
+ * revoked credential.
+ */
+export declare function parseStatusList(token: string): Promise<{
+    payload: Record<string, unknown>;
+    list: StatusListToken;
+}>;
+/** Read one entry. Values are packed least significant bits first, per the spec. */
+export declare function readStatus(list: StatusListToken, idx: number): StatusValue;
+export declare function isStale(list: StatusListToken, maxAge: number | string | undefined, now?: number): boolean;
+/**
+ * Publish a status list.
+ *
+ * The verifier side of revocation is useless without this, and leaving issuers to hand roll the
+ * bitstring is how you end up with lists that disagree about bit order.
+ *
+ * Size it generously and set it once: a list covering a million credentials is 125 KB before
+ * compression and a few KB after, because the bits are nearly all zero.
+ */
+export declare function createStatusList(options: {
+    issuer: string;
+    key: Jwk;
+    kid: string;
+    alg?: Alg;
+    /** Where verifiers refresh this list. Becomes the `sub` claim. */
+    uri: string;
+    /** How many credentials the list covers. */
+    size: number;
+    revoked?: number[];
+    suspended?: number[];
+    /** Seconds, or a duration string. Verifiers compare this against maxStatusAge. */
+    expiresIn?: number | string;
+    /** Override the issue time. Exists for tests and for republishing a historical list. */
+    issuedAt?: number;
+}): Promise<string>;

package/dist/status.js

@@ -0,0 +1,122 @@
+import { b64url, b64urlJson, unb64url, unb64urlJson } from './bytes.js';
+import { deflate, inflateEither } from './compress.js';
+import { importPrivateKey, sign } from './crypto.js';
+import { seconds, nowSeconds } from './duration.js';
+import { QredentialError } from './errors.js';
+/**
+ * Parse a Token Status List JWT that the verifier already has on disk.
+ *
+ * Signature checking happens in verify(), against the same trust list as the credential, because a
+ * status list from an unverified source is worse than no status list: it lets an attacker clear a
+ * revoked credential.
+ */
+export async function parseStatusList(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+        throw new QredentialError('malformed_status_list', 'status list token is not a JWT');
+    }
+    let payload;
+    try {
+        payload = unb64urlJson(parts[1]);
+    }
+    catch (error) {
+        throw new QredentialError('malformed_status_list', 'status list payload is not readable', {
+            cause: error,
+        });
+    }
+    const sl = payload['status_list'];
+    if (!sl || typeof sl.lst !== 'string') {
+        throw new QredentialError('malformed_status_list', 'status list token has no status_list.lst');
+    }
+    const bits = sl.bits ?? 1;
+    if (![1, 2, 4, 8].includes(bits)) {
+        throw new QredentialError('malformed_status_list', `unsupported status list bit width: ${bits}`);
+    }
+    return {
+        payload,
+        list: {
+            issuer: String(payload['iss'] ?? ''),
+            uri: typeof payload['sub'] === 'string' ? payload['sub'] : undefined,
+            issuedAt: typeof payload['iat'] === 'number' ? payload['iat'] : undefined,
+            expiresAt: typeof payload['exp'] === 'number' ? payload['exp'] : undefined,
+            bits,
+            bytes: await inflateEither(unb64url(sl.lst)),
+        },
+    };
+}
+/** Read one entry. Values are packed least significant bits first, per the spec. */
+export function readStatus(list, idx) {
+    if (idx < 0 || !Number.isInteger(idx)) {
+        throw new QredentialError('invalid_option', `invalid status index: ${idx}`);
+    }
+    const perByte = 8 / list.bits;
+    const byteIndex = Math.floor(idx / perByte);
+    const byte = list.bytes[byteIndex];
+    if (byte === undefined)
+        return 'unknown';
+    const shift = (idx % perByte) * list.bits;
+    const mask = (1 << list.bits) - 1;
+    const value = (byte >> shift) & mask;
+    if (value === 0)
+        return 'valid';
+    if (value === 1)
+        return 'invalid';
+    if (value === 2)
+        return 'suspended';
+    return 'unknown';
+}
+export function isStale(list, maxAge, now = nowSeconds()) {
+    if (list.expiresAt !== undefined && now > list.expiresAt)
+        return true;
+    if (maxAge === undefined)
+        return false;
+    if (list.issuedAt === undefined)
+        return true;
+    return now - list.issuedAt > seconds(maxAge);
+}
+/**
+ * Publish a status list.
+ *
+ * The verifier side of revocation is useless without this, and leaving issuers to hand roll the
+ * bitstring is how you end up with lists that disagree about bit order.
+ *
+ * Size it generously and set it once: a list covering a million credentials is 125 KB before
+ * compression and a few KB after, because the bits are nearly all zero.
+ */
+export async function createStatusList(options) {
+    const alg = options.alg ?? 'ES256';
+    const iat = options.issuedAt ?? nowSeconds();
+    if (!Number.isSafeInteger(options.size) || options.size < 1) {
+        throw new QredentialError('invalid_option', `status list size must be a positive integer, received ${options.size}`);
+    }
+    let bytes;
+    try {
+        bytes = new Uint8Array(Math.ceil(options.size / 8));
+    }
+    catch (error) {
+        // A size large enough to fail allocation is a caller mistake, not a crash to pass upward.
+        throw new QredentialError('invalid_option', `status list of ${options.size} entries cannot be allocated`, { cause: error });
+    }
+    const set = (indices, value) => {
+        for (const idx of indices ?? []) {
+            if (idx < 0 || idx >= options.size || !Number.isInteger(idx)) {
+                throw new QredentialError('invalid_option', `status index ${idx} is outside a list of ${options.size}`);
+            }
+            bytes[Math.floor(idx / 8)] |= value << idx % 8;
+        }
+    };
+    set(options.revoked, 1);
+    set(options.suspended, 2);
+    const payload = {
+        iss: options.issuer,
+        sub: options.uri,
+        iat,
+        status_list: { bits: 1, lst: b64url(await deflate(bytes, 'deflate')) },
+    };
+    if (options.expiresIn !== undefined)
+        payload['exp'] = iat + seconds(options.expiresIn);
+    const header = { alg, typ: 'statuslist+jwt', kid: options.kid };
+    const input = `${b64urlJson(header)}.${b64urlJson(payload)}`;
+    const key = await importPrivateKey(options.key, alg);
+    return `${input}.${b64url(await sign(input, key, alg))}`;
+}