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

card レンダリングスイートは、JSON テンプレートを使用して 検証可能な クレデンシャルを標準化されたデータ表示形式に変換する。この形式により、 ウォレットは重要なデータを強調し、追加フィールドを設定可能なレスポンシブなカードレイアウトで クレデンシャルを表示できる。このメソッドを実装するウォレットは、標準化された JSON 出力を 独自のカード UI デザインでレンダリングできるため、ウォレットが特定のクレデンシャルタイプを ネイティブでサポートしていない場合でもクレデンシャルを表示できる。

テンプレートは、card 出力構造に一致する JSON オブジェクトである。 テンプレート内の文字列値には、検証可能な クレデンシャル内のフィールドを参照する JSON pointer 文字列 （JavaScript Object Notation (JSON) Pointer で指定）を使用できる。テンプレートを処理する際、 JSON pointer 文字列はクレデンシャルデータに対して評価され、解決された値に置き換えられる。 テンプレートは、以下で定義される JSON テンプレートスキーマに適合しなければならず、 結果の出力は card 出力スキーマに適合しなければならない。複数の フィールドにまたがる複合データはサポートされず、各フィールドは単一の JSON pointer を参照する。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "description", "fields"],
  "properties": {
    "name": {
      "type": "string",
      "description": "リテラル文字列または JSON pointer としての表示名（例: \"/credentialSubject/degree/name\"）"
    },
    "description": {
      "type": "string",
      "description": "リテラル文字列または JSON pointer としての説明"
    },
    "icon": {
      "type": "string",
      "description": "リテラル文字列または JSON pointer としてのアイコン URL/data URI"
    },
    "theme": {
      "type": "object",
      "properties": {
        "primaryColor": {
          "type": "string",
          "description": "リテラル文字列または JSON pointer としてのプライマリカラー"
        },
        "accentColor": {
          "type": "string",
          "description": "リテラル文字列または JSON pointer としてのアクセントカラー"
        }
      },
      "additionalProperties": false
    },
    "fields": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["label", "value"],
        "properties": {
          "label": {
            "type": "string",
            "description": "フィールドラベル（JSON pointer ではなくリテラル文字列でなければならない）"
          },
          "value": {
            "type": "string",
            "pattern": "^/",
            "description": "JSON pointer 文字列としてのフィールド値（\"/\" で始まらなければならない）"
          },
          "language": {
            "type": "string",
            "description": "フィールド用の任意の BCP 47 言語タグ"
          }
        },
        "additionalProperties": false
      }
    },
    "validFrom": {
      "type": "string",
      "description": "リテラルの ISO 8601 日付文字列または JSON pointer としての有効期間開始日"
    },
    "validUntil": {
      "type": "string",
      "description": "リテラルの ISO 8601 日付文字列または JSON pointer としての有効期間終了日"
    }
  },
  "additionalProperties": false
}

{
  "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 テンプレートがレンダリング テンプレートとして使用される。テンプレートは JSON pointer 文字列を使用してクレデンシャルデータを参照する。

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "card",
    // JSON テンプレートは VC に埋め込まれている
    "template": "data:application/json;base64,eyJuYW1lIjogIi9jcmVkZW50aWFsU3ViamVjdC9kZWdyZWUvbmFtZSIsICJkZXNjcmlwdGlvbiI6ICJVbml2ZXJzaXR5IERlZ3JlZSBDcmVkZW50aWFsIiwgImZpZWxkcyI6IFt7ImxhYmVsIjogIkluc3RpdHV0aW9uIiwgInZhbHVlIjogIi9pc3N1ZXIifV19"
  }
}

次の例では、Web 上の JSON テンプレートにリンクし、digestMultibase プロパティを使用して変更から保護する。

{
...
"renderMethod": {
  "type": "TemplateRenderMethod",
  "renderSuite": "card",
  "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": "TemplateRenderMethod",
  "renderSuite": "card",
  "digestMultibase": "zQmG270iEu5h6JqWAPdhyxz2dRerWC85Wg6wFl9znFCwYxAp"
}

html レンダリングスイートにより、テンプレート作成者は 検証可能な クレデンシャルをレンダリングするための HTML テンプレートを提供できる。 HTML は、template または template.id（template の値がオブジェクトの場合）の値として、 リモート参照または data: URL 経由で参照できる。HTML フラグメント内の JavaScript は、 HTML テンプレートとともにサンドボックス化された iframe 内でホストされる HTML データブロック （すなわち <script type="application/vc"></script>）を介して提供される、 フィルタリング済みの検証可能な クレデンシャルデータをレンダリングする役割を担う。

{
  "@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": "名前の例",
    "notRendered": "表示されるべきではない"
  },
  "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": {
      "accessMode": [
        "visual"
      ],
      "mediaType": "application/html",
      "style": {
        "width": "800px",
        "height": "800px"
      }
    }
  }
}

実装は、フィルタリング済みの検証可能な クレデンシャルデータを使用して JavaScript が HTML テンプレートを安全に レンダリングできる環境を提供しなければならない。 さらに、ホストページは、Oblivious HTTP [RFC9458] または保護リレーを使用して要求元クライアントと要求先オリジンを関連付けないその他の手段を用いて、 行われるすべてのリクエスト（例えば template.id の参照解決）のプライバシーを 保護すべきである。

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

ホストページ

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

テンプレート コード

レンダリングメソッド内で提供される、またはリモートから参照される HTML フラグメント。

ラッパー コード

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

少なくとも、追跡およびその他のプライバシー侵害を防ぐため、この環境はナビゲーション、 外部コンテンツの読み込み、およびホストページへのアクセスを 防止しなければならない。

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

<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（または失敗した場合は
// reject される）。代わりに表示またはエラーを表示するために使用できる
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}}));
};

nfc レンダリングスイートは、検証可能な クレデンシャルを表すバイナリペイロードを、無線 NFC 接続を介して送信する。

以下の例では、完全に埋め込まれた NFC ペイロードがレンダリング テンプレートとして使用され、クレデンシャルに関連付けられたバーコード識別子のみを開示する。

{
...
"renderMethod": {
  "type": "TemplateRenderMethod",
  "renderSuite": "nfc",
  "name": "タップして送信",
  // NFC ペイロードが埋め込まれている
  "template": "data:application/octet-stream;base64,2QZkpQGDG...G8XJWnROcY4Biw",
  // NFC 経由ではバーコードのみが送信される
  "renderProperty": ["/credentialSubject/barcode"]
}
...
}

ホストページは、HTML テンプレートをホストする iframe 要素を作成しなければならない。 ホストページは、ナビゲーションおよびトップレベルへのアクセスを 防止するため、iframe の sandbox 属性を allow-scripts に設定しなければならない。

1. vc を、レンダリングする検証可能な クレデンシャルとする。
2. renderMethod を、vc 内で選択された renderMethod プロパティとし、ここで renderMethod.type は TemplateRenderMethod、 renderMethod.renderSuite は html である。
3. renderMethod.template が文字列である場合、 template を renderMethod.template の値とする。
4. renderMethod.template がマップである場合、 template を renderMethod.template.id 内の URL を取得した結果とする。

ホストページは、検証可能な クレデンシャル vc を、renderMethod.renderProperty が存在する場合には、 そこで指定されたプロパティのみを含むようにフィルタリングしなければならない。 renderMethod.renderProperty が存在しない場合は、検証可能な クレデンシャル全体が 使用される。

このフィルタリングは、Data Integrity ECDSA Cryptosuites v1.0 仕様 [VC-DI-ECDSA] の セクション 3.4.13 selectJsonLd で定義された selectJsonLd アルゴリズムを、 renderMethod.renderProperty に存在する JSON Pointer [RFC6901] 値に適用することによって 実行しなければならない。

ホストページは、フィルタリングされた 検証可能な クレデンシャルと HTML テンプレートを、上記で定義されたラッパーコードテンプレートに埋め込むことによって、 ラッパーコードを作成しなければならない。

1. wrapperCode を、<head> 内に <meta http-equiv="Content-Security-Policy" content="default-src data: 'unsafe-inline'"> を持つ HTML Document とする。
2. datablock を、type が application/vc である HTML Data Block とする。
3. datablock の内容を、フィルタリングされた検証可能な クレデンシャルを 文字列化した JSON 形式に設定する。
4. datablock を wrapperCode の <head> に挿入する。
5. template の値を wrapperCode の <body> に 挿入する。

ホストページは、iframe の srcdoc 属性を、結果として得られたラッパーコードに設定しなければならない。

1. iframe の srcdoc 属性を、 wrapperCode を文字列化した HTML に設定する。

ホストページは、上記の説明に従って ready および error メッセージを受信するため、 ラッパーコードとの通信 チャネルを設定しなければならない。

1. renderPromise を、以下の動作をする新しい Promise とする:
   1. resolve 時には、iframe をユーザーに表示するために使用できる。
   2. reject 時には、エラーメッセージをユーザーに表示する。
2. iframe の onload イベント内で:
   1. channel を新しい MessageChannel とする。
   2. channel に新しい port1 リスナーを作成して開始し、 wrapperCode を介して iframe に挿入された template 内のコードからの ready メッセージを待ち受ける。
   3. port1 リスナーで ready メッセージを受信した場合、 renderPromise を resolve する。 error メッセージを受信した場合、エラー メッセージを使用して renderPromise を reject する。
   4. postMessage を使用して、channel の port2 を iframe のコンテンツウィンドウへ送信する。

ホストページは、レンダリングが完了した時点、または レンダリング中にエラーが発生したかどうかを判断するため、 renderPromise を使用すべきである。

ラッパーコードは、 MessageChannel を介してホストページからの通信を受信するように 設定しなければならず、テンプレートコードが使用する window.renderMethodReady メソッドを提供しなければならない。

1. window.onload イベント内で...
   1. port を、message イベントを介してホストページから受信した MessagePort とする。
   2. 以下の動作をする window.renderMethodReady 関数を作成する...
      1. 引数なしで呼び出された場合、port を介してホストページへ ready メッセージを送信する。
      2. Error 引数を指定して呼び出された場合、エラーメッセージを含む error メッセージを、port を介してホストページへ 送信する。