Implement W3C DID Resolution HTTPS Binding (v1)

.env.example

@@ -0,0 +1,5 @@
+# Port the server listens on
+PORT=8080
+
+# Host the server binds to
+HOST=0.0.0.0

.github/workflows/main.yaml

@@ -0,0 +1,34 @@
+name: Node.js CI
+
+on: [push, pull_request]
+
+permissions: {}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - name: Use Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22.x
+      - run: npm install
+      - name: Run eslint
+        run: npm run lint
+  test-node:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        node-version: [22.x, 24.x, 26.x]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - name: Run tests with Node.js ${{ matrix.node-version }}
+        run: npm test

.gitignore

@@ -1,2 +1,9 @@
 SPEC.md
 ARCHITECTURE.md
+CLAUDE.md
+SMELLS*.md
+.env
+node_modules/
+dist/
+coverage/
+.fastembed_cache/

LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026 Digital Bazaar, Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -16,7 +16,7 @@ object that describes the entity: its public keys, authentication methods, and s
 endpoints.
 
 This server exposes a single HTTP endpoint that accepts a DID (or DID URL), resolves
-it to a DID Document using [`did-io`](https://github.com/digitalbazaar/did-io), and
+it to a DID Document using [`@digitalbazaar/did-io`](https://github.com/digitalbazaar/did-io), and
 returns the result in the format the client requests.
 
 ```
@@ -27,7 +27,7 @@ Client                        did-resolver                     did-io
   |                               |                               |-- driver lookup
   |                               |                               |-- fetch/derive doc
   |                               |<-- DID Document --------------|
-  |<-- 200 application/did+ld+json|
+  |<-- 200 application/did ------|
 ```
 
 ### Endpoints
@@ -46,7 +46,7 @@ POST /1.0/identifiers/{did}
 
 | Accept Header | Response |
 |---|---|
-| `application/did+ld+json` | DID Document only |
+| `application/did` | DID Document only |
 | `application/did-resolution` | Full result: document + resolution metadata + document metadata |
 | _(default)_ | DID Document only |
 
@@ -58,14 +58,19 @@ GET /1.0/identifiers/{did-url}
 
 A DID URL extends a DID with a path, query, or fragment:
 - `did:key:z6Mk...#key-1` → returns a specific verification method
-- `did:web:example.com/user/alice?service=files` → follows the service endpoint
+
+Service endpoint dereferencing (`?service=`) is intentionally not supported:
+resolving caller-supplied endpoints would turn the server into an outbound
+HTTP request engine (SSRF / DDoS amplification surface). Requests including
+`?service=` are rejected with `501 Not Implemented`. Read the service
+endpoint from the resolved DID document directly instead.
 
 **Response formats** (controlled by `Accept` header):
 
 | Accept Header | Response |
 |---|---|
-| `application/did-url-dereferencing` | Full result: content + dereferencing metadata |
-| `text/uri-list` | HTTP 303 redirect to the resource URL |
+| `application/did-url-dereferencing` | Dereferencing result: `dereferencingMetadata` + `contentStream` + `contentMetadata` |
+| `application/did-resolution` | Full result: content + resolution metadata |
 | _(default)_ | The dereferenced resource directly |
 
 ### HTTP Status Codes
@@ -82,6 +87,38 @@ Per the [DID Resolution spec](https://w3c.github.io/did-resolution/#bindings-htt
 | Internal resolver error | `500 Internal Server Error` |
 | DID method not supported | `501 Not Implemented` |
 
+### Error Format
+
+When `Accept: application/did-resolution` is requested, error responses are
+conformant resolution results with an RFC 9457-style error object in
+`didResolutionMetadata`:
+
+```json
+{
+  "@context": "https://w3id.org/did-resolution/v1",
+  "didDocument": null,
+  "didDocumentMetadata": {},
+  "didResolutionMetadata": {
+    "error": {
+      "type": "https://www.w3.org/ns/did#METHOD_NOT_SUPPORTED"
+    }
+  }
+}
+```
+
+Error type URIs follow the W3C DID namespace:
+`https://www.w3.org/ns/did#INVALID_DID`, `#NOT_FOUND`, `#METHOD_NOT_SUPPORTED`,
+`#REPRESENTATION_NOT_SUPPORTED`, `#INTERNAL_ERROR`, etc.
+
+### Deactivated DIDs
+
+If a resolved DID document contains `"deactivated": true`, the server returns
+`410 Gone` with a null `didDocument` and `"deactivated": true` in
+`didDocumentMetadata`. Neither `did:key` nor `did:web` support deactivation
+(both are static/derived methods with no registry). Ledger-based methods such
+as `did:veres-one` or `did:ion` do — register such a driver to exercise this
+path.
+
 ### Supported DID Methods
 
 | Method | Description |
@@ -95,7 +132,7 @@ Additional methods can be added by registering a driver with the `CachedResolver
 ### Architecture
 
 ```
-src/
+lib/
 ├── index.js          # Entry point — wires server + resolver
 ├── server.js         # HTTP server, route registration
 ├── resolver.js       # did-io CachedResolver instance
@@ -110,8 +147,8 @@ src/
     └── headers.js    # Content-Type helpers
 ```
 
-The server is built on Node.js with no framework dependencies beyond what's needed for
-routing. It uses the DB-standard ESM module format throughout.
+The server uses [Express](https://expressjs.com/) for routing and the DB-standard
+ESM module format throughout.
 
 **Resolution flow:**
 
@@ -132,17 +169,17 @@ npm install
 
 ```bash
 # Start the server (default port 8080)
-node src/index.js
+node lib/index.js
 
 # Resolve a DID
-curl https://localhost:8080/1.0/identifiers/did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
+curl http://localhost:8080/1.0/identifiers/did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH
 
 # Get full resolution result
 curl -H "Accept: application/did-resolution" \
-  https://localhost:8080/1.0/identifiers/did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
+  http://localhost:8080/1.0/identifiers/did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH
 
-# Dereference a DID URL (specific verification method)
-curl https://localhost:8080/1.0/identifiers/did:key:z6Mk...%23key-1
+# Dereference a DID URL fragment (specific verification method)
+curl http://localhost:8080/1.0/identifiers/did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH%23z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH
 ```
 
 ## Configuration
@@ -159,15 +196,26 @@ curl https://localhost:8080/1.0/identifiers/did:key:z6Mk...%23key-1
    npm install @digitalbazaar/did-method-example
    ```
 
-2. Create `src/drivers/example.js`:
+2. Create `lib/drivers/example.js`:
+   ```js
+   import {driver} from '@digitalbazaar/did-method-example';
+
+   export const exampleDriver = driver();
+   ```
+   If the method uses multikey cryptography, also register the key suite:
    ```js
-   import * as ExampleDriver from '@digitalbazaar/did-method-example';
-   export const driver = ExampleDriver.driver();
+   import {Ed25519VerificationKey2020} from
+     '@digitalbazaar/ed25519-verification-key-2020';
+
+   exampleDriver.use({
+     multibaseMultikeyHeader: 'z6Mk',
+     fromMultibase: Ed25519VerificationKey2020.from
+   });
    ```
 
-3. Register it in `src/resolver.js`:
+3. Register it in `lib/resolver.js`:
    ```js
-   import {driver as exampleDriver} from './drivers/example.js';
+   import {exampleDriver} from './drivers/example.js';
    resolver.use(exampleDriver);
    ```
 
@@ -180,11 +228,33 @@ npm test       # Run test suite
 npm run lint   # Lint with @digitalbazaar/eslint-config
 ```
 
+## Spec Conformance
+
+All 35 tests in the
+[w3c-ccg/did-resolution-mocha-test-suite](https://github.com/w3c-ccg/did-resolution-mocha-test-suite)
+pass against this implementation.
+
+| Requirement | Status |
+|---|---|
+| `GET /1.0/identifiers/{did}` binding | ✅ |
+| `POST /1.0/identifiers/{did}` binding | ✅ |
+| Resolution result shape (`didDocument`, `didResolutionMetadata`, `didDocumentMetadata`) | ✅ |
+| `didResolutionMetadata.contentType` present on success | ✅ |
+| `Content-Type` header matches `didResolutionMetadata.contentType` | ✅ |
+| RFC 9457 error objects with W3C DID namespace URIs | ✅ |
+| `INVALID_DID` + 400 for malformed DID input | ✅ |
+| `NOT_FOUND` + 404 | ✅ |
+| `METHOD_NOT_SUPPORTED` + 501 | ✅ |
+| `REPRESENTATION_NOT_SUPPORTED` + 406 | ✅ |
+| Deactivated DID → 410 + null document | ✅ (requires a method that supports deactivation) |
+| DID URL dereferencing result shape | ✅ |
+
 ## Spec References
 
 - [W3C DID Resolution](https://w3c.github.io/did-resolution/)
 - [HTTPS Binding](https://w3c.github.io/did-resolution/#bindings-https)
-- [did-io](https://github.com/digitalbazaar/did-io)
+- [DID Resolution Mocha Test Suite](https://github.com/w3c-ccg/did-resolution-mocha-test-suite)
+- [@digitalbazaar/did-io](https://github.com/digitalbazaar/did-io)
 - [Danube Tech Universal Resolver](https://github.com/decentralized-identity/universal-resolver) (reference implementation)
 
 ## License

eslint.config.js

@@ -0,0 +1,22 @@
+/*!
+ * Copyright (c) 2026 Digital Bazaar, Inc.
+ */
+import config from '@digitalbazaar/eslint-config/node-recommended';
+
+export default [
+  ...config,
+  {
+    // Mocha test globals
+    files: ['test/**/*.js'],
+    languageOptions: {
+      globals: {
+        before: 'readonly',
+        after: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        describe: 'readonly',
+        it: 'readonly'
+      }
+    }
+  }
+];

lib/drivers/key.js

@@ -0,0 +1,14 @@
+/*!
+ * Copyright (c) 2026 Digital Bazaar, Inc.
+ */
+import {driver} from '@digitalbazaar/did-method-key';
+import {Ed25519VerificationKey2020} from
+  '@digitalbazaar/ed25519-verification-key-2020';
+
+export const keyDriver = driver();
+
+// Register the Ed25519 2020 suite so z6Mk... keys can be resolved.
+keyDriver.use({
+  multibaseMultikeyHeader: 'z6Mk',
+  fromMultibase: Ed25519VerificationKey2020.from
+});

lib/drivers/web.js

@@ -0,0 +1,15 @@
+/*!
+ * Copyright (c) 2026 Digital Bazaar, Inc.
+ */
+import {driver} from '@digitalbazaar/did-method-web';
+import {Ed25519VerificationKey2020} from
+  '@digitalbazaar/ed25519-verification-key-2020';
+
+export const webDriver = driver();
+
+// Register the Ed25519 2020 suite so z6Mk... keys in did:web documents
+// can be resolved to their full key material.
+webDriver.use({
+  multibaseMultikeyHeader: 'z6Mk',
+  fromMultibase: Ed25519VerificationKey2020.from
+});