Implement W3C DID Resolution HTTPS Binding (v1)

[djscruggs]

What

• Implements the W3C DID Resolution HTTPS Binding (GET and POST /1.0/identifiers/{did})
• DID URL dereferencing: fragment (#key) and path, against the resolved DID document
• Supports did:key and did:web methods via @digitalbazaar/did-io
• RFC 9457 error objects with W3C DID namespace URIs in didResolutionMetadata
• Content negotiation: application/did (DID document), application/did-resolution (full result), and application/did-url-dereferencing (dereferencing result, dereferencing only), with wildcard/empty Accept defaulting to application/did
• Deactivated DID handling: 410 + null document + deactivated: true in metadata
• Health check at GET /health

Service endpoint dereferencing (?service=) is intentionally not supported.
Resolving caller-supplied service endpoints would turn the server into an
outbound HTTP request engine — an SSRF and DDoS-amplification surface. Requests
including ?service= (unencoded or percent-encoded) are rejected explicitly
with 501 Not Implemented. Callers that need a service endpoint should read it
from the resolved DID document directly. relativeRef is dropped along with it
(and is expected to be removed from DID Resolution v1.0). Removed in 4630197
per @msporny's review.

Spec conformance

All 35 tests in w3c-ccg/did-resolution-mocha-test-suite pass:

Requirement	Status
GET /1.0/identifiers/{did} binding	✅
POST /1.0/identifiers/{did} binding	✅
Resolution result shape	✅
Content-Type header matches didResolutionMetadata.contentType	✅
RFC 9457 error objects with W3C DID namespace URIs	✅
INVALID_DID + 400	✅
NOT_FOUND + 404	✅
METHOD_NOT_SUPPORTED + 501	✅
REPRESENTATION_NOT_SUPPORTED + 406 (conformant result shape)	✅
Deactivated DID → 410 + null document	✅
DID URL dereferencing result shape (fragment / path)	✅
application/did-url-dereferencing → dereferencing result envelope + 200	✅
Content-Type header matches dereferencingMetadata.contentType	✅
Service endpoint dereferencing (?service=)	❌ Intentionally unsupported (SSRF/DDoS surface); rejected with 501

Error handling: did-io typed errors

Driver-not-found classification now relies on a typed error from
@digitalbazaar/did-io rather than parsing error message strings:

• Bumped @digitalbazaar/did-io to ^2.2.0, which sets
  err.name = 'NotSupportedError' when no driver is registered for a DID
  method (did-io#70).
• classifyError now checks e.name === 'NotSupportedError' instead of the
  brittle e.message.includes('Driver') && ...('not found') substring match,
  so it no longer breaks if did-io reworded the message.
• This is the path that produces METHOD_NOT_SUPPORTED + 501 for unsupported
  DID methods.

PR review changes addressed

• Removed service endpoint dereferencing (?service=) and relativeRef to close the SSRF / DDoS-amplification surface (per @msporny)
• Renamed workflow file to .yaml; upgraded to actions/checkout@v6, actions/setup-node@v6
• Removed serial job dependency (lint and test now run in parallel)
• Added Node.js 26.x to test matrix (required upgrading mocha 10 → 11 for ESM compat)
• src/ → lib/ per DB convention
• Package version set to 0.0.1-0
• Added LICENSE file (BSD-3-Clause)
• Switched eslint config to node-recommended preset
• Copyright year updated to 2026 across all files
• Fixed all JSDoc @returns declarations and description sentences

Second review round

• Removed double percent-decoding: Express already decodes wildcard params, so the manual decodeURIComponent calls corrupted identifiers containing literal percent characters
• Added a JSON error middleware: malformed percent-encoding in the path and malformed JSON POST bodies now return JSON 400 instead of Express's HTML error page (5xx responses return a generic message — no internal details leaked)
• ?service= is now rejected explicitly with 501 instead of being silently ignored (previously the unencoded form resolved the bare DID as if no query were present)
• Remote 4xx during did:web resolution (401/403/429) now classifies as NOT_FOUND instead of INVALID_DID — the DID may be valid even when the host rejects the request
• didResolutionMetadata.contentType now matches the Content-Type header on dereferencing responses
• Restored the application/did-url-dereferencing media type, which had been removed alongside service dereferencing in 4630197 although it is a response format only (a local lookup in the already-resolved document — no outbound request surface). Dereferencing returns the spec envelope (dereferencingMetadata, contentStream, contentMetadata) for that Accept type; this brings the W3C suite back from 33/35 to 35/35

Testing

• npm test passes on Node 22, 24, 26 (CI green)
• Resolution + fragment/path dereferencing tests pass locally (27 passing, 2 pending live-network)
• npm run lint passes with 0 errors, 0 warnings
• W3C did-resolution-mocha-test-suite: 35/35 passing against the local server

Verifying conformance locally

# 1. Start this server
node lib/index.js

# 2. In another terminal — clone and run the suite
git clone https://github.com/w3c-ccg/did-resolution-mocha-test-suite
cd did-resolution-mocha-test-suite
npm install
npm test

The suite needs a localConfig.cjs in its root to point at this server.
Create it with:

const TEST_DID_KEY =
  'did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH';
const TEST_KEY_FRAGMENT = encodeURIComponent(
  `${TEST_DID_KEY}#${TEST_DID_KEY.slice('did:key:'.length)}`);

module.exports = {
  settings: {enableInteropTests: false, testAllImplementations: false},
  implementations: [{
    name: 'digitalbazaar/did-resolver',
    implementation: 'did-resolver (local)',
    didResolvers: [{
      id: 'digitalbazaar/did-resolver',
      endpoint: 'http://localhost:8080/1.0/identifiers',
      tags: ['did-resolution'],
      supportedDids: {
        valid: [{did: TEST_DID_KEY, resolutionOptions: {}}],
        notFound: 'did:web:does-not-exist.example.invalid',
        derefUrls: [{didUrl: TEST_KEY_FRAGMENT, dereferencingOptions: {}}]
      }
    }]
  }]
};

🤖 Generated with Claude Code
Co-Authored-By: Claude Sonnet 4.6 noreply@anthropic.com

[davidlehn]

Adding some basic updates, didn't get to the meat of it.

• All the copyright dates should be updated.
• In general we've used ./lib/ rather than ./src/. Mostly for historical reasons. (Honestly, I'd use ./src/ these days otherwise.) Not sure if it matters other than convention.

[msporny]

Partial, high-level review (have not looked at the code yet):

• DID URL dereferencing: fragment (#key), service endpoint (?service=), relativeRef

relativeRef is likely to be removed in v1.0. We should probably drop support for it eventually (next month or two).

Content negotiation: application/did-resolution, application/did-url-dereferencing, application/did+ld+json, text/uri-list

Do not support did-url-dereferencing, it's an attack vector that can DDoS a server (fetch these 50GB files for me).

application/did+ld+json is the wrong media type... should be application/did

text/uri-list is being removed

303 redirect with empty body for text/uri-list (spec-required)

This should be removed as a feature.

[djscruggs]

All feedback addressed in commit e81371c:

• Removed application/did-url-dereferencing and text/uri-list support entirely
• Removed relativeRef support
• Changed DID Document media type to application/did
• errors.js: merged two maps into one, rewrote classifyError to use e.status and instanceof TypeError before message parsing
• Filed INTERNAL_ERROR not defined in W3C DID vocabulary w3c/did-resolution#337 for the missing INTERNAL_ERROR vocabulary entry
• CI: lint job fixed at Node 22.x (no matrix), jobs run in parallel

[djscruggs]

From @msporny

relativeRef is likely to be removed in v1.0. We should probably drop support for it eventually (next month or two).
...
Do not support did-url-dereferencing, it's an attack vector that can DDoS a server (fetch these 50GB files for me).

Fixed both in the latest commit, now explicitly mentioned in the PR - see PR review changes addressed