Skip to content

net: bind verifications and registrations to the subject's address and key; verified senders only - #1036

Open
samlown wants to merge 21 commits into
mainfrom
net-verifier-audience
Open

samlown wants to merge 21 commits into
mainfrom
net-verifier-audience

Conversation

@samlown

@samlown samlown commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

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

  • Problem: anyone could copy a verified party's envelope, register it at their own address, and an authority would name the verifier for them.
  • Fix: verifier countersignatures now count only when their aud is the subject's address. Each address needs its own verification. breaking
  • Verifiers also include cnf, naming the key the subject presented to them. breaking

Registrations bound to the key (RFC 7800 cnf, as in OAuth DPoP)

  • Authority countersignatures need a cnf naming the subject's key, and the envelope's from/to must be confirmed by that key. breaking
  • Endorsement.Key reports 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. breaking
  • New spec §7.3 (key lineage): authorities keep each address's key history. A rotation request signed with both the old and new key keeps the verification without involving the verifier. A request signed only with an unknown key starts a new history and needs a new verification.
  • In a key change, the current key's signature must name the new key with cnf, and authorities count only confirming signatures made within MaxRequestAge (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. SignKeyChange signs such a request, and Client.DeliveryConfirmations gives authorities each signature's signing time and cnf. §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.
  • New helpers for authorities: Client.DeliveryKeys and Client.FindVerifications.
  • New head.WithConfirmation option and dsig JKT(), the RFC 7638 thumbprint in base64url form.

Verified senders only, with direct verifiers

  • Authorities register only verified parties: a registration countersignature must name a verifier whose own countersignature is valid. There is no registered-only status. breaking
  • Client.VerifyAuthority is replaced by Client.VerifyEndorsement. Endorsement.Verified, ErrUnknownAuthority and ErrNotVerified are removed in favour of ErrNotEndorsed. breaking
  • WithVerifiers lets a receiver with its own agreements accept verifiers directly, without an authority, when their cnf names the sender's key. There are none by default; trusted authorities are checked first and remain the public index.
  • A countersignature with a verifier claim is a registration and never counts as a verification, even from an address trusted in both roles.
  • A directly trusted verification counts while the subject still publishes its bound key as valid. A subject changing key retires the old one once a verification binds the new one.

Retired keys and freshness

  • Every GOBL Net signature checked needs an iat no later than now. breaking
  • Deliveries and /who responses must use a key that is still valid when received. This stops a leaked, retired key from signing with a backdated iat.
  • Authority countersignatures need an exp at most 90 days after iat (ACME style), with automatic renewal recommended.

Document bound to its digest

  • Signatures cover the document only through the header digest, and nothing in net compared 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.VerifyEndorsement and Client.FindVerifications now reject an envelope with no document, or whose document does not match its digest.
  • Spec §5: a participant MUST reject such an envelope before relying on any of its signatures.

Hardening

  • HTTPFetcher connects to the IP addresses it has checked, instead of resolving the hostname again (DNS rebinding).
  • HTTPFetcher refuses every IANA special-purpose range that is not globally reachable, and the NAT64, 6to4 and Teredo ranges.
  • HTTPFetcher follows no redirects (§9): an HTTPS endpoint redirecting to http:// would otherwise downgrade a key fetch, forward a request token, or resend a delivery over plain HTTP. A redirect is a definitive failure.
  • At most four signatures per issuer are checked against keys in one check, to limit how many key fetches one envelope can trigger.
  • HTTPFetcher gives each resolved address but the last 2 seconds before trying the next, and its errors wrap the transport cause.

Edge cases

  • An unreachable verifier key is reported over expired or invalid evidence, so an outage never reads as "not verified".
  • VerifySender accepts 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.
  • A key's valid_from is checked against the signature's iat, which allows 30 seconds of clock skew; the current time is checked only against valid_until.
  • DeliveryConfirmations keeps a key's signature naming a successor over a plain one made up to MaxRequestAge later, so a retried request does not lose its key change.
  • SignKeyChange adds 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:

  • reconciling document parties with the verified sender;
  • domains changing hands;
  • hosted addresses;
  • unsigned header data;
  • replays.

Follow-up

Testing

Tampering suite (net/tamper_test.go, merged in from #1037): runs VerifySender against 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 verifier aud check, the digest check, the delivery bound-key check, the authority-as-verifier check, the 90-day cap or the registration cnf check each makes at least one case fail.

go test ./net ./head ./dsig and golangci-lint pass. New tests cover:

  • verifier aud and cnf handling, including a copied envelope;
  • registrations without cnf, bound to another key, missing iat/exp, or longer than 90 days;
  • registrations naming no verifier, an invalid one, or the authority itself;
  • verifiers trusted directly with WithVerifiers;
  • deliveries with no iat, a future iat, or a key retired since signing;
  • the per-issuer candidate cap;
  • DeliveryKeys during a rotation, and FindVerifications returning every valid verification;
  • VerifySender with another key, the wrong recipient, or no verifier;
  • envelopes with no document, no digest, or a digest that does not match.

🤖 Generated with Claude Code

samlown and others added 4 commits November 13, 2026 21:55
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

codecov Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.48024% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.98%. Comparing base (0487f2f) to head (6655883).

Files with missing lines Patch % Lines
net/client.go 94.64% 3 Missing ⚠️
net/authorities.go 99.37% 1 Missing ⚠️
net/send.go 92.30% 1 Missing ⚠️
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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread net/authorities.go Resolved
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings November 13, 2026 23:04
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
samlown added a commit to invopop/gobl.lookup that referenced this pull request Nov 13, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

A critical active issue remains because verifier signatures without a required non-empty cnf confirmation can be accepted as valid endorsements.

1 open issue

Review effort: Lite

Copilot AI lite review requested due to automatic review settings November 13, 2026 23:08

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment thread net/verify.go Resolved
Comment thread head/header.go Resolved
Comment thread net/client.go Resolved
Comment thread net/verify.go Resolved
Comment thread net/verify.go Resolved
Comment thread net/verify.go Resolved
samlown and others added 2 commits November 15, 2026 09:41
…ctly

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings November 15, 2026 13:29
@samlown samlown changed the title net: bind verifications and registrations to the subject's address and key net: bind verifications and registrations to the subject's address and key; verified senders only Nov 15, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment thread net/authorities.go Resolved
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>
Copilot AI lite review requested due to automatic review settings November 15, 2026 13:33

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings November 15, 2026 13:41
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>
Copilot AI lite review requested due to automatic review settings November 15, 2026 21:26

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

A critical SSRF issue remains because isPublicIP allows reserved IPv4 and IPv6 documentation ranges, so unsafe destinations can still be dialed.

1 open issue
4 resolved since last review

Review effort: Lite

Comment thread net/client.go Resolved
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>
Copilot AI lite review requested due to automatic review settings November 15, 2026 22:18

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The SSRF protection omits the IANA-reserved 192.52.193.0/24 range, allowing addresses there to pass isPublicIP and be dialed contrary to the documented policy.

1 open issue
1 resolved since last review

Review effort: Lite

Comment thread net/client.go
Comment on lines +101 to +105
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>
Copilot AI lite review requested due to automatic review settings November 15, 2026 22:30
samlown added a commit to invopop/gobl.lookup that referenced this pull request Nov 15, 2026
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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed because multi-candidate verification can mask transient key-fetch failures with definitive errors, changing callers’ retry behavior.

1 open issue

Review effort: Lite

samlown and others added 5 commits November 15, 2026 23:03
§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>
Copilot AI lite review requested due to automatic review settings November 15, 2026 23:03
samlown added a commit to invopop/gobl.lookup that referenced this pull request Nov 15, 2026
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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 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>
Copilot AI lite review requested due to automatic review settings November 19, 2026 14:32

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Active moderate and critical findings remain in net/verify.go, including incorrect same-second key-rotation handling and failure to reject expired signatures.

3 open issues

Review effort: Lite

Comment thread net/verify.go
Comment on lines +152 to +155
if err := checkIssued(p); err != nil {
reason = err
continue
}
Comment thread net/verify.go Resolved
- 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>
Copilot AI lite review requested due to automatic review settings November 19, 2026 14:44

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants