@learncard/learn-card-plugin 1.2.24 → 1.2.26

package/src/verificationPrettifier.ts

@@ -0,0 +1,160 @@
+import { VerificationItem, VerificationStatusEnum } from '@learncard/types';
+
+type Label = { check: string; message: string };
+
+const SUCCESS_LABELS: Record<string, Label> = {
+    parse: { check: 'Format', message: 'Valid' },
+    disclosure_hash_integrity: { check: 'Selective Disclosure', message: 'Claims verified' },
+    issuer_resolved: { check: 'Issuer', message: 'Identified' },
+    issuer_signature: { check: 'Signature', message: 'Valid' },
+    expiration: { check: 'Expiration', message: 'Does Not Expire' },
+    vct: { check: 'Credential Type', message: 'Verified' },
+    proof: { check: 'Proof', message: 'Valid' },
+    credentialStatus: { check: 'Status', message: 'Active' },
+    // The W3C verifier (learn-card/verify.ts) normalizes both `status` and
+    // `credentialStatus` success rows to check: 'status' (lowercase), so the
+    // bare `status` alias is required or those rows render unprettified.
+    status: { check: 'Status', message: 'Active' },
+    credentialSchema: { check: 'Schema', message: 'Valid' },
+};
+
+const ERROR_LABELS: Record<string, Label> = {
+    invalid_compact_form: { check: 'Format', message: 'Invalid' },
+    invalid_jwt: { check: 'Format', message: 'Invalid' },
+    invalid_typ: { check: 'Format', message: 'Invalid type' },
+    missing_iss: { check: 'Issuer', message: 'Missing' },
+    missing_vct: { check: 'Credential Type', message: 'Missing' },
+    missing_alg: { check: 'Signature', message: 'Algorithm missing' },
+    unsupported_alg: { check: 'Signature', message: 'Unsupported algorithm' },
+    unsupported_sd_alg: { check: 'Selective Disclosure', message: 'Unsupported algorithm' },
+    invalid_disclosure: { check: 'Selective Disclosure', message: 'Invalid' },
+    disclosure_hash_mismatch: { check: 'Selective Disclosure', message: 'Tampered' },
+    issuer_resolution_failed: { check: 'Issuer', message: 'Could not be found' },
+    verification_method_not_found: { check: 'Issuer', message: 'Key not found' },
+    verification_method_not_authorized: { check: 'Issuer', message: 'Key not authorized' },
+    signature_invalid: { check: 'Signature', message: 'Invalid' },
+    expired: { check: 'Expiration', message: 'Expired' },
+    not_yet_valid: { check: 'Expiration', message: 'Not yet valid' },
+    vct_mismatch: { check: 'Credential Type', message: 'Mismatch' },
+    status_check_failed: { check: 'Status', message: 'Revoked or suspended' },
+    kb_jwt_invalid: { check: 'Key Binding', message: 'Invalid' },
+    presentation_verification_failed: { check: 'Presentation', message: 'Invalid' },
+    key_binding_mismatch: { check: 'Holder Key', message: 'Mismatch' },
+    unsupported_cnf_confirmation_type: { check: 'Holder Key', message: 'Unsupported type' },
+    internal_error: { check: 'Verification', message: 'Something went wrong' },
+};
+
+const isAlreadyPrettified = (check: string | undefined): boolean => {
+    if (!check) return true;
+    return /^[A-Z]/.test(check) || /\s/.test(check);
+};
+
+const extractErrorCode = (message: string | undefined): string | undefined => {
+    if (!message) return undefined;
+    const match = message.match(/^([a-z][a-z0-9_]*):/);
+    return match?.[1];
+};
+
+/**
+ * Derive a snake_case error code from a `check` that may already be a raw
+ * diagnostic phrase. The W3C verifier's `transformErrorCheck` returns
+ * `error.split(' error')[0]`, which can be e.g. `"signature_invalid: bad
+ * signature"` — the leading token before `:`/whitespace is the real code.
+ */
+const codeFromCheck = (check: string | undefined): string | undefined => {
+    if (!check) return undefined;
+    const token = check.split(/[:\s]/)[0];
+    return /^[a-z][a-z0-9_]*$/.test(token) ? token : undefined;
+};
+
+/**
+ * Resolve a known ERROR_LABELS code from a failed item. Layer 1
+ * (verify.ts) puts the code in `check` (possibly containing spaces) and
+ * the human diagnostic in `details`, NOT `message` — so scan all three
+ * and only accept a candidate that maps to a known label.
+ */
+const resolveErrorCode = (item: VerificationItem): string | undefined => {
+    const candidates = [
+        extractErrorCode(item.message),
+        extractErrorCode(item.details),
+        codeFromCheck(item.check),
+    ];
+    return candidates.find((code): code is string => code !== undefined && code in ERROR_LABELS);
+};
+
+/**
+ * A `message` is "raw" when it carries no human-meaningful detail
+ * beyond the check code itself. Upstream verifiers vary:
+ *
+ * - SD-JWT-VC plugin emits `{ check: 'expiration', message: 'expiration' }`
+ *   (or message === undefined) — the message is a placeholder and we
+ *   should replace it with the prettified label.
+ * - The W3C VC verifier (`packages/plugins/learn-card/src/verify.ts`)
+ *   emits `{ check: 'expiration', message: 'Expires 28 FEB 2023' }` —
+ *   the message is already humanized with credential-specific detail
+ *   (the actual expiration date), and we MUST preserve it.
+ * - SD-JWT-VC failures arrive as `{ check: 'signature_invalid',
+ *   message: 'signature_invalid: details' }` — the message is raw
+ *   diagnostic prefixed with the code; replace with the label.
+ *
+ * Treating "message looks raw" as the trigger keeps the prettifier
+ * idempotent and non-destructive for any verifier that has already
+ * done its own humanization.
+ */
+const isMessageRaw = (message: string | undefined, check: string): boolean => {
+    if (!message) return true;
+    if (message === check) return true;
+    if (/^[a-z][a-z0-9_]*$/.test(message)) return true;
+    if (message.startsWith(`${check}:`)) return true;
+    return false;
+};
+
+export const prettifyVerificationItem = (item: VerificationItem): VerificationItem => {
+    const isFailed = item.status === VerificationStatusEnum.Failed;
+
+    if (isFailed) {
+        // Failures are resolved before the `isAlreadyPrettified` guard
+        // because Layer 1 emits a `check` that often contains whitespace
+        // (e.g. "signature_invalid: bad signature"), which the guard would
+        // otherwise treat as already-prettified and skip.
+        const code = resolveErrorCode(item);
+        if (!code) return item;
+        const label = ERROR_LABELS[code];
+
+        // The UI renders failed rows as `message ?? details`. If Layer 1
+        // humanized the diagnostic into `details` (e.g. "Expired 28 FEB
+        // 2023", "Status: Revoked"), preserve it: keep `message` empty so
+        // the UI falls through to `details`. If `message` itself is already
+        // humanized, keep it. Only when neither carries human detail do we
+        // synthesize the generic label, so a real diagnostic is never shadowed.
+        const detailsHumanized = Boolean(item.details) && !isMessageRaw(item.details, item.check);
+        const messageHumanized = Boolean(item.message) && !isMessageRaw(item.message, item.check);
+
+        let message: string | undefined;
+        if (messageHumanized) message = item.message;
+        else if (detailsHumanized) message = undefined;
+        else message = label.message;
+
+        return {
+            ...item,
+            check: label.check,
+            message,
+        };
+    }
+
+    if (isAlreadyPrettified(item.check)) return item;
+
+    const label = SUCCESS_LABELS[item.check];
+    if (label) {
+        return {
+            ...item,
+            check: label.check,
+            message: isMessageRaw(item.message, item.check) ? label.message : item.message,
+        };
+    }
+
+    return item;
+};
+
+export const prettifyVerificationItems = (items: VerificationItem[]): VerificationItem[] =>
+    items.map(prettifyVerificationItem);

package/src/verify.ts

@@ -0,0 +1,194 @@
+import {
+    StatusCheckEntry,
+    VC,
+    VerificationCheck,
+    VerificationItem,
+    VerificationStatusEnum,
+} from '@learncard/types';
+import { format } from 'date-fns';
+
+import { LearnCard } from '@learncard/core';
+import { ProofOptions } from '@learncard/didkit-plugin';
+
+const STATUS_CHECKS = new Set(['status', 'credentialStatus']);
+
+const isStatusCheck = (check: string): boolean => STATUS_CHECKS.has(check);
+
+const getStatusPurposeLabel = (statusPurpose: string): string => {
+    switch (statusPurpose) {
+        case 'revocation':
+            return 'Revocation';
+        case 'suspension':
+            return 'Suspension';
+        default:
+            return statusPurpose
+                .replace(/([a-z])([A-Z])/g, '$1 $2')
+                .replace(/[-_]+/g, ' ')
+                .replace(/\s+/g, ' ')
+                .trim()
+                .replace(/\b\w/g, letter => letter.toUpperCase());
+    }
+};
+
+const getClearStatusMessage = (statusPurpose: string): string => {
+    switch (statusPurpose) {
+        case 'revocation':
+            return 'Not Revoked';
+        case 'suspension':
+            return 'Not Suspended';
+        default:
+            return `${getStatusPurposeLabel(statusPurpose)} Clear`;
+    }
+};
+
+const getSetStatusMessage = (statusPurpose: string): string => {
+    switch (statusPurpose) {
+        case 'revocation':
+            return 'Revoked';
+        case 'suspension':
+            return 'Suspended';
+        default:
+            return `${getStatusPurposeLabel(statusPurpose)} Set`;
+    }
+};
+
+const getUniqueStatusPurposes = (statuses: StatusCheckEntry[]): string[] => [
+    ...new Set(statuses.map(status => status.statusPurpose)),
+];
+
+const transformStatusCheckMessage = (statusEntries: StatusCheckEntry[] = []): string => {
+    const setStatuses = statusEntries.filter(status => status.isSet);
+    if (setStatuses.length > 0) {
+        return getUniqueStatusPurposes(setStatuses).map(getSetStatusMessage).join(', ');
+    }
+
+    const clearPurposes = getUniqueStatusPurposes(statusEntries);
+    if (clearPurposes.length === 1) return getClearStatusMessage(clearPurposes[0]!);
+
+    return 'Active';
+};
+
+const getStatusErrorMessage = (
+    error: string,
+    verificationCheck?: VerificationCheck
+): string | undefined => {
+    if (/credential is revoked/i.test(error)) return 'Status: Revoked';
+    if (/credential is suspended/i.test(error)) return 'Status: Suspended';
+
+    const statusPurpose = error.match(/credential status is set for purpose:\s*([^.]+)/i)?.[1];
+    if (statusPurpose) return `Status: ${getSetStatusMessage(statusPurpose.trim())}`;
+
+    if (!/status/i.test(error)) return;
+
+    const setStatuses = verificationCheck?.status?.filter(status => status.isSet) ?? [];
+    if (setStatuses.length > 0) return `Status: ${transformStatusCheckMessage(setStatuses)}`;
+};
+
+const transformErrorCheck = (
+    error: string,
+    _credential: VC,
+    verificationCheck?: VerificationCheck
+): string => {
+    if (getStatusErrorMessage(error, verificationCheck)) return 'status';
+
+    const prefix = error.split(' error')[0];
+
+    return prefix || error;
+};
+
+const transformErrorMessage = (
+    error: string,
+    credential: VC,
+    verificationCheck?: VerificationCheck
+): string => {
+    const statusErrorMessage = getStatusErrorMessage(error, verificationCheck);
+    if (statusErrorMessage) return statusErrorMessage;
+
+    if (error.startsWith('expiration')) {
+        return credential.expirationDate
+            ? `Expired ${format(new Date(credential.expirationDate), 'dd MMM yyyy').toUpperCase()}`
+            : 'Expired';
+    }
+
+    return error;
+};
+
+const transformWarningCheck = (warning: string, _credential: VC): string => {
+    if (warning.includes('Boost Authenticity')) return 'Boost Authenticity';
+
+    const prefix = warning.split(' warning')[0];
+
+    return prefix || warning;
+};
+
+const transformCheckMessage = (
+    check: string,
+    credential: VC,
+    verificationCheck: VerificationCheck
+): string => {
+    if (isStatusCheck(check)) return transformStatusCheckMessage(verificationCheck.status);
+
+    return (
+        {
+            proof: 'Valid',
+            expiration: credential.expirationDate
+                ? `Expires ${format(
+                      new Date(credential.expirationDate),
+                      'dd MMM yyyy'
+                  ).toUpperCase()}`
+                : 'Does Not Expire',
+        }[check] || check
+    );
+};
+
+export const verifyCredential = (
+    learnCard: LearnCard<
+        any,
+        any,
+        {
+            verifyCredential: (
+                credential: VC,
+                options?: Partial<ProofOptions>
+            ) => Promise<VerificationCheck>;
+        }
+    >
+): ((
+    _learnCard: LearnCard<any, any, any>,
+    credential: VC,
+    options?: Partial<ProofOptions>,
+    prettify?: boolean
+) => Promise<VerificationItem[] | VerificationCheck>) => {
+    return async (_learnCard, credential, options, prettify = false) => {
+        const rawVerificationCheck = await learnCard.invoke.verifyCredential(credential, options);
+
+        if (!prettify) return rawVerificationCheck;
+
+        const verificationItems: VerificationItem[] = [];
+
+        rawVerificationCheck.errors.forEach(error => {
+            verificationItems.push({
+                status: VerificationStatusEnum.Failed,
+                check: transformErrorCheck(error, credential, rawVerificationCheck),
+                details: transformErrorMessage(error, credential, rawVerificationCheck),
+            });
+        });
+
+        rawVerificationCheck.warnings.forEach(warning => {
+            verificationItems.push({
+                status: VerificationStatusEnum.Error,
+                check: transformWarningCheck(warning, credential),
+                message: warning,
+            });
+        });
+
+        rawVerificationCheck.checks.forEach(check => {
+            verificationItems.push({
+                status: VerificationStatusEnum.Success,
+                check: isStatusCheck(check) ? 'status' : check,
+                message: transformCheckMessage(check, credential, rawVerificationCheck),
+            });
+        });
+
+        return verificationItems;
+    };
+};