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

summary 렌더링 스위트는 공통 렌더링 방법 속성을 다음과 같이 사용합니다.

요약 객체는 아래에 정의된 멤버를 갖는 JSON 객체 [RFC8259]입니다. 동일한 정의가 템플릿과 렌더링된 출력에 적용됩니다. 템플릿에서 문자열로 정의된 멤버의 값은 대신 JavaScript Object Notation (JSON) 포인터에 명시된 것처럼 /로 시작하며 검증 가능한 자격 증명의 값을 참조하는 JSON 포인터 문자열일 MAY 수 있습니다. 다만 필드 객체의 label 및 value 멤버에 대해 명시된 예외가 있습니다. 렌더링된 출력에서는 모든 JSON 포인터가 해결된 값으로 대체됩니다.

name

자격 증명 요약의 표시 이름을 포함하는 REQUIRED 문자열입니다.

description

자격 증명 요약의 설명 텍스트를 포함하는 REQUIRED 문자열입니다.

icon

요약에 표시할 아이콘 또는 이미지의 URL 또는 data: URL [RFC2397]을 포함하는 OPTIONAL 문자열입니다.

theme

다음 멤버를 갖는 OPTIONAL 색상 테마 객체입니다.

primaryColor

배경 및 강조에 사용할 기본 색상을 포함하는 OPTIONAL 문자열입니다.

accentColor

강조 및 강조 표현에 사용할 강조 색상을 포함하는 OPTIONAL 문자열입니다.

fields

표시 순서대로 배치된 사용자 지정 데이터 필드의 REQUIRED 배열입니다. 각 필드는 다음 멤버를 갖는 객체입니다.

label

필드 레이블을 포함하는 REQUIRED 문자열입니다. 템플릿에서는 레이블이 리터럴 문자열이어야 하며, 여기에서는 JSON 포인터를 사용할 수 없습니다.

value

필드 값을 포함하는 REQUIRED 문자열입니다. 템플릿에서는 값이 JSON 포인터 문자열이어야 합니다(예: "/issuer").

language

필드의 레이블 및/또는 값의 언어를 나타내는 언어 식별용 태그에 명시된 OPTIONAL 언어 태그입니다.

direction

필드의 레이블 및/또는 값의 텍스트 방향을 나타내는 웹의 문자열: 언어 및 방향 메타데이터에 명시된 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": "예제 대학교"
    },
    {
      "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"
  }
}

다음 예제는 웹의 JSON 템플릿에 연결하고 digestMultibase 속성을 사용하여 수정되지 않도록 보호합니다.

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

다음 예제는 웹의 렌더링 템플릿에 연결하고 digestMultibase 속성을 사용하여 보호합니다.

{
...
"renderMethod": {
  // 이 렌더링 방법은 웹에서 가져옵니다.
  "id": "https://degrees.example/bachelors-card.jsonld",
  "mediaType": "application/ld+json",
  "type": "SuiteRenderMethod",
  "renderSuite": "summary",
  "digestMultibase": "zQmG270iEu5h6JqWAPdhyxz2dRerWC85Wg6wFl9znFCwYxAp"
}

html 렌더링 스위트는 공통 렌더링 방법 속성을 다음과 같이 사용합니다.

구현은 필터링된 검증 가능한 자격 증명 데이터를 사용하여 JavaScript가 HTML 템플릿을 안전하게 렌더링할 수 있는 환경을 MUST 제공해야 합니다. 또한 호스트 페이지는 보호 릴레이를 사용하여 요청 클라이언트와 요청된 출처를 분리함으로써, Oblivious HTTP [RFC9458] 또는 다른 수단을 사용하여 이루어진 모든 요청(예: template.id 역참조)의 개인정보를 보호하는 것이 SHOULD 권장됩니다.

다음 용어는 이 환경을 설명하는 데 사용됩니다.

호스트 페이지

HTML 템플릿을 렌더링하기 위한 안전한 환경을 제공합니다.

템플릿 코드

내부에 제공되거나 원격으로 참조되는 렌더링 방법의 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 제한을 추가하고 준비 및 오류 이벤트를 호스트 페이지와 통신하는 래퍼 코드를 조합하여 이러한 환경을 제공할 수 있습니다.

샌드박스된 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으로 표시합니다. 여기서는 무엇이든
      // 대신 수행할 수 있으며, 표시할 HTML을 생성하기 위한 mustache/기타 스타일
      // 템플릿 처리도 포함됩니다.

      // FIXME: 데이터 블록/스크립트 태그에 가장 적합한 이름/위치를 결정합니다.
      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으로 표시합니다. 여기서는 무엇이든
    // 대신 수행할 수 있으며, 표시할 HTML을 생성하기 위한 mustache/기타 스타일
    // 템플릿 처리도 포함됩니다.

    // FIXME: 데이터 블록/스크립트 태그에 가장 적합한 이름/위치를 결정합니다.
    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]);
};

// 준비 또는 오류에 대한 이벤트 응답을 설정합니다.
// 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);
});

// 상위 창에서 통신 포트로 해결될 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에 함수를 연결합니다.
// "ready" 상태인지(또는 오류가 발생했는지)를 알리고 메시지를
// 상위 창으로 보내어 iframe을 표시할지 결정할 수 있도록 합니다.
window.renderMethodReady = function(err) {
  portPromise.then(port => port.postMessage(
    !err ? 'ready' : {error: {message: err.message}}));
};

렌더링 환경 기본 설정은 렌더링 방법 내에서 제공할 MAY 수 있습니다. 이 객체의 목적은 제공된 템플릿을 렌더링할 때 권장 사용 방식, 표시 및 의도된 접근 모드를 제공하는 것입니다. 구현은 제공된 경우 이러한 기본 설정을 따르는 것이 SHOULD 권장됩니다.

outputPreference 객체는 다음 속성 중 하나 이상을 포함할 MAY 수 있습니다.

style 객체는 다음 속성 중 하나 이상을 포함할 MAY 수 있습니다.

static 렌더링 스위트는 공통 렌더링 메서드 속성을 다음과 같이 사용합니다: