[codex] Add verification relationship resolver

[moisesja]

Fixes #71

Summary

• add the VerificationRelationship public API and relationship-entry helpers for DID documents
• add IVerificationRelationshipResolver with a default resolver that checks whether a controller DID document authorizes a verification method for a requested W3C verification relationship
• wire the resolver into dependency injection and refactor DID URL dereferencing to share the relationship helper
• document the new authorization primitive in the PRD and changelog, with focused Core and did:key regression coverage

Validation

• dotnet test netdid.sln --no-restore (807 passed)

[moisesja]

Review — PR #74: Add verification relationship resolver

Overall this is solid work. The design is sound, the refactor of DefaultDidUrlDereferencer is behaviorally identical, and the tri-state result is the right call for security-critical code that needs to distinguish "infrastructure unavailable" from "controller said no." A few items worth discussing before merge:

---

1. CHANGELOG entry is too long

The [Unreleased] ### Added bullet is several hundred words — more like a design doc than a changelog entry. Consider trimming to 3–4 sentences covering what it does, why the heuristic it replaces is wrong, and which downstream issue it unblocks. The full rationale already lives in PRD §10.5 and the test file docstrings.

---

2. Undocumented input behavior when verificationMethodDidUrl is fragment-relative

NormalizeVmId is applied to both the entry id and the query verificationMethodDidUrl. If a caller passes "#k1" as the VM URL, normalization silently converts it to "{controllerDid}#k1" before the comparison. That's probably useful behaviour, but:

• The interface signature says the parameter is a "verification method DID URL" — the name implies an absolute form.
• ArgumentException.ThrowIfNullOrWhiteSpace guards null/whitespace but not relative forms.
• No test covers the case where the query (not the entry) is fragment-relative.

Recommend either: (a) add a test documenting this works, or (b) add a guard/note in the XML doc making the accepted forms explicit. Leaving it silent means a caller who accidentally passes "#k1" gets a result that may surprise them.

---

3. AuthorizationDecision, VerificationRelationshipAuthorizationResult, and IVerificationRelationshipResolver all in one file

Not wrong, but these are three distinct public API elements. Consumers browsing the public surface have to know to look in IVerificationRelationshipResolver.cs to find AuthorizationDecision. Splitting them into separate files (one type per file, matching the convention used everywhere else in NetDid.Core) would improve discoverability. Low priority if you'd rather do it at next touch.

---

What looks good

• Tri-state result — ControllerNotResolvable with ResolutionError propagated is the right fail-closed design.
• TryAddSingleton in DI — allows consumers to swap in their own implementation without fighting registration order.
• Behavior-identical dereferencer refactor — the string overload of GetRelationshipEntries returns null for unknown names just like the old private switch, and the if (verificationRelationship is not null) guard is preserved.
• Test coverage — all 10 acceptance cases from the plan have dedicated tests; the did:key regression suite locks the key-type/relationship contract end-to-end.
• No internal caching on the resolver — the right call; caching belongs at the IDidResolver layer.

Item 1 is easy to address before marking ready for review. Items 2 and 3 are lower-priority polish. Overall the implementation is correct and production-ready.

---

Generated by Claude Code