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.

Sign up for GitHub

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

Add details about HTTPS binding. #108

Merged
merged 4 commits into from
Jan 22, 2025
Merged

Add details about HTTPS binding. #108

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
166048c
Add details about HTTPS binding.
peacekeeper Jan 9, 2025
54a0a34
Update index.html
peacekeeper Jan 9, 2025
fa5c855
Fix HTML bugs
peacekeeper Jan 9, 2025
d41aaba
Fix HTML bugs.
peacekeeper Jan 22, 2025
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
156 changes: 94 additions & 62 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1101,12 +1101,13 @@ <h2>Dereferencing the Fragment</h2>
<var>input <a>DID URL</a></var>.</li>
<li>Return the <var>output <a>service endpoint</a> URL</var>.</li>
</ol>
</li>
<li>Otherwise, dereference the DID fragment as defined by the media type ([[RFC2046]]) of the resource.
For example, if the resource is a representation of a DID document with media type <code>application/did</code>, then
the fragment is treated according to the rules associated with the
<a href="https://www.w3.org/TR/json-ld11/#iana-considerations">JSON-LD 1.1: application/ld+json media type</a>
[JSON-LD11].
</li>
</li>
</ol>

<p class="note">
Expand Down Expand Up @@ -1828,32 +1829,60 @@ <h1>Bindings</h1>
<section id="bindings-https">
<h2>HTTP(S) Binding</h2>
<p>This section defines a <a>DID resolver</a> <a>binding</a> which exposes the
<a>DID resolution</a> and/or <a>DID URL dereferencing</a> functions (including all
resolution options and output data) via an HTTP(S) endpoint. See <a href="#resolver-architectures"></a>.</p>
<a>DID resolution</a> and/or <a>DID URL dereferencing</a> functions (including all
resolution/dereferencing options and metadata) via an HTTP(S) endpoint. See <a href="#resolver-architectures"></a>.</p>

<p>The HTTP(S) binding is a <a>remote binding</a>. It requires a known HTTP(S) URL where a remote
Copy link
Contributor

Choose a reason for hiding this comment

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

Wondering if we need to say that HTTPS can also be used locally. HTTPS does not mean always connecting to a remote DID resolver

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I agree, I created issue #111 for this.

<a>DID resolver</a> can be invoked. This URL is called the <var><a>DID resolver</a> HTTP(S) endpoint</var></p>

<p>The HTTP(S) binding for <a>DID resolvers</a> requires a known HTTP(S) URL called the
<var><a>DID resolver</a> HTTP(S) endpoint</var>.</p>
<p>Using this binding, the <a>DID resolution</a> function (see
<a href="#resolving"></a>) and/or <a>DID URL dereferencing</a> function (see <a href="#dereferencing"></a>)
can be executed as follows:</p>
<a href="#resolving"></a>) and/or <a>DID URL dereferencing</a> function (see <a href="#dereferencing"></a>)
can be executed as follows:</p>

<ol class="algorithm">
<li>Initialize a <var>request HTTP(S) URL</var> with the <var><a>DID resolver</a> HTTP(S) endpoint</var>.
<ol class="algorithm">
<li>Append the <var>input <a>DID</a></var> or
<var>input <a>DID URL</a></var> to the <var>request HTTP(S) URL</var>. Certain characters
MUST be percent-encoded (as specified in <a
data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>).</li>
<li>Encode the <code>accept</code> <var>resolution option</var>
as the <code>Accept</code> HTTP header in the request.</li>
<li>Encode all other resolution options as
query parameters in the <var>request HTTP(S) URL</var>.</li>
</ol>
<li>Initialize a <var>request HTTP(S) URL</var> with the <var><a>DID resolver</a> HTTP(S) endpoint</var>.</li>
<pre class="example nohighlight">https://dev.uniresolver.io/1.0/identifiers/</pre>
Copy link
Member

@msporny msporny Jan 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

We'll want to use a made-up URL here.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I agree. I created issue #109 to address this across the whole document.

<li>For the <a>DID resolution</a> function:
<ol class="algorithm">
<li>Append the <var>input <a>DID</a></var> to the <var>request HTTP(S) URL</var>.</li>
<pre class="example nohighlight">https://dev.uniresolver.io/1.0/identifiers/did:example:1234</pre>
<li>Set the <code>Accept</code> <var>HTTP request header</var> to `application/ld+json;profile="https://w3id.org/did-resolution"`
in order to request a complete <a href="#did-resolution-result"></a>, OR</li>
<li>set the <code>Accept</code> <var>HTTP request header</var> to the value of the <b>accept</b> <var>resolution option</var>.</li>
<li>If any other <var>resolution options</var> are provided:
<ol class="algorithm">
<li>The <var>input <a>DID</a></var> MUST be URL-encoded (as specified in <a
data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>).</li>
<li>Encode all <var>resolution options</var> except <b>accept</b> as
query parameters in the <var>request HTTP(S) URL</var>.</li>
<pre class="example nohighlight">https://dev.uniresolver.io/1.0/identifiers/did%3Aexample%3A1234?option1=value1&option2=value2</pre>
</ol>
</li>
</ol>
</li>
<li>Execute an HTTP <code>GET</code> request on the <var>request HTTP(S) URL</var>.</li>
<li>Dereference the <var>input <a>DID</a></var> or <var>input <a>DID URL</a></var> by executing the
<a>DID URL dereferencing</a> algorithm as defined in <a href="#dereferencing"></a></li>
<li>If the output of the <a>DID URL dereferencing</a> function contains the <b>dereferencingMetadata</b> property <b>error</b>,
then the HTTP response status code MUST be set to the value that corresponds to the value of the <b>error</b> property,
<li>For the <a>DID URL dereferencing</a> function:
<ol class="algorithm">
<li>Append the <var>input <a>DID URL</a></var> to the <var>request HTTP(S) URL</var>.</li>
<pre class="example nohighlight">https://dev.uniresolver.io/1.0/identifiers/did:example:1234?service=files&relativeRef=/resume.pdf</pre>
<li>Set the <code>Accept</code> <var>HTTP request header</var> to `application/ld+json;profile="https://w3id.org/did-url-dereferencing"`
in order to request a complete <a href="#did-url-dereferencing-result"></a>, OR</li>
<li>set the <code>Accept</code> <var>HTTP request header</var> to the value of the <b>accept</b> <var>dereferencing option</var>.</li>
<li>If any other <var>dereferencing options</var> are provided:
<ol class="algorithm">
<li>The <var>input <a>DID URL</a></var> MUST be URL-encoded (as specified in <a
data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>).</li>
<li>Encode all <var>dereferencing options</var> except <b>accept</b> as
query parameters in the <var>request HTTP(S) URL</var>.</li>
<pre class="example nohighlight">https://dev.uniresolver.io/1.0/identifiers/did%3Aexample%3A1234%3Fservice%3Dfiles%26relativeRef%3D%2Fresume.pdf?option1=value1&option2=value2</pre>
</ol>
</li>
</ol>
</li>
<li>Execute an HTTP <code>GET</code> request on the <var>request HTTP(S) URL</var>. This invokes the <a>DID resolution</a> or
<a>DID URL dereferencing</a> function at the remote <a>DID resolver</a>.</li>
<li>If the <a>DID resolution</a> or <a>DID URL dereferencing</a> function returns an <b>error</b> metadata property in the
<b>didResolutionMetadata</b> or <b>dereferencingMetadata</b>,
then the HTTP response status code MUST correspond to the value of the <b>error</b> metadata property,
according to the following table:
<table class="simple">
<thead>
Expand Down Expand Up @@ -1926,61 +1955,64 @@ <h2>HTTP(S) Binding</h2>
</tbody>
</table>
</li>
<li>If the output of the <a>DID URL dereferencing</a> function contains the <b>didDocumentMetadata</b> property <b>deactivated</b> with value <b>true</b>:
<li>If the <a>DID resolution</a> or <a>DID URL dereferencing</a> function returns a <b>deactivated</b> metadata property with
the value <code>true</code> in the <b>didDocumentMetadata</b> or <b>contentMetadata</b>:
<ol class="algorithm">
<li>The HTTP response status code MUST be <code>410</code>.</li>
</ol>
</li>
<li>If the output of the <a>DID URL dereferencing</a> function contains the <b>didDocumentStream</b>:
<li>For the <a>DID resolution</a> function:
<ol class="algorithm">
<li>If the value of the <code>Accept</code> HTTP header is absent or `application/did+ld+json` (or other media type of a conformant representation of a <a>DID document</a>):
<ol class="algorithm">
<li>The HTTP response status code MUST be <code>200</code>.</li>
<li>The HTTP response MUST contain a <code>Content-Type</code> header. The
value of this header MUST be `application/did+ld+json` (or other media type of a conformant representation of a <a>DID document</a>).</li>
<li>The HTTP response body MUST contain the <b>didDocumentStream</b>, in the representation corresponding to the <code>Accept</code> HTTP header.</li>
</ol>
<li>If the value of the <code>Content-Type</code> <var>HTTP response header</var> is `application/ld+json;profile="https://w3id.org/did-resolution"`:
<ol class="algorithm">
<li>The <var>HTTP body</var> MUST contain a <a>DID resolution result</a> (see <a href="#did-resolution-result"></a>) that
is the result of the <a>DID resolution</a> function.</li>
</ol>
</li>
<li>If the value of the <code>Accept</code> HTTP header is `application/ld+json;profile="https://w3id.org/did-resolution"`:
<ol class="algorithm">
<li>Produce a <a>DID resolution result</a> (see (see <a href="#did-resolution-result"></a>) and populate it with the <b>didDocumentStream</b>,
<b>didResolutionMetadata</b>, and <b>didDocumentMetadata</b> that are the output of the
<a>DID resolution</a> function.</li>
<li>The HTTP response status code MUST be <code>200</code>.</li>
<li>The HTTP response MUST contain a <code>Content-Type</code> header. The
value of this header MUST be `application/ld+json;profile="https://w3id.org/did-resolution"`.</li>
<li>The HTTP response body MUST contain the produced <a>DID resolution result</a>.</li>
</ol>
<li>If the function is successful and returns a <b>didDocument</b>:
<ol class="algorithm">
<li>The HTTP response status code MUST be <code>200</code>.</li>
<li>The HTTP response MUST contain a <code>Content-Type</code> <var>HTTP response header</var>. Its value MUST be the value of the
<b>contentType</b> metadata property in the <b>didResolutionMetadata</b> (see <a href="#did-resolution-metadata"></a>).</li>
<li>The HTTP response body MUST contain the <b>didDocument</b> that is the result of the
<a>DID resolution</a> function, in the representation corresponding to the <code>Content-Type</code> <var>HTTP response header</var>.</li>
</ol>
</li>
</ol>
</li>
<li>If the output of the <a>DID URL dereferencing</a> function is a <a>service endpoint</a> URL:
<ol class="algorithm">
<li>The HTTP response status code MUST be <code>303</code>.</li>
<li>The HTTP response MUST contain an <code>Location</code> header. The value of this header
MUST be the <var>output <a>service endpoint</a> URL</a></var>.</li>
</ol>
<li>For the <a>DID URL dereferencing</a> function:
<ol class="algorithm">
<li>If the value of the <code>Content-Type</code> <var>HTTP response header</var> is `application/ld+json;profile="https://w3id.org/did-url-dereferencing"`:
<ol class="algorithm">
<li>The <var>HTTP body</var> MUST contain a <a>DID URL dereferencing result</a> (see <a href="#did-url-dereferencing-result"></a>) that
is the result of the <a>DID URL dereferencing</a> function.</li>
</ol>
</li>
<li>If the function is successful and returns a <b>contentStream</b> and a <b>contentType</b> metadata property with the value <code>text/uri-list</code> in the <b>dereferencingMetadata</b>:
<ol class="algorithm">
<li>The HTTP response status code MUST be <code>303</code>.</li>
<li>The HTTP response MUST contain an <code>Location</code> header. The value of this header
MUST be the <var>output <a>service endpoint</a> URL</var>.</li>
<li>the HTTP response body MUST be empty.</li>
</ol>
</li>
<li>If the function is successful and returns a <b>contentStream</b> with any other <b>contentType</b>:
<ol class="algorithm">
<li>The HTTP response status code MUST be <code>200</code>.</li>
<li>The HTTP response MUST contain a <code>Content-Type</code> <var>HTTP response header</var>. Its value MUST be the value of the
<b>contentType</b> metadata property in the <b>dereferencingMetadata</b> (see <a href="#did-url-dereferencing-metadata"></a>).</li>
<li>The HTTP response body MUST contain the <b>contentStream</b> that is the result of the
<a>DID URL dereferencing</a> function, in the representation corresponding to the <code>Content-Type</code> <var>HTTP response header</var>.</li>
</ol>
</li>
</ol>
</li>
</ol>

<div>
<p>See <a href="https://github.com/decentralized-identity/universal-resolver/blob/main/openapi/openapi.yaml">here</a> for an OpenAPI definition.</p>
</div>

<div class="issue">
<p>TODO: Review HTTP(S) binding for <a>DID resolution</a> and <a>DID URL dereferencing</a>,
including the following topics:</p>
<ul>
<li>How are <var>resolution options</var> passed via HTTP(S)? Using the query string and/or HTTP headers?</li>
<li>How is the output data (<a>DID document</a>, <a>DID resolution result</a>) returned via HTTP(S)?</li>
<li>How should <code>Accept</code> and <code>Content-Type</code> HTTP headers be used? How are
the <code>resolve()</code> and <code>resolveRepresentation()</code> functions called? See <a href="https://github.com/w3c/did-core/issues/417">
this issue</a> for a discussion.</li>
<li>Are two separate HTTP(S) endpoints required/allowed for the <code>resolve()</code> and
<code>dereference()</code> functions, or can/must a single HTTP(S) endpoint be used?</li>
</ul>
</div>

</section>

<section>
Expand Down
Loading