Repository navigation
net: bind verifications and registrations to the subject's address and key; verified senders only - #1036
net: bind verifications and registrations to the subject's address and key; verified senders only#1036samlown wants to merge 21 commits into
Conversation
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #1036 +/- ##
==========================================
+ Coverage 96.93% 96.98% +0.04%
==========================================
Files 336 336
Lines 15422 15666 +244
==========================================
+ Hits 14949 15193 +244
Misses 472 472
Partials 1 1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
🟡 Changes recommended
A critical active issue allows verifier countersignatures without a bound subject key to be accepted, potentially reporting unverified authorities as verified.
1 open issue
What changed in this PR
This pull request hardens GOBL Net identity verification by binding registrations and verifications to both subject addresses and keys, enforcing signature freshness, and reducing network and key-fetch attack surfaces.
Changes:
- Adds address- and key-bound registration and verification checks, key-lineage helpers, and delivered-envelope validation.
- Enforces signature timestamps, expiry, retired-key handling, per-issuer limits, and DNS-rebinding-resistant dialing.
- Adds confirmation and JWK thumbprint support across
head,dsig, tests, documentation, and release notes.
| File | Description |
|---|---|
| net/who.go | Updates sender verification to validate delivered envelopes and registered sender keys. |
| net/who_test.go | Tests key-bound deliveries, client identity requirements, and recipient validation. |
| net/verify.go | Adds delivery-key extraction, freshness and key-validity checks, and issuer candidate limits. |
| net/verify_test.go | Covers key rotation, timestamp validation, retired keys, and signature-fetch limits. |
| net/README.md | Documents address and key binding, freshness, key lineage, and protocol hardening. |
| net/net.go | Updates package documentation for the revised sender-verification and lineage APIs. |
| net/client.go | Makes HTTP dialing use previously validated IP addresses to mitigate DNS rebinding. |
| net/authorities.go | Adds registration claim validation, key-bound endorsements, verification lookup, and lineage support. |
| net/authorities_test.go | Tests registration constraints, verifier audiences, key binding, and verification lookup. |
| head/header.go | Adds RFC 7800 confirmation claims and the WithConfirmation signing option. |
| head/header_test.go | Tests serialization and parsing of confirmation claims. |
| dsig/key.go | Adds RFC 7638 base64url JWK thumbprint helpers. |
| dsig/key_test.go | Tests JKT formatting and consistency between private and public keys. |
| changes/unreleased/net-verifier-audience.md | Records the breaking changes and security hardening. |
Review effort: Lite
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Copilot review overview
7 open issues
The per-issuer cap is enforced bybreaking aftermaxIssuerCandidatesmatching payloads, which… · New Reject verifier countersignatures missing subject-key confirmation The doc comment refers todsig.PublicKey’sThumbprint, but this option is wired tocnf.jkt… · New The returned error wrapsErrUnavailablebut does not wraplastErr(uses%v), so callers lose… · NewcheckIssuedandpub.Allows(...)compute specific failure reasons, butpairKeysdrops them and… · NewcheckIssuedandpub.Allows(...)compute specific failure reasons, butpairKeysdrops them and… · NewcheckIssuedandpub.Allows(...)compute specific failure reasons, butpairKeysdrops them and… · New
Review effort: Lite
…ctly Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
🟡 Changes recommended
A critical active issue remains because overlapping verifier and authority addresses can let a registration-only envelope bypass the requirement for an independently named verifier.
7 open issues
Exclude authorities from direct verifier evidence · New The per-issuer cap is enforced bybreaking aftermaxIssuerCandidatesmatching payloads, which…checkIssuedandpub.Allows(...)compute specific failure reasons, butpairKeysdrops them and…checkIssuedandpub.Allows(...)compute specific failure reasons, butpairKeysdrops them and…checkIssuedandpub.Allows(...)compute specific failure reasons, butpairKeysdrops them and… The returned error wrapsErrUnavailablebut does not wraplastErr(uses%v), so callers lose… The doc comment refers todsig.PublicKey’sThumbprint, but this option is wired tocnf.jkt…
1 resolved since last review
Review effort: Lite
Keep the reason the last delivery signature failed, wrap dial errors, and document the cnf thumbprint encoding. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
🔵 Needs a closer look
A critical active finding remains in net/authorities.go because overlapping authority and verifier configuration can accept an authority’s own registration countersignature as independent verification, bypassing the required trust-role separation.
2 open issues
5 resolved since last review
checkIssuedandpub.Allows(...)compute specific failure reasons, butpairKeysdrops them and…checkIssuedandpub.Allows(...)compute specific failure reasons, butpairKeysdrops them and…checkIssuedandpub.Allows(...)compute specific failure reasons, butpairKeysdrops them and… The returned error wrapsErrUnavailablebut does not wraplastErr(uses%v), so callers lose… The doc comment refers todsig.PublicKey’sThumbprint, but this option is wired tocnf.jkt…
Review effort: Lite
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refuse shared, reserved, benchmarking and NAT64 addresses when fetching, never count a registration countersignature as a verification, and state that a directly trusted bound key counts while the subject publishes it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add the documentation, 6to4, Teredo, discard and segment routing ranges from the IANA special-purpose registries to the fetcher's address guard. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
| var nonPublicNets = func() []*stdnet.IPNet { | ||
| cidrs := []string{ | ||
| "0.0.0.0/8", // this network (RFC 791) | ||
| "100.64.0.0/10", // shared address space (RFC 6598) | ||
| "192.0.0.0/24", // IETF protocol assignments (RFC 6890) |
In a key change the current key's confirming signature names the new key with cnf, and authorities count only confirming signatures made within MaxRequestAge, so an earlier request cannot be replayed to bind another key. DeliveryConfirmations reports each confirming signature's signing time and cnf. HTTPFetcher follows no redirects, which could move a key fetch, a request token or a delivery to plain HTTP. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Registration requests count only confirming signatures made within the last 5 minutes, and a key change needs the current key's signature to name the new key with cnf, so a replayed request cannot move a lineage to another key. Deliveries follow no redirects and refuse every address that is not globally reachable. Uses gobl from invopop/gobl#1036. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
§7.3 starts from what a subject does: renew, change key, or start over. A first registration takes one key, and a key bound before can no longer start a new lineage, which let a retired key take an address back. SignKeyChange signs a key change with the current key naming the next. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signatures cover the document only through the header's digest, so deliveries, /who responses and countersignatures are now checked against it before any signature is relied on. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
README.md §12.1 lists what ties each fact a participant relies on to the document, the addresses, the subject's key and the present. The tampering suite runs VerifySender against copied, edited, reordered and re-addressed envelopes and signatures, for clients trusting an authority and a verifier directly. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A first registration takes one key, and a key bound before can no longer start a lineage again, which let a retired key take an address back while the original verification still bound it. Tests sign key changes with goblnet.SignKeyChange. Uses gobl from invopop/gobl#1036. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
🔵 Needs a closer look
Human assessment is needed because the omitted review evidence includes critical document-binding failures and a moderate error-propagation issue that could accept altered identity data or misreport retryable outages.
1 open issue
Review effort: Lite
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
| if err := checkIssued(p); err != nil { | ||
| reason = err | ||
| continue | ||
| } |
- VerifyEndorsement and FindVerifications report an unreachable verifier key over expired or invalid evidence. - VerifySender accepts a delivery signed with the key any valid endorsement binds. - Deliveries check only that the key is not retired by now; valid_from is checked against iat, which allows clock skew. - DeliveryConfirmations keeps a signature naming a successor over a plain one made up to MaxRequestAge later. - One VerifyEndorsement call checks at most four signatures per issuer. - SignKeyChange adds neither signature when one fails. - HTTPFetcher wraps transport errors, and gives each resolved address but the last 2 seconds. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
🔵 Needs a closer look
Human assessment is needed because the registration validation permits an expiry before its issue time under clock skew, creating an invalid signed registration that the current checks accept.
2 open issues
1 resolved since last review
Review effort: Lite


Summary
Follow-up to #1035, closing the security gaps found while reviewing the merged design. Verifications and registrations are now bound to the subject's address and key, and a sender counts only when a verifier confirmed it.
Verifications bound to the address
audis the subject's address. Each address needs its own verification. breakingcnf, naming the key the subject presented to them. breakingRegistrations bound to the key (RFC 7800
cnf, as in OAuth DPoP)cnfnaming the subject's key, and the envelope'sfrom/tomust be confirmed by that key. breakingEndorsement.Keyreports the bound key.VerifySender(ctx, env)now takes the delivered envelope. It rejects a delivery not signed with the sender's endorsed key, so a new holder of a lapsed domain can't use the old holder's identity. breakingcnf, and authorities count only confirming signatures made withinMaxRequestAge(5 minutes). Without both, a new holder of a domain could replay an old request, republish the old public key, and add its own key to take over the lineage.SignKeyChangesigns such a request, andClient.DeliveryConfirmationsgives authorities each signature's signing time andcnf. §7.3 now starts from what a subject does (renew, change key, or start over), a first registration takes one key, and a key bound before cannot start a lineage again.Client.DeliveryKeysandClient.FindVerifications.head.WithConfirmationoption anddsigJKT(), the RFC 7638 thumbprint in base64url form.Verified senders only, with direct verifiers
Client.VerifyAuthorityis replaced byClient.VerifyEndorsement.Endorsement.Verified,ErrUnknownAuthorityandErrNotVerifiedare removed in favour ofErrNotEndorsed. breakingWithVerifierslets a receiver with its own agreements accept verifiers directly, without an authority, when theircnfnames the sender's key. There are none by default; trusted authorities are checked first and remain the public index.verifierclaim is a registration and never counts as a verification, even from an address trusted in both roles.Retired keys and freshness
iatno later than now. breaking/whoresponses must use a key that is still valid when received. This stops a leaked, retired key from signing with a backdatediat.expat most 90 days afteriat(ACME style), with automatic renewal recommended.Document bound to its digest
netcompared the two, so a party's name or tax ID, or an invoice body, could be changed after signing without invalidating any signature.Client.VerifyDelivery,Client.Who,Client.VerifyEndorsementandClient.FindVerificationsnow reject an envelope with no document, or whose document does not match its digest.Hardening
HTTPFetcherconnects to the IP addresses it has checked, instead of resolving the hostname again (DNS rebinding).HTTPFetcherrefuses every IANA special-purpose range that is not globally reachable, and the NAT64, 6to4 and Teredo ranges.HTTPFetcherfollows no redirects (§9): an HTTPS endpoint redirecting tohttp://would otherwise downgrade a key fetch, forward a request token, or resend a delivery over plain HTTP. A redirect is a definitive failure.HTTPFetchergives each resolved address but the last 2 seconds before trying the next, and its errors wrap the transport cause.Edge cases
VerifySenderaccepts a delivery signed with the key any valid endorsement binds, such as an authority binding the old key and a direct verifier the new one during a key change.valid_fromis checked against the signature'siat, which allows 30 seconds of clock skew; the current time is checked only againstvalid_until.DeliveryConfirmationskeeps a key's signature naming a successor over a plain one made up toMaxRequestAgelater, so a retried request does not lose its key change.SignKeyChangeadds neither signature when one fails.Spec
§2, §4, §5, §7, §7.1, §7.2, §7.3, §9, §11 and §12 are updated. New §12.1 Bindings is a table of each fact a participant relies on and what ties it to the document, the addresses, the subject's key and the present, plus what is never evidence; a new fact or claim needs its own row. §7.2 now defines two statuses, verified and unverified, reached through a trusted authority or a directly trusted verifier. §12 gains notes on:
Follow-up
gobl.lookup: key lineage and verified-only registration in Register only verified parties, bound to subject keys with key lineage gobl.lookup#13.gobl.dev:/whomust sign each response with the registered key;VerifySender(ctx, env);net.SignKeyChange;/.well-known/gobl/without redirects.Testing
Tampering suite (
net/tamper_test.go, merged in from #1037): runsVerifySenderagainst an attacker who can copy, edit, reorder and re-address envelopes and signatures, and sign with its own keys. Hand-written cases plus every claim of every signature edited without re-signing, each run for a client trusting an authority and one trusting a verifier directly (146 runs). Removing the verifieraudcheck, the digest check, the delivery bound-key check, the authority-as-verifier check, the 90-day cap or the registrationcnfcheck each makes at least one case fail.go test ./net ./head ./dsigandgolangci-lintpass. New tests cover:audandcnfhandling, including a copied envelope;cnf, bound to another key, missingiat/exp, or longer than 90 days;WithVerifiers;iat, a futureiat, or a key retired since signing;DeliveryKeysduring a rotation, andFindVerificationsreturning every valid verification;VerifySenderwith another key, the wrong recipient, or no verifier;🤖 Generated with Claude Code