Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix rendering of examples #237

Merged
merged 5 commits into from
Feb 17, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
.vscode
node_modules
.idea
DS_Store
77 changes: 38 additions & 39 deletions index.html
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@
<meta charset="utf-8" />
<title>Securing Verifiable Credentials using JOSE and COSE</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"></script>
<script src='./respec-plugins/vc-jose-cose.js'></script>
<link rel="stylesheet" href="./respec-plugins/vc-jose-cose.css">
<script src="https://cdn.jsdelivr.net/gh/w3c/vc-jose-cose@fix-examples/plugin/dist/main.js"></script>
<script class="remove">
// See https://github.com/w3c/respec/wiki/ for how to configure
// ReSpec
Expand All @@ -16,13 +15,13 @@
// specification status (e.g., WD, NOTE, etc.). If in doubt use
// ED.
specStatus: "WD",

// the specification's short name, as in
// http://www.w3.org/TR/short-name/
shortName: "vc-jose-cose",

// if you wish the publication date to be other than today, set
// this
// this
// publishDate: "2023-07-20",

// implementationReportURI:
Expand All @@ -32,7 +31,7 @@

// if there is a previously published draft, uncomment this and
// set its YYYY-MM-DD date and its maturity status
previousPublishDate: "2023-07-10",
previousPublishDate: "2023-07-10",
previousMaturity: "WD",

// extend the bibliography entries localBiblio: vcwg.localBiblio,
Expand Down Expand Up @@ -82,7 +81,7 @@

maxTocLevel: 3,
inlineCSS: true,
postProcess: [postProcessWithWorker],
postProcess: [window.respecVcJoseCose.processVcJoseCose],
license: "w3c-software-doc",
xref: true,
otherLinks: [{
Expand Down Expand Up @@ -159,7 +158,7 @@ <h2>Introduction</h2>
defined by the OAuth, JOSE, and COSE working groups at the IETF.
This includes SD-JWT [[SD-JWT]] and COSE [[RFC9052]],
and provides an approach using well-defined content types
[[RFC6838]] and structured suffixes [[MULTIPLE-SUFFIXES]]
[[RFC6838]] and structured suffixes [[MULTIPLE-SUFFIXES]]
to distinguish the data types of unsecured documents conforming to [[VC-DATA-MODEL-2.0]]
from the data types of secured documents conforming to [[VC-DATA-MODEL-2.0]],
as defined in this specification.
Expand Down Expand Up @@ -212,7 +211,7 @@ <h2>Securing the VC Data Model</h2>
<p>
A benefit to this approach is that payloads can be made to conform
directly to [[VC-DATA-MODEL-2.0]] without any mappings or
transformation, while at the same time supporting registered
transformation, while at the same time supporting registered
header parameters and claims that are understood in the context of JOSE and COSE.
</p>
<p>
Expand Down Expand Up @@ -245,7 +244,7 @@ <h2>Securing JSON-LD Verifiable Credentials with JOSE</h2>
for additional details regarding usage of <code>typ</code> and
<code>cty</code>.
</p>

<pre class="example vc-jose-cose" title="A simple example of a verifiable credential">
{
"@context": [
Expand Down Expand Up @@ -281,7 +280,7 @@ <h2>Securing JSON-LD Verifiable Credentials with JOSE</h2>
<h2>Securing JSON-LD Verifiable Presentations with JOSE</h2>
<p>
This section details how to use JOSE to secure verifiable presentations conforming
to [[VC-DATA-MODEL-2.0]].
to [[VC-DATA-MODEL-2.0]].
</p>
<p>
[[RFC7515]] MAY be used to secure this media type.
Expand Down Expand Up @@ -321,7 +320,7 @@ <h2>Securing JSON-LD Verifiable Presentations with JOSE</h2>
<p>
To improve interoperability, implementations SHOULD support the compact serialization (<code>application/sd-jwt</code>),
and MAY support the JSON serialization (<code>application/sd-jwt+json</code>).
If the JSON serialization is used, it is RECOMMENDED that a profile be defined,
If the JSON serialization is used, it is RECOMMENDED that a profile be defined,
to ensure any addition JSON members are understood consistently.
</p>
</section>
Expand Down Expand Up @@ -418,7 +417,7 @@ <h2>JOSE Header Parameters and JWT Claims</h2>
which represent the validity of the data that is being secured.
</p>
<p>
The claims and security provided by this specification are independent of the data
The claims and security provided by this specification are independent of the data
secured and semantics provided by the [[VC-DATA-MODEL-2.0]]. This means that while the security
features of this specification ensure data integrity and authenticity, they do
not dictate the interpretation of claim data.
Expand Down Expand Up @@ -493,7 +492,7 @@ <h2>Key Discovery</h2>
<!-- DID URLS via "issuer" and "holder" -->
<p>
When <a href="#iss">iss</a> is absent and the <a data-cite="VC-DATA-MODEL-2.0#dfn-issuers">issuer</a>
is identified as a <a data-cite="DID-CORE#did-subject">DID Subject</a>,
is identified as a <a data-cite="DID-CORE#did-subject">DID Subject</a>,
the <a href="#kid">kid</a> MUST be an absolute <a data-cite="DID-CORE#relative-did-urls">DID URL</a>.
</p>
<pre class="example" title="An issuer identified by a DID">
Expand Down Expand Up @@ -568,9 +567,9 @@ <h2>Key Discovery</h2>
</pre>

<!-- REGULAR URLS via "iss" -->

<p>
When <a href="#iss">iss</a> is present and is a [[URL]],
When <a href="#iss">iss</a> is present and is a [[URL]],
the <a href="#kid">kid</a> MUST match a key discovered via a JWT Issuer Metadata Request,
as described in [[SD-JWT-VC]].
</p>
Expand Down Expand Up @@ -618,7 +617,7 @@ <h2>iss</h2>
If <code>iss</code> is present in the <a data-cite="RFC7515#section-4.1">JOSE Header</a>
or the <a data-cite="RFC7519#section-4.1.1">JWT Claims </a>,
a <a data-cite="VC-DATA-MODEL-2.0#dfn-verifier">verifier</a> can use this parameter
to obtain a <a data-cite="RFC7517#section-4">JSON Web Key</a> to use in the
to obtain a <a data-cite="RFC7517#section-4">JSON Web Key</a> to use in the
<a data-cite="VC-DATA-MODEL-2.0#dfn-verify">verification</a> process.
</p>
<p>
Expand All @@ -633,7 +632,7 @@ <h2>iss</h2>
distinguish the specific key used.
</p>
</section>

<section>
<h2>cnf</h2>
<p>
Expand All @@ -645,17 +644,17 @@ <h2>cnf</h2>
</p>
</section>
</section>

<section>
<h2>Well Known URIs</h2>
<p class="issue" data-number="160">
The working group is currently exploring how
The working group is currently exploring how
<a data-cite="RFC5785#section-3">Defining Well-Known Uniform Resource Identifiers (URIs)</a>
could be leveraged to assist a <a data-cite="VC-DATA-MODEL-2.0#dfn-verifier">verifier</a> in discovering verification keys for
<a data-cite="VC-DATA-MODEL-2.0#dfn-issuers">issuers</a>
and <a data-cite="VC-DATA-MODEL-2.0#dfn-holders">holders</a>.
</p>

<section>
<h2>JWT Issuer</h2>
<p>
Expand Down Expand Up @@ -794,7 +793,7 @@ <h3>Verification Material</h3>
Implementations MAY convert keys between formats as desired for operational purposes or
to interface with cryptographic libraries. As an internal implementation detail, such
conversion MUST NOT affect the external representation of key material.
</p>
</p>

<p>
An example of a <a>controller document</a> containing <a>verification
Expand Down Expand Up @@ -861,11 +860,11 @@ <h3>JsonWebKey</h3>
</p>
<p>
As specified in <a data-cite="RFC7517#section-4.4">Section 4.4 of the JWK specification</a>,
the OPTIONAL `alg` property identifies the algorithm intended for use with the public key,
the OPTIONAL `alg` property identifies the algorithm intended for use with the public key,
and SHOULD be included to prevent security issues that can arise when using the same
key with multiple algorithms. As specified in <a data-cite="RFC7518#section-6.2.1.1">
Section 6.2.1.1 of the JWA specification</a>, describing a key using an elliptic curve,
the REQUIRED `crv` property is used to identify the particular curve type of the public key.
Section 6.2.1.1 of the JWA specification</a>, describing a key using an elliptic curve,
the REQUIRED `crv` property is used to identify the particular curve type of the public key.
As specified in <a data-cite="RFC7515#section-4.1.4">Section 4.1.4 of the JWS specification</a>,
the OPTIONAL `kid` property is a hint used to help discover the key; if present, the `kid` value SHOULD
match, or be included in, the `id` property of the encapsulating `JsonWebKey` object,
Expand Down Expand Up @@ -1231,7 +1230,7 @@ <h2><code>application/vc+ld+json+sd-jwt</code></h2>
<tr>
<td>Encoding considerations: </td>
<td>
binary; `application/sd-jwt` values are a series of base64url-encoded values
binary; `application/sd-jwt` values are a series of base64url-encoded values
(some of which may be the empty string) separated by period ('.') or tilde ('~') characters.
</td>
</tr>
Expand Down Expand Up @@ -1275,7 +1274,7 @@ <h2><code>application/vp+ld+json+sd-jwt</code></h2>
<tr>
<td>Encoding considerations: </td>
<td>
binary; `application/sd-jwt` values are a series of base64url-encoded values
binary; `application/sd-jwt` values are a series of base64url-encoded values
(some of which may be the empty string) separated by period ('.') or tilde ('~') characters.
</td>
</tr>
Expand All @@ -1295,7 +1294,7 @@ <h2><code>application/vp+ld+json+sd-jwt</code></h2>
</tr>
</table>
</section>

<section id="vc-ld-json-cose-media-type">
<h2><code>application/vc+ld+json+cose</code></h2>
<p>
Expand Down Expand Up @@ -1395,7 +1394,7 @@ <h2><code>application/vp+ld+json+cose</code></h2>
</table>
</section>
</section>

</section>
<section>
<h3>Other Considerations</h3>
Expand Down Expand Up @@ -1726,7 +1725,7 @@ <h2>
"id": "https://subject.vendor.example"
}
},
"https://vendor.example/credentials/42",
"https://vendor.example/credentials/42",
"did:example:123",
"urn:uuid:01ec9426-c175-4e39-a006-d30050e28214",
"urn:ietf:params:oauth:jwk-thumbprint:sha-256:_Fpfe27AuGmEljZE9s2lw2UH-qrZLRFNrWbJrWIe4SI",
Expand Down Expand Up @@ -1780,7 +1779,7 @@ <h2>
},
}
</pre>

<pre class="example" title="A COSE Sign 1 with an attached payload">
18( / COSE Sign 1 /
[
Expand All @@ -1791,7 +1790,7 @@ <h2>
]
)
</pre>

<pre class="example" title="A COSE Sign 1 with a detached payload">
18( / COSE Sign 1 /
[
Expand All @@ -1803,7 +1802,7 @@ <h2>
)
</pre>
<p>
The payload can be either a credential or presentation as described in
The payload can be either a credential or presentation as described in
<a data-cite="VC-DATA-MODEL-2.0#securing-verifiable-credentials">Securing Verifiable Credentials</a>.
</p>
</section>
Expand All @@ -1823,14 +1822,14 @@ <h2>Verification Algorithm</h2>
</p>

<p>
When verifying a credential or presentation secured with SD-JWT, the algorithm defined in
When verifying a credential or presentation secured with SD-JWT, the algorithm defined in
[[SD-JWT] for
Verification of the SD-JWT
MUST be followed.
</p>

<p>
When verifying a credential or presentation secured with COSE_Sign1, the algorithm defined in
When verifying a credential or presentation secured with COSE_Sign1, the algorithm defined in
<a data-cite="RFC9052#section-4.4">
Signing and Verification Process
</a> MUST be followed.
Expand All @@ -1852,25 +1851,25 @@ <h2>Validation Algorithm</h2>
</p>

<p>
The verified payload MUST be a well formed compact JSON-LD document, as described in
The verified payload MUST be a well formed compact JSON-LD document, as described in
<a data-cite="VC-DATA-MODEL-2.0/#conformance">Verifiable Credentials Data Model v2.0</a>.
</p>

<p>
Schema extension mechanisms such as <code>credentialSchema</code> SHOULD be checked.
If the extension mechanism <code>type</code> is not understood,
If the extension mechanism <code>type</code> is not understood,
this property MUST be ignored.
</p>

<p>
Status extension mechanisms such as <code>credentialStatus</code> SHOULD be checked.
If the extension mechanism <code>type</code> is not understood,
If the extension mechanism <code>type</code> is not understood,
this property MUST be ignored.
</p>

<p>
Based on the validation policy of the verifier and the type of credentials and type of securing mechanism,
additional validation checks might be applied. For example, dependencies between multiple credentials,
Based on the validation policy of the verifier and the type of credentials and type of securing mechanism,
additional validation checks might be applied. For example, dependencies between multiple credentials,
ordering or timing information associated with multiple credentials, and/or multiple presentations
could cause an otherwise valid credential or presentation to be considered invalid.
</p>
Expand Down
28 changes: 28 additions & 0 deletions plugin/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Verifiable Credential Service Worker Plugin for ReSpec

But with support for v2, and no JSON-LD processing.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this "but" compare with?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not a good sentence —

https://github.com/w3c/respec-vc but with support for v2, and no JSON-LD processing.

Neither is this —

Verifiable Credential Service Worker Plugin for ReSpec but with support for v2, and no JSON-LD processing.

Nor this —

Verifiable Credentials for ReSpec but with support for v2, and no JSON-LD processing.

Nor this —

Verifiable Credential extensions to ReSpec but with support for v2, and no JSON-LD processing.

Please provide some rephrasing, I guess through a new PR since this one was rushed through.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After cycling this through my brain a few more times, I think what the above was trying to say is —

# Verifiable Credential Service Worker Plugin for ReSpec

The 
**[Verifiable Credential Service Worker Plugin for ReSpec](https://github.com/w3c/vc-jose-cose/tree/main/plugin)** 
is basically the **[Verifiable Credential extensions to ReSpec](https://github.com/w3c/respec-vc)**, 
but with support for VCDM v2, and without JSON-LD processing.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@TallTed handling this here #241


# Usage

To use this extension, add the `respec-plugins` directory to your spec,
then configure respect to use the worker to post process like so:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
then configure respect to use the worker to post process like so:
then configure ReSpec to use the worker to post-process like so:


```html
<head>
<title>Respec Service Worker Plugin Test</title>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<title>Respec Service Worker Plugin Test</title>
<title>ReSpec Service Worker Plugin Test</title>

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks @TallTed similar to my response to David, I will incorporate your changes in a follow-up PR.

<meta http-equiv='Content-Type' content='text/html;charset=utf-8' />
<script src='https://www.w3.org/Tools/respec/respec-w3c' class='remove'></script>
<script src="https://cdn.jsdelivr.net/gh/w3c/vc-jose-cose/plugin/dist/main.js"></script>
<script type="text/javascript" class="remove">
var respecConfig = {
// ...
postProcess: [window.respecVcJoseCose.processVcJoseCose]
};
</script>
</head>
```

### Credits

Based on https://github.com/transmute-industries/respec-vc-jwt, which was based
on the original plugin here https://github.com/digitalbazaar/respec-vc
Loading
Loading