@learncard/render-method-plugin 3.0.4 → 3.0.6

package/package.json

@@ -1,64 +1,66 @@
 {
-  "name": "@learncard/render-method-plugin",
-  "version": "3.0.4",
-  "description": "LearnCard plugin for attaching W3C renderMethod to Verifiable Credentials",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/render-method-plugin.esm.js",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/render-method-plugin.esm.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "author": "Learning Economy Foundation (www.learningeconomy.io)",
-  "license": "MIT",
-  "homepage": "https://github.com/learningeconomy/LearnCard/tree/main/packages/plugins/render-method/README.md",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/learningeconomy/LearnCard.git"
-  },
-  "bugs": {
-    "url": "https://github.com/learningeconomy/LearnCard/issues"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.2.2",
-    "@types/node": "^17.0.31",
-    "aqu": "0.4.3",
-    "esbuild": "^0.14.38",
-    "esbuild-jest": "^0.5.0",
-    "esbuild-plugin-copy": "^1.3.0",
-    "jest": "^29.3.0",
-    "rimraf": "^3.0.2",
-    "shx": "^0.3.4",
-    "ts-jest": "^29.0.3",
-    "@learncard/core": "9.4.24",
-    "@learncard/types": "5.17.4",
-    "@learncard/helpers": "1.3.6"
-  },
-  "peerDependencies": {
-    "@learncard/core": "9.4.24",
-    "@learncard/types": "5.17.4",
-    "@learncard/helpers": "1.3.6"
-  },
-  "dependencies": {
-    "@learncard/helpers": "1.3.6"
-  },
-  "types": "./dist/index.d.ts",
-  "sideEffects": false,
-  "scripts": {
-    "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntypoint.js ./dist/index.cjs && tsc --p tsconfig.json && shx cp ./dist/index.d.ts ./dist/index.d.cts",
-    "test": "jest --passWithNoTests",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --silent --ci --coverage --coverageReporters=\"text\" --coverageReporters=\"text-summary\""
-  }
-}
+    "name": "@learncard/render-method-plugin",
+    "version": "3.0.6",
+    "description": "LearnCard plugin for attaching W3C renderMethod to Verifiable Credentials",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/render-method-plugin.esm.js",
+    "exports": {
+        ".": {
+            "development": "./src/index.ts",
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/render-method-plugin.esm.js"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        }
+    },
+    "files": [
+        "dist",
+        "src"
+    ],
+    "scripts": {
+        "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntypoint.js ./dist/index.cjs && tsc --p tsconfig.json && shx cp ./dist/index.d.ts ./dist/index.d.cts",
+        "test": "jest --passWithNoTests",
+        "test:watch": "jest --watch",
+        "test:coverage": "jest --silent --ci --coverage --coverageReporters=\"text\" --coverageReporters=\"text-summary\""
+    },
+    "author": "Learning Economy Foundation (www.learningeconomy.io)",
+    "license": "MIT",
+    "homepage": "https://github.com/learningeconomy/LearnCard/tree/main/packages/plugins/render-method/README.md",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/learningeconomy/LearnCard.git"
+    },
+    "bugs": {
+        "url": "https://github.com/learningeconomy/LearnCard/issues"
+    },
+    "devDependencies": {
+        "@learncard/core": "9.4.26",
+        "@learncard/helpers": "1.3.8",
+        "@learncard/types": "5.17.5",
+        "@types/jest": "^29.2.2",
+        "@types/node": "^17.0.31",
+        "aqu": "0.4.3",
+        "esbuild": "^0.14.38",
+        "esbuild-jest": "^0.5.0",
+        "esbuild-plugin-copy": "^1.3.0",
+        "jest": "^29.3.0",
+        "rimraf": "^3.0.2",
+        "shx": "^0.3.4",
+        "ts-jest": "^29.0.3"
+    },
+    "peerDependencies": {
+        "@learncard/core": "9.4.26",
+        "@learncard/helpers": "1.3.8",
+        "@learncard/types": "5.17.5"
+    },
+    "dependencies": {
+        "@learncard/helpers": "1.3.8"
+    },
+    "types": "./dist/index.d.ts",
+    "sideEffects": false
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './plugin';
+export * from './read';

package/src/plugin.ts

@@ -0,0 +1,150 @@
+import { UnsignedVC, TemplateRenderMethod } from '@learncard/types';
+
+import {
+    AttachRenderMethodConfig,
+    RenderMethodDependentLearnCard,
+    RenderMethodPlugin,
+    RENDER_METHOD_CONTEXT,
+} from './types';
+import {
+    buildRenderData,
+    findRenderMethod,
+    findRenderMethods,
+    findTemplateRenderMethod,
+    findTemplateRenderMethods,
+    getRenderMethods,
+    getSvgMustacheRenderMethod,
+} from './read';
+
+/**
+ * The default hosted SVG Mustache template, served from `packages/render-method-templates/`.
+ *
+ * Exported so callers can opt in to the default explicitly:
+ *
+ *     lc.invoke.attachRenderMethod(vc, { templateId: DEFAULT_TEMPLATE_ID })
+ *
+ * Per the opt-in contract for `attachRenderMethod`, calling without a config will NOT attach this
+ * template — callers must be explicit.
+ */
+export const DEFAULT_TEMPLATE_ID = 'https://templates.learncard.com/svg/card/card-1.0.0.svg';
+
+/**
+ * Validates a `templateId` URL. Only `http://` and `https://` schemes are accepted.
+ *
+ * Why this exists: the `templateId` is fetched at render time. Permitting `javascript:`,
+ * `file:`, or empty strings would expose the renderer to obvious script-injection or
+ * local-file-read vectors. The renderer (`renderSvgMustache`) also runs DOMPurify as a
+ * second line of defense, but blocking unsafe schemes at the source is cheaper.
+ */
+const isValidTemplateId = (templateId: string): boolean => {
+    if (!templateId || !templateId.trim()) return false;
+    return /^https?:\/\//i.test(templateId);
+};
+
+/**
+ * Builds a `TemplateRenderMethod` from the given config. Inline `templateValue` takes priority
+ * and is URL-encoded into a `data:image/svg+xml,...` URI. Otherwise `templateId` is used as-is.
+ *
+ * @throws if neither `templateId` nor `templateValue` is provided, if `templateId` is not http(s),
+ *         or if `templateValue` is empty.
+ */
+export const buildTemplateRenderMethod = (
+    config: AttachRenderMethodConfig
+): TemplateRenderMethod => {
+    let template: string;
+
+    if ('templateValue' in config && config.templateValue !== undefined) {
+        if (!config.templateValue.trim()) {
+            throw new Error(
+                'buildTemplateRenderMethod: `templateValue` must be a non-empty SVG string.'
+            );
+        }
+        template = `data:image/svg+xml,${encodeURIComponent(config.templateValue)}`;
+    } else if ('templateId' in config && config.templateId !== undefined) {
+        if (!isValidTemplateId(config.templateId)) {
+            throw new Error(
+                `buildTemplateRenderMethod: \`templateId\` must be an http(s) URL, got: ${config.templateId}`
+            );
+        }
+        template = config.templateId;
+    } else {
+        throw new Error(
+            'buildTemplateRenderMethod: must provide either `templateId` or `templateValue` in config.'
+        );
+    }
+
+    return {
+        type: 'TemplateRenderMethod',
+        // TODO: Add other render suites (e.g., WebRenderingTemplate2022, HtmlMustacheRenderingTemplate)
+        renderSuite: 'svg-mustache',
+        template,
+        // Only include renderProperty when explicitly provided to avoid overriding VC defaults
+        ...(config.renderProperty ? { renderProperty: config.renderProperty } : {}),
+        // TODO: Make mediaType configurable per renderSuite once additional suites are supported
+        outputPreference: { mediaType: 'image/svg+xml' as const },
+    };
+};
+
+/**
+ * Attaches a `TemplateRenderMethod` to an unsigned VC, merging with any existing `renderMethod`
+ * entries. Injects the render-method JSON-LD context if not already present.
+ *
+ * **Opt-in semantics:** If `config` is omitted, the VC is returned UNCHANGED. The caller must
+ * explicitly opt in by providing `templateId` or `templateValue`. Pass `DEFAULT_TEMPLATE_ID` to
+ * use the default hosted template.
+ *
+ * This contract intentionally avoids polluting every issued credential's `@context` with the
+ * draft render-method context URL. See `RENDER_METHOD_CONTEXT` for the rationale.
+ */
+export const attachRenderMethod = (
+    vc: UnsignedVC,
+    config?: AttachRenderMethodConfig
+): UnsignedVC => {
+    // Opt-in: no config → no-op. Callers must explicitly choose a template.
+    if (!config) return vc;
+
+    const renderMethod = buildTemplateRenderMethod(config);
+
+    // Normalize @context to an array so we can safely append to it.
+    const context = Array.isArray(vc['@context']) ? vc['@context'] : [vc['@context']];
+    const updatedContext = context.includes(RENDER_METHOD_CONTEXT)
+        ? context
+        : [...context, RENDER_METHOD_CONTEXT];
+
+    const existingRenderMethod = vc.renderMethod;
+    let updatedRenderMethod: TemplateRenderMethod | TemplateRenderMethod[];
+
+    if (!existingRenderMethod) {
+        updatedRenderMethod = renderMethod;
+    } else if (Array.isArray(existingRenderMethod)) {
+        updatedRenderMethod = [...(existingRenderMethod as TemplateRenderMethod[]), renderMethod];
+    } else {
+        updatedRenderMethod = [existingRenderMethod as TemplateRenderMethod, renderMethod];
+    }
+
+    return {
+        ...vc,
+        '@context': updatedContext,
+        renderMethod: updatedRenderMethod,
+    };
+};
+
+export const getRenderMethodPlugin = (
+    _learnCard: RenderMethodDependentLearnCard
+): RenderMethodPlugin => ({
+    name: 'Render Method',
+    displayName: 'Render Method Plugin',
+    description:
+        'Attaches W3C renderMethod to Verifiable Credentials for standards-based rendering',
+    methods: {
+        attachRenderMethod: (_lc, vc, config) => attachRenderMethod(vc, config),
+        buildTemplateRenderMethod: (_lc, config) => buildTemplateRenderMethod(config),
+        getRenderMethods: (_lc, vc) => getRenderMethods(vc),
+        findRenderMethod: (_lc, vc, predicate) => findRenderMethod(vc, predicate),
+        findRenderMethods: (_lc, vc, predicate) => findRenderMethods(vc, predicate),
+        findTemplateRenderMethod: (_lc, vc, suite) => findTemplateRenderMethod(vc, suite),
+        findTemplateRenderMethods: (_lc, vc, suite) => findTemplateRenderMethods(vc, suite),
+        getSvgMustacheRenderMethod: (_lc, vc) => getSvgMustacheRenderMethod(vc),
+        buildRenderData: (_lc, vc, renderProperty) => buildRenderData(vc, renderProperty),
+    },
+});

package/src/read.ts

@@ -0,0 +1,225 @@
+import { unwrapBoostCredential } from '@learncard/helpers';
+import {
+    UnsignedVC,
+    VC,
+    RenderMethod,
+    TemplateRenderMethod,
+    TemplateRenderMethodValidator,
+} from '@learncard/types';
+
+type AnyCredential = VC | UnsignedVC;
+type JsonRecord = Record<string, unknown>;
+
+/** Mustache context shape produced by `buildRenderData`. */
+export type RenderMethodData = JsonRecord;
+
+/**
+ * Type guard for any `TemplateRenderMethod` (Zod-validated). Use for shape
+ * checks before treating an unknown `renderMethod` entry as a template render.
+ */
+export const isTemplateRenderMethod = (rm: unknown): rm is TemplateRenderMethod =>
+    TemplateRenderMethodValidator.safeParse(rm).success;
+
+/**
+ * Type guard for `TemplateRenderMethod` with `renderSuite === 'svg-mustache'`.
+ * Exported so consumers can compose their own selection (e.g., capability
+ * negotiation across multiple suites the renderer supports).
+ */
+export const isSvgMustacheRenderMethod = (rm: unknown): rm is TemplateRenderMethod => {
+    const parsed = TemplateRenderMethodValidator.safeParse(rm);
+    return parsed.success && parsed.data.renderSuite === 'svg-mustache';
+};
+
+/**
+ * Returns all `renderMethod` entries on a VC. Normalizes single-object form to
+ * an array and unwraps `CertifiedBoostCredential` so callers don't have to
+ * think about the wrapping layer.
+ *
+ * Entries are NOT validated here. Callers apply type guards via
+ * `findRenderMethod` / `findRenderMethods`, or one of the typed conveniences.
+ */
+export const getRenderMethods = (vc: AnyCredential): RenderMethod[] => {
+    const effective = (unwrapBoostCredential(vc) ?? vc) as
+        | Record<string, unknown>
+        | undefined;
+    const raw = effective?.renderMethod;
+    if (!raw) return [];
+    return (Array.isArray(raw) ? raw : [raw]) as RenderMethod[];
+};
+
+/**
+ * First `renderMethod` matching a type-guard predicate, or `null` if none.
+ *
+ * The predicate receives raw entries so it can apply Zod-validated guards
+ * (e.g., `isSvgMustacheRenderMethod`). The return type is narrowed by the
+ * predicate.
+ */
+export function findRenderMethod<T extends RenderMethod = RenderMethod>(
+    vc: AnyCredential,
+    predicate: (rm: RenderMethod) => rm is T
+): T | null {
+    for (const entry of getRenderMethods(vc)) {
+        if (predicate(entry)) return entry;
+    }
+    return null;
+}
+
+/** Like `findRenderMethod`, but returns every matching entry. */
+export function findRenderMethods<T extends RenderMethod = RenderMethod>(
+    vc: AnyCredential,
+    predicate: (rm: RenderMethod) => rm is T
+): T[] {
+    return getRenderMethods(vc).filter(predicate);
+}
+
+/**
+ * First `TemplateRenderMethod` on a VC whose `renderSuite` matches the given
+ * suite name, or `null`. Accepts a single suite string OR an array of suite
+ * strings (returns the first match across the list — useful for capability
+ * negotiation when a renderer supports multiple suites).
+ *
+ * Returns the Zod-parsed shape (not the raw entry).
+ *
+ *     findTemplateRenderMethod(vc, 'svg-mustache')
+ *     findTemplateRenderMethod(vc, ['svg-mustache', 'html-mustache'])
+ */
+export const findTemplateRenderMethod = (
+    vc: AnyCredential,
+    suite: string | readonly string[]
+): TemplateRenderMethod | null => {
+    const suites = typeof suite === 'string' ? new Set([suite]) : new Set(suite);
+    for (const entry of getRenderMethods(vc)) {
+        const parsed = TemplateRenderMethodValidator.safeParse(entry);
+        if (parsed.success && suites.has(parsed.data.renderSuite)) {
+            return parsed.data;
+        }
+    }
+    return null;
+};
+
+/** Like `findTemplateRenderMethod`, but returns every matching entry. */
+export const findTemplateRenderMethods = (
+    vc: AnyCredential,
+    suite: string | readonly string[]
+): TemplateRenderMethod[] => {
+    const suites = typeof suite === 'string' ? new Set([suite]) : new Set(suite);
+    const result: TemplateRenderMethod[] = [];
+    for (const entry of getRenderMethods(vc)) {
+        const parsed = TemplateRenderMethodValidator.safeParse(entry);
+        if (parsed.success && suites.has(parsed.data.renderSuite)) {
+            result.push(parsed.data);
+        }
+    }
+    return result;
+};
+
+/**
+ * Convenience: the first svg-mustache `TemplateRenderMethod` on a VC, or `null`.
+ * Equivalent to `findTemplateRenderMethod(vc, 'svg-mustache')`.
+ */
+export const getSvgMustacheRenderMethod = (
+    vc: AnyCredential
+): TemplateRenderMethod | null => findTemplateRenderMethod(vc, 'svg-mustache');
+
+/**
+ * Prototype-pollution guard. JSON Pointers come from credential data
+ * (untrusted), and these three keys are the canonical pollution vectors when
+ * a pointer is walked with bracket-indexing.
+ */
+const isUnsafeKey = (key: string): boolean =>
+    key === '__proto__' || key === 'constructor' || key === 'prototype';
+
+const resolvePointer = (obj: unknown, pointer: string): unknown => {
+    if (!pointer || pointer === '/') return obj;
+    const parts = pointer
+        .replace(/^\//, '')
+        .split('/')
+        .map(p => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+
+    if (parts.some(isUnsafeKey)) return undefined;
+
+    let current: unknown = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== 'object')
+            return undefined;
+        current = (current as Record<string, unknown>)[part];
+    }
+    return current;
+};
+
+const buildRenderDataFromPointers = (
+    vc: AnyCredential,
+    pointers: string[]
+): JsonRecord => {
+    const result: JsonRecord = Object.create(null) as JsonRecord;
+    const isUnsafeKey = (key: string): boolean =>
+        key === '__proto__' || key === 'constructor' || key === 'prototype';
+
+    for (const pointer of pointers) {
+        const value = resolvePointer(vc, pointer);
+        if (value === undefined) continue;
+
+        const parts = pointer
+            .replace(/^\//, '')
+            .split('/')
+            .map(p => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+
+        if (parts.some(isUnsafeKey)) continue;
+
+        let current = result;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const part = parts[i];
+            if (!current[part] || typeof current[part] !== 'object') {
+                current[part] = Object.create(null) as JsonRecord;
+            }
+            current = current[part] as JsonRecord;
+        }
+
+        const lastPart = parts[parts.length - 1];
+        if (isUnsafeKey(lastPart)) continue;
+        current[lastPart] = value;
+    }
+
+    return result;
+};
+
+/**
+ * Builds the portable Mustache context for a VC. Designed for SVG / HTML /
+ * text Mustache templates that may have been authored against any of these
+ * shapes:
+ *
+ *     {{credentialSubject.name}}                                // direct VC paths
+ *     {{credential.credentialSubject.name}}                     // `credential` alias
+ *     {{vc.issuer.name}}                                        // `vc` alias
+ *     {{#credentialSubjects}}{{name}}{{/credentialSubjects}}    // section over array
+ *
+ * The top-level credential is the single source of truth; aliases keep older
+ * templates working. When `renderProperty` (RFC 6901 JSON Pointers) is given,
+ * those values are overlaid at their pointer paths in the resulting context.
+ *
+ * This function does NOT unwrap `CertifiedBoostCredential` — pass the layer
+ * you want the template to bind to. `getRenderMethods` is the helper that
+ * unwraps.
+ */
+export const buildRenderData = (
+    vc: AnyCredential,
+    renderProperty?: string[]
+): RenderMethodData => {
+    const credential = vc as unknown as JsonRecord;
+    const base: RenderMethodData = {
+        ...credential,
+        vc: credential,
+        credential,
+        credentialSubjects: Array.isArray(credential.credentialSubject)
+            ? credential.credentialSubject
+            : [credential.credentialSubject].filter(Boolean),
+    };
+
+    if (!renderProperty || renderProperty.length === 0) return base;
+
+    return {
+        ...base,
+        ...buildRenderDataFromPointers(vc, renderProperty),
+        credential,
+    };
+};