@learncard/render-method-plugin 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Learning Economy Foundation <sdk@learningeconomy.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# @learncard/render-method-plugin
+
+Attach W3C `renderMethod` entries to Verifiable Credentials using SVG Mustache templates.
+
+The plugin is stateless and has no required dependent methods or control planes.
+
+## Install
+
+This plugin is part of the LearnCard monorepo and is built with the workspace. It is registered automatically as part of the default LearnCard wallet stack (see `packages/learn-card-base/src/helpers/walletHelpers.ts`).
+
+To add it manually to a custom LearnCard instance:
+
+```ts
+import { getRenderMethodPlugin } from '@learncard/render-method-plugin';
+
+const lc = await baseLc.addPlugin(getRenderMethodPlugin(baseLc));
+```
+
+## API
+
+### Write side
+
+| Method | Signature | Description |
+|---|---|---|
+| `attachRenderMethod` | `(vc, config?) => UnsignedVC` | Attaches a `TemplateRenderMethod` to the VC and injects the JSON-LD context. **Opt-in:** returns the VC unchanged when `config` is omitted. Merges with existing `renderMethod` entries. |
+| `buildTemplateRenderMethod` | `(config) => TemplateRenderMethod` | Builds a `TemplateRenderMethod` descriptor without mutating a VC. |
+
+### Read side
+
+Layered API — pick the level that fits your need:
+
+| Method | Signature | When to use |
+|---|---|---|
+| `findTemplateRenderMethod` | `(vc, suite \| suites[]) => TemplateRenderMethod \| null` | **Most common.** Filter by `renderSuite` string. Pass an array for capability negotiation. |
+| `findTemplateRenderMethods` | `(vc, suite \| suites[]) => TemplateRenderMethod[]` | All matches of a suite (or any of several). |
+| `getSvgMustacheRenderMethod` | `(vc) => TemplateRenderMethod \| null` | Backward-compatible alias for `findTemplateRenderMethod(vc, 'svg-mustache')`. |
+| `findRenderMethod` | `(vc, predicate) => T \| null` | Escape hatch: arbitrary predicate for non-template render methods. |
+| `findRenderMethods` | `(vc, predicate) => T[]` | Same, all matches. |
+| `getRenderMethods` | `(vc) => RenderMethod[]` | Raw access. Unwraps `CertifiedBoostCredential`, normalizes object↔array. No validation. |
+| `buildRenderData` | `(vc, renderProperty?) => Record<string, unknown>` | Portable Mustache context (adds `vc` / `credential` / `credentialSubjects` aliases). Optional RFC 6901 overlay. |
+
+### Type guards (composable selection)
+
+| Guard | Narrows to |
+|---|---|
+| `isTemplateRenderMethod(rm)` | `TemplateRenderMethod` (Zod-validated shape) |
+| `isSvgMustacheRenderMethod(rm)` | `TemplateRenderMethod` with `renderSuite === 'svg-mustache'` |
+
+### Constants
+
+- `DEFAULT_TEMPLATE_ID` — URL of the default hosted LearnCard template. Pass as `templateId` to opt in.
+- `RENDER_METHOD_CONTEXT` — JSON-LD context URL injected by `attachRenderMethod`. See the [draft context warning](#draft-context-warning).
+
+### Throws
+
+- `attachRenderMethod` / `buildTemplateRenderMethod` throw if:
+  - `templateId` is provided but is not an `http://` or `https://` URL.
+  - `templateValue` is provided but is empty or whitespace-only.
+  - `buildTemplateRenderMethod` is called without either field set.
+
+### `AttachRenderMethodConfig`
+
+`templateId` and `templateValue` are mutually exclusive — provide one or the other. The discriminated union enforces this at compile time.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `templateId` | `string` | HTTPS URL of a hosted SVG Mustache template. Only `http://` and `https://` schemes are accepted. |
+| `templateValue` | `string` | Inline SVG Mustache content (embedded as a URL-encoded `data:image/svg+xml,` URI). Must be non-empty. |
+| `renderProperty` | `string[]?` | JSON Pointer paths (RFC 6901) scoping which VC fields are exposed to the template. |
+
+## Opt-in semantics
+
+`attachRenderMethod` is **opt-in**. Calling it without a config returns the VC unchanged, which means callers must explicitly choose to attach a render method:
+
+```ts
+// No-op — returns vc unchanged
+lc.invoke.attachRenderMethod(vc);
+
+// Attaches the default template
+lc.invoke.attachRenderMethod(vc, { templateId: DEFAULT_TEMPLATE_ID });
+
+// Attaches a custom hosted template
+lc.invoke.attachRenderMethod(vc, { templateId: 'https://example.com/badge.svg' });
+
+// Attaches an inline template (URL-encoded into a data: URI)
+lc.invoke.attachRenderMethod(vc, { templateValue: '<svg>...</svg>' });
+```
+
+This contract intentionally avoids polluting every issued credential's `@context` with the draft render-method context URL. See the [draft context warning](#draft-context-warning).
+
+## Quick start
+
+### Use the default LearnCard template
+
+```ts
+import { DEFAULT_TEMPLATE_ID } from '@learncard/render-method-plugin';
+
+const vcWithRender = lc.invoke.attachRenderMethod(unsignedVc, {
+    templateId: DEFAULT_TEMPLATE_ID,
+});
+const signedVc = await lc.invoke.issueCredential(vcWithRender);
+```
+
+### Use a custom hosted template
+
+```ts
+const vcWithRender = lc.invoke.attachRenderMethod(unsignedVc, {
+    templateId: 'https://templates.example.com/badge.svg',
+    renderProperty: ['/credentialSubject/name', '/credentialSubject/description'],
+});
+const signedVc = await lc.invoke.issueCredential(vcWithRender);
+```
+
+### Use an inline template
+
+```ts
+const svgTemplate =
+    '<svg xmlns="http://www.w3.org/2000/svg"><text>{{credentialSubject.name}}</text></svg>';
+
+const vcWithRender = lc.invoke.attachRenderMethod(unsignedVc, {
+    templateValue: svgTemplate,
+});
+const signedVc = await lc.invoke.issueCredential(vcWithRender);
+```
+
+### Build a render method descriptor independently
+
+```ts
+const renderMethod = lc.invoke.buildTemplateRenderMethod({
+    templateId: 'https://templates.example.com/badge.svg',
+});
+// renderMethod.type === 'TemplateRenderMethod'
+// renderMethod.renderSuite === 'svg-mustache'
+```
+
+## Feature-flag interaction
+
+In `apps/learn-card-app`, the `useRenderMethodEnabled` hook gates the **display** path (the `RenderMethodDisplay` component, the `BoostDisplayStyleSelector`, the `getSvgMustacheRenderMethod` lookup). It does **not** gate the write path — whether to attach a render method to a credential is a per-callsite decision and follows the opt-in semantics above.
+
+In other words: enabling the LaunchDarkly flag turns on rendering for credentials that already have a `renderMethod`, but it does not retroactively change which credentials carry one.
+
+## Draft context warning
+
+`RENDER_METHOD_CONTEXT` currently points to a community-group draft hosted on Digital Bazaar's GitHub Pages:
+
+```
+https://digitalbazaar.github.io/vc-render-method-context/contexts/v2rc2.jsonld
+```
+
+The `v2rc2` suffix means "v2, release candidate 2". This is **not** a finalized W3C TR. Risks of issuing VCs that reference this URL in their `@context`:
+
+- The URL could move, be renamed, or 404 — JSON-LD context resolution would fail at verification time.
+- Term definitions could change between rc2 and a final spec, breaking interpretation.
+- The context is not statically cached by DidKit — verification incurs a network fetch.
+
+Mitigation plan (not yet implemented):
+
+- Bundle the context locally, mirroring the pattern in `packages/learn-card-contexts/`.
+- Migrate to the stable W3C TR context URL when the spec finalizes.
+
+Tracking: <https://www.w3.org/TR/vc-render-method/>
+
+The opt-in semantics above are the primary mitigation for now — credentials that don't need a render method don't get this context URL.
+
+## Extending: supporting a new render suite
+
+The read-side API is intentionally generic so new render suites can be added by callers without a plugin release. For `TemplateRenderMethod`-shaped suites, you don't write any predicate code:
+
+```ts
+// Filter by a single suite
+const found = lc.invoke.findTemplateRenderMethod(vc, 'html-mustache');
+
+// Capability negotiation — first match across the suites your renderer supports
+const renderable = lc.invoke.findTemplateRenderMethod(vc, [
+    'svg-mustache',
+    'html-mustache',
+]);
+
+// All matches (e.g., when offering the user a choice)
+const allHtml = lc.invoke.findTemplateRenderMethods(vc, 'html-mustache');
+```
+
+For non-template render methods (e.g., a future `WebRenderingTemplate2022` with a different shape), use the predicate-based `findRenderMethod` escape hatch with your own type guard.
+
+The plugin handles **selection** and **data shaping** uniformly across suites. The **actual rendering** (Mustache hydration + sanitization) stays in the app/UI layer because sanitization policy (DOMPurify for SVG, different rules for HTML, etc.) is renderer-specific.
+
+## Architectural boundary
+
+- **In the plugin** (this package): data domain — attach renderMethod to VCs, find renderMethod entries, shape Mustache contexts. Pure, isomorphic, CLI-safe.
+- **In the app**: render domain — Mustache hydration into a target format, DOMPurify sanitization, DOM insertion. Browser-specific.
+
+The seam is "data that describes how to render" (plugin) vs. "execute the render and put pixels on screen" (app).
+
+## Notes
+
+- Only `svg-mustache` is supported as a render suite at this time. The renderer in `apps/learn-card-app/src/helpers/renderMethod.helpers.ts` performs DOMPurify sanitization on the hydrated SVG before insertion.
+- See `src/types.ts` for types, `src/plugin.ts` for the write side, `src/read.ts` for the read side.
+- See `src/test/plugin.test.ts` for the full behavior contract.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './plugin';
+export * from './read';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+'use strict';
+
+if (process.env.NODE_ENV === 'production') {
+    module.exports = require('./render-method-plugin.cjs.production.min.js');
+} else {
+    module.exports = require('./render-method-plugin.cjs.development.js');
+}

package/dist/plugin.d.ts

@@ -0,0 +1,35 @@
+import { UnsignedVC, TemplateRenderMethod } from '@learncard/types';
+import { AttachRenderMethodConfig, RenderMethodDependentLearnCard, RenderMethodPlugin } from './types';
+/**
+ * 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 declare const DEFAULT_TEMPLATE_ID = "https://templates.learncard.com/svg/card/card-1.0.0.svg";
+/**
+ * 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 declare const buildTemplateRenderMethod: (config: AttachRenderMethodConfig) => TemplateRenderMethod;
+/**
+ * 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 declare const attachRenderMethod: (vc: UnsignedVC, config?: AttachRenderMethodConfig) => UnsignedVC;
+export declare const getRenderMethodPlugin: (_learnCard: RenderMethodDependentLearnCard) => RenderMethodPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAEpE,OAAO,EACH,wBAAwB,EACxB,8BAA8B,EAC9B,kBAAkB,EAErB,MAAM,SAAS,CAAC;AAWjB;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,4DAA4D,CAAC;AAe7F;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,WAC1B,wBAAwB,KACjC,oBAiCF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,OACvB,UAAU,WACL,wBAAwB,KAClC,UA4BF,CAAC;AAEF,eAAO,MAAM,qBAAqB,eAClB,8BAA8B,KAC3C,kBAgBD,CAAC"}

package/dist/read.d.ts

@@ -0,0 +1,75 @@
+import { UnsignedVC, VC, RenderMethod, TemplateRenderMethod } 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 declare const isTemplateRenderMethod: (rm: unknown) => rm is TemplateRenderMethod;
+/**
+ * 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 declare const isSvgMustacheRenderMethod: (rm: unknown) => rm is TemplateRenderMethod;
+/**
+ * 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 declare const getRenderMethods: (vc: AnyCredential) => 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 declare function findRenderMethod<T extends RenderMethod = RenderMethod>(vc: AnyCredential, predicate: (rm: RenderMethod) => rm is T): T | null;
+/** Like `findRenderMethod`, but returns every matching entry. */
+export declare function findRenderMethods<T extends RenderMethod = RenderMethod>(vc: AnyCredential, predicate: (rm: RenderMethod) => rm is T): T[];
+/**
+ * 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 declare const findTemplateRenderMethod: (vc: AnyCredential, suite: string | readonly string[]) => TemplateRenderMethod | null;
+/** Like `findTemplateRenderMethod`, but returns every matching entry. */
+export declare const findTemplateRenderMethods: (vc: AnyCredential, suite: string | readonly string[]) => TemplateRenderMethod[];
+/**
+ * Convenience: the first svg-mustache `TemplateRenderMethod` on a VC, or `null`.
+ * Equivalent to `findTemplateRenderMethod(vc, 'svg-mustache')`.
+ */
+export declare const getSvgMustacheRenderMethod: (vc: AnyCredential) => TemplateRenderMethod | null;
+/**
+ * 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 declare const buildRenderData: (vc: AnyCredential, renderProperty?: string[]) => RenderMethodData;
+export {};
+//# sourceMappingURL=read.d.ts.map

package/dist/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../src/read.ts"],"names":[],"mappings":"AACA,OAAO,EACH,UAAU,EACV,EAAE,EACF,YAAY,EACZ,oBAAoB,EAEvB,MAAM,kBAAkB,CAAC;AAE1B,KAAK,aAAa,GAAG,EAAE,GAAG,UAAU,CAAC;AACrC,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,sBAAsB,OAAQ,OAAO,KAAG,EAAE,IAAI,oBACJ,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,OAAQ,OAAO,KAAG,EAAE,IAAI,oBAG7D,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,OAAQ,aAAa,KAAG,YAAY,EAOhE,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAClE,EAAE,EAAE,aAAa,EACjB,SAAS,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,EAAE,IAAI,CAAC,GACzC,CAAC,GAAG,IAAI,CAKV;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EACnE,EAAE,EAAE,aAAa,EACjB,SAAS,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,EAAE,IAAI,CAAC,GACzC,CAAC,EAAE,CAEL;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,OAC7B,aAAa,SACV,MAAM,GAAG,SAAS,MAAM,EAAE,KAClC,oBAAoB,GAAG,IASzB,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,OAC9B,aAAa,SACV,MAAM,GAAG,SAAS,MAAM,EAAE,KAClC,oBAAoB,EAUtB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,OAC/B,aAAa,KAClB,oBAAoB,GAAG,IAAoD,CAAC;AAgE/E;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,OACpB,aAAa,mBACA,MAAM,EAAE,KAC1B,gBAkBF,CAAC"}