검증 가능한 자격 증명 렌더링 방법 v1.0

card 렌더 스위트는 JSON 템플릿을 사용하여 검증 가능한 자격 증명을 표준화된 데이터 표시 형식으로 변환합니다. 이 형식을 사용하면 지갑에서 주요 데이터가 강조되고 추가 필드를 구성할 수 있는 반응형 카드 레이아웃으로 자격 증명을 표시할 수 있습니다. 이 메서드를 구현하는 지갑은 표준화된 JSON 출력을 자체 카드 UI 디자인으로 렌더링할 수 있으므로, 지갑에서 특정 자격 증명 유형을 기본적으로 지원하지 않는 경우에도 자격 증명을 표시할 수 있습니다.

템플릿과 렌더링된 출력은 모두 아래에 제시된 단일 정의인 카드 객체를 공유하는 JSON 객체입니다. 템플릿의 문자열 값은 JavaScript 객체 표기법(JSON) 포인터에 명시된 JSON 포인터 문자열일 수 있으며, 이는 검증 가능한 자격 증명의 값을 참조합니다. 템플릿을 처리할 때 JSON 포인터 문자열은 자격 증명 데이터를 기준으로 평가되고 해석된 값으로 대체됩니다. 템플릿과 그 결과로 생성되는 출력은 모두 카드 객체 정의를 준수해야 합니다. 여러 필드에 걸친 복합 데이터는 지원되지 않으며, 각 필드는 단일 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
}

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "card",
    // JSON 템플릿은 VC에 포함됩니다
    "template": "data:application/json;base64,eyJuYW1lIjogIi9jcmVkZW50aWFsU3ViamVjdC9kZWdyZWUvbmFtZSIsICJkZXNjcmlwdGlvbiI6ICJVbml2ZXJzaXR5IERlZ3JlZSBDcmVkZW50aWFsIiwgImZpZWxkcyI6IFt7ImxhYmVsIjogIkluc3RpdHV0aW9uIiwgInZhbHVlIjogIi9pc3N1ZXIifV19"
  }
}

{
...
"renderMethod": {
  "type": "TemplateRenderMethod",
  "renderSuite": "card",
  "template": {
    // 이 JSON 템플릿은 웹에서 가져옵니다
    "id": "https://degree.example/credential-templates/bachelors.json",
    "mediaType": "application/json",
    "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR"
  }
}

{
...
"renderMethod": {
  // 이 렌더 메서드는 웹에서 가져옵니다
  "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 템플릿을 감싸는 코드.

최소한 이 환경은 추적 및 기타 개인정보 보호 피해를 방지하기 위해 탐색, 외부 콘텐츠 로드, 호스트 페이지에 대한 접근을 반드시 방지해야 한다.

환경은 또한 사용자의 환경에서 사용할 수 있는 모든 국제화 및 접근성 설정을 템플릿 코드에 노출해야 합니다. 이를 통해 템플릿은 개인이 이미 자신의 사용자 에이전트 또는 운영 체제에 표현한 언어, 텍스트 크기, 대비 및 모션 환경 설정을 따를 수 있습니다. 이러한 설정의 예로는 rem 단위 및 prefers-contrast, prefers-reduced-motion, forced-colors와 같은 미디어 쿼리처럼 CSS에 반영되는 설정과, Intl 및 Navigator.language에서 제공하는 로케일 정보처럼 JavaScript에서 사용할 수 있는 설정이 있습니다.

예를 들어 브라우저 기반 구현은 호스트 페이지에 대한 Content Security Policy [CSP3] 제한, HTML 템플릿을 호스팅하는 iframe의 샌드박싱 및 HTML 템플릿을 래핑하여 추가 CSP 제한을 적용하고 호스트 페이지와 준비 및 오류 이벤트 통신을 제공하는 래퍼 코드를 조합하여 이러한 환경을 제공할 수 있습니다.

샌드박스 처리된 iframe은 기본적으로 위의 국제화 및 접근성 요구 사항을 충족합니다. 이 섹션에서 설명한 샌드박스 및 CSP 제한은 CSS 미디어 쿼리나 Intl 및 Navigator.language와 같은 JavaScript API를 방해하지 않습니다. 모바일 플랫폼의 WebView와 같이 html 렌더 스위트를 위한 대체 렌더링 환경도 사용할 수 있습니다.

<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('템플릿 렌더링 스크립트 실행 중');

      // 예제 렌더러로 자격 증명을 JSON으로 표시한다. 여기서는 무엇이든
      // 대신 수행할 수 있으며, 표시할 HTML을 생성하기 위한 mustache/기타 스타일의
      // 템플릿 처리도 포함된다

      // 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('템플릿 렌더링 스크립트 실행 중');

    // 예제 렌더러로 자격 증명을 JSON으로 표시한다. 여기서는 무엇이든
    // 대신 수행할 수 있으며, 표시할 HTML을 생성하기 위한 mustache/기타 스타일의
    // 템플릿 처리도 포함된다

    // 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('렌더링 준비 완료');
  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('렌더링 실패', 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}}));
};

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. vc에서 선택한 renderMethod 속성 중 renderMethod.type이 TemplateRenderMethod이고 renderMethod.renderSuite가 html인 것을 renderMethod라고 하자.
3. renderMethod.template이 문자열이면, template을 renderMethod.template의 값이라고 하자.
4. renderMethod.template이 맵이면, template을 renderMethod.template.id의 URL을 가져온 결과라고 하자.

호스트 페이지는 renderMethod.renderProperty가 존재하는 경우 여기에 지정된 속성만 포함하도록 검증 가능한 자격 증명 vc를 반드시 필터링해야 한다. renderMethod.renderProperty가 존재하지 않으면 전체 검증 가능한 자격 증명을 사용한다.

이 필터링은 Data Integrity ECDSA Cryptosuites v1.0 명세 [VC-DI-ECDSA]의 섹션 3.4.13 selectJsonLd에 정의된 selectJsonLd 알고리즘을 renderMethod.renderProperty에 있는 JSON 포인터 [RFC6901] 값에 적용하여 반드시 수행해야 한다.

호스트 페이지는 필터링된 검증 가능한 자격 증명과 HTML 템플릿을 위에서 정의한 래퍼 코드 템플릿에 삽입하여 래퍼 코드를 반드시 생성해야 한다.

1. wrapperCode를 <head>에 <meta http-equiv="Content-Security-Policy" content="default-src data: 'unsafe-inline'">가 있는 HTML 문서라고 하자.
2. datablock을 type이 application/vc인 HTML 데이터 블록이라고 하자.
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. 이제 wrapperCode를 통해 iframe에 삽입된 template의 코드에서 오는 ready 메시지를 수신하는 새 port1 리스너를 channel에 생성하고 시작한다.
   3. port1 리스너에서 ready 메시지를 수신하면 renderPromise를 이행한다. error 메시지를 수신하면 오류 메시지와 함께 renderPromise를 거부한다.
   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를 통해 호스트 페이지에 보낸다.