feat!: did-resolver interface + spec-conformant query parameters (#89, #130) by brianorwhatever · Pull Request #4 · aviarytech/didwebvh-ts

brianorwhatever · 2026-06-25T06:51:28Z

Summary

Adopts the standard W3C did-resolver interface and settles the open query-parameter questions. Breaking change — major version bump to 3.0.0.

Resolves decentralized-identity#89 (support did-resolver interface) and decentralized-identity#130 (query parameter support).

What changed

resolveDID / resolveDIDFromLog return the standard resolution shape { didResolutionMetadata, didDocument, didDocumentMetadata } — a clean break from { did, doc, meta, controlled }. They no longer throw on failure; errors come back as a result with didDocument: null and a standard error code.
New getResolver(config?) returns { webvh: DIDResolver }, registrable in a did-resolver Resolver — did:webvh is now a drop-in alongside did:web, did:ethr, etc. Works zero-config via a built-in defaultVerifier (Ed25519), overridable with getResolver({ verifier }).
verificationMethod resolution removed entirely — implementation-specific, not in any spec, and a footgun (returned a historical document version).
Resolution selectors are mutually exclusive — at most one of versionId / versionTime / versionNumber; any combination returns invalidDidUrl.
Both v1.0 and v0.5 map to the standard shape via a single mapping layer; internal updateDID/deactivateDID keep using the rich per-version core resolver unchanged.

New modules

src/verifier.ts — defaultVerifier (Ed25519 via @stablelib/ed25519).
src/resolver-result.ts — pure mapping (toResolutionResult, toErrorResult, assertSingleVersionSelector, mapErrorToCode, InvalidDidUrlError) + result types.
src/resolver.ts — getResolver(); parses DID-URL query params, enforces selector rules, returns DIDResolutionResult.

Implementation note

did-resolver exposes ?-query parameters as the raw, undecoded parsed.query string (only ;-matrix params populate parsed.params). Since the did:webvh spec uses ? query parameters, getResolver parses parsed.query itself. It decodes per RFC 3986 (decodeURIComponent, + is literal) rather than URLSearchParams (form-encoding, + → space) so a versionTime with a +HH:MM timezone offset isn't corrupted.

Testing

New unit tests: defaultVerifier, the mapping layer, and the mutual-exclusivity guard.
New integration test: getResolver() in a real did-resolver Resolver — fresh DID, ?versionId/?versionNumber/?versionTime, selector-combination → invalidDidUrl, not-found, deactivated, zero-config.
Migrated the full existing suite to the standard shape; deleted the obsolete verificationMethod resolution tests.

Gates (all green locally)

bun test — 273 pass / 0 fail
bunx biome ci . — clean
bun run check — clean
bun run build — succeeds

🤖 Generated with Claude Code

Note

Implement W3C did-resolver interface and spec-conformant query parameters for did:webvh

resolveDID and resolveDIDFromLog now return DIDResolutionResult (with didDocument, didDocumentMetadata, didResolutionMetadata) instead of a custom { did, doc, meta } shape; errors are reported via didResolutionMetadata.error rather than thrown exceptions.
Adds src/resolver.ts with a getResolver factory for registering did:webvh with the did-resolver library, including robust RFC 3986 decoding of version selector query parameters (versionId, versionTime, versionNumber).
Adds src/resolver-result.ts with helpers toResolutionResult, toErrorResult, mapErrorToCode, and assertSingleVersionSelector; standardized error codes include invalidDid, invalidDidUrl, notFound, and internalError.
Adds src/verifier.ts with defaultVerifier, a built-in Ed25519 verifier used automatically when callers omit a verifier option.
Removes verificationMethod as a resolution selector from both v0.5 and v1.0 method implementations and from ResolutionOptions.
Risk: breaking change (v3.0.0) — all callers must switch from { did, doc, meta } destructuring to DIDResolutionResult fields and from catching thrown errors to checking didResolutionMetadata.error.

^{Macroscope summarized 5e08585.}

…hape - delete removed verificationMethod resolution tests - convert resolution-failure assertions from throws to error results - add getResolver integration + resolver-result/verifier unit tests - apply biome formatting

…n shape

URLSearchParams applies application/x-www-form-urlencoded rules where '+' decodes to a space. A DID URL query is a URI component (RFC 3986) where '+' is literal, so a versionTime with a +HH:MM timezone offset was corrupted into an Invalid Date. Parse the query manually with decodeURIComponent instead.

brianorwhatever · 2026-06-25T07:16:04Z

@macroscope review

macroscopeapp · 2026-06-25T07:16:19Z

Manual reviews triggered for commit 5e08585:

^{All prior checks · these links stay valid even if you push more commits.}

macroscopeapp · 2026-06-25T07:16:25Z

Just FYI for future @mentions, I'm Macroscope-App, not Macroscope.

Review in progress. Results will be posted as check runs when complete.

macroscopeapp · 2026-06-25T07:25:48Z

Approvability

Verdict: Needs human review

1 blocking correctness issue found. Major version bump (v3.0.0) introducing W3C did-resolver interface integration with breaking API changes. New feature capabilities and an unresolved review comment about incorrect handling of DID URL paths/fragments warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}

- resolver.ts: reject NaN versionNumber / Invalid Date versionTime as invalidDidUrl - resolver-result.ts: tighten mapErrorToCode so validation errors embedding '404'/'not found' (attacker-controlled log data) aren't misclassified as notFound; only genuine log-fetch absence maps to notFound - cli.ts: surface resolution errors in update/deactivate instead of TypeError on meta.updateKeys - examples: return the resolution error before file-serving fallback (avoid https:/// fetch) - tests: cover the new validation paths; reclassify invalid-update-key read as invalidDid

brianorwhatever · 2026-06-25T07:33:21Z

@macroscope-app review

macroscopeapp · 2026-06-25T07:33:42Z

Review in progress. Results will be posted as check runs when complete.

- resolver-result.ts: preserve a valid earlier document when returned alongside a warning-level error (e.g. explicit version selector resolves while a later entry fails witness verification) instead of dropping it - resolver-result.ts: toErrorResult now synthesizes RFC9457 problemDetails (type/title/detail) so fetch/validation/invalidDidUrl errors keep structured error info - cli.ts: resolve a deactivated DID's identifier from the log instead of printing an empty id - tests: cover preserved-doc and problemDetails behavior

brianorwhatever · 2026-06-25T07:59:05Z

@macroscope-app review

macroscopeapp · 2026-06-25T07:59:26Z

Review in progress. Results will be posted as check runs when complete.

macroscopeapp · 2026-06-25T08:06:38Z

+    }
+
+    // parsed.did is the bare DID without query/fragment.
+    return resolveDID(parsed.did, selector);


🟡 Medium src/resolver.ts:79

getResolver() ignores parsed.path and parsed.fragment when building the selector, so DID URLs with paths or fragments (e.g., did:webvh:...#key-1) return the full DID document instead of the dereferenced resource. did-resolver passes these components to method resolvers specifically for dereferencing, so discarding them produces incorrect results for valid inputs.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @src/resolver.ts around line 79: `getResolver()` ignores `parsed.path` and `parsed.fragment` when building the selector, so DID URLs with paths or fragments (e.g., `did:webvh:...#key-1`) return the full DID document instead of the dereferenced resource. `did-resolver` passes these components to method resolvers specifically for dereferencing, so discarding them produces incorrect results for valid inputs.

Intentionally not changing this. Per the W3C DID spec, resolve() returns the DID document; dereferencing a path/fragment to a specific resource is a separate operation (dereferenceURL). did-resolver method resolvers (did:web, did:ethr, …) all return the full DID document and leave fragment/path handling to the caller — so discarding parsed.path/parsed.fragment here is the correct, standard behavior. did:webvh file/path dereferencing is handled separately by the resolver servers (see the /resolve/:id/* routes in the examples).

- resolver-result.ts: add 'internalError' code; classify 5xx/network/transport failures as internalError instead of invalidDid (document-validation errors stay invalidDid). Synthesize problemDetails for it too. - examples/express-resolver.ts: map resolution error codes to HTTP status (notFound->404, invalid*->400, internalError->500) instead of a blanket 400. - tests: cover internalError classification; update network-failure expectation.

brianorwhatever · 2026-06-25T08:13:04Z

@macroscope-app review

macroscopeapp · 2026-06-25T08:13:31Z

Review in progress. Results will be posted as check runs when complete.

…rning error Only bail on resolution error when didDocument is null; a valid earlier version can be returned alongside warning-level error metadata (consistent with toResolutionResult preserving the doc).

brianorwhatever · 2026-06-25T08:23:43Z

@macroscope-app review

macroscopeapp · 2026-06-25T08:24:03Z

Review in progress. Results will be posted as check runs when complete.

A valid DID served from an unauthorized (401/403), gone (410), rate-limited (429), or failing (5xx) endpoint is a resolver-side internal error, not a document-validation failure. 404/empty-log stay notFound; document-validation errors stay invalidDid.

brianorwhatever · 2026-06-25T08:35:03Z

@macroscope-app review

macroscopeapp · 2026-06-25T08:35:28Z

Review in progress. Results will be posted as check runs when complete.

brianorwhatever · 2026-06-25T09:32:38Z

Superseded by the upstream PR at decentralized-identity#138 (same branch, rebased onto current DIF main). Closing in favor of that one.

brianorwhatever closed this Jun 25, 2026

brianorwhatever reopened this Jun 25, 2026

brianorwhatever added 12 commits June 25, 2026 00:10

build: add did-resolver dep, promote ed25519, bump to 3.0.0

b4200fc

feat: add built-in default Ed25519 verifier

a9b0a60

feat: add resolution-result mapping layer and types

5b3c12e

refactor: remove verificationMethod resolution from v1.0 and v0.5 cores

d3fee9a

feat!: resolveDID/resolveDIDFromLog return standard DIDResolutionResult

148a282

feat: add getResolver() for the did-resolver interface

d994fa4

feat: export getResolver, defaultVerifier, and result types

cef9a8c

refactor: update CLI to standard resolution shape

a36dd12

docs: update example resolvers to standard resolution shape

67b0c5e

docs: document did-resolver interface, getResolver, and new resolutio…

bd5d679

…n shape

brianorwhatever force-pushed the design/did-resolver-query-params branch from 71d3b8c to c340fc0 Compare June 25, 2026 07:11

macroscopeapp Bot reviewed Jun 25, 2026

View reviewed changes

Comment thread src/cli.ts

Comment thread src/resolver.ts

Comment thread examples/express-resolver.ts

Comment thread src/resolver-result.ts

macroscopeapp Bot reviewed Jun 25, 2026

View reviewed changes

Comment thread src/resolver-result.ts Outdated

Comment thread src/resolver-result.ts

Comment thread src/cli.ts

style: format resolver-result test (biome)

00d84c0

macroscopeapp Bot reviewed Jun 25, 2026

View reviewed changes

Comment thread examples/elysia-resolver.ts Outdated

fix: example resolvers serve files when a usable doc accompanies a wa…

58aa1ab

…rning error Only bail on resolution error when didDocument is null; a valid earlier version can be returned alongside warning-level error metadata (consistent with toResolutionResult preserving the doc).

macroscopeapp Bot reviewed Jun 25, 2026

View reviewed changes

Comment thread src/resolver-result.ts

brianorwhatever closed this Jun 25, 2026

Uh oh!

Conversation

brianorwhatever commented Jun 25, 2026 • edited by macroscopeapp Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

New modules

Implementation note

Testing

Gates (all green locally)

Implement W3C did-resolver interface and spec-conformant query parameters for did:webvh

Uh oh!

brianorwhatever commented Jun 25, 2026

Uh oh!

macroscopeapp Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

macroscopeapp Bot commented Jun 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

macroscopeapp Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approvability

Uh oh!

brianorwhatever commented Jun 25, 2026

Uh oh!

macroscopeapp Bot commented Jun 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brianorwhatever commented Jun 25, 2026

Uh oh!

macroscopeapp Bot commented Jun 25, 2026

Uh oh!

Uh oh!

macroscopeapp Bot Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

brianorwhatever Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

brianorwhatever commented Jun 25, 2026

Uh oh!

macroscopeapp Bot commented Jun 25, 2026

Uh oh!

Uh oh!

brianorwhatever commented Jun 25, 2026

Uh oh!

macroscopeapp Bot commented Jun 25, 2026

Uh oh!

Uh oh!

brianorwhatever commented Jun 25, 2026

Uh oh!

macroscopeapp Bot commented Jun 25, 2026

Uh oh!

brianorwhatever commented Jun 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

brianorwhatever commented Jun 25, 2026 •

edited by macroscopeapp Bot

Loading

macroscopeapp Bot commented Jun 25, 2026 •

edited

Loading

macroscopeapp Bot commented Jun 25, 2026 •

edited

Loading