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

summary 渲染套件按以下方式使用通用渲染方法属性：

摘要对象是一个 JSON 对象 [RFC8259]， 其成员定义如下。 同一定义既适用于模板，也适用于渲染输出。在 模板中，任何定义为字符串的成员，其值可以改为 一个 JSON 指针字符串（以 / 开头，如JavaScript 对象表示法（JSON） 指针中所规定），用于 引用可验证 凭证中的值，但字段对象的 label 和 value 成员另有说明。在渲染输出中， 每个 JSON 指针都已被其解析值替换。

name

一个必需的字符串，包含凭证 摘要的显示名称。

description

一个必需的字符串，包含凭证 摘要的描述文本。

icon

一个可选的字符串，包含用于在摘要中显示的图标或图像的URL 或 data: URL [RFC2397]。

theme

一个可选的颜色主题对象，包含以下成员：

primaryColor

一个可选的字符串，包含用于 背景和 突出显示的主颜色。

accentColor

一个可选的字符串，包含用于 突出显示和强调的强调色。

fields

一个必需的自定义数据字段数组，按显示顺序排列。每个 字段都是一个 包含以下成员的对象：

label

一个必需的字符串，包含字段标签。在 模板中，标签必须 是字面字符串；此处不允许使用 JSON 指针。

value

一个必需的字符串，包含字段值。在 模板中，该值必须 是 JSON 指针字符串（例如 "/issuer"）。

language

一个可选的语言标签（如用于标识 语言的标签中所规定），用于指示 字段标签和/或值的语言。

direction

一个可选的方向标签（如Web 上的字符串：语言和 方向元数据中所规定），用于指示 字段标签和/或值的文本方向。

validFrom

一个可选的 ISO 8601 日期字符串，用于指示凭证何时 开始 有效。

validUntil

一个可选的 ISO 8601 日期字符串，用于指示凭证何时 不再 有效。

在处理前，模板应该根据上述摘要对象定义 进行 验证。摘要模板的非规范性 JSON Schema 见C. 摘要模板 JSON Schema。

以下示例展示一个包含 JSON 指针 字符串的有效摘要模板：

{
  "name": "/credentialSubject/degree/name",
  "description": "大学学位凭证",
  "icon": "/credentialSubject/icon",
  "theme": {
    "primaryColor": "#1a5490",
    "accentColor": "/credentialSubject/theme/accentColor"
  },
  "fields": [
    {
      "label": "院校",
      "value": "/issuer"
    },
    {
      "label": "学位类型",
      "value": "/credentialSubject/degree/type"
    },
    {
      "label": "颁发日期",
      "value": "/validFrom"
    }
  ],
  "validFrom": "/validFrom",
  "validUntil": "/validUntil"
}

以下示例展示一个有效的摘要输出：

{
  "name": "理学与文学学士",
  "description": "大学学位凭证",
  "icon": "https://example.edu/icons/degree.svg",
  "theme": {
    "primaryColor": "#1a5490",
    "accentColor": "#4a90e2"
  },
  "fields": [
    {
      "label": "院校",
      "value": "示例大学"
    },
    {
      "label": "学位类型",
      "value": "BachelorDegree"
    },
    {
      "label": "毕业日期",
      "value": "2010-05-15"
    }
  ],
  "validFrom": "2010-01-01T19:23:24Z",
  "validUntil": null
}

在以下示例中，JSON 模板作为 data: URL [RFC2397] 直接嵌入 可验证 凭证中。

{
  ...
  "renderMethod": {
    "type": "SuiteRenderMethod",
    "renderSuite": "summary",
    // JSON 模板嵌入在 VC 中
    "template": "data:application/json;base64,eyJuYW1lIjogIi9jcmVkZW50aWFsU3ViamVjdC9kZWdyZWUvbmFtZSIsICJkZXNjcmlwdGlvbiI6ICJVbml2ZXJzaXR5IERlZ3JlZSBDcmVkZW50aWFsIiwgImZpZWxkcyI6IFt7ImxhYmVsIjogIkluc3RpdHV0aW9uIiwgInZhbHVlIjogIi9pc3N1ZXIifV19"
  }
}

下一个示例链接到 Web 上的 JSON 模板，并通过 digestMultibase 属性防止其被修改。

{
...
"renderMethod": {
  "type": "SuiteRenderMethod",
  "renderSuite": "summary",
  "template": {
    // 此 JSON 模板从 Web 获取
    "id": "https://degree.example/credential-templates/bachelors.json",
    "mediaType": "application/json",
    "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR"
  }
}

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

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

html 渲染套件按以下方式使用通用渲染方法属性：

实现必须提供一个允许 JavaScript 使用经过筛选的可验证 凭证数据安全地 渲染 HTML 模板的环境。 此外，宿主页面应该通过使用 Oblivious HTTP [RFC9458] 或其他通过使用保护性中继将请求客户端与被请求源解除关联的方法， 保护任何请求（例如解引用 template.id）的 隐私。

以下术语用于描述此环境：

宿主 页面

提供用于渲染 HTML 模板的安全环境。

模板 代码

在渲染方法中提供或由其远程引用的 HTML 片段。

包装 代码

包装 HTML 模板以提供附加安全 限制并与宿主页面通信的代码。

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

该环境还必须向模板代码公开用户环境中可用的所有 国际化和无障碍设置。这使模板能够遵循个人已经向 其用户代理或操作系统表达的语言、文本大小、 对比度和动画偏好。此类设置的示例包括 CSS 中反映的设置，例如 rem 单位以及 prefers-contrast、prefers-reduced-motion 和 forced-colors 等媒体查询，还包括 JavaScript 可用的设置，例如由 Intl 和 Navigator.language 提供的区域设置信息。

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

沙盒化的 iframe 默认满足上述国际化和无障碍 要求。本节所述的沙盒和 CSP 限制 不会干扰 CSS 媒体查询，也不会干扰 Intl 和 Navigator.language 等 JavaScript API。html 渲染套件也可以使用其他渲染环境， 例如移动平台上的 WebView。

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

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

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

<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>

<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>
  <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>

<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": "颁发者"
  },
  "credentialSubject": {
    "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>

// 一个在渲染就绪时兑现（或在渲染失败时
// 拒绝）的 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]);
};

// 设置对就绪或错误事件的响应
// 注：本节特定于钱包/渲染器的 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 = '渲染失败：' + err.message;
  console.error('rendering failed', err);
});

// 添加一个将兑现为来自
// 父窗口的通信端口的 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}}));
};

渲染环境偏好可以在渲染 方法中提供。该 对象的目的是在渲染所提供模板时，提供关于使用方式、显示方式和预期 访问模式的建议。实现应该 在提供这些偏好时遵循它们。

outputPreference 对象可以包含以下任意 属性：

style 对象可以包含以下任意 属性：

static 渲染套件按如下方式使用通用渲染方法属性：