検証可能なクレデンシャルのレンダリング方法 v1.0

summary レンダースイートは、共通のレンダリングメソッドプロパティを次のように使用する。

サマリーオブジェクトは、以下で定義するメンバーを持つ JSON オブジェクト [RFC8259] である。 同じ定義がテンプレートとレンダリング済み出力に適用される。テンプレートでは、 文字列として定義された任意のメンバーの値は、代わりに JSON ポインター文字列（JavaScript Object Notation (JSON) Pointer で指定されるように / で始まる）として、 検証可能な クレデンシャル内の値を参照してMAYよい。ただし、 フィールドオブジェクトの label および value メンバーについて 注記されている場合を除く。レンダリング済み出力では、 すべての JSON ポインターが解決された値に置き換えられている。

name

クレデンシャルサマリーの表示名を含むREQUIREDな文字列。

description

クレデンシャルサマリーの説明文を含むREQUIREDな文字列。

icon

サマリーに表示するアイコンまたは画像のURLまたは data: URL [RFC2397] を含む OPTIONALな文字列。

theme

次のメンバーを持つOPTIONALなカラーテーマオブジェクト。

primaryColor

背景および強調表示に使用するプライマリカラーを 含むOPTIONALな文字列。

accentColor

強調表示および強調表現に使用するアクセントカラーを 含むOPTIONALな文字列。

fields

表示順で並べられたカスタムデータフィールドのREQUIREDな配列。 各フィールドは、次のメンバーを持つ オブジェクトである。

label

フィールドラベルを含むREQUIREDな文字列。テンプレートでは、 ラベルはリテラル文字列でMUSTなければならず、 ここでは JSON ポインターは許可されない。

value

フィールド値を含むREQUIREDな文字列。テンプレートでは、 値は JSON ポインター文字列（たとえば "/issuer"）で MUSTなければならない。

language

フィールドのラベルおよび／または値の言語を示す、 言語を識別するための タグで指定されるOPTIONALな言語タグ。

direction

フィールドのラベルおよび／または値のテキスト方向を示す、 Web 上の文字列：言語および 方向メタデータで指定されるOPTIONALな方向タグ。

validFrom

クレデンシャルが有効になる時点を示す OPTIONALな ISO 8601 日付文字列。

validUntil

クレデンシャルが有効でなくなる時点を示す OPTIONALな ISO 8601 日付文字列。

テンプレートは、処理前に上記のサマリーオブジェクト定義に対して 検証されるSHOULDべきである。 サマリーテンプレート用の非規範的な 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": "Example University"
    },
    {
      "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 テンプレートを安全にレンダリングできる環境を提供しMUSTなければならない。 さらに、ホストページは、 （たとえば template.id の参照解決などの）任意のリクエストについて、 Oblivious HTTP [RFC9458] または保護リレーを使用して要求元クライアントと要求先オリジンとの関連付けを 切り離すその他の手段を使用し、そのプライバシーを保護するSHOULDべきである。

この環境を説明するため、以下の用語を使用する。

ホスト ページ

HTML テンプレートをレンダリングするための安全な環境を提供する。

テンプレート コード

Render Method 内で提供される、またはリモートで参照される HTML フラグメント。

ラッパー コード

追加のセキュリティ制限とホストページとの通信を 提供するために HTML テンプレートをラップするコード。

最低限、環境は追跡およびその他のプライバシー上の害を防止するため、 ナビゲーション、外部コンテンツの読み込み、およびホストページへのアクセスを 防止しMUSTなければならない。

環境はまた、ユーザー環境で利用可能なすべての国際化および アクセシビリティ設定をテンプレートコードに公開しMUSTなければならない。 これにより、テンプレートは個人がユーザーエージェントまたはオペレーティングシステムに対して すでに表明している言語、テキストサイズ、コントラスト、およびモーション設定を尊重できる。 このような設定の例には、rem 単位や prefers-contrast、prefers-reduced-motion、 forced-colors といったメディアクエリーなど CSS に反映されるものに加え、 Intl および Navigator.language によって提供される ロケール情報など、JavaScript で利用可能なものが含まれる。

たとえばブラウザーを基盤とする実装では、 ホストページに対する Content Security Policy [CSP3] 制限、 HTML テンプレートをホストする iframe のサンドボックス化、および HTML テンプレートをラップして追加の CSP 制限を加え、 ホストページとの ready および error イベント通信を提供するラッパーコードを組み合わせることで、 このような環境を提供できる。

サンドボックス化された iframe は、デフォルトで上記の国際化および アクセシビリティ要件を満たす。このセクションで説明するサンドボックスおよび CSP 制限は、 CSS メディアクエリーや Intl、Navigator.language などの JavaScript API を妨げない。モバイルプラットフォーム上の WebView など、 html レンダースイート用の代替レンダリング環境も可能である。

ホストページ（通常はウォレットまたは検証可能な クレデンシャルのレンダラー）は、 HTML テンプレートがトップレベルのブラウジングコンテキストをナビゲートすること、 外部コンテンツへアクセスすること、ホストページへアクセスすること、 およびリモートコンテンツを読み込むことを防止しMUSTなければならない。

ホストページを使用する場合、次の規則が適用される。

• Content Security Policy (CSP) 制限には frame-src 'none' を含めMUSTなければならない。 これにより iframe では src の代わりに srcdoc の使用が強制され、 ブラウザーが HTML テンプレートを読み込むことを防止する。その結果、 ホストページのコードは、 リモート参照されたテンプレートコードを事前に読み込み、 テンプレートをラッパーコードへ挿入する前に、 レスポンスを対応する digestMultibase 値と照合する必要がある。
• HTML テンプレートをホストする iframe には、 ナビゲーションおよびトップレベルへのアクセスを防止するため、 sandbox="allow-scripts" を設定しMUSTなければならない。

<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]);
};

// 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 = 'レンダリングに失敗しました: ' + 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]);
    }
  });
});

// テンプレートが「ready」のとき（またはエラーが発生したとき）に呼び出す
// 関数を window に追加し、親へメッセージを送信して、親が iframe を
// 表示するかどうかを決定できるようにする
window.renderMethodReady = function(err) {
  portPromise.then(port => port.postMessage(
    !err ? 'ready' : {error: {message: err.message}}));
};

レンダリング環境の設定は Render Method 内で指定してMAYよい。この オブジェクトの目的は、提供されたテンプレートをレンダリングするときの推奨される使用方法、 表示、および意図されるアクセスモードを提供することである。実装は、 これらの設定が提供された場合、それに従うSHOULDべきである。

outputPreference オブジェクトは、次のプロパティのいずれかを 含んでMAYよい。

style オブジェクトは、次のプロパティのいずれかを 含んでMAYよい。

static レンダースイートでは、共通のレンダーメソッドプロパティを次のように使用する: