The `svg-mustache` Render Suite

The `svg-mustache` render suite uses the Mustache templating language to modify an SVG file, which is then used to render a visual representation of the [=verifiable credential=].

In the example below, a fully embedded SVG file is used as the rendering template.

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "svg-mustache",
    // the SVG file is embedded in the VC
    "template": "data:image/svg+xml;base64,Qjei89...3jZpW"
  }
}
          

The next example links to the SVG file on the Web and secures it against modification by using the `digestMultibase` property.

{
...
"renderMethod": {
  "type": "TemplateRenderMethod",
  "renderSuite": "svg-mustache",
  "template": {
    // this SVG file is fetched from the Web
    "id": "https://degree.example/credential-templates/bachelors",
    "mediaType": "image/svg+xml",
    "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR"
  }
}
          

The next example links to the rendering template on the Web and secures it using the `digestMultibase` property:

{
...
"renderMethod": {
  // this render method is fetched from the Web
  "id": "https://degrees.example/bachelors-svg.jsonld",
  "mediaType": "application/ld+json",
  "type": "TemplateRenderMethod",
  "renderSuite": "svg-mustache",
  "digestMultibase": "zQmG270iEu5h6JqWAPdhyxz2dRerWC85Wg6wFl9znFCwYxAp"
}
          

The `pdf-mustache` Render Suite

The `pdf-mustache` render suite uses the Mustache templating language to modify a PDF file, which is then used to render a visual representation of the [=verifiable credential=].

In the example below, a fully embedded PDF file is used as the rendering template.

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "pdf-mustache",
    // this PDF file is embedded in the VC
    "template": "data:application/pdf;base64,k309SK...pwK83b"
  }
}
          

The next example links to the PDF file on the Web and secures it against modification by using the `digestMultibase` property.

{
...
"renderMethod": {
  "type": "TemplateRenderMethod",
  "renderSuite": "pdf-mustache",
  "template": {
    // this PDF file is fetched from the Web
    "id": "https://degree.example/bachelors.pdf",
    "mediaType": "application/pdf",
    "digestMultibase": "zQmznFCwYxApG270iEu5h6JqWAPdhyxz2dRerWC85Wg6wFl9"
  }
}
          

The next example links to the rendering template on the Web and secures it using the `digestMultibase` property:

{
...
"renderMethod": {
  // this render method is fetched from the Web
  "id": "https://degrees.example/bachelors-pdf.jsonld",
  "type": "TemplateRenderMethod",
  "renderSuite": "pdf-mustache",
  "digestMultibase": "zQmEu5h6JqWAPdhyxmz2dRerWC85Wg6wFl9znFCwYxApG270"
}
          

The `nfc` Render Suite

The `nfc` render suite transmits a binary payload representing the [=verifiable credential=] over a wireless NFC connection.

In the example below, a fully embedded NFC payload is used as the rendering template, which only discloses the barcode identifier associated with the credential.

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "nfc",
    "name": "Tap to send",
    // the NFC payload is embedded
    "template": "data:application/octet-stream;base64,2QZkpQGDG...G8XJWnROcY4Biw",
    // only the barcode is transmitted over NFC
    "renderProperty": ["/credentialSubject/barcode"]
  }
  
}
        

The `html` Render Suite

The `html` render suite allows template authors to provide an HTML template to render a [=verifiable credential=]. The HTML can be referenced remotely or via a `data:` URL as the value of either `template` or `template.id` (when the value of `template` is an object). JavaScript within the HTML fragment is responsible for rendering the filtered [=verifiable credential=] data provided via an HTML data block (i.e. `<script type="application/vc"></script>`) hosted in a sandboxed iframe alongside the HTML template.

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "type": [
    "VerifiableCredential",
    "NameCredential"
  ],
  "issuer": {
    "id": "did:example:1234",
    "name": "The Issuer"
  },
  "credentialSubject": {
    "name": "Example Name",
    "notRendered": "should not appear"
  },
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "html",
    "renderProperty": [
      "/issuer/name",
      "/credentialSubject/name"
    ],
    "template": {
      "id": "https://test.example/credential-templates/NameCredential.html",
      "mediaType": "text/html",
      "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR"
    },
    "outputPreference": {
      "mode": [
        "visual"
      ],
      "mediaType": "application/html",
      "style": {
        "width": "800px",
        "height": "800px"
      }
    }
  }
}
        

Implementations MUST provide an environment that allows for JavaScript to safely render the HTML template using the filtered [=verifiable credential=] data. The following terminology is used to describe this environment:

host page

Provides the secure environment for rendering the HTML template.

template code

The HTML fragment provided within or remotely referenced by the Render Method.

wrapper code

Code that wraps the HTML template to provide additional security restrictions and communication with the [=host page=].

At minimum, the environment MUST prevent navigation, loading of external content, and access to the [=host page=] in order to prevent tracking and other privacy harms.

Browser based implementations, for example, can provide such an environment using a combination of Content Security Policy [[CSP3]] restrictions on a [=host page=], sandboxing of an `iframe` hosting the HTML template, and wrapper code that wraps the HTML template to add additional CSP restrictions and provides ready and error event communication with the [=host page=].

graph TD
    subgraph Wallet's VC Rendering HTML
        direction LR
        A(VC) -- selectively disclosed --> B{VC subset datablock}
        subgraph "iframe[srcdoc] wrapper code"
            B{VC subset datablock}
            C[HTML/CSS/JS template from renderMethod]
        end
        C[HTML/CSS/JS template from renderMethod] --> D[renderMethodReady]
    end
          

Host Page

The [=host page=] (typically a Wallet or [=verifiable credential=] renderer) MUST prevent the HTML template from navigating the top-level browsing context, accessing external content, accessing the [=host page=], and loading any remote content.

If a [=host page=] is used, the following rules apply:

• The Content Security Policy (CSP) restrictions MUST include `frame-src 'none'`. This forces the use of `srcdoc` instead of `src` for iframes, which prevents the browser from loading the HTML template. In turn, this forces the [=host page=] code to preload remotely referenced template code and check the response against the related `digestMultibase` value prior to injecting the template into the [=wrapper code=].
• `sandbox="allow-scripts"` MUST be set on the `iframe` hosting the HTML template to prevent navigation and top-level access.

Template Code

The HTML [=template code=] referenced by the `template` property in the `renderMethod` MUST be an HTML fragment that contains the HTML, CSS, and JavaScript necessary to render the [=verifiable credential=]. The [=template code=] MUST NOT include any `<html>`, `<head>`, or `<body>` tags, as these will be provided by the [=wrapper code=].

Wrapper Code

The template HTML fragment MUST be wrapped in [=wrapper code=] that provides the data block containing the partial [=verifiable credential=] and adds an additional CSP policies to prevent navigation and external content loading. Specifically, the [=wrapper code=] MUST add the following CSP restrictions of `default-src data: 'unsafe-inline'` to prevent any network requests from being made by the [=template code=].

To complete the setup, the [=host page=] MUST inject the [=wrapper code=] (once populated with the [=verifiable credential=] and the [=template code=]) into the iframe's `srcdoc` attribute which will run any JavaScript contained in the [=wrapper code=] and [=template code=].

Ready and Error Events

The iframe created in the [=wrapper code=] MUST provide a communication channel to allow the template to notify the [=host page=] when rendering is complete or if there was an error during rendering. This can be accomplished using the `postMessage` API with a `MessageChannel` setup by the [=wrapper code=].

The JavaScript shown below would be added to the above [=host page=] to add an `onload` event to the iframe which sets up the `MessageChannel`. The [=host page=] also creates a `Promise` that resolves when a `ready` message is received from the [=wrapper code=] or rejects when an `error` message is received. The [=wrapper code=] also provides a `window.renderMethodReady` method for use by the template to notify the [=host page=] that rendering is complete or send back an error message.

With this setup, the template JavaScript can call `window.renderMethodReady()` to notify the [=host page=] that rendering is complete or call `window.renderMethodReady(new Error("error message"))` to notify the [=host page=] of an error.

Algorithms

The following sections outline the algorithms that are used by the `html` render suite to safely render the HTML template. Alternative algorithms MAY be used as long as the security and privacy outcomes as well as the output is the same.

Host Page

The [=host page=] MUST create an `iframe` element to host the HTML template. The [=host page=] MUST set the `sandbox` attribute on the `iframe` to `allow-scripts` to prevent navigation and top-level access.

1. Let `vc` be the [=verifiable credential=] to be rendered.
2. Let `renderMethod` be the chosen `renderMethod` property in `vc` where `renderMethod.type` is `TemplateRenderMethod` and `renderMethod.renderSuite` is `html`.
3. If `renderMethod.template` is a [=string=], then let `template` be the value of `renderMethod.template`.
4. If `renderMethod.template` is a [=map=], then let `template` be the result of fetching the URL in `renderMethod.template.id`.

The [=host page=] MUST filter the [=verifiable credential=] `vc` to only include the properties specified in `renderMethod.renderProperty`, if it is present. If `renderMethod.renderProperty` is not present, the entire [=verifiable credential=] is used.

This filtering MUST be done by applying the `selectJsonLd` algorithm defined in Section 3.4.13 selectJsonLd of the Data Integrity ECDSA Cryptosuites v1.0 specification [[VC-DI-ECDSA]] to the JSON Pointer [[RFC6901]] values present in `renderMethod.renderProperty`.

The [=host page=] MUST create the [=wrapper code=] by embedding the filtered [=verifiable credential=] and the HTML template into the [=wrapper code=] template defined above.

1. Let `wrapperCode` be an HTML Document with `<meta http-equiv="Content-Security-Policy" content="default-src data: 'unsafe-inline'">` in the `<head>`.
2. Let `datablock` be an HTML Data Block with a `type` of `application/vc`.
3. Set the contents of `datablock` to be the filtered [=verifiable credential=] in stringified JSON format.
4. Insert `datablock` into the `<head>` of `wrapperCode`.
5. Insert the value of `template` into the `<body>` of `wrapperCode`.

The [=host page=] MUST set the `srcdoc` attribute of the `iframe` to the resulting [=wrapper code=].

1. Set the `srcdoc` attribute of the `iframe` to the stringified HTML of `wrapperCode`.

The [=host page=] MUST setup a communication channel with the [=wrapper code=] to receive `ready` and `error` messages as described above.

1. Let `renderPromise` be a new `Promise` that:
   1. On `resolve`, can be used to display the `iframe` to the user.
   2. On `reject`, display the error message to the user.
2. In the `onload` event of the `iframe`:
   1. Let `channel` be a new `MessageChannel`.
   2. Create and start a new `port1` listener on `channel` that listens for a `ready` message from the code in `template` now injected into the `iframe` via `wrapperCode`.
   3. In the `port1` listener, if a `ready` message is received, resolve `renderPromise`. If an `error` message is received, reject `renderPromise` with the error message.
   4. Use `postMessage` to send `port2` of `channel` to the `iframe` content window.

The [=host page=] SHOULD use the `renderPromise` to determine when rendering is complete or if there was an error during rendering.

Wrapper Code

The [=wrapper code=] MUST setup to receive communication from the [=host page=] via the `MessageChannel` and provide the `window.renderMethodReady` method for use by the [=template code=].

1. In the `window.onload` event...
   1. Let `port` be the `MessagePort` received from the [=host page=] via the `message` event.
   2. Create `window.renderMethodReady` function that...
      1. If called with no arguments, sends a `ready` message to the [=host page=] via `port`.
      2. If called with an `Error` argument, sends an `error` message to the [=host page=] via `port` with the error message.

Action API

The Host is the application that displays the document with the help of the Template Renderer. The Template Renderer MUST be a web application embedded within an iframe specified by `renderMethod`.`id`. It MUST communicate with the Host application using postMessage API to perform actions.

All actions follow the same structure. They are composed of `type` and `payload`:

1. `type` indicates the kind of action being executed, for instance, `RENDER_DOCUMENT` means rendering a document. The type of an action is mandatory.
2. `payload` indicates optional data associated to the type, for instance, the content of the document to render.

An open source reference implementation is available on GitHub.

The interaction between the Host and the Template Renderer is illustrated in the following diagram.

{ type: "GET_TEMPLATES" }

      {
        type: "SELECT_TEMPLATE",
        payload: "CUSTOM_TEMPLATE"
      }
                  

      {
        type: "RENDER_DOCUMENT",
        payload: {
          document: {
            credentialSubject: ...,
            renderMethod: ...
          }
        }
      }
                  

{ type: "PRINT" }

      {
        type: "OBFUSCATE",
        payload: "a[0].b.c",
      }
                

      {
        type: "UPDATE_HEIGHT",
        payload: 150,
      }
                  

      {
        type: "UPDATE_TEMPLATES",
        payload: [
          {
            id: "template1",
            label: "template1",
          },
          {
            id: "template2",
            label: "template2",
          }
        ]
      }