可验证凭证渲染方法 v1.0

摘要

本规范描述了可验证凭证数据模型的一种扩展机制，该机制可用于通过视觉、听觉或触觉媒介来表示可验证凭证。它涵盖了将可验证凭证渲染到实体文档、数字图像、屏幕阅读器或盲文输出。

当颁发者有特定方式，想要通过视觉、听觉或触觉机制向观察者表达可验证凭证时，可以使用渲染方法。例如，某个员工徽章凭证的颁发者可能希望包含其企业徽标的丰富图像，并将员工信息具体放置在徽章的特定区域。他们还可能希望为有与视力相关的无障碍需求的个人提供该徽章重要方面的音频朗读。

以下术语用于描述本规范中的概念。

声明: 关于某个主体作出的断言。
凭证: 由颁发者作出的一组一个或多个声明。凭证中的声明可以关于不同的主体。
我们对凭证的定义不同于 NIST 对凭证的定义。
数据最小化: 将共享数据量严格限制为成功完成任务或目标所需的最小量的行为。
去中心化标识符: 一种基于 URL 的可移植标识符，也称为 DID，与某个实体相关联。这些标识符最常用于可验证凭证，并与主体相关联，使得可验证凭证本身可以很容易地从一个凭证存储库移植到另一个，而无需重新颁发该凭证。 DID 的一个示例是 did:example:123456abcdef。
去中心化标识符文档: 也称为 DID document，这是一个可使用可验证数据注册表访问的文档，其中包含与特定去中心化标识符相关的信息，例如关联的凭证存储库和公钥信息。
默认图: 包含所有未明确属于命名图的声明的图。
派生谓词: 关于可验证凭证中另一个属性的值的、可验证的布尔断言。这些在零知识证明风格的可验证呈示中很有用，因为它们可以限制信息披露。例如，如果某个可验证凭证包含用于以厘米表示特定身高的属性，则派生谓词可能会引用可验证凭证中的身高属性，表明颁发者证明身高值满足最低身高要求，而无需实际披露具体身高值。例如，主体高于 150 厘米。
数字签名: 一种用于证明数字消息真实性的数学方案。
实体: 任何可以在陈述中作为抽象名词或具体名词被引用的事物。实体包括但不限于人、组织、物理事物、文档、抽象概念、虚构角色以及任意文本。任何实体都可能在生态系统中执行角色，只要它有能力这样做。请注意，有些实体从根本上无法采取行动，例如字符串 "abc" 无法颁发凭证。
图: 一组声明，形成一个由主体及其与其他主体或数据之间关系组成的信息网络。每个声明都是某个图的一部分；对于命名图，这是显式的，或者对于默认图则是隐式的。
持有者: 实体可以通过拥有一个或多个可验证凭证并从中生成可验证呈示而执行的一种角色。持有者通常但不总是其所持有的可验证凭证的主体。持有者将其凭证存储在凭证存储库中。
身份: 用于跨上下文跟踪实体的手段。数字身份能够跨数字上下文跟踪和定制实体交互，通常使用标识符和属性。身份信息的意外分发或使用可能损害隐私。此类信息的收集和使用应遵循数据最小化原则。
身份提供者: 身份提供者有时缩写为 IdP，是一种为持有者创建、维护和管理身份信息的系统，同时向联盟或分布式网络中的依赖方应用提供认证服务。在这种情况下，持有者始终是主体。即使可验证凭证是不记名凭证，也假定这些可验证凭证仍由主体持有，如果并非如此，则它们已被攻击者窃取。本规范不使用该术语，除非将本文档中的概念与其他规范进行比较或映射。本规范将身份提供者概念解耦为两个不同的概念：颁发者和持有者。
颁发者: 实体可以通过对一个或多个主体作出声明，由这些声明创建可验证凭证，并将该可验证凭证传输给持有者而执行的一种角色。
命名图: 与特定属性（例如 verifiableCredential）相关联的图。这些属性会产生独立的图，其中包含相应 JSON 对象中定义的所有声明。
呈示: 从一个或多个可验证凭证派生的数据，这些凭证由一个或多个颁发者颁发，并与特定的验证者共享。
凭证存储库: 一种程序，例如存储保险库或个人可验证凭证钱包，用于存储并保护对持有者的可验证凭证的访问。
选择性披露: 持有者能够就共享哪些信息作出细粒度决策的能力。
主体: 被声明所涉及的事物。
用户代理: 一种程序，例如浏览器或其他 Web 客户端，它在持有者、颁发者和验证者之间调解通信。
验证: 对来自特定颁发者的声明，能够满足验证者针对特定用途的业务要求的保证。本规范定义了验证者如何核验可验证凭证和可验证呈示。
它还规定验证者在依赖可验证凭证中的声明之前，先对这些声明进行确认。然而，这种确认的手段差异很大，并且超出本规范的范围。预期验证者会针对某些声明信任某些颁发者，并应用他们自己的规则来确定哪些凭证中的哪些声明适合由他们的系统使用。
可验证凭证: 可验证凭证是一种防篡改凭证，其作者身份可以通过密码学方式验证。可验证凭证可用于构建可验证呈示，而后者也可以通过密码学方式验证。
可验证数据注册表: 系统可以通过调解标识符、密钥及其他相关数据（例如可验证凭证模式、撤销注册表、颁发者公钥等）的创建和核验而执行的一种角色，这些数据可能是使用可验证凭证所必需的。一些配置可能需要面向主体的可关联标识符。一些注册表，例如 UUID 和公钥注册表，可能只是充当标识符的命名空间。
可验证呈示: 可验证呈示是一种防篡改的呈示，其编码方式使数据的作者身份可在密码学核验过程之后被信任。某些类型的可验证呈示可能包含从原始可验证凭证合成而来、但不包含原始可验证凭证的数据（例如，零知识证明）。
核验: 对可验证凭证或可验证呈示是否分别为颁发者或呈示者的真实且当前的陈述进行评估。这包括检查：凭证（或呈示）是否符合规范；证明方法是否满足；以及如果存在，状态检查是否成功。对凭证进行核验并不意味着对凭证中编码的声明的真实性进行评估。
验证者: 实体通过接收一个或多个可验证凭证，并可选地将其置于可验证呈示中进行处理而执行的一种角色。其他规范可能将此概念称为依赖方。
核验材料: 可作为密码学公钥或任何其他用于核验证明的数据的信息。
URL: 统一资源定位符，如 [URL] 所定义。URL 可以被解引用，从而产生某个资源，例如文档。解引用或获取 URL 的规则由 URL scheme定义。本规范不使用术语 URI 或 IRI，因为这些术语被认为会使 Web 开发者感到困惑。

除标记为非规范性的章节外，本规范中的所有编写指南、图示、示例和注释均为非规范性内容。本规范中的其他所有内容均为规范性内容。

本文档中的关键词 MAY、MUST、MUST NOT、OPTIONAL、RECOMMENDED、REQUIRED 和 SHOULD 应按 BCP 14 [RFC2119] [RFC8174] 中所述进行解释，且仅当它们像此处所示以全大写形式出现时才如此解释。

一致的渲染方法是数据模型的任何具体表达，只要它符合本规范中的规范性陈述。具体而言，本文档第 2. 数据模型和第 2.2.4.2 算法节中的所有相关规范性陈述MUST得到执行。

一致的处理器是任何以软件和/或硬件实现、用于生成或消费一致的渲染方法的算法。一致的处理器MUST在消费不一致文档时产生错误。

本文档还包含一些含有 JSON 和 JSON-LD 内容的示例。其中一些示例包含无效 JSON 字符，例如内联注释（//）以及使用省略号（...）表示对示例价值不大的信息。提醒实现者，如果希望将这些信息用作有效 JSON 或 JSON-LD，应移除这些内容。

以下各节概述了本规范用于渲染方法的数据模型

renderMethod 属性是可验证凭证数据模型规范 [VC-DATA-MODEL-2.0] 中的一个保留扩展点。颁发者可以在可验证凭证中使用此属性，以表达一个或多个首选渲染方法。

renderMethod: renderMethod 属性的值MUST指定一个或多个渲染方法，软件可以使用这些方法通过视觉、听觉或触觉机制来表达可验证凭证。每个 renderMethod 值MUST指定其 type，例如 TemplateRenderMethod。每个渲染提示的精确内容由具体的 renderMethod type 定义决定。

当颁发者希望为可验证凭证指定基于模板的渲染指令时，他们MAY添加一个使用以下所述数据模型的 renderMethod 属性。

属性描述

id 一个OPTIONAL的字符串，它遵循 URL 标准，并且在获取时，会解引用到一个渲染模板。

type 一个REQUIRED的字符串，其值MUST为 TemplateRenderMethod。

renderSuite 一个REQUIRED的字符串，用于标识生成具体渲染所使用的算法。

name 一个OPTIONAL的、人类可读的字符串，可显示出来以提供将要执行的渲染类型提示。此属性可用于允许个人在多个呈示模式之间进行选择的图形界面中。

description 一个OPTIONAL的、人类可读的字符串，相比 name，它提供了关于特定渲染何时可能有用的更详细描述。

renderProperty 一个OPTIONAL的列表，其中包含字符串值；每个值均符合 JavaScript 对象表示法（JSON） Pointer语法，用于指定在使用此特定渲染方法时，从可验证凭证中暴露哪些属性。如果未提供 renderProperty，则在使用渲染方法时，假定会共享整个可验证凭证。

template

一个OPTIONAL的URL或映射，它提供或引用将用于执行渲染的模板。如果该值是URL，则它MAY是包含模板代码的 data: URL [RFC2397]。如果该值是映射，则它MUST符合以下规则：

属性	描述
id	一个REQUIRED的字符串，它遵循 URL 标准，并且在获取时，会解引用到诸如 SVG 或 PDF 文件之类的模板。
mediaType	一个RECOMMENDED的字符串，用于标识 `id` 值的媒体类型，如媒体类型规范和注册过程中所规定。
digestMultibase	模板文件的一个OPTIONAL的、采用 multibase 编码的 Multihash。 multibase 值MUST为 `u`（base64url-nopad），并且 multihash 值MUST为具有 256 位输出的 SHA-2（`0x12`）。

digestMultibase 如果指定了 id，则这是所引用渲染方法的一个 OPTIONAL的、采用 multibase 编码的 Multihash。 multibase 值MUST为 u （base64url-nopad），并且 multihash 值MUST为具有 256 位输出的 SHA-2（0x12）。

上面展示的数据模型在下面示例中的可验证凭证中表达。

示例 1：颁发者使用 render 属性

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2",
    "https://w3id.org/vc/render-method/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "validFrom": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science and Arts"
    }
  },
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "svg-mustache",
    "template": {
      "id": "https://example.edu/credential-templates/BachelorDegree",
      "mediaType": "image/svg+xml",
      "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR",
      "renderProperty": [
        "/issuer", "/validFrom", "/credentialSubject/degree/name"
      ]
    }
  }
  
}

在上面的示例中，颁发者为学士学位提供了一个基于 Mustache 的 SVG 渲染模板，该模板将使用 renderProperty 中列出的可验证凭证中的具体信息进行填充。

svg-mustache 渲染套件使用 Mustache 模板语言修改 SVG 文件，然后使用该文件来渲染可验证凭证的视觉表示。

在下面的示例中，一个完全嵌入的 SVG 文件被用作渲染模板。

示例 2：svg-mustache 渲染套件的基本用法

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "svg-mustache",
    // SVG 文件嵌入在 VC 中
    "template": "data:image/svg+xml;base64,Qjei89...3jZpW"
  }
}

下一个示例链接到 Web 上的 SVG 文件，并通过使用 digestMultibase 属性保护它免遭修改。

示例 3：用于 SVG 渲染模板的远程托管 SVG 文件

{
...
"renderMethod": {
  "type": "TemplateRenderMethod",
  "renderSuite": "svg-mustache",
  "template": {
    // 此 SVG 文件从 Web 获取
    "id": "https://degree.example/credential-templates/bachelors",
    "mediaType": "image/svg+xml",
    "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR"
  }
}

下一个示例链接到 Web 上的渲染模板，并使用 digestMultibase 属性保护它：

示例 4：远程托管的 SVG 渲染方法

{
...
"renderMethod": {
  // 此渲染方法从 Web 获取
  "id": "https://degrees.example/bachelors-svg.jsonld",
  "mediaType": "application/ld+json",
  "type": "TemplateRenderMethod",
  "renderSuite": "svg-mustache",
  "digestMultibase": "zQmG270iEu5h6JqWAPdhyxz2dRerWC85Wg6wFl9znFCwYxAp"
}

pdf-mustache 渲染套件使用 Mustache 模板语言修改 PDF 文件，然后使用该文件来渲染可验证凭证的视觉表示。

在下面的示例中，一个完全嵌入的 PDF 文件被用作渲染模板。

示例 5：pdf-mustache 渲染套件的基本用法

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "pdf-mustache",
    // 此 PDF 文件嵌入在 VC 中
    "template": "data:application/pdf;base64,k309SK...pwK83b"
  }
}

下一个示例链接到 Web 上的 PDF 文件，并通过使用 digestMultibase 属性保护它免遭修改。

示例 6：用于 PDF 渲染模板的远程托管 PDF 文件

{
...
"renderMethod": {
  "type": "TemplateRenderMethod",
  "renderSuite": "pdf-mustache",
  "template": {
    // 此 PDF 文件从 Web 获取
    "id": "https://degree.example/bachelors.pdf",
    "mediaType": "application/pdf",
    "digestMultibase": "zQmznFCwYxApG270iEu5h6JqWAPdhyxz2dRerWC85Wg6wFl9"
  }
}

下一个示例链接到 Web 上的渲染模板，并使用 digestMultibase 属性保护它：

示例 7：远程托管的 PDF 渲染模板

{
...
"renderMethod": {
  // 此渲染方法从 Web 获取
  "id": "https://degrees.example/bachelors-pdf.jsonld",
  "type": "TemplateRenderMethod",
  "renderSuite": "pdf-mustache",
  "digestMultibase": "zQmEu5h6JqWAPdhyxmz2dRerWC85Wg6wFl9znFCwYxApG270"
}

nfc 渲染套件通过无线 NFC 连接传输表示可验证凭证的二进制载荷。

在下面的示例中，一个完全嵌入的 NFC 载荷被用作渲染模板，它只披露与该凭证相关联的条形码标识符。

示例 8：nfc 渲染套件的用法

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "nfc",
    "name": "Tap to send",
    // NFC 载荷被嵌入
    "template": "data:application/octet-stream;base64,2QZkpQGDG...G8XJWnROcY4Biw",
    // 仅通过 NFC 传输条形码
    "renderProperty": ["/credentialSubject/barcode"]
  }
  ...
}

html 渲染套件允许模板作者提供 HTML 模板来渲染可验证凭证。HTML 可以作为 template 或 template.id（当 template 的值是对象时）的值，通过远程方式引用，或通过 data: URL 引用。HTML 片段中的 JavaScript 负责渲染通过 HTML 数据块（即 <script type="application/vc"></script>）提供的经过筛选的可验证凭证数据，该数据块与 HTML 模板一起托管在沙盒化 iframe 中。

示例 9：使用 HTML 渲染套件的示例 VC

{
  "@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"
      }
    }
  }
}

实现MUST提供一种环境，使 JavaScript 能够使用经过筛选的可验证凭证数据安全地渲染 HTML 模板。以下术语用于描述此环境：

宿主页面: 为渲染 HTML 模板提供安全环境。
模板代码: 在渲染方法中提供或由其远程引用的 HTML 片段。
包装器代码: 包装 HTML 模板的代码，用于提供额外的安全限制，并与宿主页面通信。

至少，该环境MUST阻止导航、外部内容加载以及对宿主页面的访问，以防止跟踪和其他隐私损害。

例如，基于浏览器的实现可以使用以下组合来提供此类环境：对宿主页面施加内容安全策略 [CSP3] 限制、对托管 HTML 模板的 iframe 进行沙盒化，以及包装器代码；该包装器代码包装 HTML 模板以添加额外的 CSP 限制，并提供与宿主页面的 ready 和 error 事件通信。

宿主页面（通常是钱包或可验证凭证渲染器）MUST 阻止 HTML 模板导航顶级浏览上下文、访问外部内容、访问宿主页面以及加载任何远程内容。

如果使用宿主页面，则适用以下规则：

内容安全策略（CSP）限制MUST包括 frame-src 'none'。这会强制 iframe 使用 srcdoc 而不是 src，从而阻止浏览器加载 HTML 模板。进而，这会迫使宿主页面代码预加载远程引用的模板代码，并在将模板注入包装器代码之前，根据相关的 digestMultibase 值检查响应。
在托管 HTML 模板的 iframe 上MUST设置 sandbox="allow-scripts"，以防止导航和顶级访问。

示例 10：最小宿主页面

<html>
  <head>
    <meta http-equiv="content-security-policy" content="frame-src 'none'">
  </head>
  <body>
    <iframe id="renderer" sandbox="allow-scripts allow-modals" srcdoc=""></iframe>
  </body>
</html>

由 renderMethod 中的 template 属性引用的 HTML 模板代码MUST是一个 HTML 片段，其中包含渲染可验证凭证所必需的 HTML、CSS 和 JavaScript。该模板代码MUST NOT 包含任何 <html>、<head> 或 <body> 标签，因为这些将由包装器代码提供。

示例 11：示例 HTML 模板片段

<div>
  <script>
    document.addEventListener('DOMContentLoaded', (event) => {
      console.log('running template render script');

      // 将凭证显示为 JSON，作为示例渲染器；这里也可以
      // 改为执行任何其他操作，包括 mustache/其他风格的
      // 模板处理，以生成用于显示的 HTML

      // FIXME: 确定数据块/script 标签的最佳名称/位置
      const credential = JSON.parse(document.querySelector(
        'head > script[name="credential"]').innerHTML);

      document.querySelector('#credentialSubject-name').innerText =
        credential.credentialSubject.name;
      document.querySelector('#issuer-name').innerText =
        credential.issuer.name;

      // TBD: 向宿主发出渲染完成信号
      window.renderMethodReady();
    });
  </script>
  <style>
    h1 {
      color: blue;
    }
  </style>

  <h1 id="credentialSubject-name"></h1>
  <p>颁发者：<span id="issuer-name"></span></p>
</div>

模板 HTML 片段MUST被包装在包装器代码中，该包装器代码提供包含部分可验证凭证的数据块，并添加额外的 CSP 策略，以阻止导航和外部内容加载。具体而言，包装器代码MUST添加以下 CSP 限制：default-src data: 'unsafe-inline'，以阻止模板代码发出任何网络请求。

示例 12：用于在 iframe[srcdoc] 中包装模板和凭证的包装器代码

<html>
  <head>
    <meta http-equiv="content-security-policy" content="default-src data: 'unsafe-inline'">
    <script name="credential" type="application/vc">${JSON.stringify(credential)}</script>
  </head>
  <body>${template}</body>
</html>

为完成设置，宿主页面MUST将包装器代码（在填入可验证凭证和模板代码后）注入 iframe 的 srcdoc 属性中，这将运行包装器代码和模板代码中包含的任何 JavaScript。

示例 13：包含模板和凭证的组合包装器代码

<html>
  <head>
    <meta http-equiv="content-security-policy" content="default-src 'none' data: 'unsafe-inline'">

<!-- 注入到包装器代码中的凭证数据块。 -->
<script name="credential" type="application/vc">{
  "@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"
  }
}</script>
<!-- 凭证数据块结束 -->

</head>
<body>

<!-- 注入到包装器代码中的模板 HTML。 -->
<div>
  <script>
    console.log('running template render script');

    // 将凭证显示为 JSON，作为示例渲染器；这里也可以
    // 改为执行任何其他操作，包括 mustache/其他风格的
    // 模板处理，以生成用于显示的 HTML

    // FIXME: 确定数据块/script 标签的最佳名称/位置
    const credential = JSON.parse(document.querySelector(
      'head > script[name="credential"]').innerHTML);

    document.querySelector('#credentialSubject-name').innerText =
      credential.credentialSubject.name;
    document.querySelector('#issuer-name').innerText =
      credential.issuer.name;

    // TBD: 向宿主发出渲染完成信号
    window.renderMethodReady()
  </script>
  <style>
    h1 {
      color: blue;
    }
  </style>

  <h1 id="credentialSubject-name"></h1>
  <p>颁发者：<span id="issuer-name"></span></p>
</div>
<!-- 模板 HTML 结束 -->

  </body>
</html>

在包装器代码中创建的 iframe MUST提供一个通信通道，以允许模板在渲染完成时，或在渲染期间发生错误时通知宿主页面。这可以使用 postMessage API 以及由包装器代码设置的 MessageChannel 来实现。

下面显示的 JavaScript 会添加到上述宿主页面中，为 iframe 添加 onload 事件以设置 MessageChannel。该宿主页面还会创建一个 Promise，当从包装器代码收到 ready 消息时解析，或在收到 error 消息时拒绝。包装器代码还提供一个 window.renderMethodReady 方法，供模板用来通知宿主页面渲染完成或返回错误消息。

示例 14：为设置 MessageChannel 而添加到宿主页面的内容

// 一个 promise，在渲染准备就绪时解析（或在失败时拒绝）；
// 可用于显示内容或错误
let resolveRender;
let rejectRender;
const readyPromise = new Promise((resolve, reject) => {
  resolveRender = resolve;
  rejectRender = reject;
});

// 设置通信通道，供 iframe 中的模板代码使用
renderer.onload = () => {
  // 创建 MessageChannel；将一个端口传递给 iframe
  const channel = new MessageChannel();
  // 启动消息队列，以便 iframe 加载时消息不会丢失
  channel.port1.start();
  // 处理 `ready` 消息
  channel.port1.onmessage = function ready(event) {
    if(event.data === 'ready') {
      // 取消隐藏 iframe，因为它已准备就绪
      resolveRender();
    } else {
      rejectRender(new Error(event.data?.error?.message));
    }
    channel.port1.onmessage = undefined;
  };
  // 发送 "start" 消息；将 `port2` 发送给 iframe 用于返回通信
  renderer.contentWindow.postMessage('start', '*', [channel.port2]);
};

// 设置对 ready 或 error 的事件响应
// NOTE: 本节取决于钱包/渲染器的 UX 需求
readyPromise.then(() => {
  console.log('rendering ready');
  const renderer = document.getElementById('renderer');
  renderer.hidden = false;
}).catch(err => {
  const errorMessage = document.getElementById('error-message');
  errorMessage.style.display = 'block';
  errorMessage.innerText = 'Rendering failed: ' + err.message;
  console.error('rendering failed', err);
});

示例 15：用于连接 MessageChannel 并创建 `renderMethodReady` 的包装器代码补充

// 添加 promise，它将解析为来自
// 父窗口的通信端口
const portPromise = new Promise(resolve => {
  window.addEventListener('message', function start(event) {
    if(event.data === 'start' && event.ports?.[0]) {
      window.removeEventListener('message', start);
      resolve(event.ports[0]);
    }
  });
});

// 将一个函数附加到 window，供模板在
// “准备就绪”（或发生错误）时调用，该函数会向
// 父级发送消息，以便父级决定是否显示 iframe
window.renderMethodReady = function(err) {
  portPromise.then(port => port.postMessage(
    !err ? 'ready' : {error: {message: err.message}}));
};

通过此设置，模板 JavaScript 可以调用 window.renderMethodReady() 来通知宿主页面渲染完成，或者调用 window.renderMethodReady(new Error("error message")) 来通知宿主页面发生错误。

以下各节概述了 html 渲染套件用于安全渲染 HTML 模板的算法。只要安全和隐私结果以及输出相同， MAY使用替代算法。

宿主页面MUST创建一个 iframe 元素来托管 HTML 模板。该宿主页面MUST将 iframe 上的 sandbox 属性设置为 allow-scripts，以防止导航和顶级访问。

令 vc 为要渲染的可验证凭证。
令 renderMethod 为 vc 中选定的 renderMethod 属性，其中 renderMethod.type 是 TemplateRenderMethod，且 renderMethod.renderSuite 是 html。
如果 renderMethod.template 是字符串，则令 template 为 renderMethod.template 的值。
如果 renderMethod.template 是映射，则令 template 为获取 renderMethod.template.id 中 URL 的结果。

如果存在 renderMethod.renderProperty，则宿主页面MUST筛选可验证凭证 vc，使其仅包含 renderMethod.renderProperty 中指定的属性。如果不存在 renderMethod.renderProperty，则使用整个可验证凭证。

此筛选MUST通过应用 Data Integrity ECDSA Cryptosuites v1.0 规范 [VC-DI-ECDSA] 第 3.4.13 节 selectJsonLd 中定义的 selectJsonLd 算法来完成，该算法应用于 renderMethod.renderProperty 中存在的 JSON Pointer [RFC6901] 值。

宿主页面MUST通过将经过筛选的可验证凭证和 HTML 模板嵌入到上面定义的包装器代码模板中，来创建包装器代码。

令 wrapperCode 为一个 HTML Document，其中在 <head> 中包含 <meta http-equiv="Content-Security-Policy" content="default-src data: 'unsafe-inline'">。
令 datablock 为一个 type 为 application/vc 的 HTML 数据块。
将 datablock 的内容设置为字符串化 JSON 格式的经过筛选的可验证凭证。
将 datablock 插入 wrapperCode 的 <head> 中。
将 template 的值插入 wrapperCode 的 <body> 中。

宿主页面MUST将 iframe 的 srcdoc 属性设置为生成的包装器代码。

将 iframe 的 srcdoc 属性设置为 wrapperCode 的字符串化 HTML。

宿主页面MUST与包装器代码建立通信通道，以接收如上所述的 ready 和 error 消息。

令 renderPromise 为一个新的 Promise，它：
1. 在 resolve 时，可用于向用户显示 iframe。
2. 在 reject 时，向用户显示错误消息。
在 iframe 的 onload 事件中：
1. 令 channel 为新的 MessageChannel。
2. 在 channel 上创建并启动新的 port1 监听器，该监听器监听来自现在已通过 wrapperCode 注入到 iframe 中的 template 代码的 ready 消息。
3. 在 port1 监听器中，如果收到 ready 消息，则解析 renderPromise。如果收到 error 消息，则使用错误消息拒绝 renderPromise。
4. 使用 postMessage 将 channel 的 port2 发送到 iframe 内容窗口。

宿主页面SHOULD使用 renderPromise 来确定渲染何时完成，或渲染期间是否发生错误。

包装器代码MUST设置为通过 MessageChannel 接收来自宿主页面的通信，并提供 window.renderMethodReady 方法，供模板代码使用。

在 window.onload 事件中……
1. 令 port 为通过 message 事件从宿主页面接收的 MessagePort。
2. 创建 window.renderMethodReady 函数，该函数……
  1. 如果在没有参数的情况下调用，则通过 port 向宿主页面发送 ready 消息。
  2. 如果使用 Error 参数调用，则通过 port 向宿主页面发送带有错误消息的 error 消息。

EmbeddedRenderer 由颁发者用于渲染可验证凭证。可验证凭证通过文档中引用的 Template Renderer 网站，在嵌入的 <iframe> 内以 HTML 形式渲染。这种安排允许使用 OpenAttestationMerkleProofSignature2018 进行交互式选择性披露。

Template Renderer 是嵌入在 iframe 中的 Web 应用程序。它基于选定的模板渲染可验证凭证，并且必须监听来自 Host 应用程序的特定消息，以便促进渲染过程。

目前存在许多 EmbeddedRenderer 颁发者和 embedded renderer 实现。

当颁发者希望为可验证凭证指定嵌入式渲染指令时，他们MAY添加一个使用以下所述数据模型的 renderMethod 属性。

属性	描述
id	一个 URL，用于定位实现 EmbeddedRenderer Action API 的网站。
type	`type` 属性MUST为 `EmbeddedRenderer`。
renderName	由 `id` 指定的网站用于渲染文档的模板名称。可以为 embedded renderer 使用不同模板，以呈现可验证凭证的不同 HTML 视图。

上面展示的数据模型在下面示例中的可验证凭证中表达。

示例 16：颁发者使用 renderMethod 属性

  {
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://w3id.org/security/data-integrity/v2",
      "https://trustvc.io/context/render-method-context-v2.json",
    ],
    "credentialSubject": {
     ...
    },
    "type": ["VerifiableCredential"],
    "issuer": "did:web:trustvc.github.io:did:1",
    "validFrom": "2024-04-01T12:19:52Z",
    "id": "urn:uuid:01992e54-cc5e-700e-a80b-60ddf0fffca9",
  },
  "renderMethod": [
      {
        "type": "EMBEDDED_RENDERER",
        "templateName": "DEMO_CERTIFICATE",
        "id": "https://generic-templates.tradetrust.io"
      }
  ]
}

该可验证凭证指定了位于 https://generic-templates.tradetrust.io 的嵌入式渲染器，并使用名为 DEMO_CERTIFICATE 的模板。

embedded renderer 可以支持不同模板，以提供可验证凭证的不同视图。下面是同一可验证凭证使用不同模板的两种渲染效果。

Host 是借助 Template Renderer 显示文档的应用程序。Template Renderer MUST是嵌入在由 renderMethod.id 指定的 iframe 中的 Web 应用程序。它MUST使用 postMessage API 与 Host 应用程序通信以执行操作。

所有操作都遵循相同结构。它们由 type 和 payload 组成：

type 表示正在执行的操作类型，例如 RENDER_DOCUMENT 表示渲染文档。操作的 type 是必需的。
payload 表示与该 type 相关联的可选数据，例如要渲染的文档内容。

一个开源参考实现可在 GitHub 上获得。

Host 与 Template Renderer 之间的交互如下图所示。

当 iframe 首次显示时，host 会向 iframe 发送命令以渲染文档。支持的 4 种操作类型如下所述。

type	payload	操作
`GET_TEMPLATES`	`{ type: "GET_TEMPLATES" }`	获取 renderer 针对给定文档支持的模板列表。模板列表由 iframe 中的 UPDATE_TEMPLATES 调用返回。
`SELECT_TEMPLATE`	`{ type: "SELECT_TEMPLATE", payload: "CUSTOM_TEMPLATE" }`	选择用于渲染的模板。它应来自 GET_TEMPLATES 返回的列表。如果未找到，则使用默认模板。
`RENDER_DOCUMENT`	`{ type: "RENDER_DOCUMENT", payload: { document: { credentialSubject: ..., renderMethod: ... } } }`	使用所选模板在 IFRAME 内渲染可验证凭证。 Document 是可验证凭证的 JSON 对象形式。
`PRINT`	`{ type: "PRINT" }`	MUST显示打印对话框，以便可以打印 IFRAME 的内容。

iframe 使用这些操作来更新 host，以便进行格式调整或选择性遮盖。

type	payload	操作
`OBFUSCATE`	`{ type: "OBFUSCATE", payload: "a[0].b.c", }`	这用于选择性遮盖。Host 会获知已被混淆字段的路径，以便 host 可以创建一个更新后的文档版本，其中所选字段已被混淆。
`UPDATE_HEIGHT`	`{ type: "UPDATE_HEIGHT", payload: 150, }`	以像素为单位通知 Host 嵌入式 iframe 的高度，以便 Host 可以在浏览器中调整大小。
`UPDATE_TEMPLATES`	`{ type: "UPDATE_TEMPLATES", payload: [ { id: "template1", label: "template1", }, { id: "template2", label: "template2", } ] }`	通知 Host 可从 RENDER_METHOD 或 GET_TEMPLATES 调用中使用的模板名称列表。

可验证凭证渲染方法 v1.0

摘要

本文档的状态

1. 引言

1.1 术语

1.2 一致性

2. 数据模型

2.1 `renderMethod` 属性

2.2 TemplateRenderMethod

2.2.1 `svg-mustache` 渲染套件

2.2.2 `pdf-mustache` 渲染套件

2.2.3 `nfc` 渲染套件

2.2.4 `html` 渲染套件

2.2.4.1 宿主页面

2.2.4.1.1 模板代码

2.2.4.1.2 包装器代码

2.2.4.1.3 Ready 和 Error 事件

2.2.4.2 算法

2.2.4.2.1 宿主页面

2.2.4.2.2 包装器代码

2.3 EmbeddedRenderer

2.3.1 Action API

2.3.1.1 Host 到 Frame 的操作

2.3.1.2 Frame 到 Host 的操作

3. 算法

3.1 渲染 (TemplateRenderMethod)

A. 安全注意事项

B. 隐私注意事项

C. 国际化注意事项

D. 参考文献

D.1 规范性引用

可验证凭证渲染方法 v1.0

摘要

本文档的状态

1. 引言

1.1 术语

1.2 一致性

2. 数据模型

2.1 renderMethod 属性

2.2 TemplateRenderMethod

2.2.1 svg-mustache 渲染套件

2.2.2 pdf-mustache 渲染套件

2.2.3 nfc 渲染 套件

2.2.4 html 渲染 套件

2.2.4.1 宿主页面

2.2.4.1.1 模板代码

2.2.4.1.2 包装器代码

2.2.4.1.3 Ready 和 Error 事件

2.2.4.2 算法

2.2.4.2.1 宿主页面

2.2.4.2.2 包装器代码

2.3 EmbeddedRenderer

2.3.1 Action API

2.3.1.1 Host 到 Frame 的操作

2.3.1.2 Frame 到 Host 的操作

3. 算法

3.1 渲染 (TemplateRenderMethod)

A. 安全注意事项

B. 隐私注意事项

C. 国际化 注意事项

D. 参考文献

D.1 规范性引用

2.1 `renderMethod` 属性

2.2.1 `svg-mustache` 渲染套件

2.2.2 `pdf-mustache` 渲染套件

2.2.3 `nfc` 渲染套件

2.2.4 `html` 渲染套件

C. 国际化注意事项