From 68c25ab321158f949740614cb1c8bf04f6417af2 Mon Sep 17 00:00:00 2001 From: Sam Lown Date: Fri, 13 Nov 2026 22:48:20 +0000 Subject: [PATCH 01/11] Bind registrations to subject keys and keep key lineage Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 6 + README.md | 207 ++-- cmd/gobl.lookup/setup.go | 6 +- go.mod | 4 +- go.sum | 6 +- internal/domain/delivery/delivery.go | 23 +- internal/domain/delivery/delivery_test.go | 51 +- internal/domain/identity.go | 50 +- internal/domain/identity_test.go | 33 +- internal/domain/lineage.go | 67 ++ internal/domain/models/registration.go | 21 + internal/domain/registrations.go | 361 +++---- internal/interfaces/web/inbox.go | 7 +- internal/interfaces/web/web.go | 7 +- internal/interfaces/web/web_test.go | 1053 +++++++++------------ internal/interfaces/web/who.go | 10 +- 16 files changed, 934 insertions(+), 978 deletions(-) create mode 100644 internal/domain/lineage.go diff --git a/CHANGELOG.md b/CHANGELOG.md index ef5b8f7..2b28234 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ ### Changed +- Registrations follow the latest GOBL Net spec. A request is an ordinary delivery from the subject to the lookup, confirmed by its signature for the lookup, and needs no request token; the subject is its `from` address. The lookup drops the request signature, countersigns with a `cnf` claim binding the subject's key, and addresses the envelope back to the subject. +- The lookup keeps each address's key lineage (`Registration.Lineage`). A request signed with the current and a new key rolls over to the new key; one signed only with an unknown key starts a new lineage. A verifier is named only when its countersignature binds, with `cnf`, a key in the lineage, so rollovers keep a party verified and a new holder of an address cannot inherit its verification. +- Verifiers are no longer accepted delivering to the lookup on a subject's behalf; the subject registers again with the verified envelope. The renewal rule based on an unchanged digest is replaced by the lineage check. +- `GET /.well-known/gobl/who` answers with the lookup's party envelope addressed and signed for the requester. +- Deliveries to subjects carry no request token. + - Verification is now list-driven and automatic: the registry accepts a configured set of verification providers (`--verifiers` / `VERIFIERS`), and a registration or renewal arriving with a valid countersignature from one of them is verified on arrival — the countersignature is cryptographically checked against the provider's published key before being named (an unreachable key endpoint registers unverified and logs `inbox.auto_verify_unavailable`; the derivation re-runs on renewal). `gobl.lookup verify
` loses the `--verifier` flag and becomes a recovery command that re-derives the verifier from the stored envelope, e.g. after a provider is added to the accepted list. The discovery link stamped on countersigned envelopes uses the standard `verification` category (the previous `authority` value failed envelope validation on re-signing). - Transient failures now answer `503 Service Unavailable` instead of diff --git a/README.md b/README.md index bd1aa42..fc5ca05 100644 --- a/README.md +++ b/README.md @@ -16,49 +16,63 @@ Copyright 2026 [Invopop S.L.](https://invopop.com). ## How registration works -1. A GOBL Net node (e.g. a `gobl.dev` operator at - `alice.example`) signs an envelope containing its `org.Party` - and POSTs it to lookup's `/.well-known/gobl/inbox`. The - envelope's signed `iss=alice.example`, - `aud=lookup.gobl.org` (signed claims carry bare addresses — GOBL - Net is implied). -2. Lookup verifies the signature, then confirms the sender checks - out as a *sending* participant: it performs `GET /who` on - `alice.example` (re-fetching her published key in the process) - and requires a verified, self-signed party. A `204 No Content` - marks a receive-only account and rejects the registration with - `403 Forbidden`. -3. Lookup persists the envelope in CouchDB, countersigns it with - an Authority signature (`iss=lookup.gobl.org`, - `aud=alice.example`, `exp` = 90 days - out), and POSTs the **countersigned** envelope back to - `https://alice.example/.well-known/gobl/inbox` as a follow-up - message. The original POST is acknowledged with the standard - empty `202 Accepted` used for all inbox deliveries. -4. Alice publishes the countersigned envelope on her `/who`. Any - GOBL Net verifier can now confirm that lookup has attested to - her registration via `net.Client.VerifyAuthority` / - `net.Client.VerifySender`. - -No new protocol endpoints — registration uses the standard GOBL -Net `/inbox` POST in both directions. Marking a registration as -verified (spec §5.3, the `verifier` claim) happens automatically -when the envelope carries a countersignature from an accepted -verification provider; the full self-service flow is specified in -[How verification works](#how-verification-works) below. +1. A GOBL Net node (e.g. a `gobl.dev` operator at `alice.example`) + sends its party envelope to lookup's `/.well-known/gobl/inbox` + as an ordinary delivery: `from` is `gobl:alice.example`, `to` is + `gobl:lookup.gobl.org`, and Alice signs it with `iss=alice.example` + and `aud=lookup.gobl.org`. No request token is needed; the + signature is the authentication. +2. Lookup verifies the delivery (`net.Client.DeliveryKeys`), then + confirms the sender is a *sending* participant: it performs + `GET /who` on `alice.example` and requires a verified party. A + `204 No Content` marks a receive-only account and rejects the + registration with `403 Forbidden`. +3. Lookup updates Alice's [key lineage](#key-lineage) from the keys + that signed the request, drops Alice's request signature, + countersigns as the Authority (`iss=lookup.gobl.org`, + `aud=alice.example`, `cnf` naming Alice's current key, `exp` = 90 + days out), and addresses the envelope back (`from` + `gobl:lookup.gobl.org`, `to` `gobl:alice.example`). It persists + the record and acknowledges the POST with `202 Accepted`. +4. Lookup delivers the countersigned envelope to + `https://alice.example/.well-known/gobl/inbox`. +5. Alice publishes the envelope at her `/who`, signing each response + for its requester with the key the countersignature binds. Any + GOBL Net participant can now confirm her registration with + `net.Client.VerifyAuthority` / `net.Client.VerifySender`. + +No new protocol endpoints: registration uses the standard GOBL Net +`/inbox` in both directions. ### Endorsement lifetime and renewal -Every countersignature carries a 90-day `exp` claim — verifiers -reject it after that, so parties renew by re-registering before it -passes (Let's Encrypt style). A renewal that re-submits the -**unchanged** party document (same digest) is countersigned with -the party's current `verifier` claim: verified stays verified, -while the verifier's own longer-lived countersignature (a year or -more, in the spirit of EV certificates) continues to evidence the -KYC. Submitting changed party data is a fresh registration — the -verifier is dropped and KYC must be repeated. - +Every countersignature carries a 90-day `exp` claim, which receivers +reject after it passes, so parties renew by registering again before +then, Let's Encrypt style: submitting the envelope they hold, +countersignatures and all, signed for the lookup. The lookup +supersedes its own earlier countersignature. Changing the party +document changes its digest, so a verifier's countersignature on the +old document no longer applies and the registration starts +unverified. + +### Key lineage + +The lookup keeps each address's key lineage (spec §7.3): the keys it +has bound in turn, by RFC 7638 thumbprint and kid. The keys that +sign a registration request decide what happens: + +| Request signed with | Result | +|--------------------------------------|------------------------------------------------------------| +| the current key (or a first key) | renewal (or first registration): the key stays bound | +| the current key and a new key | rollover: the new key joins the lineage and is bound | +| only a key that is not the current one | a lost key or a new holder: a new lineage starts | +| two keys at a first registration | the key a verification binds starts the lineage, then rolls over | + +The lookup names a verifier only when its countersignature binds, +with `cnf`, a key in the current lineage. A rollover therefore keeps +a party verified with no work from its verifier, while a new holder +of a lapsed domain can register the address but cannot be verified +as its previous holder. Parties should rotate keys at renewal. ## How verification works @@ -100,11 +114,10 @@ inbox deliveries. inspectable up front. 4. **Session hand-off.** Lookup POSTs the party's **stored, countersigned envelope** to the verifier's session API in the - background, authenticated with a request token for - `lookup.gobl.org` (spec §5.5). Sending the stored envelope - pins the verification to an exact `uuid` + `dig`: the verifier - MUST countersign those bytes, so the checks and the eventual - signature cannot drift apart. The verifier answers with an + background. Sending the stored envelope pins the verification to + an exact `uuid` + `dig`: the verifier MUST countersign those + bytes, so the checks and the eventual signature cannot drift + apart. The verifier answers with an opaque, single-use session URL (or an error if it cannot serve the party's jurisdiction); lookup redirects the user's browser to it. Session URLs are unguessable on purpose — @@ -118,35 +131,33 @@ inbox deliveries. on the verifier's side: the registry stays free. From here the provider runs its usual process (document checks, liveness, registry/UBO lookups, AML screening). -6. **Countersign and return.** On success the verifier - countersigns the envelope from step 4 (`iss=`, - `aud=`, `exp` a year or more — spec §5.3) and POSTs - the envelope back to lookup's standard `/inbox` with its own - request token. To the inbox this is an ordinary renewal: same - digest, first signature still the subject's, one extra - countersignature aboard. Failed or abandoned sessions simply - never produce a countersignature; sessions expire after a few - days and the verifier SHOULD notify lookup so the flow's status - page can say so. -7. **Auto-verify.** When a renewal arrives carrying a valid - countersignature from a verifier on the trusted-verifier list, - lookup re-countersigns with `verifier=` - automatically — the same act as `gobl.lookup verify`, without - the operator. The stored record gains `verifier` + - `verified_at`. -8. **Deliver and publish.** The now twice-countersigned envelope - (subject self-signature, verifier countersignature, lookup - countersignature naming the verifier) is delivered to the - subject's own `/inbox` — the standard registration delivery - path. The subject publishes it at its `/who`; only then do - receivers see the verified status. The verify status page tells - the user this last step is theirs. - -Renewal interplay is unchanged: re-registering the identical party -document keeps the verifier claim; changed party data drops it and -the party goes through verification again (the verifier's own -countersignature attests to the *checked* data, not to future -edits). +6. **Countersign and return.** As part of its checks the verifier + has the subject deliver the envelope from its address, which + proves control of the address and names the subject's key. On + success the verifier countersigns the envelope from step 4 + (`iss=`, `aud=`, `cnf` naming that key, `exp` + a year or more — spec §7.1) and delivers it to the **subject's** + inbox, `from` the verifier `to` the subject. Verifiers never + deliver to the lookup: GOBL Net has no forwarding. Failed or + abandoned sessions simply never produce a countersignature; + sessions expire after a few days. +7. **Renew with the verification.** The subject registers again + with the envelope it received. Lookup finds the valid + countersignature from a verifier on its trusted list, checks its + `cnf` names a key in the subject's lineage, and countersigns + with `verifier=` — the same act as + `gobl.lookup verify`, without the operator. The stored record + gains `verifier` + `verified_at`. +8. **Deliver and publish.** The countersigned envelope (verifier + countersignature and lookup countersignature naming the + verifier) is delivered to the subject's inbox, which publishes + it at its `/who`; only then do receivers see the verified + status. + +Renewals keep the verifier as long as the subject presents the +verifier's countersignature and it binds a key in the lineage; +changed party data, or a lineage restarted by a lost key, drops it +and the party goes through verification again. **Implementation gaps** (in rough order): @@ -195,26 +206,25 @@ The domain never imports the transport layer. | Method | Path | Auth | Purpose | |--------|-------------------------------------|-------|----------------------------------------------------------| -| POST | `/.well-known/gobl/inbox` | token | Registration entry — must carry an `org.Party` document. | -| GET | `/.well-known/gobl/who` | token | Lookup's identity (self-signed party envelope). | +| POST | `/.well-known/gobl/inbox` | signature | Registration entry — must carry an `org.Party` document. | +| GET | `/.well-known/gobl/who` | token | Lookup's identity, signed for the requester. | | GET | `/.well-known/gobl/keys/` | open | Single published key. | | GET | `/.well-known/jwks.json` | open | Bulk JWK Set (for jwt.io-style tooling). | | GET | `/parties/
` | open | Public registration record by address. | | GET | `/parties/` | open | Public registration record by envelope UUID. | | GET | `/healthz` | open | Liveness check. | -The who and inbox endpoints require a bearer request token (spec -§5.5) minted from the caller's own published key; requests without -a valid token get `401`, and `503` when the token cannot be checked -because the issuer's key endpoint is unreachable (retry). The token's issuer may be a trusted -intermediary transmitting on the registrant's behalf — the -registration subject always comes from the envelope's own -signature. Key discovery stays open (it is what makes token -verification possible), and `/parties` remains an open directory of -registered — hence deliberately public — identities. The lookup's -own outbound requests (the sender `GET /who` eligibility check and -countersigned-envelope deliveries) authenticate the same way, as -`lookup.gobl.org`. Authenticated requests are logged with the +The who endpoint requires a bearer request token (spec §6) minted +from the caller's own published key; requests without a valid token +get `401`, and `503` when the token cannot be checked because the +issuer's key endpoint is unreachable (retry). The response is +addressed and signed for the token's issuer. Inbox deliveries carry +no token: the registration subject is the envelope's `from`, +confirmed by its signature for the lookup. Key discovery stays open, +and `/parties` remains an open directory of registered — hence +deliberately public — identities. The lookup's own sender `GET /who` +eligibility check authenticates as `lookup.gobl.org`; its deliveries +carry no token. Authenticated requests are logged with the requester address, forming the request audit log. ## Quickstart (local dev) @@ -258,7 +268,10 @@ registered address with id `registration:
`: "envelope": { ... full countersigned envelope ... }, "delivery_attempts": 1, "last_delivery_at": "2026-06-07T...", - "verified_at": null + "verified_at": null, + "lineage": [ + { "jkt": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs", "kid": "...", "added_at": "2026-06-07T..." } + ] } ``` @@ -306,13 +319,15 @@ arrives from a secret independently of the host). ## Operations -- **Re-registration vs renewal**: re-submitting the unchanged party - document (same digest) is a renewal — it keeps the current - `verifier` and `verified_at`, stamping a fresh 90-day - countersignature. Submitting **changed** party data drops the - `verifier` and clears `verified_at`; verifying again requires - another `gobl.lookup verify
` call. Audit trail lives in - CouchDB revisions. +- **Renewal and key changes**: a request signed with the current key + renews, stamping a fresh 90-day countersignature; one signed with + the current and a new key rolls over to the new key. Either keeps + `verifier` and `verified_at` while the request carries a + verification bound to a key in the lineage. Changed party data, or + a request signed only with an unknown key, drops the `verifier` + and clears `verified_at`. Records without a lineage (registered + before key lineage) need one fresh registration. Audit trail lives + in CouchDB revisions. - **Delivery failures**: the inbox handler responds `202` once the record is persisted; delivery to the sender's `/inbox` happens asynchronously. Failures land on `Record.LastDeliveryError`; diff --git a/cmd/gobl.lookup/setup.go b/cmd/gobl.lookup/setup.go index b74da55..d7cb5bb 100644 --- a/cmd/gobl.lookup/setup.go +++ b/cmd/gobl.lookup/setup.go @@ -55,10 +55,10 @@ func buildDomain(ctx context.Context, cfg config.Config) (*domain.Setup, func(), Identity: id, Registrations: reg, Verifiers: verifiers, - // The client and sender authenticate outbound requests as the - // lookup itself (bearer request tokens, spec §5.5). + // The client authenticates /who requests as the lookup itself + // (bearer request tokens, spec §6). Client: goblnet.NewClient(goblnet.WithIdentity(id.Address(), id.PrivateKey)), - Sender: delivery.New(id.Address(), id.PrivateKey), + Sender: delivery.New(), // domain.New defaults this to https:// when empty. PublicBaseURL: strings.TrimRight(cfg.PublicBaseURL, "/"), Logger: slog.Default(), diff --git a/go.mod b/go.mod index 60f4c65..0d4d4b8 100644 --- a/go.mod +++ b/go.mod @@ -19,7 +19,7 @@ require ( github.com/buger/jsonparser v1.1.2 // indirect github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect github.com/expr-lang/expr v1.17.8 // indirect - github.com/go-jose/go-jose/v4 v4.1.4 // indirect + github.com/go-jose/go-jose/v4 v4.1.6 // indirect github.com/google/uuid v1.6.0 // indirect github.com/inconshreveable/mousetrap v1.1.0 // indirect github.com/invopop/jsonschema v0.14.0 // indirect @@ -34,3 +34,5 @@ require ( golang.org/x/text v0.38.0 // indirect gopkg.in/yaml.v3 v3.0.1 // indirect ) + +replace github.com/invopop/gobl => ../gobl diff --git a/go.sum b/go.sum index 85f05ed..bf1cefb 100644 --- a/go.sum +++ b/go.sum @@ -18,8 +18,8 @@ github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/expr-lang/expr v1.17.8 h1:W1loDTT+0PQf5YteHSTpju2qfUfNoBt4yw9+wOEU9VM= github.com/expr-lang/expr v1.17.8/go.mod h1:8/vRC7+7HBzESEqt5kKpYXxrxkr31SaO8r40VO/1IT4= -github.com/go-jose/go-jose/v4 v4.1.4 h1:moDMcTHmvE6Groj34emNPLs/qtYXRVcd6S7NHbHz3kA= -github.com/go-jose/go-jose/v4 v4.1.4/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08= +github.com/go-jose/go-jose/v4 v4.1.6 h1:sNRkftxFJxwsILiQukqp5z83QBSmntVwmgRY7AqBDO4= +github.com/go-jose/go-jose/v4 v4.1.6/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08= github.com/go-kivik/kivik/v4 v4.5.2 h1:Xi6QyjscrWrSRQEEW/25vaWyh20ZCg3LhTm6AqFRZCc= github.com/go-kivik/kivik/v4 v4.5.2/go.mod h1:5YlQJZim4qvaJ3T0fCAS6U4oaN4hzXK6CVY9nvN4Phg= github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= @@ -34,8 +34,6 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/invopop/couch v0.1.0 h1:ctMKLeIxnab9KW11KtEAQSl7RzGgMxndavLphx99LpY= github.com/invopop/couch v0.1.0/go.mod h1:xzBNVglDnLcpf1Z9BJxiIG1liESSIkMuvIczSl4zcls= -github.com/invopop/gobl v0.504.1-0.20260811215754-c231ee2feae5 h1:C124OmPhan8ocPR78006Aa/dCEdzPNlSMJZik5yTghM= -github.com/invopop/gobl v0.504.1-0.20260811215754-c231ee2feae5/go.mod h1:HmiEdQreTSQYyNbhs81VKTmI7BAJKYC/6enh9RDwnE0= github.com/invopop/jsonschema v0.14.0 h1:MHQqLhvpNUZfw+hM3AZDYK7jxO8FZoQeQM77g8iyZjg= github.com/invopop/jsonschema v0.14.0/go.mod h1:ygm6C2EaVNMBDPpaPlnOA2pFAxBnxGjFlMZABxm9n2I= github.com/invopop/yaml v0.3.1 h1:f0+ZpmhfBSS4MhG+4HYseMdJhoeeopbSKbq5Rpeelso= diff --git a/internal/domain/delivery/delivery.go b/internal/domain/delivery/delivery.go index 09943ac..9337382 100644 --- a/internal/domain/delivery/delivery.go +++ b/internal/domain/delivery/delivery.go @@ -19,7 +19,6 @@ import ( "time" "github.com/invopop/gobl" - "github.com/invopop/gobl/dsig" "github.com/invopop/gobl/net" ) @@ -51,25 +50,24 @@ type Sender interface { } // HTTPSender is the HTTP implementation of Sender. Construct with New; -// the zero value is not usable. Every request carries a bearer -// request token (spec §5.5) minted from the lookup's own identity. +// the zero value is not usable. Requests carry no request token: an +// inbox delivery is authenticated by the envelope's own signature +// (spec §6). type HTTPSender struct { client *http.Client - self net.Address - key *dsig.PrivateKey } // New returns an HTTPSender whose transport refuses to dial any // resolved IP that is loopback, private, link-local, multicast, or -// unspecified, and which authenticates its requests as self. -func New(self net.Address, key *dsig.PrivateKey) *HTTPSender { - return newSender(self, key, false) +// unspecified. +func New() *HTTPSender { + return newSender(false) } // newSender builds an HTTPSender; allowLoopback bypasses the SSRF // guard, intended only for tests that talk to httptest servers bound // to 127.0.0.1. There is no public wrapper that exposes it. -func newSender(self net.Address, key *dsig.PrivateKey, allowLoopback bool) *HTTPSender { +func newSender(allowLoopback bool) *HTTPSender { transport := &http.Transport{ ForceAttemptHTTP2: true, MaxIdleConns: 50, @@ -85,8 +83,6 @@ func newSender(self net.Address, key *dsig.PrivateKey, allowLoopback bool) *HTTP // caller's context (see Send), keeping it in step with the // domain's delivery timeout. client: &http.Client{Transport: transport}, - self: self, - key: key, } } @@ -111,11 +107,6 @@ func (s *HTTPSender) Send(ctx context.Context, addr net.Address, env *gobl.Envel } req.Header.Set("Content-Type", "application/json") req.Header.Set("Accept", "application/json") - token, err := net.NewToken(s.key, s.self, addr, 0) - if err != nil { - return fmt.Errorf("%w: mint request token: %v", ErrSendFailed, err) - } - req.Header.Set("Authorization", "Bearer "+token) resp, err := s.client.Do(req) if err != nil { // Transport failures are transient: the async delivery loop diff --git a/internal/domain/delivery/delivery_test.go b/internal/domain/delivery/delivery_test.go index 4ac414b..96a5604 100644 --- a/internal/domain/delivery/delivery_test.go +++ b/internal/domain/delivery/delivery_test.go @@ -2,7 +2,6 @@ package delivery import ( "context" - "encoding/json" "errors" stdnet "net" "net/http" @@ -20,11 +19,6 @@ import ( "github.com/stretchr/testify/require" ) -var ( - testSelf = net.Address("lookup.example") - testSelfKey = dsig.NewES256Key() -) - func buildEnvelope(t *testing.T) *gobl.Envelope { t.Helper() msg := ¬e.Message{Content: "hi"} @@ -54,7 +48,7 @@ func TestSenderSend202(t *testing.T) { // normally refuse). We use the same internal-only constructor // trick gobl/net does for its tests, then exercise the transport // directly via a one-off request matching what Send constructs. - s := newSender(testSelf, testSelfKey, true) + s := newSender(true) req, _ := http.NewRequest(http.MethodPost, srv.URL+net.InboxPath, strings.NewReader(`{}`)) req.Header.Set("Content-Type", "application/json") resp, err := s.client.Do(req) @@ -71,7 +65,7 @@ func TestSenderRejectsLoopbackByDefault(t *testing.T) { })) defer srv.Close() - s := New(testSelf, testSelfKey) + s := New() // httptest binds 127.0.0.1 — the default Sender MUST refuse. req, _ := http.NewRequest(http.MethodPost, srv.URL+net.InboxPath, strings.NewReader(`{}`)) _, err := s.client.Do(req) @@ -90,13 +84,13 @@ func TestSafeDialContextRejectsLoopback(t *testing.T) { } func TestSendNilEnvelope(t *testing.T) { - err := New(testSelf, testSelfKey).Send(context.Background(), net.Address("alice.example"), nil) + err := New().Send(context.Background(), net.Address("alice.example"), nil) require.Error(t, err) assert.True(t, errors.Is(err, ErrSendFailed)) } func TestSendInvalidAddress(t *testing.T) { - err := New(testSelf, testSelfKey).Send(context.Background(), net.Address("not a domain"), buildEnvelope(t)) + err := New().Send(context.Background(), net.Address("not a domain"), buildEnvelope(t)) require.Error(t, err) assert.True(t, errors.Is(err, ErrSendFailed)) } @@ -110,7 +104,7 @@ func TestTransportSurfacesUpstreamStatus(t *testing.T) { w.WriteHeader(http.StatusUnauthorized) })) defer srv.Close() - s := newSender(testSelf, testSelfKey, true) + s := newSender(true) req, _ := http.NewRequest(http.MethodPost, srv.URL+net.InboxPath, strings.NewReader(`{}`)) req.Header.Set("Content-Type", "application/json") resp, err := s.client.Do(req) @@ -145,11 +139,9 @@ type roundTripFunc func(*http.Request) (*http.Response, error) func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) } -func TestSendMintsRequestToken(t *testing.T) { +func TestSendCarriesNoRequestToken(t *testing.T) { var got *http.Request s := &HTTPSender{ - self: testSelf, - key: testSelfKey, client: &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) { got = r return &http.Response{ @@ -162,42 +154,13 @@ func TestSendMintsRequestToken(t *testing.T) { require.NoError(t, s.Send(context.Background(), net.Address("alice.example"), buildEnvelope(t))) require.NotNil(t, got) - auth := got.Header.Get("Authorization") - require.True(t, strings.HasPrefix(auth, "Bearer "), "request carries a bearer token") - - // The token must verify as self → alice.example. - pub, err := json.Marshal(testSelfKey.Public()) - require.NoError(t, err) - client := net.NewClient(net.WithFetcher(&mapFetcher{data: map[string][]byte{ - testSelf.KeyURL(testSelfKey.ID()): pub, - }})) - iss, err := client.VerifyToken(context.Background(), strings.TrimPrefix(auth, "Bearer "), "alice.example") - require.NoError(t, err) - assert.Equal(t, testSelf, iss) -} - -// mapFetcher serves a URL-keyed byte map for token verification. -type mapFetcher struct { - data map[string][]byte -} - -func (m *mapFetcher) Fetch(_ context.Context, url string, _ http.Header) ([]byte, error) { - if d, ok := m.data[url]; ok { - return d, nil - } - return nil, net.ErrFetchFailed -} - -func (m *mapFetcher) Post(_ context.Context, _ string, _ []byte, _ http.Header) error { - return net.ErrFetchFailed + assert.Empty(t, got.Header.Get("Authorization"), "inbox deliveries are authenticated by their signatures") } func TestSendRetryableTaxonomy(t *testing.T) { send := func(t *testing.T, status int) error { t.Helper() s := &HTTPSender{ - self: testSelf, - key: testSelfKey, client: &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) { return &http.Response{StatusCode: status, Body: http.NoBody, Request: r}, nil })}, diff --git a/internal/domain/identity.go b/internal/domain/identity.go index a0a1688..9b9e5ea 100644 --- a/internal/domain/identity.go +++ b/internal/domain/identity.go @@ -57,31 +57,37 @@ func (d *Identity) JWKS() ([]byte, error) { return d.model.JWKS() } func (d *Identity) PublicKeys() []*dsig.PublicKey { return d.model.PublicKeys } // VerifyRequest verifies the Authorization header of an inbound who -// or inbox request (a bearer request token, spec §5.5) and returns +// request (a bearer request token, spec §5.5) and returns // the verified requester address. The token's audience must be this // lookup and its freshness window must include the current time. func (d *Identity) VerifyRequest(ctx context.Context, header string) (goblnet.Address, error) { return d.client.VerifyAuthorization(ctx, header, d.Address()) } -// PartyEnvelope returns the JSON of the lookup's party wrapped in a -// self-signed envelope (iss = the lookup's address, no aud), served -// at GET /.well-known/gobl/who. The response is a static document: -// it is signed once per process and cached. -func (d *Identity) PartyEnvelope() ([]byte, error) { +// PartyEnvelope returns the JSON of the lookup's party envelope for +// requester, served at GET /.well-known/gobl/who: from the lookup to +// the requester, signed for it (spec §5.1). The unsigned envelope is +// built once per process; each response gets its own signature. +func (d *Identity) PartyEnvelope(requester goblnet.Address) ([]byte, error) { d.partyOnce.Do(func() { env, err := gobl.Envelop(d.model.Party) if err != nil { d.partyErr = fmt.Errorf("identity: envelop party: %w", err) return } - if err := env.Sign(d.model.PrivateKey, head.WithIssuer(d.Address().String())); err != nil { - d.partyErr = fmt.Errorf("identity: sign party: %w", err) - return - } d.partyData, d.partyErr = json.Marshal(env) }) - return d.partyData, d.partyErr + if d.partyErr != nil { + return nil, d.partyErr + } + env := new(gobl.Envelope) + if err := json.Unmarshal(d.partyData, env); err != nil { + return nil, fmt.Errorf("identity: copy party envelope: %w", err) + } + if err := goblnet.Sign(env, d.model.PrivateKey, d.Address(), requester); err != nil { + return nil, fmt.Errorf("identity: sign party: %w", err) + } + return json.Marshal(env) } // CounterSignOptions configure a CounterSign call. @@ -90,17 +96,19 @@ type CounterSignOptions struct { // countersigned; copied into the signed `aud` field so the // resulting signature is bound to that specific subject. Subject goblnet.Address - // Verifier names the authority that performed identity + // Key is the thumbprint of the subject key the registration binds, + // carried as the signed `cnf` claim (spec §7.3). + Key string + // Verifier names the participant that performed identity // verification (KYC/KYB) of the subject, carried as the signed - // `verifier` claim. The lookup names itself when it performed the - // verification. Empty asserts registration only. + // `verifier` claim. Empty asserts registration only. Verifier goblnet.Address } // CounterSign adds a fresh Authority countersignature to env, valid -// for endorsementTTL (carried as the signed `exp` claim). The -// envelope's UUID and Digest are unchanged — only the Signatures -// slice grows. +// for endorsementTTL (carried as the signed `exp` claim), and addresses +// env from this lookup to the subject, which the countersignature +// confirms. The envelope's UUID and Digest are unchanged. func (d *Identity) CounterSign(env *gobl.Envelope, opts CounterSignOptions) error { if env == nil || env.Head == nil { return errors.New("identity: cannot countersign a nil envelope") @@ -119,13 +127,15 @@ func (d *Identity) CounterSign(env *gobl.Envelope, opts CounterSignOptions) erro sigs = append(sigs, sig) } env.Signatures = sigs + if opts.Key == "" { + return errors.New("identity: cannot countersign without a subject key") + } signOpts := []head.SignOption{ - head.WithIssuer(d.Address().String()), - head.WithAudience(opts.Subject.String()), head.WithExpiration(time.Now().Add(endorsementTTL)), + head.WithConfirmation(opts.Key), } if opts.Verifier != "" { signOpts = append(signOpts, head.WithVerifier(opts.Verifier.String())) } - return env.Sign(d.model.PrivateKey, signOpts...) + return goblnet.Sign(env, d.model.PrivateKey, d.Address(), opts.Subject, signOpts...) } diff --git a/internal/domain/identity_test.go b/internal/domain/identity_test.go index c086129..79aca2e 100644 --- a/internal/domain/identity_test.go +++ b/internal/domain/identity_test.go @@ -36,25 +36,31 @@ func newTestIdentity(t *testing.T) *domain.Identity { return setup.Identity() } -func TestPartyEnvelopeIsSelfSigned(t *testing.T) { +func TestPartyEnvelopeIsSignedForTheRequester(t *testing.T) { id := newTestIdentity(t) - data, err := id.PartyEnvelope() + data, err := id.PartyEnvelope("alice.example") require.NoError(t, err) env := new(gobl.Envelope) require.NoError(t, json.Unmarshal(data, env)) require.Len(t, env.Signatures, 1) + assert.Equal(t, id.URI(), env.Head.From) + assert.Equal(t, "gobl:alice.example", env.Head.To.String()) p, err := head.SignedPayload(env.Signatures[0]) require.NoError(t, err) assert.Equal(t, id.Address().String(), p.Iss) - assert.Empty(t, p.Aud, "a GET who response has no caller to bind to") + assert.Equal(t, "alice.example", p.Aud) - // The envelope is signed once and cached: a second call returns - // the identical bytes. - again, err := id.PartyEnvelope() + // Each requester gets its own signature over the same document. + other, err := id.PartyEnvelope("bob.example") + require.NoError(t, err) + envB := new(gobl.Envelope) + require.NoError(t, json.Unmarshal(other, envB)) + assert.Equal(t, env.Head.UUID, envB.Head.UUID) + pb, err := head.SignedPayload(envB.Signatures[0]) require.NoError(t, err) - assert.Equal(t, data, again) + assert.Equal(t, "bob.example", pb.Aud) } func TestCounterSign(t *testing.T) { @@ -72,15 +78,28 @@ func TestCounterSign(t *testing.T) { // Authority countersignature. require.NoError(t, id.CounterSign(env, domain.CounterSignOptions{ Subject: net.Address("alice.example"), + Key: "alice-key", Verifier: net.Address("kyc.example"), })) require.Len(t, env.Signatures, 2) + assert.Equal(t, id.URI(), env.Head.From) + assert.Equal(t, "gobl:alice.example", env.Head.To.String()) p, err := head.SignedPayload(env.Signatures[1]) require.NoError(t, err) assert.Equal(t, id.Address().String(), p.Iss) assert.Equal(t, "alice.example", p.Aud) assert.Equal(t, "kyc.example", p.Verifier) + require.NotNil(t, p.Confirmation) + assert.Equal(t, "alice-key", p.Confirmation.JKT) + assert.NotZero(t, p.ExpiresAt) +} + +func TestCounterSignRequiresAKey(t *testing.T) { + id := newTestIdentity(t) + env, err := gobl.Envelop(¬e.Message{Content: "party doc"}) + require.NoError(t, err) + require.Error(t, id.CounterSign(env, domain.CounterSignOptions{Subject: "alice.example"})) } func TestCounterSignNilEnvelope(t *testing.T) { diff --git a/internal/domain/lineage.go b/internal/domain/lineage.go new file mode 100644 index 0000000..71bff2c --- /dev/null +++ b/internal/domain/lineage.go @@ -0,0 +1,67 @@ +package domain + +import ( + "errors" + "time" + + "github.com/invopop/gobl/dsig" + + "github.com/invopop/gobl.lookup/internal/domain/models" +) + +// errLineage is returned when a registration request's keys cannot +// extend or start a lineage. +var errLineage = errors.New("registration must be signed with the current key, a new key, or both") + +// nextLineage applies the keys confirming a registration request to +// the current lineage (spec §7.3) and returns the resulting one, whose +// last key is bound. verified holds the cnf thumbprints of accepted +// verification countersignatures on the request, which order the keys +// of a first registration signed with two. +func nextLineage(lineage []*models.LineageKey, keys []*dsig.PublicKey, verified []string, now time.Time) ([]*models.LineageKey, error) { + entry := func(k *dsig.PublicKey) *models.LineageKey { + return &models.LineageKey{JKT: k.JKT(), KID: k.ID(), AddedAt: now} + } + var current string + if len(lineage) > 0 { + current = lineage[len(lineage)-1].JKT + } + switch len(keys) { + case 1: + k := keys[0] + if k.JKT() == current { + return lineage, nil // renewal + } + // A first registration, or a key that is not the current one: + // a lost key or a new holder of the address starts afresh. + return []*models.LineageKey{entry(k)}, nil + case 2: + a, b := keys[0], keys[1] + if current != "" { + switch current { + case a.JKT(): + return append(lineage, entry(b)), nil + case b.JKT(): + return append(lineage, entry(a)), nil + } + return nil, errLineage + } + switch { + case contains(verified, a.JKT()) && !contains(verified, b.JKT()): + return []*models.LineageKey{entry(a), entry(b)}, nil + case contains(verified, b.JKT()) && !contains(verified, a.JKT()): + return []*models.LineageKey{entry(b), entry(a)}, nil + } + return nil, errLineage + } + return nil, errLineage +} + +func contains(list []string, s string) bool { + for _, v := range list { + if v == s { + return true + } + } + return false +} diff --git a/internal/domain/models/registration.go b/internal/domain/models/registration.go index 4ce73ae..0edd500 100644 --- a/internal/domain/models/registration.go +++ b/internal/domain/models/registration.go @@ -48,6 +48,27 @@ type Registration struct { LastDeliveryError string `json:"last_delivery_error,omitempty"` LastDeliveryAt *time.Time `json:"last_delivery_at,omitempty"` VerifiedAt *time.Time `json:"verified_at,omitempty"` + // Lineage lists the subject keys bound in turn since the lineage + // last started (spec §7.3); the last is the current one. + Lineage []*LineageKey `json:"lineage,omitempty"` +} + +// LineageKey is one subject key in a registration's lineage. +type LineageKey struct { + // JKT is the key's RFC 7638 thumbprint, as carried in cnf claims. + JKT string `json:"jkt"` + // KID is the key's ID at the subject's address. + KID string `json:"kid"` + // AddedAt is when the key joined the lineage. + AddedAt time.Time `json:"added_at"` +} + +// CurrentKey returns the lineage's current key, or nil. +func (r *Registration) CurrentKey() *LineageKey { + if len(r.Lineage) == 0 { + return nil + } + return r.Lineage[len(r.Lineage)-1] } // RegistrationDocID returns the CouchDB document ID for a given address. diff --git a/internal/domain/registrations.go b/internal/domain/registrations.go index 5816c69..d45a77c 100644 --- a/internal/domain/registrations.go +++ b/internal/domain/registrations.go @@ -9,6 +9,7 @@ import ( "github.com/invopop/gobl" "github.com/invopop/gobl/head" + "github.com/invopop/gobl/org" goblnet "github.com/invopop/gobl/net" "github.com/invopop/gobl/uuid" @@ -61,12 +62,14 @@ func newRegistrations(store RegistrationStore, identity *Identity, client *gobln } } -// Register processes a registration request: a signed envelope -// containing the subject's org.Party. It establishes the subject from -// the party document itself, resolves the subject's own GET /who to -// confirm the address serves a public identity, countersigns the +// Register processes a registration request: a delivery to this +// lookup's inbox of the subject's party envelope. The subject is the +// envelope's from address, confirmed by a signature for this lookup +// with the subject's current key, a new key, or both (spec §7.3). It +// resolves the subject's own GET /who to confirm the address serves an +// identity, updates the subject's key lineage, countersigns the // envelope as the Authority, persists the record, and queues -// asynchronous delivery back to the subject's /inbox. The persisted +// asynchronous delivery back to the subject's inbox. The persisted // record is returned once stored; delivery happens in the background. func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*models.Registration, error) { if err := env.Validate(); err != nil { @@ -74,76 +77,64 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode return nil, ErrValidation.WithMessage("envelope failed validation: %s", err.Error()) } - // Party envelopes are bearer documents (spec §8.3): the subject is - // the address the party document itself declares, attested by a - // valid self-signature — no audience binding, no significance to - // signature order. The request token carries delivery intent and - // the who eligibility check below gates who can register. - sender, err := d.client.VerifyParty(ctx, env) + keys, err := d.client.DeliveryKeys(ctx, env, d.identity.Address()) if err != nil { - switch { - case errors.Is(err, goblnet.ErrUnavailable): + if errors.Is(err, goblnet.ErrUnavailable) { d.log.Warn("inbox.rejected", "reason", "verify_unavailable", "error", err.Error()) - return nil, ErrUnavailable.WithMessage("could not reach the subject's key endpoint; retry later") - case errors.Is(err, goblnet.ErrPartyMissing): - d.log.Warn("inbox.rejected", "reason", "not_a_party", "error", err.Error()) - return nil, ErrValidation.WithMessage("registration envelope must contain an org.Party declaring a gobl: endpoint") + return nil, ErrUnavailable.WithMessage("could not reach the sender's key endpoint; retry later") } d.log.Warn("inbox.rejected", "reason", "verify_failed", "error", err.Error()) - return nil, ErrUnauthorized.WithMessage("signature verification failed") + return nil, ErrUnauthorized.WithMessage("envelope is not signed by its sender for this lookup: %s", err.Error()) + } + sender, err := goblnet.ParseAddress(env.Head.From.Opaque()) + if err != nil { + return nil, ErrValidation.WithCause(err) + } + if _, ok := env.Extract().(*org.Party); !ok { + d.log.Warn("inbox.rejected", "reason", "not_a_party", "caller", string(sender)) + return nil, ErrValidation.WithMessage("registration envelope must contain an org.Party") } // Any signature claiming to be this lookup's must actually be one: - // a returned envelope (e.g. from a verification provider, §5.3) - // carries the original countersignature, and a broken or forged - // copy means the envelope is not what was endorsed. + // a renewal carries the previous countersignature, and a broken or + // forged copy means the envelope is not what was endorsed. if err := d.verifyOwnSignatures(env); err != nil { d.log.Warn("inbox.rejected", "reason", "own_signature_invalid", "caller", string(sender), "error", err.Error()) return nil, ErrUnauthorized.WithMessage("envelope carries an invalid countersignature claiming this lookup") } - // The subject of a registration is a *sending* participant, so it - // must serve a public identity of its own: GET /who on the sender - // (which also re-fetches its published key) must return a verified - // party. A 204 marks a receive-only account, which cannot register. - if _, err := d.client.Who(ctx, sender); err != nil { - // A transient outage while resolving the sender's who must not - // permanently reject the registration: senders stop retrying - // on 4xx, so surface a retryable condition instead. - if errors.Is(err, goblnet.ErrUnavailable) { - d.log.Warn("inbox.rejected", "reason", "who_unavailable", "caller", string(sender), "error", err.Error()) - return nil, ErrUnavailable.WithMessage("could not reach sender's public identity; retry later") - } - reason := "who_failed" - msg := "could not resolve sender's public identity" - switch { - case errors.Is(err, goblnet.ErrNoContent): - reason = "who_no_content" - msg = "sender does not publish a public identity; senders must serve GET /who" - case errors.Is(err, goblnet.ErrPending): - reason = "who_pending" - msg = "sender defers identity disclosure; senders must serve GET /who openly to register" - } - d.log.Warn("inbox.rejected", "reason", reason, "caller", string(sender), "error", err.Error()) - return nil, ErrForbidden.WithMessage("%s", msg) - } - - // An unchanged party re-registering before its endorsement expires - // is a renewal and keeps its current verifier; anything else - // starts as registered only. Either way, a countersignature from - // an accepted verification provider on the incoming envelope wins: - // it attests to exactly this digest, so the registration is - // verified from the start (auto-verify — the manual verify command - // only re-triggers this same derivation). - verifier, renewal := d.renewalVerifier(ctx, sender, env) - if av, err := d.acceptedVerifier(ctx, env); av != "" { - verifier = av - } else if err != nil { + if err := d.checkWho(ctx, sender); err != nil { + return nil, err + } + + prev, err := d.store.Get(ctx, sender) + switch { + case errors.Is(err, repos.ErrNotFound): + prev = nil + case err != nil: + return nil, ErrInternal.WithCause(err) + } + + // Accepted verifications bind a subject key with cnf; one counts + // only while that key is in the subject's lineage, which a rollover + // extends and a lost key or a new holder of the address restarts. + verifications, verr := d.acceptedVerifications(ctx, env, sender) + if verr != nil { // A provider's key endpoint was unreachable: register // unverified rather than reject — the derivation re-runs on // the next renewal, or via the verify command. - d.log.Warn("inbox.auto_verify_unavailable", "caller", string(sender), "error", err.Error()) + d.log.Warn("inbox.auto_verify_unavailable", "caller", string(sender), "error", verr.Error()) + } + var lineage []*models.LineageKey + if prev != nil { + lineage = prev.Lineage + } + lineage, err = nextLineage(lineage, keys, verificationKeys(verifications), time.Now().UTC()) + if err != nil { + d.log.Warn("inbox.rejected", "reason", "lineage", "caller", string(sender), "keys", len(keys)) + return nil, ErrValidation.WithMessage("%s", err.Error()) } + verifier := pickVerifier(verifications, lineage) // Stamp the discovery link to the public record before signing: // stamping replaces any copy from an earlier countersign round — @@ -151,12 +142,15 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode // unsigned (mutable post-signature) by design; the link is a // discovery hint, not part of the trust claim. d.stampDiscoveryLink(env) + d.dropRequestSignatures(env, sender) - // Countersign: adds Authority signature with iss=lookup, - // aud=sender, any preserved verifier claim, and a 90-day exp. - // UUID + digest unchanged. + // Countersign: adds the Authority signature for the subject's + // address and current key, with any verifier claim and a 90-day + // exp, and addresses the envelope back to the subject. UUID and + // digest unchanged. if err := d.identity.CounterSign(env, CounterSignOptions{ Subject: sender, + Key: lineage[len(lineage)-1].JKT, Verifier: verifier, }); err != nil { d.log.Error("inbox.countersign_failed", "caller", string(sender), "error", err.Error()) @@ -165,7 +159,7 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode // Persist before delivery so the record exists even if the // downstream POST fails. - rec, err := d.upsert(ctx, sender, env, verifier, renewal) + rec, err := d.upsert(ctx, prev, sender, env, verifier, lineage) if err != nil { d.log.Error("inbox.persist_failed", "caller", string(sender), "error", err.Error()) return nil, ErrInternal.WithCause(err) @@ -174,7 +168,7 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode "caller", string(sender), "envelope", env.Head.UUID.String(), "verifier", string(verifier), - "renewal", renewal, + "lineage", len(lineage), ) // Fire-and-forget delivery: the caller is acknowledged as soon @@ -187,16 +181,44 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode return rec, nil } +// checkWho confirms the subject of a registration is a sending +// participant: GET /who on it must return a verified identity. A 204 +// marks a receive-only account, which cannot register. +func (d *Registrations) checkWho(ctx context.Context, sender goblnet.Address) error { + _, err := d.client.Who(ctx, sender) + if err == nil { + return nil + } + // A transient outage while resolving the sender's who must not + // permanently reject the registration: senders stop retrying on + // 4xx, so surface a retryable condition instead. + if errors.Is(err, goblnet.ErrUnavailable) { + d.log.Warn("inbox.rejected", "reason", "who_unavailable", "caller", string(sender), "error", err.Error()) + return ErrUnavailable.WithMessage("could not reach sender's public identity; retry later") + } + reason := "who_failed" + msg := "could not resolve sender's public identity" + switch { + case errors.Is(err, goblnet.ErrNoContent): + reason = "who_no_content" + msg = "sender does not publish a public identity; senders must serve GET /who" + case errors.Is(err, goblnet.ErrPending): + reason = "who_pending" + msg = "sender defers identity disclosure; senders must serve GET /who openly to register" + } + d.log.Warn("inbox.rejected", "reason", reason, "caller", string(sender), "error", err.Error()) + return ErrForbidden.WithMessage("%s", msg) +} + // Verify marks an existing registration as identity-verified: it // derives the verifier from the countersignatures already on the // stored envelope — the most recent one from an accepted verification -// provider — re-countersigns with the `verifier` claim naming it, and -// delivers the result synchronously to the subject's inbox. The same -// derivation runs automatically when a registration arrives carrying -// a provider countersignature, so this command exists for recovery: -// e.g. a provider added to the accepted list after its -// countersignature was received. The registry names itself only when -// it is on its own accepted list. +// provider whose cnf names a key in the subject's lineage — +// re-countersigns with the `verifier` claim naming it, and delivers +// the result synchronously to the subject's inbox. The same derivation +// runs automatically on every registration, so this command exists +// for recovery: e.g. a provider added to the accepted list after its +// countersignature was received. func (d *Registrations) Verify(ctx context.Context, addr goblnet.Address) (*models.Registration, error) { rec, err := d.store.Get(ctx, addr) if errors.Is(err, repos.ErrNotFound) { @@ -208,14 +230,19 @@ func (d *Registrations) Verify(ctx context.Context, addr goblnet.Address) (*mode if rec.CountersignedEnvelope == nil { return nil, ErrValidation.WithMessage("registration for %s has no countersigned envelope", addr) } + key := rec.CurrentKey() + if key == nil { + return nil, ErrValidation.WithMessage("registration for %s has no key lineage; the subject must register again", addr) + } env := rec.CountersignedEnvelope - verifier, aerr := d.acceptedVerifier(ctx, env) + verifications, aerr := d.acceptedVerifications(ctx, env, addr) + verifier := pickVerifier(verifications, rec.Lineage) if verifier == "" { if aerr != nil { return nil, ErrUnavailable.WithMessage("could not check verifier countersignatures: %s", aerr.Error()) } - return nil, ErrValidation.WithMessage("no countersignature from an accepted verifier on the registration envelope for %s", addr) + return nil, ErrValidation.WithMessage("no countersignature from an accepted verifier for a key of %s on the registration envelope", addr) } // Restamp the discovery link (deduplicating any earlier rounds) @@ -224,6 +251,7 @@ func (d *Registrations) Verify(ctx context.Context, addr goblnet.Address) (*mode d.stampDiscoveryLink(env) if err := d.identity.CounterSign(env, CounterSignOptions{ Subject: addr, + Key: key.JKT, Verifier: verifier, }); err != nil { return nil, ErrInternal.WithCause(err) @@ -258,53 +286,88 @@ func (d *Registrations) Verify(ctx context.Context, addr goblnet.Address) (*mode return rec, nil } -// acceptedVerifier returns the address behind the most recent -// unexpired countersignature on env whose signer is an accepted -// verification provider and whose signature verifies against the -// provider's published key, or "". The crypto check matters here: -// naming a verifier whose signature consumers would reject makes the -// registry attest to garbage. Latest-iat wins when several providers -// have countersigned. The error is non-nil only when a candidate's -// key endpoint was unreachable (net.ErrUnavailable) — the caller -// decides whether that degrades or aborts. -func (d *Registrations) acceptedVerifier(ctx context.Context, env *gobl.Envelope) (goblnet.Address, error) { +// acceptedVerifications returns the valid countersignatures for +// subject on env from accepted verification providers. The crypto +// check matters: naming a verifier whose signature consumers would +// reject makes the registry attest to garbage. The error is non-nil +// only when a provider's key endpoint was unreachable +// (net.ErrUnavailable) — the caller decides whether that degrades or +// aborts. +func (d *Registrations) acceptedVerifications(ctx context.Context, env *gobl.Envelope, subject goblnet.Address) ([]*goblnet.Verification, error) { var ( - best goblnet.Address - bestIat int64 = -1 + found []*goblnet.Verification unavailable error ) - now := time.Now().UTC().Unix() - for _, sig := range env.Signatures { - p, err := head.SignedPayload(sig) - if err != nil { - continue - } - issuer, err := goblnet.ParseAddress(p.Iss) - if err != nil || !d.verifiers[issuer] { - continue - } - if p.ExpiresAt != 0 && now >= p.ExpiresAt { - continue - } - if p.IssuedAt <= bestIat { - continue - } - pub, err := d.client.FetchKey(ctx, issuer, sig.KeyID()) + for v := range d.verifiers { + ver, err := d.client.FindVerification(ctx, env, v, subject) if err != nil { if errors.Is(err, goblnet.ErrUnavailable) { unavailable = err } continue } - if err := env.Head.Verify(sig, pub); err != nil { + found = append(found, ver) + } + return found, unavailable +} + +// verificationKeys returns the cnf thumbprints of verifications. +func verificationKeys(vs []*goblnet.Verification) []string { + keys := make([]string, 0, len(vs)) + for _, v := range vs { + if v.Key != "" { + keys = append(keys, v.Key) + } + } + return keys +} + +// pickVerifier returns the verifier of the most recent verification +// whose cnf names a key in lineage, or "". +func pickVerifier(vs []*goblnet.Verification, lineage []*models.LineageKey) goblnet.Address { + var best *goblnet.Verification + for _, v := range vs { + if !inLineage(lineage, v.Key) { continue } - best, bestIat = issuer, p.IssuedAt + if best == nil || v.IssuedAt.After(best.IssuedAt) { + best = v + } + } + if best == nil { + return "" + } + return best.Verifier +} + +func inLineage(lineage []*models.LineageKey, jkt string) bool { + if jkt == "" { + return false + } + for _, k := range lineage { + if k.JKT == jkt { + return true + } } - if best == "" && unavailable != nil { - return "", unavailable + return false +} + +// dropRequestSignatures removes the subject's signatures for this +// lookup: they confirmed the registration request and have served +// their purpose (spec §5). +func (d *Registrations) dropRequestSignatures(env *gobl.Envelope, sender goblnet.Address) { + sigs := env.Signatures[:0] + for _, sig := range env.Signatures { + if p, err := head.SignedPayload(sig); err == nil { + iss, ierr := goblnet.ParseAddress(p.Iss) + aud, aerr := goblnet.ParseAddress(p.Aud) + if ierr == nil && aerr == nil && iss == sender && aud == d.identity.Address() { + continue + } + } + sigs = append(sigs, sig) } - return best, nil + env.Signatures = sigs } // verifyOwnSignatures checks every signature claiming this lookup's @@ -380,76 +443,40 @@ func (d *Registrations) found(rec *models.Registration, err error) (*models.Regi return rec, nil } -// renewalVerifier resolves the verifier claim for a registration's -// countersignature. An existing record whose countersigned envelope -// has the same digest as the incoming one is renewing an unchanged -// party and keeps its current verifier; any other case starts as -// registered only (no verifier). -func (d *Registrations) renewalVerifier(ctx context.Context, sender goblnet.Address, env *gobl.Envelope) (goblnet.Address, bool) { - prev, err := d.store.Get(ctx, sender) - if err != nil || prev.CountersignedEnvelope == nil || !sameDigest(prev.CountersignedEnvelope, env) { - return "", false - } - return prev.Verifier, true -} - -// sameDigest reports whether both envelopes carry the same document -// digest. -func sameDigest(a, b *gobl.Envelope) bool { - if a == nil || b == nil || a.Head == nil || b.Head == nil { - return false - } - da, db := a.Head.Digest, b.Head.Digest - return da != nil && db != nil && da.Algorithm == db.Algorithm && da.Value == db.Value -} - -// upsert reads any existing record for sender (preserving the store's -// _rev token for optimistic concurrency), then writes the new state -// with the freshly countersigned envelope. A renewal keeps the -// record's verification timestamp; a re-registration with changed -// party data clears it — prior KYC no longer applies. -func (d *Registrations) upsert(ctx context.Context, sender goblnet.Address, env *gobl.Envelope, verifier goblnet.Address, renewal bool) (*models.Registration, error) { - prev, err := d.store.Get(ctx, sender) - switch { - case errors.Is(err, repos.ErrNotFound): - r := models.NewRegistration(sender, env.Head.UUID) - r.Verifier = verifier - if verifier != "" { - now := time.Now().UTC() - r.VerifiedAt = &now - } - r.Status = models.StatusCountersigned - r.CountersignedEnvelope = env - if err := d.store.Put(ctx, r); err != nil { - return nil, err - } - return r, nil - case err != nil: - return nil, err +// upsert writes the registration record for sender from the freshly +// countersigned envelope, building on prev (nil for a first +// registration, preserving the store's _rev token otherwise). +func (d *Registrations) upsert(ctx context.Context, prev *models.Registration, sender goblnet.Address, env *gobl.Envelope, verifier goblnet.Address, lineage []*models.LineageKey) (*models.Registration, error) { + rec := prev + prevVerifier := goblnet.Address("") + if rec == nil { + rec = models.NewRegistration(sender, env.Head.UUID) + } else { + prevVerifier = rec.Verifier + rec.IncomingEnvelopeUUID = env.Head.UUID + rec.ReceivedAt = time.Now().UTC() + rec.DeliveryAttempts = 0 + rec.LastDeliveryError = "" + rec.LastDeliveryAt = nil } - prevVerifier := prev.Verifier - prev.IncomingEnvelopeUUID = env.Head.UUID - prev.ReceivedAt = time.Now().UTC() - prev.Verifier = verifier - prev.Status = models.StatusCountersigned - prev.CountersignedEnvelope = env - prev.DeliveryAttempts = 0 - prev.LastDeliveryError = "" - prev.LastDeliveryAt = nil + rec.Verifier = verifier + rec.Status = models.StatusCountersigned + rec.CountersignedEnvelope = env + rec.Lineage = lineage // The verification timestamp follows the verifier: dropped when // the verifier is dropped, kept across renewals with the same // verifier, and stamped fresh when a (new) provider verifies. switch { case verifier == "": - prev.VerifiedAt = nil - case prev.VerifiedAt == nil || verifier != prevVerifier: + rec.VerifiedAt = nil + case rec.VerifiedAt == nil || verifier != prevVerifier: now := time.Now().UTC() - prev.VerifiedAt = &now + rec.VerifiedAt = &now } - if err := d.store.Put(ctx, prev); err != nil { + if err := d.store.Put(ctx, rec); err != nil { return nil, err } - return prev, nil + return rec, nil } // deliverAsync POSTs the countersigned envelope to the sender's own diff --git a/internal/interfaces/web/inbox.go b/internal/interfaces/web/inbox.go index 56b13b0..3e0099a 100644 --- a/internal/interfaces/web/inbox.go +++ b/internal/interfaces/web/inbox.go @@ -39,14 +39,13 @@ func handleInbox(s *domain.Setup, log *slog.Logger) http.HandlerFunc { http.Error(w, "invalid envelope JSON", http.StatusBadRequest) return } - // The requester (token iss) may be a trusted intermediary - // transmitting on the registrant's behalf; the domain resolves - // the subject from the envelope's own signature. + // The domain resolves the subject from the envelope's from + // address and the signature confirming it. if _, err := s.Registrations().Register(r.Context(), env); err != nil { writeError(w, err) return } - log.Info("inbox.received", "requester", string(requesterFrom(r.Context()))) + log.Info("inbox.received", "remote", r.RemoteAddr) w.WriteHeader(http.StatusAccepted) } } diff --git a/internal/interfaces/web/web.go b/internal/interfaces/web/web.go index da3ac18..e221642 100644 --- a/internal/interfaces/web/web.go +++ b/internal/interfaces/web/web.go @@ -1,8 +1,9 @@ // Package web is the HTTP transport adapter for the lookup service. // It exposes the standard GOBL Net well-known endpoints (inbox / who // / keys / jwks) plus the public /parties registry record. The who -// and inbox endpoints require a bearer request token (spec §5.5); -// key discovery and the /parties directory stay open. Handlers are +// endpoint requires a bearer request token (spec §6); inbox +// deliveries are authenticated by their own signatures, and key +// discovery and the /parties directory stay open. Handlers are // thin: they parse the request, delegate to the domain services, and // map domain errors onto HTTP status codes. package web @@ -29,7 +30,7 @@ func NewMux(setup *domain.Setup, log *slog.Logger) http.Handler { } mux := http.NewServeMux() - mux.HandleFunc("POST "+goblnet.InboxPath, requireAuth(setup, log, handleInbox(setup, log))) + mux.HandleFunc("POST "+goblnet.InboxPath, handleInbox(setup, log)) mux.HandleFunc("GET "+goblnet.WhoPath, requireAuth(setup, log, handleWho(setup, log))) mux.HandleFunc("GET "+goblnet.KeysPath+"/{kid}", handleKey(setup, log)) mux.HandleFunc("GET "+goblnet.JWKSPath, handleJWKS(setup, log)) diff --git a/internal/interfaces/web/web_test.go b/internal/interfaces/web/web_test.go index 6d0bca5..27218f6 100644 --- a/internal/interfaces/web/web_test.go +++ b/internal/interfaces/web/web_test.go @@ -47,7 +47,7 @@ func (m *mockFetcher) Fetch(_ context.Context, url string, _ http.Header) ([]byt return nil, goblnet.ErrFetchFailed } -func (m *mockFetcher) Post(_ context.Context, _ string, _ []byte, _ http.Header) error { +func (m *mockFetcher) Post(_ context.Context, _ string, _ []byte) error { return goblnet.ErrFetchFailed } @@ -98,6 +98,7 @@ type fixture struct { registry *repos.MemoryRegistrations sender *mockSender mux http.Handler + accepted int } func newFixture(t *testing.T) *fixture { @@ -123,7 +124,7 @@ func newFixture(t *testing.T) *fixture { }, errs: map[string]error{}, } - client := goblnet.NewClient(goblnet.WithFetcher(fetcher)) + client := goblnet.NewClient(goblnet.WithFetcher(fetcher), goblnet.WithIdentity(lookup.Address(), lookup.PrivateKey)) reg := repos.NewMemoryRegistrations() send := &mockSender{} @@ -139,37 +140,115 @@ func newFixture(t *testing.T) *fixture { mux := web.NewMux(setup, discardLogger()) f := &fixture{t: t, lookup: lookup, subject: subKey, subAddr: subAddr, verifier: verifKey, verifAddr: verifAddr, fetcher: fetcher, registry: reg, sender: send, mux: mux} // The registration flow resolves the sender's own GET /who, so the - // fixture serves a self-signed identity for the subject by default. - who, _ := json.Marshal(f.signPartyEnvelope(subAddr.String(), "")) + // fixture serves the subject's identity, signed for the lookup. + who, _ := json.Marshal(f.request(f.party(), f.subject)) fetcher.data[subAddr.WhoURL()] = who return f } -// signPartyEnvelope builds a fresh signed envelope from subject with -// the given iss/aud. -func (f *fixture) signPartyEnvelope(iss, aud string) *gobl.Envelope { +// party returns a fresh party document for the subject. +func (f *fixture) party() *org.Party { + return &org.Party{Name: "Alice"} +} + +// request envelopes party as a registration request from the subject +// to the lookup, signed with each of keys. +func (f *fixture) request(party *org.Party, keys ...*dsig.PrivateKey) *gobl.Envelope { f.t.Helper() - party := &org.Party{ - Name: "Alice", - Endpoints: []*org.Endpoint{{URI: f.subAddr.URI()}}, - } env, err := gobl.Envelop(party) require.NoError(f.t, err) - opts := []head.SignOption{head.WithIssuer(iss)} - if aud != "" { - opts = append(opts, head.WithAudience(aud)) + f.signRequest(env, keys...) + return env +} + +// signRequest signs env from the subject to the lookup with each of +// keys, publishing each key at the subject's address. +func (f *fixture) signRequest(env *gobl.Envelope, keys ...*dsig.PrivateKey) { + f.t.Helper() + for _, k := range keys { + f.publish(k) + require.NoError(f.t, goblnet.Sign(env, k, f.subAddr, f.lookup.Address())) + } +} + +// publish serves key at the subject's key endpoint. +func (f *fixture) publish(key *dsig.PrivateKey) { + pub, _ := json.Marshal(key.Public()) + f.fetcher.data[f.subAddr.KeyURL(key.ID())] = pub +} + +// register POSTs env to the lookup's inbox and returns the status. +func (f *fixture) register(env *gobl.Envelope) int { + f.t.Helper() + body, err := json.Marshal(env) + require.NoError(f.t, err) + resp := f.do(http.MethodPost, goblnet.InboxPath, body, "") + defer resp.Body.Close() //nolint:errcheck + if resp.StatusCode == http.StatusAccepted { + f.accepted++ + } + return resp.StatusCode +} + +// record returns the stored registration for the subject. +func (f *fixture) record() *models.Registration { + f.t.Helper() + rec, err := f.registry.Get(context.Background(), f.subAddr) + require.NoError(f.t, err) + return rec +} + +// counterSignAsVerifier stamps the fixture verifier's countersignature +// for the subject onto env, binding key, as a provider would after +// completing its checks. +func (f *fixture) counterSignAsVerifier(env *gobl.Envelope, key *dsig.PrivateKey) { + f.t.Helper() + opts := []head.SignOption{ + head.WithIssuer(f.verifAddr.String()), + head.WithAudience(f.subAddr.String()), + head.WithExpiration(time.Now().Add(365 * 24 * time.Hour)), + } + if key != nil { + opts = append(opts, head.WithConfirmation(key.JKT())) + } + require.NoError(f.t, env.Sign(f.verifier, opts...)) +} + +// authority returns the payload of the lookup's countersignature on env. +func (f *fixture) authority(env *gobl.Envelope) *head.SigningPayload { + f.t.Helper() + for _, sig := range env.Signatures { + p, err := head.SignedPayload(sig) + require.NoError(f.t, err) + if p.Iss == f.lookup.Address().String() { + return p + } } - require.NoError(f.t, env.Sign(f.subject, opts...)) + f.t.Fatal("no lookup countersignature") + return nil +} + +// renewal returns the envelope the lookup delivered to the subject, +// signed again as a request to the lookup with keys. +func (f *fixture) renewal(keys ...*dsig.PrivateKey) *gobl.Envelope { + f.t.Helper() + sent := f.waitForDeliveries(f.accepted) + require.Len(f.t, sent, f.accepted) + data, err := json.Marshal(sent[len(sent)-1].env) + require.NoError(f.t, err) + env := new(gobl.Envelope) + require.NoError(f.t, json.Unmarshal(data, env)) + f.signRequest(env, keys...) return env } -// waitForDelivery spins until the mock sender records something or the -// deadline expires. The inbox handler delivers async so the POST +// waitForDeliveries spins until the mock sender records n deliveries +// or two seconds pass. The inbox handler delivers async so the POST // returns immediately. -func (f *fixture) waitForDelivery(d time.Duration) []sentEnvelope { - deadline := time.Now().Add(d) +func (f *fixture) waitForDeliveries(n int) []sentEnvelope { + deadline := time.Now().Add(2 * time.Second) for time.Now().Before(deadline) { - if got := f.sender.records(); len(got) > 0 { + if got := f.sender.records(); len(got) >= n { return got } time.Sleep(5 * time.Millisecond) @@ -178,7 +257,7 @@ func (f *fixture) waitForDelivery(d time.Duration) []sentEnvelope { } // bearer mints a request token from the subject for the lookup, as -// any conforming client would attach to a who or inbox request. +// any conforming client would attach to a who request. func (f *fixture) bearer() string { f.t.Helper() token, err := goblnet.NewToken(f.subject, f.subAddr, f.lookup.Address(), 0) @@ -186,10 +265,6 @@ func (f *fixture) bearer() string { return "Bearer " + token } -func (f *fixture) post(path string, body []byte) *http.Response { - return f.do(http.MethodPost, path, body, f.bearer()) -} - func (f *fixture) get(path string) *http.Response { return f.do(http.MethodGet, path, nil, f.bearer()) } @@ -215,228 +290,377 @@ func (f *fixture) do(method, path string, body []byte, auth string) *http.Respon func TestInboxAcceptsRegistration(t *testing.T) { f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusAccepted, resp.StatusCode) + env := f.request(f.party(), f.subject) + require.Equal(t, http.StatusAccepted, f.register(env), "no request token is needed") - // Record persisted with the Authority countersignature. Delivery - // happens asynchronously and the mock sender is instant, so the - // record may already have advanced from countersigned to - // delivered by the time we read it. - rec, err := f.registry.Get(context.Background(), f.subAddr) - require.NoError(t, err) + // Delivery happens asynchronously and the mock sender is instant, + // so the record may already have advanced to delivered. + rec := f.record() assert.Contains(t, []models.Status{models.StatusCountersigned, models.StatusDelivered}, rec.Status) assert.Empty(t, rec.Verifier, "initial registration carries no verifier") - require.NotNil(t, rec.CountersignedEnvelope) - require.Len(t, rec.CountersignedEnvelope.Signatures, 2, - "original subject signature + lookup countersignature") - - // Inspect the Authority signature's payload. - authSig := rec.CountersignedEnvelope.Signatures[1] - p, err := head.SignedPayload(authSig) - require.NoError(t, err) - assert.Equal(t, f.lookup.Address().String(), p.Iss) + require.Len(t, rec.Lineage, 1) + assert.Equal(t, f.subject.JKT(), rec.Lineage[0].JKT) + assert.Equal(t, f.subject.ID(), rec.Lineage[0].KID) + + // The request signature is dropped; the lookup's countersignature + // addresses the envelope back to the subject. + out := rec.CountersignedEnvelope + require.Len(t, out.Signatures, 1) + assert.Equal(t, f.lookup.Address().URI(), out.Head.From) + assert.Equal(t, f.subAddr.URI(), out.Head.To) + p := f.authority(out) assert.Equal(t, f.subAddr.String(), p.Aud) - assert.Empty(t, p.Verifier, "initial countersignature carries no verifier claim") + require.NotNil(t, p.Confirmation) + assert.Equal(t, f.subject.JKT(), p.Confirmation.JKT) + assert.Empty(t, p.Verifier) + assert.Greater(t, p.ExpiresAt, time.Now().Add(89*24*time.Hour).Unix()) + assert.LessOrEqual(t, p.ExpiresAt, time.Now().Add(90*24*time.Hour).Unix()) // Discovery link stamped on the (mutable) header. - require.NotEmpty(t, rec.CountersignedEnvelope.Head.Links) - link := rec.CountersignedEnvelope.Head.Links[0] + require.NotEmpty(t, out.Head.Links) + link := out.Head.Links[0] assert.Equal(t, head.LinkCategoryKeyVerification, link.Category) assert.Equal(t, cbc.Key("lookup"), link.Key) assert.Contains(t, link.URL, env.Head.UUID.String()) - // Delivery goroutine eventually posts to the subject's inbox. - sent := f.waitForDelivery(2 * time.Second) + sent := f.waitForDeliveries(1) require.Len(t, sent, 1) assert.Equal(t, f.subAddr, sent[0].to) assert.Equal(t, env.Head.UUID, sent[0].env.Head.UUID) -} -func TestInboxAcceptsBearerEnvelope(t *testing.T) { - // Party envelopes are bearer documents (spec §8.3): the canonical - // registration is the audience-free publication signature alone. - f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), "") - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusAccepted, resp.StatusCode) + // The delivered envelope is a valid GOBL Net delivery to the + // subject, endorsed by the lookup for the subject's key. + lookupPub, _ := json.Marshal(f.lookup.PrivateKey.Public()) + f.fetcher.data[f.lookup.Address().KeyURL(f.lookup.PrivateKey.ID())] = lookupPub + c := goblnet.NewClient(goblnet.WithFetcher(f.fetcher)) + require.NoError(t, c.VerifyDelivery(context.Background(), sent[0].env, f.subAddr)) } -func TestInboxIgnoresForeignAud(t *testing.T) { - // An audience on the subject's signature is a legacy hop artifact - // and carries no meaning here; the request token is the intent. +func TestInboxRejectsRequests(t *testing.T) { f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), "someone.else") - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusAccepted, resp.StatusCode) -} + other := dsig.NewES256Key() -func TestInboxRejectsNonPartyDocument(t *testing.T) { - f := newFixture(t) - // Sign a non-party document instead of a party. - msg := &org.Inbox{Code: "x"} - env, err := gobl.Envelop(msg) - require.NoError(t, err) - require.NoError(t, env.Sign(f.subject, - head.WithIssuer(f.subAddr.String()), - head.WithAudience(f.lookup.Address().String()))) - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode) -} + t.Run("not a party", func(t *testing.T) { + env, err := gobl.Envelop(&org.Inbox{Code: "x"}) + require.NoError(t, err) + f.signRequest(env, f.subject) + assert.Equal(t, http.StatusUnprocessableEntity, f.register(env)) + }) -func TestInboxRejectsOversizedBody(t *testing.T) { - f := newFixture(t) - // Larger than the handler's 1 MiB cap → rejected, not truncated. - resp := f.post(goblnet.InboxPath, bytes.Repeat([]byte("a"), (1<<20)+1024)) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusRequestEntityTooLarge, resp.StatusCode) -} + t.Run("signed by an unpublished key", func(t *testing.T) { + env, err := gobl.Envelop(f.party()) + require.NoError(t, err) + require.NoError(t, goblnet.Sign(env, other, f.subAddr, f.lookup.Address())) + assert.Equal(t, http.StatusUnauthorized, f.register(env)) + }) -func TestInboxRejectsMalformedJSON(t *testing.T) { - f := newFixture(t) - resp := f.post(goblnet.InboxPath, []byte("not json")) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusBadRequest, resp.StatusCode) -} + t.Run("signed for another audience", func(t *testing.T) { + env, err := gobl.Envelop(f.party()) + require.NoError(t, err) + require.NoError(t, goblnet.Sign(env, f.subject, f.subAddr, "someone.example")) + env.Head.To = f.lookup.Address().URI() + assert.Equal(t, http.StatusUnauthorized, f.register(env)) + }) -func TestInboxRejectsUnknownSigner(t *testing.T) { - f := newFixture(t) - // Sign with a brand-new key not served by the fetcher. - other := dsig.NewES256Key() - party := &org.Party{ - Name: "Mallory", - Endpoints: []*org.Endpoint{{URI: goblnet.Address("mallory.example").URI()}}, - } - env, err := gobl.Envelop(party) - require.NoError(t, err) - require.NoError(t, env.Sign(other, - head.WithIssuer("mallory.example"), - head.WithAudience(f.lookup.Address().String()))) - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusUnauthorized, resp.StatusCode) -} + t.Run("addressed to another participant", func(t *testing.T) { + env, err := gobl.Envelop(f.party()) + require.NoError(t, err) + require.NoError(t, goblnet.Sign(env, f.subject, f.subAddr, "someone.example")) + assert.Equal(t, http.StatusUnauthorized, f.register(env)) + }) -func TestReRegistrationDropsVerifier(t *testing.T) { - f := newFixture(t) - // First registration. - env1 := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - body1, _ := json.Marshal(env1) - f.post(goblnet.InboxPath, body1).Body.Close() //nolint:errcheck - - // Manually mark as verified to simulate the admin path. - rec, _ := f.registry.Get(context.Background(), f.subAddr) - rec.Verifier = "kyc.example" - now := time.Now().UTC() - rec.VerifiedAt = &now - err := f.registry.Put(context.Background(), rec) - require.NoError(t, err) + t.Run("from naming another address", func(t *testing.T) { + env := f.request(f.party(), f.subject) + env.Head.From = "gobl:victim.example" + assert.Equal(t, http.StatusUnauthorized, f.register(env)) + }) - // Re-register: the verifier must be dropped — prior KYC no - // longer applies to changed party data. - env2 := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - body2, _ := json.Marshal(env2) - f.post(goblnet.InboxPath, body2).Body.Close() //nolint:errcheck + t.Run("oversized body", func(t *testing.T) { + resp := f.do(http.MethodPost, goblnet.InboxPath, bytes.Repeat([]byte("a"), (1<<20)+1024), "") + defer resp.Body.Close() //nolint:errcheck + assert.Equal(t, http.StatusRequestEntityTooLarge, resp.StatusCode) + }) + + t.Run("malformed JSON", func(t *testing.T) { + resp := f.do(http.MethodPost, goblnet.InboxPath, []byte("not json"), "") + defer resp.Body.Close() //nolint:errcheck + assert.Equal(t, http.StatusBadRequest, resp.StatusCode) + }) - rec2, _ := f.registry.Get(context.Background(), f.subAddr) - assert.Empty(t, rec2.Verifier) - assert.Nil(t, rec2.VerifiedAt, "verified timestamp cleared on re-registration") + t.Run("forged countersignature claiming the lookup", func(t *testing.T) { + env := f.request(f.party(), f.subject) + require.NoError(t, env.Sign(other, + head.WithIssuer(f.lookup.Address().String()), + head.WithAudience(f.subAddr.String()))) + assert.Equal(t, http.StatusUnauthorized, f.register(env)) + }) + + _, err := f.registry.Get(context.Background(), f.subAddr) + assert.ErrorIs(t, err, repos.ErrNotFound, "nothing was registered") } -// signSameParty envelopes and signs the given party without altering -// it, so repeated calls produce envelopes with identical digests — -// the renewal case. -func (f *fixture) signSameParty(party *org.Party) *gobl.Envelope { - f.t.Helper() - env, err := gobl.Envelop(party) - require.NoError(f.t, err) - require.NoError(f.t, env.Sign(f.subject, - head.WithIssuer(f.subAddr.String()), - head.WithAudience(f.lookup.Address().String()))) - return env +func TestKeyLineage(t *testing.T) { + t.Run("renewal with the current key keeps the lineage", func(t *testing.T) { + f := newFixture(t) + require.Equal(t, http.StatusAccepted, f.register(f.request(f.party(), f.subject))) + first := f.record().Lineage + + require.Equal(t, http.StatusAccepted, f.register(f.renewal(f.subject))) + rec := f.record() + assert.Equal(t, first, rec.Lineage) + require.Len(t, rec.CountersignedEnvelope.Signatures, 1, "request signature dropped, own countersignature superseded") + assert.Equal(t, 1, linkCount(rec.CountersignedEnvelope), "restamped, not duplicated") + require.NoError(t, rec.CountersignedEnvelope.Validate()) + }) + + t.Run("rollover signed with both keys keeps the verifier", func(t *testing.T) { + f := newFixture(t) + env := f.request(f.party(), f.subject) + f.counterSignAsVerifier(env, f.subject) + require.Equal(t, http.StatusAccepted, f.register(env)) + require.Equal(t, f.verifAddr, f.record().Verifier) + + next := dsig.NewES256Key() + require.Equal(t, http.StatusAccepted, f.register(f.renewal(f.subject, next))) + rec := f.record() + require.Len(t, rec.Lineage, 2) + assert.Equal(t, f.subject.JKT(), rec.Lineage[0].JKT) + assert.Equal(t, next.JKT(), rec.Lineage[1].JKT) + assert.Equal(t, f.verifAddr, rec.Verifier, "the verification binds a key in the lineage") + p := f.authority(rec.CountersignedEnvelope) + assert.Equal(t, next.JKT(), p.Confirmation.JKT) + assert.Equal(t, f.verifAddr.String(), p.Verifier) + + // And on to a third key, signed with the second. + third := dsig.NewES256Key() + require.Equal(t, http.StatusAccepted, f.register(f.renewal(next, third))) + rec = f.record() + require.Len(t, rec.Lineage, 3) + assert.Equal(t, f.verifAddr, rec.Verifier) + }) + + t.Run("a new key alone starts a new lineage and drops the verifier", func(t *testing.T) { + // A lost key, or a new holder of the address: the previous + // verification does not carry over. + f := newFixture(t) + env := f.request(f.party(), f.subject) + f.counterSignAsVerifier(env, f.subject) + require.Equal(t, http.StatusAccepted, f.register(env)) + + newHolder := dsig.NewES256Key() + require.Equal(t, http.StatusAccepted, f.register(f.renewal(newHolder))) + rec := f.record() + require.Len(t, rec.Lineage, 1) + assert.Equal(t, newHolder.JKT(), rec.Lineage[0].JKT) + assert.Empty(t, rec.Verifier) + assert.Nil(t, rec.VerifiedAt) + assert.Empty(t, f.authority(rec.CountersignedEnvelope).Verifier) + }) + + t.Run("two keys at a first registration follow the verification", func(t *testing.T) { + f := newFixture(t) + next := dsig.NewES256Key() + env := f.request(f.party(), f.subject, next) + f.counterSignAsVerifier(env, f.subject) + require.Equal(t, http.StatusAccepted, f.register(env)) + rec := f.record() + require.Len(t, rec.Lineage, 2) + assert.Equal(t, f.subject.JKT(), rec.Lineage[0].JKT) + assert.Equal(t, next.JKT(), rec.Lineage[1].JKT) + assert.Equal(t, f.verifAddr, rec.Verifier) + }) + + t.Run("two keys at a first registration without a verification are rejected", func(t *testing.T) { + f := newFixture(t) + env := f.request(f.party(), f.subject, dsig.NewES256Key()) + assert.Equal(t, http.StatusUnprocessableEntity, f.register(env)) + }) + + t.Run("two keys, neither current, are rejected", func(t *testing.T) { + f := newFixture(t) + require.Equal(t, http.StatusAccepted, f.register(f.request(f.party(), f.subject))) + assert.Equal(t, http.StatusUnprocessableEntity, + f.register(f.renewal(dsig.NewES256Key(), dsig.NewES256Key()))) + }) } -func TestRenewalPreservesVerifier(t *testing.T) { - f := newFixture(t) - party := &org.Party{ - Name: "Alice", - Endpoints: []*org.Endpoint{{URI: f.subAddr.URI()}}, - } - env1 := f.signSameParty(party) // assigns the party's UUID - body1, _ := json.Marshal(env1) - f.post(goblnet.InboxPath, body1).Body.Close() //nolint:errcheck +func TestAutoVerify(t *testing.T) { + t.Run("names an accepted verifier binding the subject's key", func(t *testing.T) { + f := newFixture(t) + env := f.request(f.party(), f.subject) + f.counterSignAsVerifier(env, f.subject) + require.Equal(t, http.StatusAccepted, f.register(env)) + rec := f.record() + assert.Equal(t, f.verifAddr, rec.Verifier) + assert.NotNil(t, rec.VerifiedAt) + assert.Equal(t, f.verifAddr.String(), f.authority(rec.CountersignedEnvelope).Verifier) + }) - // Simulate out-of-band KYC. - rec, err := f.registry.Get(context.Background(), f.subAddr) - require.NoError(t, err) - rec.Verifier = "kyc.example" - now := time.Now().UTC() - rec.VerifiedAt = &now - require.NoError(t, f.registry.Put(context.Background(), rec)) + t.Run("survives renewal of the delivered envelope", func(t *testing.T) { + f := newFixture(t) + env := f.request(f.party(), f.subject) + f.counterSignAsVerifier(env, f.subject) + require.Equal(t, http.StatusAccepted, f.register(env)) + verifiedAt := f.record().VerifiedAt + + require.Equal(t, http.StatusAccepted, f.register(f.renewal(f.subject))) + rec := f.record() + assert.Equal(t, f.verifAddr, rec.Verifier) + assert.Equal(t, verifiedAt, rec.VerifiedAt, "renewal keeps the verification timestamp") + final := rec.CountersignedEnvelope + require.Len(t, final.Signatures, 2, "lookup + verifier, nothing stale") + assert.Equal(t, 1, sigCountBy(final, f.lookup.Address())) + assert.Equal(t, 1, sigCountBy(final, f.verifAddr)) + }) - // Renew with the unchanged party document (same digest). - env2 := f.signSameParty(party) - body2, _ := json.Marshal(env2) - resp := f.post(goblnet.InboxPath, body2) - defer resp.Body.Close() //nolint:errcheck - require.Equal(t, http.StatusAccepted, resp.StatusCode) + ignored := map[string]func(f *fixture, env *gobl.Envelope){ + "for another key": func(f *fixture, env *gobl.Envelope) { + f.counterSignAsVerifier(env, dsig.NewES256Key()) + }, + "without a cnf": func(f *fixture, env *gobl.Envelope) { + f.counterSignAsVerifier(env, nil) + }, + "for another address": func(f *fixture, env *gobl.Envelope) { + require.NoError(f.t, env.Sign(f.verifier, + head.WithIssuer(f.verifAddr.String()), + head.WithAudience("copier.example"), + head.WithConfirmation(f.subject.JKT()))) + }, + "forged": func(f *fixture, env *gobl.Envelope) { + require.NoError(f.t, env.Sign(dsig.NewES256Key(), + head.WithIssuer(f.verifAddr.String()), + head.WithAudience(f.subAddr.String()), + head.WithConfirmation(f.subject.JKT()))) + }, + } + for name, stamp := range ignored { + t.Run("ignores a verification "+name, func(t *testing.T) { + f := newFixture(t) + env := f.request(f.party(), f.subject) + stamp(f, env) + require.Equal(t, http.StatusAccepted, f.register(env), "registration proceeds unverified") + rec := f.record() + assert.Empty(t, rec.Verifier) + assert.Nil(t, rec.VerifiedAt) + }) + } +} - rec2, err := f.registry.Get(context.Background(), f.subAddr) +func TestVerifyDerivesFromStoredEnvelope(t *testing.T) { + // A provider countersignature received while the provider was not + // yet on the accepted list is picked up later by the verify + // command — the recovery path. + f := newFixture(t) + bare := domain.New(domain.Deps{ + Identity: f.lookup, + Registrations: f.registry, + Client: goblnet.NewClient(goblnet.WithFetcher(f.fetcher), goblnet.WithIdentity(f.lookup.Address(), f.lookup.PrivateKey)), + Sender: f.sender, + PublicBaseURL: "https://lookup.example", + Logger: discardLogger(), + }) + env := f.request(f.party(), f.subject) + f.counterSignAsVerifier(env, f.subject) + _, err := bare.Registrations().Register(context.Background(), env) require.NoError(t, err) - assert.Equal(t, goblnet.Address("kyc.example"), rec2.Verifier, "renewal keeps the verifier") - assert.NotNil(t, rec2.VerifiedAt, "renewal keeps the verification timestamp") + // Let the async delivery goroutine finish its Put before Verify + // reads and rewrites the record. + require.NotEmpty(t, f.waitForDeliveries(1)) + require.Empty(t, f.record().Verifier) + + // Simulate a record poisoned with a duplicate discovery link: the + // verify command heals it. + rec := f.record() + rec.CountersignedEnvelope.Head.Links = append(rec.CountersignedEnvelope.Head.Links, + rec.CountersignedEnvelope.Head.Links[0]) + require.NoError(t, f.registry.Put(context.Background(), rec)) - // The renewal countersignature asserts the preserved verifier and - // a fresh ~90 day expiry. - sigs := rec2.CountersignedEnvelope.Signatures - p, err := head.SignedPayload(sigs[len(sigs)-1]) + setup := domain.New(domain.Deps{ + Identity: f.lookup, + Registrations: f.registry, + Client: goblnet.NewClient(goblnet.WithFetcher(f.fetcher)), + Sender: f.sender, + Verifiers: []goblnet.Address{f.verifAddr}, + PublicBaseURL: "https://lookup.example", + Logger: discardLogger(), + }) + rec, err = setup.Registrations().Verify(context.Background(), f.subAddr) require.NoError(t, err) - assert.Equal(t, "kyc.example", p.Verifier) - assert.Greater(t, p.ExpiresAt, time.Now().Add(89*24*time.Hour).Unix()) - assert.Less(t, p.ExpiresAt, time.Now().Add(91*24*time.Hour).Unix()) + assert.Equal(t, f.verifAddr, rec.Verifier) + assert.NotNil(t, rec.VerifiedAt) + assert.Equal(t, 1, linkCount(rec.CountersignedEnvelope)) + require.NoError(t, rec.CountersignedEnvelope.Validate()) + p := f.authority(rec.CountersignedEnvelope) + assert.Equal(t, f.subject.JKT(), p.Confirmation.JKT) + assert.Equal(t, 1, sigCountBy(rec.CountersignedEnvelope, f.lookup.Address())) } -func TestPartiesLookupByUUID(t *testing.T) { +func TestVerifyWithoutAcceptedCountersignature(t *testing.T) { f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - body, _ := json.Marshal(env) - f.post(goblnet.InboxPath, body).Body.Close() //nolint:errcheck - _ = f.waitForDelivery(2 * time.Second) + require.Equal(t, http.StatusAccepted, f.register(f.request(f.party(), f.subject))) + require.NotEmpty(t, f.waitForDeliveries(1)) - resp := f.get("/parties/" + env.Head.UUID.String()) - defer resp.Body.Close() //nolint:errcheck - require.Equal(t, http.StatusOK, resp.StatusCode) - var got gobl.Envelope - require.NoError(t, json.NewDecoder(resp.Body).Decode(&got)) - assert.Equal(t, env.Head.UUID, got.Head.UUID) - require.Len(t, got.Signatures, 2) + _, err := f.setup().Registrations().Verify(context.Background(), f.subAddr) + require.Error(t, err) + assert.True(t, errors.Is(err, domain.ErrValidation)) } -func TestPartiesLookupByAddress(t *testing.T) { - f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - body, _ := json.Marshal(env) - f.post(goblnet.InboxPath, body).Body.Close() //nolint:errcheck +func TestInboxChecksTheSendersWho(t *testing.T) { + cases := []struct { + name string + err error + status int + }{ + {"missing", goblnet.ErrFetchFailed, http.StatusForbidden}, + {"receive-only", goblnet.ErrNoContent, http.StatusForbidden}, + {"deferred", goblnet.ErrPending, http.StatusForbidden}, + {"unavailable", fmt.Errorf("%w: HTTP 503", goblnet.ErrUnavailable), http.StatusServiceUnavailable}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + f := newFixture(t) + delete(f.fetcher.data, f.subAddr.WhoURL()) + f.fetcher.errs[f.subAddr.WhoURL()] = tc.err + assert.Equal(t, tc.status, f.register(f.request(f.party(), f.subject))) + }) + } +} - resp := f.get("/parties/" + string(f.subAddr)) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusOK, resp.StatusCode) +func TestInboxKeyUnavailable(t *testing.T) { + // The sender's key endpoint is unreachable: the lookup answers 503 + // so the sender retries, not a definitive 401. + f := newFixture(t) + env := f.request(f.party(), f.subject) + f.fetcher.errs[f.subAddr.KeyURL(f.subject.ID())] = fmt.Errorf("%w: HTTP 503", goblnet.ErrUnavailable) + assert.Equal(t, http.StatusServiceUnavailable, f.register(env)) } -func TestPartiesLookupNotFound(t *testing.T) { +func TestPartiesLookup(t *testing.T) { f := newFixture(t) - resp := f.get("/parties/nobody.example") - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusNotFound, resp.StatusCode) + env := f.request(f.party(), f.subject) + require.Equal(t, http.StatusAccepted, f.register(env)) + _ = f.waitForDeliveries(1) + + t.Run("by UUID", func(t *testing.T) { + resp := f.get("/parties/" + env.Head.UUID.String()) + defer resp.Body.Close() //nolint:errcheck + require.Equal(t, http.StatusOK, resp.StatusCode) + var got gobl.Envelope + require.NoError(t, json.NewDecoder(resp.Body).Decode(&got)) + assert.Equal(t, env.Head.UUID, got.Head.UUID) + }) + + t.Run("by address", func(t *testing.T) { + resp := f.get("/parties/" + string(f.subAddr)) + defer resp.Body.Close() //nolint:errcheck + assert.Equal(t, http.StatusOK, resp.StatusCode) + }) + + t.Run("not found", func(t *testing.T) { + resp := f.get("/parties/nobody.example") + defer resp.Body.Close() //nolint:errcheck + assert.Equal(t, http.StatusNotFound, resp.StatusCode) + }) } func TestKeysEndpoint(t *testing.T) { @@ -478,11 +702,13 @@ func TestWhoGet(t *testing.T) { var got gobl.Envelope require.NoError(t, json.NewDecoder(resp.Body).Decode(&got)) + assert.Equal(t, f.lookup.Address().URI(), got.Head.From) + assert.Equal(t, f.subAddr.URI(), got.Head.To, "addressed to the requester") require.Len(t, got.Signatures, 1) p, err := head.SignedPayload(got.Signatures[0]) require.NoError(t, err) assert.Equal(t, f.lookup.Address().String(), p.Iss) - assert.Empty(t, p.Aud, "GET who response is not bound to a caller") + assert.Equal(t, f.subAddr.String(), p.Aud, "signed for the requester") } func TestRequestAuth(t *testing.T) { @@ -494,14 +720,6 @@ func TestRequestAuth(t *testing.T) { assert.Equal(t, http.StatusUnauthorized, resp.StatusCode) }) - t.Run("inbox without a token is rejected", func(t *testing.T) { - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - body, _ := json.Marshal(env) - resp := f.do(http.MethodPost, goblnet.InboxPath, body, "") - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusUnauthorized, resp.StatusCode) - }) - t.Run("non-bearer scheme is rejected", func(t *testing.T) { resp := f.do(http.MethodGet, goblnet.WhoPath, nil, "Basic dXNlcjpwdw==") defer resp.Body.Close() //nolint:errcheck @@ -517,14 +735,21 @@ func TestRequestAuth(t *testing.T) { }) t.Run("token from an unresolvable issuer is rejected", func(t *testing.T) { - other := dsig.NewES256Key() - token, err := goblnet.NewToken(other, "unknown.example", f.lookup.Address(), 0) + token, err := goblnet.NewToken(dsig.NewES256Key(), "unknown.example", f.lookup.Address(), 0) require.NoError(t, err) resp := f.do(http.MethodGet, goblnet.WhoPath, nil, "Bearer "+token) defer resp.Body.Close() //nolint:errcheck assert.Equal(t, http.StatusUnauthorized, resp.StatusCode) }) + t.Run("token issuer key unavailable", func(t *testing.T) { + f := newFixture(t) + f.fetcher.errs[f.subAddr.KeyURL(f.subject.ID())] = fmt.Errorf("%w: HTTP 503", goblnet.ErrUnavailable) + resp := f.get(goblnet.WhoPath) + defer resp.Body.Close() //nolint:errcheck + assert.Equal(t, http.StatusServiceUnavailable, resp.StatusCode) + }) + t.Run("keys and parties stay open", func(t *testing.T) { resp := f.do(http.MethodGet, goblnet.KeyPath(f.lookup.PrivateKey.ID()), nil, "") defer resp.Body.Close() //nolint:errcheck @@ -532,19 +757,6 @@ func TestRequestAuth(t *testing.T) { }) } -func TestInboxRejectsPendingWho(t *testing.T) { - // A registrant deferring its own /who disclosure (202) cannot be - // confirmed as a sending participant. - f := newFixture(t) - f.fetcher.errs[f.subAddr.WhoURL()] = goblnet.ErrPending - - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusForbidden, resp.StatusCode) -} - func TestHealth(t *testing.T) { f := newFixture(t) resp := f.get("/healthz") @@ -552,300 +764,18 @@ func TestHealth(t *testing.T) { assert.Equal(t, http.StatusOK, resp.StatusCode) } -func TestInboxRejectsSenderWithoutWho(t *testing.T) { - f := newFixture(t) - // The sender's key resolves, but its GET /who does not. - delete(f.fetcher.data, f.subAddr.WhoURL()) - - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusForbidden, resp.StatusCode) -} - -func TestInboxRejectsReceiveOnlySender(t *testing.T) { - f := newFixture(t) - // A 204 from the sender's who marks a receive-only account, which - // cannot register as a sender. - delete(f.fetcher.data, f.subAddr.WhoURL()) - f.fetcher.errs[f.subAddr.WhoURL()] = goblnet.ErrNoContent - - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusForbidden, resp.StatusCode) -} - -func TestRequestAuthUnavailable(t *testing.T) { - // The requester's key endpoint is unreachable: the lookup answers - // 503 so the caller retries, not a definitive 401. - f := newFixture(t) - f.fetcher.errs[f.subAddr.KeyURL(f.subject.ID())] = fmt.Errorf("%w: HTTP 503", goblnet.ErrUnavailable) - - resp := f.get(goblnet.WhoPath) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusServiceUnavailable, resp.StatusCode) -} - -func TestInboxWhoUnavailable(t *testing.T) { - // A transient outage resolving the sender's who must answer 503 — - // a 4xx would make the sender stop retrying its registration. - f := newFixture(t) - f.fetcher.errs[f.subAddr.WhoURL()] = fmt.Errorf("%w: HTTP 503", goblnet.ErrUnavailable) - - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusServiceUnavailable, resp.StatusCode) -} - -// counterSignAsVerifier stamps the fixture verifier's countersignature -// onto env, as a provider would after completing its checks. -func (f *fixture) counterSignAsVerifier(env *gobl.Envelope) { - f.t.Helper() - require.NoError(f.t, env.Sign(f.verifier, - head.WithIssuer(f.verifAddr.String()), - head.WithAudience(f.subAddr.String()), - head.WithExpiration(time.Now().Add(365*24*time.Hour)))) -} - -func TestAutoVerifyOnRegistration(t *testing.T) { - // A registration arriving with an accepted provider's - // countersignature is verified from the start: the lookup's own - // countersignature names the verifier without operator action. - f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - f.counterSignAsVerifier(env) - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - require.Equal(t, http.StatusAccepted, resp.StatusCode) - - rec, err := f.registry.Get(context.Background(), f.subAddr) - require.NoError(t, err) - assert.Equal(t, f.verifAddr, rec.Verifier) - assert.NotNil(t, rec.VerifiedAt) - - // The lookup countersignature carries the verifier claim. - sigs := rec.CountersignedEnvelope.Signatures - p, err := head.SignedPayload(sigs[len(sigs)-1]) - require.NoError(t, err) - assert.Equal(t, f.verifAddr.String(), p.Verifier) -} - -func TestAutoVerifyRejectsForgedCountersignature(t *testing.T) { - // A countersignature claiming the provider's address but made with - // a different key must not be named: consumers would reject it. - f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - forged := dsig.NewES256Key() - require.NoError(t, env.Sign(forged, - head.WithIssuer(f.verifAddr.String()), - head.WithAudience(f.subAddr.String()))) - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - require.Equal(t, http.StatusAccepted, resp.StatusCode, "registration proceeds unverified") - - rec, err := f.registry.Get(context.Background(), f.subAddr) - require.NoError(t, err) - assert.Empty(t, rec.Verifier) - assert.Nil(t, rec.VerifiedAt) -} - -func TestVerifyDerivesFromStoredEnvelope(t *testing.T) { - // A provider countersignature received while the provider was not - // yet on the accepted list is picked up later by the verify - // command — the recovery path. - f := newFixture(t) - - // A parallel setup with no accepted verifiers registers the party - // with the countersignature aboard but unverified. - bare := domain.New(domain.Deps{ - Identity: f.lookup, - Registrations: f.registry, - Client: goblnet.NewClient(goblnet.WithFetcher(f.fetcher)), - Sender: f.sender, - PublicBaseURL: "https://lookup.example", - Logger: discardLogger(), - }) - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - f.counterSignAsVerifier(env) - _, err := bare.Registrations().Register(context.Background(), env) - require.NoError(t, err) - // Let the async delivery goroutine finish its Put before Verify - // reads and rewrites the record. - require.NotEmpty(t, f.waitForDelivery(2*time.Second)) - rec, err := f.registry.Get(context.Background(), f.subAddr) - require.NoError(t, err) - require.Empty(t, rec.Verifier) - - // The fixture setup accepts verify.example: Verify derives it. - f2 := domain.New(domain.Deps{ +// setup returns a domain setup sharing the fixture's store, sender and +// fetcher, accepting the fixture's verifier. +func (f *fixture) setup() *domain.Setup { + return domain.New(domain.Deps{ Identity: f.lookup, Registrations: f.registry, - Client: goblnet.NewClient(goblnet.WithFetcher(f.fetcher)), + Client: goblnet.NewClient(goblnet.WithFetcher(f.fetcher), goblnet.WithIdentity(f.lookup.Address(), f.lookup.PrivateKey)), Sender: f.sender, Verifiers: []goblnet.Address{f.verifAddr}, PublicBaseURL: "https://lookup.example", Logger: discardLogger(), }) - rec, err = f2.Registrations().Verify(context.Background(), f.subAddr) - require.NoError(t, err) - assert.Equal(t, f.verifAddr, rec.Verifier) - assert.NotNil(t, rec.VerifiedAt) -} - -func TestVerifyWithoutAcceptedCountersignature(t *testing.T) { - f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - body, _ := json.Marshal(env) - f.post(goblnet.InboxPath, body).Body.Close() //nolint:errcheck - - setup := domain.New(domain.Deps{ - Identity: f.lookup, - Registrations: f.registry, - Client: goblnet.NewClient(goblnet.WithFetcher(f.fetcher)), - Sender: f.sender, - Verifiers: []goblnet.Address{f.verifAddr}, - PublicBaseURL: "https://lookup.example", - Logger: discardLogger(), - }) - _, err := setup.Registrations().Verify(context.Background(), f.subAddr) - require.Error(t, err) - assert.True(t, errors.Is(err, domain.ErrValidation)) -} - -// counterSignAsLookup stamps the lookup's own countersignature, as -// Register does when it endorses a registration. -func (f *fixture) counterSignAsLookup(env *gobl.Envelope) { - f.t.Helper() - require.NoError(f.t, env.Sign(f.lookup.PrivateKey, - head.WithIssuer(f.lookup.Address().String()), - head.WithAudience(f.subAddr.String()), - head.WithExpiration(time.Now().Add(90*24*time.Hour)))) -} - -func TestReturnedEnvelopeFromVerifier(t *testing.T) { - // The §5.3 round trip: the subject registered (audience-bound - // signature), the lookup countersigned, and a verification - // provider countersigned the exact envelope and posted it back. - // The delivery binds through the subject's original registration - // signature, the lookup's own countersignature still verifies, - // and auto-verify names the provider. - f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - f.counterSignAsLookup(env) - f.counterSignAsVerifier(env) - - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - require.Equal(t, http.StatusAccepted, resp.StatusCode) - - rec, err := f.registry.Get(context.Background(), f.subAddr) - require.NoError(t, err) - assert.Equal(t, f.verifAddr, rec.Verifier, "provider countersignature auto-verifies") - assert.NotNil(t, rec.VerifiedAt) -} - -func TestReturnedEnvelopeWithForgedOwnCountersignature(t *testing.T) { - // A signature claiming to be this lookup's but made with another - // key means the envelope is not what the lookup endorsed. - f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - forged := dsig.NewES256Key() - require.NoError(t, env.Sign(forged, - head.WithIssuer(f.lookup.Address().String()), - head.WithAudience(f.subAddr.String()))) - - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusUnauthorized, resp.StatusCode) -} - -func TestWhoServesEndorsedEnvelope(t *testing.T) { - // The sender publishes the endorsed envelope exactly as delivered: - // its registration signature (audience-bound) first, the lookup's - // countersignature, and an audience-free publication signature - // appended at serve time. The eligibility lookup must accept it — - // this is the published shape every registered node converges on. - f := newFixture(t) - published := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - f.counterSignAsLookup(published) - require.NoError(t, published.Sign(f.subject, head.WithIssuer(f.subAddr.String()))) - who, _ := json.Marshal(published) - f.fetcher.data[f.subAddr.WhoURL()] = who - - env := f.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String()) - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusAccepted, resp.StatusCode) -} - -func TestRegistrationSignatureMayFollowPublicationSignature(t *testing.T) { - // A subject that signs publication-first (no audience) and appends - // the registration signature binds just as well: the audience is - // searched, not read from the first signature. - f := newFixture(t) - party := &org.Party{ - Name: "Alice", - Endpoints: []*org.Endpoint{{URI: f.subAddr.URI()}}, - } - env, err := gobl.Envelop(party) - require.NoError(t, err) - require.NoError(t, env.Sign(f.subject, head.WithIssuer(f.subAddr.String()))) - require.NoError(t, env.Sign(f.subject, - head.WithIssuer(f.subAddr.String()), - head.WithAudience(f.lookup.Address().String()))) - - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusAccepted, resp.StatusCode) -} - -func TestInboxIgnoresSignatureOrder(t *testing.T) { - // The subject comes from the party document, never from signature - // position: a permuted returned envelope registers identically. - f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), "") - f.counterSignAsLookup(env) - f.counterSignAsVerifier(env) - env.Signatures[0], env.Signatures[2] = env.Signatures[2], env.Signatures[0] - - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - require.Equal(t, http.StatusAccepted, resp.StatusCode) - - rec, err := f.registry.Get(context.Background(), f.subAddr) - require.NoError(t, err) - assert.Equal(t, f.verifAddr, rec.Verifier) -} - -func TestInboxRejectsForeignPartyDocument(t *testing.T) { - // An envelope whose party document declares someone else's address - // has no valid self-signature by its subject: nobody can register - // a party document for an address they do not control. - f := newFixture(t) - party := &org.Party{ - Name: "Impostor", - Endpoints: []*org.Endpoint{{URI: goblnet.Address("victim.example").URI()}}, - } - env, err := gobl.Envelop(party) - require.NoError(t, err) - require.NoError(t, env.Sign(f.subject, head.WithIssuer(f.subAddr.String()))) - - body, _ := json.Marshal(env) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusUnauthorized, resp.StatusCode) } // linkCount counts the lookup discovery links on an envelope. @@ -859,71 +789,7 @@ func linkCount(env *gobl.Envelope) int { return n } -func TestReturnedEnvelopeKeepsSingleDiscoveryLink(t *testing.T) { - // The verifier round trip re-registers an envelope that already - // carries the discovery link from the first round: the link must - // be restamped, not duplicated — duplicate link keys make the - // envelope invalid, and the subject's inbox would 422 the - // delivery. - f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), "") - body, _ := json.Marshal(env) - f.post(goblnet.InboxPath, body).Body.Close() //nolint:errcheck - sent := f.waitForDelivery(2 * time.Second) - require.Len(t, sent, 1) - require.Equal(t, 1, linkCount(sent[0].env)) - - // The subject forwards the round-1 envelope (link aboard) to the - // verifier, which countersigns and posts it back. - returned := sent[0].env - f.counterSignAsVerifier(returned) - body, _ = json.Marshal(returned) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - require.Equal(t, http.StatusAccepted, resp.StatusCode) - - rec, err := f.registry.Get(context.Background(), f.subAddr) - require.NoError(t, err) - assert.Equal(t, 1, linkCount(rec.CountersignedEnvelope), "restamped, not duplicated") - require.NoError(t, rec.CountersignedEnvelope.Validate(), "delivered envelope must validate at the subject's inbox") - assert.Equal(t, f.verifAddr, rec.Verifier) -} - -func TestVerifyHealsDuplicateDiscoveryLinks(t *testing.T) { - // Records poisoned by the pre-fix duplicate append must recover - // through the verify command: the stale links are stripped before - // countersigning, which would otherwise fail post-sign validation - // and wipe the envelope's signatures. - f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), "") - f.counterSignAsVerifier(env) - body, _ := json.Marshal(env) - f.post(goblnet.InboxPath, body).Body.Close() //nolint:errcheck - require.NotEmpty(t, f.waitForDelivery(2*time.Second)) - - rec, err := f.registry.Get(context.Background(), f.subAddr) - require.NoError(t, err) - // Simulate the poisoned stored state: a second identical link. - rec.CountersignedEnvelope.Head.Links = append(rec.CountersignedEnvelope.Head.Links, - rec.CountersignedEnvelope.Head.Links[0]) - require.NoError(t, f.registry.Put(context.Background(), rec)) - - setup := domain.New(domain.Deps{ - Identity: f.lookup, - Registrations: f.registry, - Client: goblnet.NewClient(goblnet.WithFetcher(f.fetcher), goblnet.WithAuthorities("lookup.example")), - Sender: f.sender, - Verifiers: []goblnet.Address{f.verifAddr}, - PublicBaseURL: "https://lookup.example", - Logger: discardLogger(), - }) - rec, err = setup.Registrations().Verify(context.Background(), f.subAddr) - require.NoError(t, err) - assert.Equal(t, 1, linkCount(rec.CountersignedEnvelope)) - require.NoError(t, rec.CountersignedEnvelope.Validate()) -} - -// sigCountBy counts valid-looking signatures by issuer address. +// sigCountBy counts signatures by issuer address. func sigCountBy(env *gobl.Envelope, addr goblnet.Address) int { n := 0 for _, sig := range env.Signatures { @@ -935,32 +801,3 @@ func sigCountBy(env *gobl.Envelope, addr goblnet.Address) int { } return n } - -func TestCounterSignSupersedesOwnSignatures(t *testing.T) { - // The verifier round trip re-registers an envelope already - // carrying the registration round's countersignature: the fresh - // one replaces it (spec §5.3), leaving exactly three signatures — - // subject, lookup, verifier. - f := newFixture(t) - env := f.signPartyEnvelope(f.subAddr.String(), "") - body, _ := json.Marshal(env) - f.post(goblnet.InboxPath, body).Body.Close() //nolint:errcheck - sent := f.waitForDelivery(2 * time.Second) - require.Len(t, sent, 1) - - returned := sent[0].env - f.counterSignAsVerifier(returned) - body, _ = json.Marshal(returned) - resp := f.post(goblnet.InboxPath, body) - defer resp.Body.Close() //nolint:errcheck - require.Equal(t, http.StatusAccepted, resp.StatusCode) - - rec, err := f.registry.Get(context.Background(), f.subAddr) - require.NoError(t, err) - final := rec.CountersignedEnvelope - require.Len(t, final.Signatures, 3, "subject + lookup + verifier, nothing stale") - assert.Equal(t, 1, sigCountBy(final, f.lookup.Address())) - assert.Equal(t, 1, sigCountBy(final, f.subAddr)) - assert.Equal(t, 1, sigCountBy(final, f.verifAddr)) - assert.Equal(t, f.verifAddr, rec.Verifier) -} diff --git a/internal/interfaces/web/who.go b/internal/interfaces/web/who.go index ff49ff2..e08b669 100644 --- a/internal/interfaces/web/who.go +++ b/internal/interfaces/web/who.go @@ -7,18 +7,18 @@ import ( "github.com/invopop/gobl.lookup/internal/domain" ) -// whoCacheControl allows the authenticated caller to cache the static -// party envelope briefly; the response requires authorization so it +// whoCacheControl allows the authenticated caller to cache its party +// envelope briefly; the response is signed for the requester so it // must not land in shared caches. The TTL bounds how quickly key or // party changes are observed by verifiers. const whoCacheControl = "private, max-age=300" // handleWho serves the lookup's identity to an authenticated -// requester: the party envelope self-signed by the lookup, the same -// static document for every authorized caller. +// requester: the party envelope from the lookup to the requester, +// signed for it. func handleWho(s *domain.Setup, log *slog.Logger) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { - body, err := s.Identity().PartyEnvelope() + body, err := s.Identity().PartyEnvelope(requesterFrom(r.Context())) if err != nil { log.Error("who.sign_failed", "error", err.Error()) http.Error(w, "could not prepare identity", http.StatusInternalServerError) From 1c8e64329d79dbe54164b3656b469ade31f9bff7 Mon Sep 17 00:00:00 2001 From: Sam Lown Date: Fri, 13 Nov 2026 22:57:02 +0000 Subject: [PATCH 02/11] Use gobl from invopop/gobl#1036 Co-Authored-By: Claude Opus 5.5 --- go.mod | 4 +--- go.sum | 2 ++ 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/go.mod b/go.mod index 0d4d4b8..379099e 100644 --- a/go.mod +++ b/go.mod @@ -5,7 +5,7 @@ go 1.25.0 require ( github.com/go-kivik/kivik/v4 v4.5.2 github.com/invopop/couch v0.1.0 - github.com/invopop/gobl v0.504.1-0.20260811215754-c231ee2feae5 + github.com/invopop/gobl v0.512.1-0.20261113224301-2cdeefbda13a github.com/magefile/mage v1.17.2 github.com/spf13/cobra v1.10.2 github.com/stretchr/testify v1.11.1 @@ -34,5 +34,3 @@ require ( golang.org/x/text v0.38.0 // indirect gopkg.in/yaml.v3 v3.0.1 // indirect ) - -replace github.com/invopop/gobl => ../gobl diff --git a/go.sum b/go.sum index bf1cefb..84fe487 100644 --- a/go.sum +++ b/go.sum @@ -34,6 +34,8 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/invopop/couch v0.1.0 h1:ctMKLeIxnab9KW11KtEAQSl7RzGgMxndavLphx99LpY= github.com/invopop/couch v0.1.0/go.mod h1:xzBNVglDnLcpf1Z9BJxiIG1liESSIkMuvIczSl4zcls= +github.com/invopop/gobl v0.512.1-0.20261113224301-2cdeefbda13a h1:ZOnidhzJBDS+5JAAw67twrNj4N8czVlTADDPOVXP8ac= +github.com/invopop/gobl v0.512.1-0.20261113224301-2cdeefbda13a/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= github.com/invopop/jsonschema v0.14.0 h1:MHQqLhvpNUZfw+hM3AZDYK7jxO8FZoQeQM77g8iyZjg= github.com/invopop/jsonschema v0.14.0/go.mod h1:ygm6C2EaVNMBDPpaPlnOA2pFAxBnxGjFlMZABxm9n2I= github.com/invopop/yaml v0.3.1 h1:f0+ZpmhfBSS4MhG+4HYseMdJhoeeopbSKbq5Rpeelso= From 336bac5e5511206c14c8f8ae4a3eaf0a1934f623 Mon Sep 17 00:00:00 2001 From: Sam Lown Date: Fri, 13 Nov 2026 23:06:57 +0000 Subject: [PATCH 03/11] Use gobl from invopop/gobl#1036 requiring verifier cnf Co-Authored-By: Claude Opus 5.5 --- go.mod | 2 +- go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/go.mod b/go.mod index 379099e..e864ffe 100644 --- a/go.mod +++ b/go.mod @@ -5,7 +5,7 @@ go 1.25.0 require ( github.com/go-kivik/kivik/v4 v4.5.2 github.com/invopop/couch v0.1.0 - github.com/invopop/gobl v0.512.1-0.20261113224301-2cdeefbda13a + github.com/invopop/gobl v0.512.1-0.20261113230617-62e54e64146b github.com/magefile/mage v1.17.2 github.com/spf13/cobra v1.10.2 github.com/stretchr/testify v1.11.1 diff --git a/go.sum b/go.sum index 84fe487..901965f 100644 --- a/go.sum +++ b/go.sum @@ -34,8 +34,8 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/invopop/couch v0.1.0 h1:ctMKLeIxnab9KW11KtEAQSl7RzGgMxndavLphx99LpY= github.com/invopop/couch v0.1.0/go.mod h1:xzBNVglDnLcpf1Z9BJxiIG1liESSIkMuvIczSl4zcls= -github.com/invopop/gobl v0.512.1-0.20261113224301-2cdeefbda13a h1:ZOnidhzJBDS+5JAAw67twrNj4N8czVlTADDPOVXP8ac= -github.com/invopop/gobl v0.512.1-0.20261113224301-2cdeefbda13a/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= +github.com/invopop/gobl v0.512.1-0.20261113230617-62e54e64146b h1:8E7dpk2LPgRsN5XZBUs3E16Zs7SwcX5MCsciA4DZzHg= +github.com/invopop/gobl v0.512.1-0.20261113230617-62e54e64146b/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= github.com/invopop/jsonschema v0.14.0 h1:MHQqLhvpNUZfw+hM3AZDYK7jxO8FZoQeQM77g8iyZjg= github.com/invopop/jsonschema v0.14.0/go.mod h1:ygm6C2EaVNMBDPpaPlnOA2pFAxBnxGjFlMZABxm9n2I= github.com/invopop/yaml v0.3.1 h1:f0+ZpmhfBSS4MhG+4HYseMdJhoeeopbSKbq5Rpeelso= From 2cd9768b66fd88c5c5d4b9ffba7a545b355ef527 Mon Sep 17 00:00:00 2001 From: Sam Lown Date: Sun, 15 Nov 2026 13:29:22 +0000 Subject: [PATCH 04/11] Register only verified parties Registrations need a verifier countersignature binding the subject's key; without one the request is rejected with 403, or 503 when the verifier key is unavailable. The verify command is removed. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 3 +- README.md | 117 +++++++++++----------- cmd/gobl.lookup/main.go | 3 +- cmd/gobl.lookup/verify.go | 78 --------------- go.mod | 2 +- go.sum | 4 +- internal/config/config.go | 7 +- internal/domain/identity.go | 13 ++- internal/domain/identity_test.go | 9 +- internal/domain/registrations.go | 113 ++++------------------ internal/interfaces/web/web_test.go | 144 +++++++++------------------- 11 files changed, 143 insertions(+), 350 deletions(-) delete mode 100644 cmd/gobl.lookup/verify.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b28234..def20ec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,8 @@ ### Changed - Registrations follow the latest GOBL Net spec. A request is an ordinary delivery from the subject to the lookup, confirmed by its signature for the lookup, and needs no request token; the subject is its `from` address. The lookup drops the request signature, countersigns with a `cnf` claim binding the subject's key, and addresses the envelope back to the subject. -- The lookup keeps each address's key lineage (`Registration.Lineage`). A request signed with the current and a new key rolls over to the new key; one signed only with an unknown key starts a new lineage. A verifier is named only when its countersignature binds, with `cnf`, a key in the lineage, so rollovers keep a party verified and a new holder of an address cannot inherit its verification. +- The lookup keeps each address's key lineage (`Registration.Lineage`). A request signed with the current and a new key rolls over to the new key; one signed only with an unknown key starts a new lineage, and needs a verification for that key. Rollovers need no new verification, and a new holder of an address cannot inherit its verification. +- The lookup registers only verified parties: a registration needs a countersignature from an accepted verifier binding, with `cnf`, a key in the subject's lineage, and is rejected with `403` without one (`503` when the verifier's key cannot be fetched). The `gobl.lookup verify` command is removed; a subject registers again instead. - Verifiers are no longer accepted delivering to the lookup on a subject's behalf; the subject registers again with the verified envelope. The renewal rule based on an unchanged digest is replaced by the lineage check. - `GET /.well-known/gobl/who` answers with the lookup's party envelope addressed and signed for the requester. - Deliveries to subjects carry no request token. diff --git a/README.md b/README.md index fc5ca05..7aab1b2 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,12 @@ # gobl.lookup A reference [GOBL Net](https://github.com/invopop/gobl/blob/net/net/README.md) -**Authority** registry service. Accepts party registrations from -GOBL Net nodes, countersigns each party envelope as the network's -default registration Authority (adding a `verifier` claim once the -party passes KYC/KYB), and posts the countersigned envelope back to -the sender's own inbox. +**Authority** registry service: a public index of verified GOBL Net +parties. Accepts registrations from GOBL Net nodes whose party +envelope carries a countersignature from an accepted KYC/KYB +verifier, countersigns each as the network's default registration +Authority with a `verifier` claim naming it, and posts the +countersigned envelope back to the sender's own inbox. > ⚠️ **EXPERIMENTAL** — GOBL Net is under active development. The > wire protocol may change without notice. @@ -16,6 +17,10 @@ Copyright 2026 [Invopop S.L.](https://invopop.com). ## How registration works +The lookup only accepts verified participants: a party gets its +envelope countersigned by a verifier first ([How verification +works](#how-verification-works)), and then registers it. + 1. A GOBL Net node (e.g. a `gobl.dev` operator at `alice.example`) sends its party envelope to lookup's `/.well-known/gobl/inbox` as an ordinary delivery: `from` is `gobl:alice.example`, `to` is @@ -28,18 +33,21 @@ Copyright 2026 [Invopop S.L.](https://invopop.com). `204 No Content` marks a receive-only account and rejects the registration with `403 Forbidden`. 3. Lookup updates Alice's [key lineage](#key-lineage) from the keys - that signed the request, drops Alice's request signature, + that signed the request, and requires a valid countersignature + for `alice.example` from an accepted verifier whose `cnf` names a + key in the lineage; without one it rejects the registration with + `403 Forbidden`. It drops Alice's request signature, countersigns as the Authority (`iss=lookup.gobl.org`, `aud=alice.example`, `cnf` naming Alice's current key, `exp` = 90 - days out), and addresses the envelope back (`from` + days out, `verifier` naming the verifier), and addresses the envelope back (`from` `gobl:lookup.gobl.org`, `to` `gobl:alice.example`). It persists the record and acknowledges the POST with `202 Accepted`. 4. Lookup delivers the countersigned envelope to `https://alice.example/.well-known/gobl/inbox`. 5. Alice publishes the envelope at her `/who`, signing each response for its requester with the key the countersignature binds. Any - GOBL Net participant can now confirm her registration with - `net.Client.VerifyAuthority` / `net.Client.VerifySender`. + GOBL Net participant can now confirm her identity with + `net.Client.VerifyEndorsement` / `net.Client.VerifySender`. No new protocol endpoints: registration uses the standard GOBL Net `/inbox` in both directions. @@ -52,8 +60,8 @@ then, Let's Encrypt style: submitting the envelope they hold, countersignatures and all, signed for the lookup. The lookup supersedes its own earlier countersignature. Changing the party document changes its digest, so a verifier's countersignature on the -old document no longer applies and the registration starts -unverified. +old document no longer applies and the party needs a new +verification before it can renew. ### Key lineage @@ -65,37 +73,34 @@ sign a registration request decide what happens: |--------------------------------------|------------------------------------------------------------| | the current key (or a first key) | renewal (or first registration): the key stays bound | | the current key and a new key | rollover: the new key joins the lineage and is bound | -| only a key that is not the current one | a lost key or a new holder: a new lineage starts | +| only a key that is not the current one | a lost key or a new holder: a new lineage starts, if a verification binds that key | | two keys at a first registration | the key a verification binds starts the lineage, then rolls over | -The lookup names a verifier only when its countersignature binds, -with `cnf`, a key in the current lineage. A rollover therefore keeps -a party verified with no work from its verifier, while a new holder -of a lapsed domain can register the address but cannot be verified -as its previous holder. Parties should rotate keys at renewal. +The lookup registers a party only when a verifier's countersignature +binds, with `cnf`, a key in the current lineage. A rollover therefore +needs no work from the verifier, while a lost key, or a new holder of +a lapsed domain, needs a new verification for its key. Parties should +rotate keys at renewal. ## How verification works > **Status: partial.** The registry side is implemented: the -> accepted-verifier list (`--verifiers` / `VERIFIERS`), auto-verify -> on registrations carrying a provider countersignature, and the -> `gobl.lookup verify` recovery command. The web flow, email OTP, +> accepted-verifier list (`--verifiers` / `VERIFIERS`), and the +> check for a provider countersignature on every registration. The web flow, email OTP, > and verifier session hand-off are not yet implemented — see the > gap list at the end of this section. -Verification upgrades a *registered* identity to *verified* by -adding two things to the party envelope: a countersignature from a -KYC/KYB provider ("verifier", e.g. `didit.gobl.org`), and a fresh -lookup countersignature carrying the `verifier` claim that points -at it. The registry orchestrates; the verifier performs and charges +Verification comes before registration. It adds a countersignature +from a KYC/KYB provider ("verifier", e.g. `didit.gobl.org`) to the +party envelope, and the lookup's countersignature then carries the +`verifier` claim that points at it. The registry orchestrates; the verifier performs and charges for the actual checks; the protocol carries the results as plain inbox deliveries. -1. **Start.** A representative of the registered party opens +1. **Start.** A representative of the party opens `https://lookup.gobl.org/verify/
`. The address MUST - already be registered (unregistered addresses are pointed at - the registration flow first) and its party MUST publish at - least one email address — the flow has no other way to reach a + serve its party envelope at `GET /who`, as registration requires + anyway, and its party MUST publish at least one email address — the flow has no other way to reach a human connected to the party. 2. **Email OTP.** Lookup sends a one-time code to an email chosen from the party's published `emails`. This does not verify the @@ -112,9 +117,9 @@ inbox deliveries. performed, price, and countersignature lifetime — so the trust a receiver will later infer from the verifier's name is inspectable up front. -4. **Session hand-off.** Lookup POSTs the party's **stored, - countersigned envelope** to the verifier's session API in the - background. Sending the stored envelope pins the verification to +4. **Session hand-off.** Lookup fetches the party envelope from the + address's `GET /who` and POSTs it to the verifier's session API in + the background. Sending that envelope pins the verification to an exact `uuid` + `dig`: the verifier MUST countersign those bytes, so the checks and the eventual signature cannot drift apart. The verifier answers with an @@ -141,41 +146,35 @@ inbox deliveries. deliver to the lookup: GOBL Net has no forwarding. Failed or abandoned sessions simply never produce a countersignature; sessions expire after a few days. -7. **Renew with the verification.** The subject registers again - with the envelope it received. Lookup finds the valid +7. **Register with the verification.** The subject registers with + the envelope it received. Lookup finds the valid countersignature from a verifier on its trusted list, checks its `cnf` names a key in the subject's lineage, and countersigns - with `verifier=` — the same act as - `gobl.lookup verify`, without the operator. The stored record - gains `verifier` + `verified_at`. + with `verifier=`. The stored record holds + `verifier` + `verified_at`. 8. **Deliver and publish.** The countersigned envelope (verifier countersignature and lookup countersignature naming the verifier) is delivered to the subject's inbox, which publishes it at its `/who`; only then do receivers see the verified status. -Renewals keep the verifier as long as the subject presents the -verifier's countersignature and it binds a key in the lineage; -changed party data, or a lineage restarted by a lost key, drops it -and the party goes through verification again. +Renewals need the subject to present the verifier's +countersignature, binding a key in the lineage; changed party data, +or a lineage restarted by a lost key, needs a new verification +before the party can renew. **Implementation gaps** (in rough order): - Policy/pricing metadata for the accepted-verifier list (the addresses themselves are configured via `--verifiers` / - `VERIFIERS`, and step 7's auto-verify is implemented: a - registration or renewal carrying a valid countersignature from an - accepted provider is verified on arrival, with the crypto checked - against the provider's published key first). + `VERIFIERS`, and step 7 is implemented, with the crypto checked + against the provider's published key). - The `/verify/
` web flow: OTP issue/check, verifier picker, redirect, and a status page for pending sessions. - The verifier session API contract (step 4): create-session request/response shape shared with bridge implementations like `didit.gobl.org`, including session expiry and failure callbacks. -- A `head.Link` on the registration delivery pointing the subject - at `verify/
`, so every registered party discovers the - upgrade path. ## Architecture @@ -188,14 +187,14 @@ internal/ domain/ business logic, orchestrated by domain.Setup domain.go Setup: wires repos + services together identity.go Identity service: countersign, /who identity, keys - registrations.go Registrations service: register, verify, find + registrations.go Registrations service: register, find errors.go typed domain errors (mapped to HTTP statuses) models/ data structures (Registration, Identity) repos/ persistence (CouchDB + in-memory; identity loader) delivery/ outbound Sender (HTTP POST to a subject's inbox) interfaces/ web/ HTTP transport: thin handlers over domain.Setup -cmd/gobl.lookup/ CLI (init / serve / verify / version) +cmd/gobl.lookup/ CLI (init / serve / version) ``` Handlers in `interfaces/web` parse the request, delegate to a domain @@ -221,7 +220,7 @@ issuer's key endpoint is unreachable (retry). The response is addressed and signed for the token's issuer. Inbox deliveries carry no token: the registration subject is the envelope's `from`, confirmed by its signature for the lookup. Key discovery stays open, -and `/parties` remains an open directory of registered — hence +and `/parties` remains an open directory of verified — hence deliberately public — identities. The lookup's own sender `GET /who` eligibility check authenticates as `lookup.gobl.org`; its deliveries carry no token. Authenticated requests are logged with the @@ -285,7 +284,6 @@ preserve the audit trail across re-registrations. |--------------------------------|-----------------------------------------------------------------------------------------| | `gobl.lookup init ` | Scaffold keypair + `party.json` + `keys/.json`. | | `gobl.lookup serve` | Run the HTTP server (terminates HTTP only; deploy behind a TLS proxy). | -| `gobl.lookup verify
` | Recovery: re-derive verified status from the accepted-provider countersignatures already on the stored envelope and re-deliver. Normally automatic at registration. | | `gobl.lookup version` | Print service + core gobl versions. | The top-level `--json` flag switches operator logs from text to @@ -293,7 +291,7 @@ JSON on stderr. ## Configuration -`serve` and `verify` read their configuration from the environment +`serve` reads its configuration from the environment (the mechanism the cluster uses to inject config and secrets); the equivalent flags override the environment for local use. @@ -321,17 +319,16 @@ arrives from a secret independently of the host). - **Renewal and key changes**: a request signed with the current key renews, stamping a fresh 90-day countersignature; one signed with - the current and a new key rolls over to the new key. Either keeps - `verifier` and `verified_at` while the request carries a - verification bound to a key in the lineage. Changed party data, or - a request signed only with an unknown key, drops the `verifier` - and clears `verified_at`. Records without a lineage (registered - before key lineage) need one fresh registration. Audit trail lives + the current and a new key rolls over to the new key. Either needs + the request to carry a verification bound to a key in the + lineage. Changed party data, or a request signed only with an + unknown key, needs a new verification. Records without a lineage + (registered before key lineage) need one fresh registration. Audit trail lives in CouchDB revisions. - **Delivery failures**: the inbox handler responds `202` once the record is persisted; delivery to the sender's `/inbox` happens asynchronously. Failures land on `Record.LastDeliveryError`; - re-running `gobl.lookup verify` retries. + the subject registers again to have it re-delivered. - **Sender eligibility**: registrations are only accepted from addresses that serve a verifiable `GET /who` identity of their own. Receive-only accounts (whose `/who` returns `204`) cannot diff --git a/cmd/gobl.lookup/main.go b/cmd/gobl.lookup/main.go index c30653e..df7adcf 100644 --- a/cmd/gobl.lookup/main.go +++ b/cmd/gobl.lookup/main.go @@ -56,7 +56,6 @@ func rootCmd() *cobra.Command { "emit logs as structured JSON on stderr (env LOG_JSON)") cmd.AddCommand(initCmd()) cmd.AddCommand(serveCmd()) - cmd.AddCommand(verifyCmd()) cmd.AddCommand(versionCmd()) return cmd } @@ -139,7 +138,7 @@ func printError(err error) { slog.Error("command failed", attrs...) } -// stdOut is a small shim so the init / verify commands can write +// stdOut is a small shim so the init command can write // human-readable confirmation to stdout without going through slog. func stdOut(cmd *cobra.Command) io.Writer { return cmd.OutOrStdout() diff --git a/cmd/gobl.lookup/verify.go b/cmd/gobl.lookup/verify.go deleted file mode 100644 index d732bc3..0000000 --- a/cmd/gobl.lookup/verify.go +++ /dev/null @@ -1,78 +0,0 @@ -package main - -import ( - "errors" - "fmt" - "log/slog" - - "github.com/spf13/cobra" - - "github.com/invopop/gobl" - goblnet "github.com/invopop/gobl/net" - - "github.com/invopop/gobl.lookup/internal/config" - "github.com/invopop/gobl.lookup/internal/domain" -) - -func verifyCmd() *cobra.Command { - cfg := config.FromEnv() - cmd := &cobra.Command{ - Use: "verify
", - Short: "Re-derive a registration's verified status from its countersignatures", - Long: `Load the existing registration for
, find the most recent -countersignature from an accepted verification provider (the -configured --verifiers list) on the stored party envelope, -countersign with a verifier claim naming it, deliver the new -envelope to the subject's /inbox, and update the registry record -(verifier=, verified_at=now). - -The same derivation runs automatically when a registration arrives -carrying a provider countersignature; this command exists for -recovery — e.g. a provider added to the accepted list after its -countersignature was received. - -The original Authority countersignature on the previous record -remains in the audit history (CouchDB revisions). This command -issues a fresh signature; the subject can publish either or both.`, - Args: cobra.ExactArgs(1), - RunE: func(cmd *cobra.Command, args []string) error { - if cfg.ConfigDir == "" { - return gobl.ErrInput.WithReason("identity directory required: set --config-dir or CONFIG_DIR") - } - if cfg.CouchDBURL() == "" { - return gobl.ErrInput.WithReason("CouchDB connection required: set --couchdb / COUCHDB_URL, or COUCHDB_HOST (+ COUCHDB_USERNAME / COUCHDB_PASSWORD)") - } - addr, err := goblnet.ParseAddress(args[0]) - if err != nil { - return gobl.ErrInput.WithCause(err) - } - ctx := cmd.Context() - - setup, cleanup, err := buildDomain(ctx, cfg) - if err != nil { - return err - } - defer cleanup() - - rec, err := setup.Registrations().Verify(ctx, addr) - if err != nil { - if errors.Is(err, domain.ErrNotFound) || errors.Is(err, domain.ErrValidation) { - return gobl.ErrInput.WithCause(err) - } - return gobl.ErrInternal.WithCause(err) - } - slog.Info("verified registration", - "address", string(addr), - "envelope", rec.IncomingEnvelopeUUID.String(), - "verifier", string(rec.Verifier), - ) - _, _ = fmt.Fprintf(stdOut(cmd), "verified %s by %s (envelope %s)\n", addr, rec.Verifier, rec.IncomingEnvelopeUUID) - return nil - }, - } - cmd.Flags().StringVar(&cfg.ConfigDir, "config-dir", cfg.ConfigDir, "directory holding the lookup identity (env CONFIG_DIR)") - cmd.Flags().StringVar(&cfg.CouchURL, "couchdb", cfg.CouchURL, "full CouchDB URL (env COUCHDB_URL; overrides the COUCHDB_* parts)") - cmd.Flags().StringVar(&cfg.CouchDatabase, "couchdb-database", cfg.CouchDatabase, "CouchDB database name (env COUCHDB_DATABASE)") - cmd.Flags().StringSliceVar(&cfg.Verifiers, "verifiers", cfg.Verifiers, "accepted verification-provider addresses (env VERIFIERS, comma-separated)") - return cmd -} diff --git a/go.mod b/go.mod index e864ffe..7e04eb6 100644 --- a/go.mod +++ b/go.mod @@ -5,7 +5,7 @@ go 1.25.0 require ( github.com/go-kivik/kivik/v4 v4.5.2 github.com/invopop/couch v0.1.0 - github.com/invopop/gobl v0.512.1-0.20261113230617-62e54e64146b + github.com/invopop/gobl v0.512.1-0.20261115094341-1c46ab6f09cf github.com/magefile/mage v1.17.2 github.com/spf13/cobra v1.10.2 github.com/stretchr/testify v1.11.1 diff --git a/go.sum b/go.sum index 901965f..f2d4591 100644 --- a/go.sum +++ b/go.sum @@ -34,8 +34,8 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/invopop/couch v0.1.0 h1:ctMKLeIxnab9KW11KtEAQSl7RzGgMxndavLphx99LpY= github.com/invopop/couch v0.1.0/go.mod h1:xzBNVglDnLcpf1Z9BJxiIG1liESSIkMuvIczSl4zcls= -github.com/invopop/gobl v0.512.1-0.20261113230617-62e54e64146b h1:8E7dpk2LPgRsN5XZBUs3E16Zs7SwcX5MCsciA4DZzHg= -github.com/invopop/gobl v0.512.1-0.20261113230617-62e54e64146b/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= +github.com/invopop/gobl v0.512.1-0.20261115094341-1c46ab6f09cf h1:lxjJXKZrYST9Qw+Mrpl9tyqjGGz2O0UDS0FaRxCM66E= +github.com/invopop/gobl v0.512.1-0.20261115094341-1c46ab6f09cf/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= github.com/invopop/jsonschema v0.14.0 h1:MHQqLhvpNUZfw+hM3AZDYK7jxO8FZoQeQM77g8iyZjg= github.com/invopop/jsonschema v0.14.0/go.mod h1:ygm6C2EaVNMBDPpaPlnOA2pFAxBnxGjFlMZABxm9n2I= github.com/invopop/yaml v0.3.1 h1:f0+ZpmhfBSS4MhG+4HYseMdJhoeeopbSKbq5Rpeelso= diff --git a/internal/config/config.go b/internal/config/config.go index 762c722..0a094ef 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -16,7 +16,7 @@ import ( "github.com/invopop/couch" ) -// Config holds the options shared by the serve and verify commands. +// Config holds the options of the serve command. // // CouchDB may be configured in two ways: a single connection URL // (CouchURL, from --couchdb / COUCHDB_URL — convenient for local dev), @@ -47,9 +47,8 @@ type Config struct { // https://. PublicBaseURL string // Verifiers lists the GOBL Net addresses of the verification - // providers this registry accepts: their countersignatures are - // named in `verifier` claims, both automatically at registration - // and by the verify command. + // providers this registry accepts: a registration needs a + // countersignature from one, which is named in its `verifier` claim. Verifiers []string // ShutdownTimeout bounds graceful shutdown of the HTTP server. ShutdownTimeout time.Duration diff --git a/internal/domain/identity.go b/internal/domain/identity.go index 9b9e5ea..3ba2b8b 100644 --- a/internal/domain/identity.go +++ b/internal/domain/identity.go @@ -101,7 +101,7 @@ type CounterSignOptions struct { Key string // Verifier names the participant that performed identity // verification (KYC/KYB) of the subject, carried as the signed - // `verifier` claim. Empty asserts registration only. + // `verifier` claim. Required. Verifier goblnet.Address } @@ -130,12 +130,11 @@ func (d *Identity) CounterSign(env *gobl.Envelope, opts CounterSignOptions) erro if opts.Key == "" { return errors.New("identity: cannot countersign without a subject key") } - signOpts := []head.SignOption{ + if opts.Verifier == "" { + return errors.New("identity: cannot countersign without a verifier") + } + return goblnet.Sign(env, d.model.PrivateKey, d.Address(), opts.Subject, head.WithExpiration(time.Now().Add(endorsementTTL)), head.WithConfirmation(opts.Key), - } - if opts.Verifier != "" { - signOpts = append(signOpts, head.WithVerifier(opts.Verifier.String())) - } - return goblnet.Sign(env, d.model.PrivateKey, d.Address(), opts.Subject, signOpts...) + head.WithVerifier(opts.Verifier.String())) } diff --git a/internal/domain/identity_test.go b/internal/domain/identity_test.go index 79aca2e..90198de 100644 --- a/internal/domain/identity_test.go +++ b/internal/domain/identity_test.go @@ -99,7 +99,14 @@ func TestCounterSignRequiresAKey(t *testing.T) { id := newTestIdentity(t) env, err := gobl.Envelop(¬e.Message{Content: "party doc"}) require.NoError(t, err) - require.Error(t, id.CounterSign(env, domain.CounterSignOptions{Subject: "alice.example"})) + require.Error(t, id.CounterSign(env, domain.CounterSignOptions{Subject: "alice.example", Verifier: "kyc.example"})) +} + +func TestCounterSignRequiresAVerifier(t *testing.T) { + id := newTestIdentity(t) + env, err := gobl.Envelop(¬e.Message{Content: "party doc"}) + require.NoError(t, err) + require.Error(t, id.CounterSign(env, domain.CounterSignOptions{Subject: "alice.example", Key: "jkt"})) } func TestCounterSignNilEnvelope(t *testing.T) { diff --git a/internal/domain/registrations.go b/internal/domain/registrations.go index d45a77c..94669a9 100644 --- a/internal/domain/registrations.go +++ b/internal/domain/registrations.go @@ -67,7 +67,9 @@ func newRegistrations(store RegistrationStore, identity *Identity, client *gobln // envelope's from address, confirmed by a signature for this lookup // with the subject's current key, a new key, or both (spec §7.3). It // resolves the subject's own GET /who to confirm the address serves an -// identity, updates the subject's key lineage, countersigns the +// identity, updates the subject's key lineage, and requires a +// verification from an accepted provider binding a key in it: the +// lookup registers only verified parties. It countersigns the // envelope as the Authority, persists the record, and queues // asynchronous delivery back to the subject's inbox. The persisted // record is returned once stored; delivery happens in the background. @@ -119,12 +121,6 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode // only while that key is in the subject's lineage, which a rollover // extends and a lost key or a new holder of the address restarts. verifications, verr := d.acceptedVerifications(ctx, env, sender) - if verr != nil { - // A provider's key endpoint was unreachable: register - // unverified rather than reject — the derivation re-runs on - // the next renewal, or via the verify command. - d.log.Warn("inbox.auto_verify_unavailable", "caller", string(sender), "error", verr.Error()) - } var lineage []*models.LineageKey if prev != nil { lineage = prev.Lineage @@ -135,6 +131,14 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode return nil, ErrValidation.WithMessage("%s", err.Error()) } verifier := pickVerifier(verifications, lineage) + if verifier == "" { + if verr != nil { + d.log.Warn("inbox.rejected", "reason", "verifier_unavailable", "caller", string(sender), "error", verr.Error()) + return nil, ErrUnavailable.WithMessage("could not reach a verifier's key endpoint; retry later") + } + d.log.Warn("inbox.rejected", "reason", "unverified", "caller", string(sender)) + return nil, ErrForbidden.WithMessage("registration needs a countersignature from an accepted verifier binding the subject's key") + } // Stamp the discovery link to the public record before signing: // stamping replaces any copy from an earlier countersign round — @@ -145,7 +149,7 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode d.dropRequestSignatures(env, sender) // Countersign: adds the Authority signature for the subject's - // address and current key, with any verifier claim and a 90-day + // address and current key, with the verifier claim and a 90-day // exp, and addresses the envelope back to the subject. UUID and // digest unchanged. if err := d.identity.CounterSign(env, CounterSignOptions{ @@ -210,103 +214,26 @@ func (d *Registrations) checkWho(ctx context.Context, sender goblnet.Address) er return ErrForbidden.WithMessage("%s", msg) } -// Verify marks an existing registration as identity-verified: it -// derives the verifier from the countersignatures already on the -// stored envelope — the most recent one from an accepted verification -// provider whose cnf names a key in the subject's lineage — -// re-countersigns with the `verifier` claim naming it, and delivers -// the result synchronously to the subject's inbox. The same derivation -// runs automatically on every registration, so this command exists -// for recovery: e.g. a provider added to the accepted list after its -// countersignature was received. -func (d *Registrations) Verify(ctx context.Context, addr goblnet.Address) (*models.Registration, error) { - rec, err := d.store.Get(ctx, addr) - if errors.Is(err, repos.ErrNotFound) { - return nil, ErrNotFound.WithMessage("no registration for %s", addr) - } - if err != nil { - return nil, ErrInternal.WithCause(err) - } - if rec.CountersignedEnvelope == nil { - return nil, ErrValidation.WithMessage("registration for %s has no countersigned envelope", addr) - } - key := rec.CurrentKey() - if key == nil { - return nil, ErrValidation.WithMessage("registration for %s has no key lineage; the subject must register again", addr) - } - env := rec.CountersignedEnvelope - - verifications, aerr := d.acceptedVerifications(ctx, env, addr) - verifier := pickVerifier(verifications, rec.Lineage) - if verifier == "" { - if aerr != nil { - return nil, ErrUnavailable.WithMessage("could not check verifier countersignatures: %s", aerr.Error()) - } - return nil, ErrValidation.WithMessage("no countersignature from an accepted verifier for a key of %s on the registration envelope", addr) - } - - // Restamp the discovery link (deduplicating any earlier rounds) - // and stamp a fresh Authority signature carrying the verifier - // claim onto the existing envelope. - d.stampDiscoveryLink(env) - if err := d.identity.CounterSign(env, CounterSignOptions{ - Subject: addr, - Key: key.JKT, - Verifier: verifier, - }); err != nil { - return nil, ErrInternal.WithCause(err) - } - rec.Verifier = verifier - now := time.Now().UTC() - rec.VerifiedAt = &now - rec.Status = models.StatusCountersigned - // Count the attempt up front (as the async path does) so a failure is - // still reflected in DeliveryAttempts. - rec.DeliveryAttempts++ - rec.LastDeliveryAt = &now - - sendCtx, cancel := context.WithTimeout(ctx, deliveryTimeout) - defer cancel() - if err := d.sender.Send(sendCtx, addr, env); err != nil { - rec.Status = models.StatusFailed - rec.LastDeliveryError = err.Error() - _ = d.store.Put(ctx, rec) - return nil, ErrInternal.WithCause(fmt.Errorf("deliver verified envelope: %w", err)) - } - rec.Status = models.StatusDelivered - rec.LastDeliveryError = "" - if err := d.store.Put(ctx, rec); err != nil { - return nil, ErrInternal.WithCause(err) - } - d.log.Info("verified registration", - "address", string(addr), - "envelope", env.Head.UUID.String(), - "verifier", string(verifier), - ) - return rec, nil -} - // acceptedVerifications returns the valid countersignatures for // subject on env from accepted verification providers. The crypto // check matters: naming a verifier whose signature consumers would // reject makes the registry attest to garbage. The error is non-nil // only when a provider's key endpoint was unreachable -// (net.ErrUnavailable) — the caller decides whether that degrades or -// aborts. +// (net.ErrUnavailable). func (d *Registrations) acceptedVerifications(ctx context.Context, env *gobl.Envelope, subject goblnet.Address) ([]*goblnet.Verification, error) { var ( found []*goblnet.Verification unavailable error ) for v := range d.verifiers { - ver, err := d.client.FindVerification(ctx, env, v, subject) + vs, err := d.client.FindVerifications(ctx, env, v, subject) if err != nil { if errors.Is(err, goblnet.ErrUnavailable) { unavailable = err } continue } - found = append(found, ver) + found = append(found, vs...) } return found, unavailable } @@ -463,13 +390,9 @@ func (d *Registrations) upsert(ctx context.Context, prev *models.Registration, s rec.Status = models.StatusCountersigned rec.CountersignedEnvelope = env rec.Lineage = lineage - // The verification timestamp follows the verifier: dropped when - // the verifier is dropped, kept across renewals with the same - // verifier, and stamped fresh when a (new) provider verifies. - switch { - case verifier == "": - rec.VerifiedAt = nil - case rec.VerifiedAt == nil || verifier != prevVerifier: + // The verification timestamp is kept across renewals with the + // same verifier, and stamped fresh when another one verifies. + if rec.VerifiedAt == nil || verifier != prevVerifier { now := time.Now().UTC() rec.VerifiedAt = &now } diff --git a/internal/interfaces/web/web_test.go b/internal/interfaces/web/web_test.go index 27218f6..15304f1 100644 --- a/internal/interfaces/web/web_test.go +++ b/internal/interfaces/web/web_test.go @@ -4,7 +4,6 @@ import ( "bytes" "context" "encoding/json" - "errors" "fmt" "io" "log/slog" @@ -152,8 +151,17 @@ func (f *fixture) party() *org.Party { } // request envelopes party as a registration request from the subject -// to the lookup, signed with each of keys. +// to the lookup, signed with each of keys, and countersigned by the +// fixture verifier binding the first. func (f *fixture) request(party *org.Party, keys ...*dsig.PrivateKey) *gobl.Envelope { + f.t.Helper() + env := f.unverified(party, keys...) + f.counterSignAsVerifier(env, keys[0]) + return env +} + +// unverified is request without the verifier's countersignature. +func (f *fixture) unverified(party *org.Party, keys ...*dsig.PrivateKey) *gobl.Envelope { f.t.Helper() env, err := gobl.Envelop(party) require.NoError(f.t, err) @@ -297,7 +305,8 @@ func TestInboxAcceptsRegistration(t *testing.T) { // so the record may already have advanced to delivered. rec := f.record() assert.Contains(t, []models.Status{models.StatusCountersigned, models.StatusDelivered}, rec.Status) - assert.Empty(t, rec.Verifier, "initial registration carries no verifier") + assert.Equal(t, f.verifAddr, rec.Verifier) + assert.NotNil(t, rec.VerifiedAt) require.Len(t, rec.Lineage, 1) assert.Equal(t, f.subject.JKT(), rec.Lineage[0].JKT) assert.Equal(t, f.subject.ID(), rec.Lineage[0].KID) @@ -305,14 +314,14 @@ func TestInboxAcceptsRegistration(t *testing.T) { // The request signature is dropped; the lookup's countersignature // addresses the envelope back to the subject. out := rec.CountersignedEnvelope - require.Len(t, out.Signatures, 1) + require.Len(t, out.Signatures, 2, "verifier + lookup") assert.Equal(t, f.lookup.Address().URI(), out.Head.From) assert.Equal(t, f.subAddr.URI(), out.Head.To) p := f.authority(out) assert.Equal(t, f.subAddr.String(), p.Aud) require.NotNil(t, p.Confirmation) assert.Equal(t, f.subject.JKT(), p.Confirmation.JKT) - assert.Empty(t, p.Verifier) + assert.Equal(t, f.verifAddr.String(), p.Verifier) assert.Greater(t, p.ExpiresAt, time.Now().Add(89*24*time.Hour).Unix()) assert.LessOrEqual(t, p.ExpiresAt, time.Now().Add(90*24*time.Hour).Unix()) @@ -408,7 +417,7 @@ func TestKeyLineage(t *testing.T) { require.Equal(t, http.StatusAccepted, f.register(f.renewal(f.subject))) rec := f.record() assert.Equal(t, first, rec.Lineage) - require.Len(t, rec.CountersignedEnvelope.Signatures, 1, "request signature dropped, own countersignature superseded") + require.Len(t, rec.CountersignedEnvelope.Signatures, 2, "request signature dropped, own countersignature superseded") assert.Equal(t, 1, linkCount(rec.CountersignedEnvelope), "restamped, not duplicated") require.NoError(t, rec.CountersignedEnvelope.Validate()) }) @@ -416,7 +425,6 @@ func TestKeyLineage(t *testing.T) { t.Run("rollover signed with both keys keeps the verifier", func(t *testing.T) { f := newFixture(t) env := f.request(f.party(), f.subject) - f.counterSignAsVerifier(env, f.subject) require.Equal(t, http.StatusAccepted, f.register(env)) require.Equal(t, f.verifAddr, f.record().Verifier) @@ -439,29 +447,32 @@ func TestKeyLineage(t *testing.T) { assert.Equal(t, f.verifAddr, rec.Verifier) }) - t.Run("a new key alone starts a new lineage and drops the verifier", func(t *testing.T) { + t.Run("a new key alone needs a new verification", func(t *testing.T) { // A lost key, or a new holder of the address: the previous // verification does not carry over. f := newFixture(t) - env := f.request(f.party(), f.subject) - f.counterSignAsVerifier(env, f.subject) - require.Equal(t, http.StatusAccepted, f.register(env)) + require.Equal(t, http.StatusAccepted, f.register(f.request(f.party(), f.subject))) + first := f.record().VerifiedAt newHolder := dsig.NewES256Key() - require.Equal(t, http.StatusAccepted, f.register(f.renewal(newHolder))) + require.Equal(t, http.StatusForbidden, f.register(f.renewal(newHolder))) + assert.Equal(t, f.subject.JKT(), f.record().CurrentKey().JKT, "rejected request leaves the lineage") + + env := f.renewal(newHolder) + f.counterSignAsVerifier(env, newHolder) + require.Equal(t, http.StatusAccepted, f.register(env)) rec := f.record() require.Len(t, rec.Lineage, 1) assert.Equal(t, newHolder.JKT(), rec.Lineage[0].JKT) - assert.Empty(t, rec.Verifier) - assert.Nil(t, rec.VerifiedAt) - assert.Empty(t, f.authority(rec.CountersignedEnvelope).Verifier) + assert.Equal(t, f.verifAddr, rec.Verifier) + assert.Equal(t, newHolder.JKT(), f.authority(rec.CountersignedEnvelope).Confirmation.JKT) + assert.Equal(t, first, rec.VerifiedAt, "same verifier") }) t.Run("two keys at a first registration follow the verification", func(t *testing.T) { f := newFixture(t) next := dsig.NewES256Key() env := f.request(f.party(), f.subject, next) - f.counterSignAsVerifier(env, f.subject) require.Equal(t, http.StatusAccepted, f.register(env)) rec := f.record() require.Len(t, rec.Lineage, 2) @@ -472,7 +483,7 @@ func TestKeyLineage(t *testing.T) { t.Run("two keys at a first registration without a verification are rejected", func(t *testing.T) { f := newFixture(t) - env := f.request(f.party(), f.subject, dsig.NewES256Key()) + env := f.unverified(f.party(), f.subject, dsig.NewES256Key()) assert.Equal(t, http.StatusUnprocessableEntity, f.register(env)) }) @@ -484,11 +495,10 @@ func TestKeyLineage(t *testing.T) { }) } -func TestAutoVerify(t *testing.T) { +func TestVerification(t *testing.T) { t.Run("names an accepted verifier binding the subject's key", func(t *testing.T) { f := newFixture(t) env := f.request(f.party(), f.subject) - f.counterSignAsVerifier(env, f.subject) require.Equal(t, http.StatusAccepted, f.register(env)) rec := f.record() assert.Equal(t, f.verifAddr, rec.Verifier) @@ -499,7 +509,6 @@ func TestAutoVerify(t *testing.T) { t.Run("survives renewal of the delivered envelope", func(t *testing.T) { f := newFixture(t) env := f.request(f.party(), f.subject) - f.counterSignAsVerifier(env, f.subject) require.Equal(t, http.StatusAccepted, f.register(env)) verifiedAt := f.record().VerifiedAt @@ -513,6 +522,19 @@ func TestAutoVerify(t *testing.T) { assert.Equal(t, 1, sigCountBy(final, f.verifAddr)) }) + t.Run("rejects a registration without one", func(t *testing.T) { + f := newFixture(t) + assert.Equal(t, http.StatusForbidden, f.register(f.unverified(f.party(), f.subject))) + _, err := f.registry.Get(context.Background(), f.subAddr) + assert.ErrorIs(t, err, repos.ErrNotFound) + }) + + t.Run("an unreachable verifier key is retryable", func(t *testing.T) { + f := newFixture(t) + f.fetcher.errs[f.verifAddr.KeyURL(f.verifier.ID())] = fmt.Errorf("%w: HTTP 503", goblnet.ErrUnavailable) + assert.Equal(t, http.StatusServiceUnavailable, f.register(f.request(f.party(), f.subject))) + }) + ignored := map[string]func(f *fixture, env *gobl.Envelope){ "for another key": func(f *fixture, env *gobl.Envelope) { f.counterSignAsVerifier(env, dsig.NewES256Key()) @@ -534,77 +556,15 @@ func TestAutoVerify(t *testing.T) { }, } for name, stamp := range ignored { - t.Run("ignores a verification "+name, func(t *testing.T) { + t.Run("rejects a verification "+name, func(t *testing.T) { f := newFixture(t) - env := f.request(f.party(), f.subject) + env := f.unverified(f.party(), f.subject) stamp(f, env) - require.Equal(t, http.StatusAccepted, f.register(env), "registration proceeds unverified") - rec := f.record() - assert.Empty(t, rec.Verifier) - assert.Nil(t, rec.VerifiedAt) + assert.Equal(t, http.StatusForbidden, f.register(env)) }) } } -func TestVerifyDerivesFromStoredEnvelope(t *testing.T) { - // A provider countersignature received while the provider was not - // yet on the accepted list is picked up later by the verify - // command — the recovery path. - f := newFixture(t) - bare := domain.New(domain.Deps{ - Identity: f.lookup, - Registrations: f.registry, - Client: goblnet.NewClient(goblnet.WithFetcher(f.fetcher), goblnet.WithIdentity(f.lookup.Address(), f.lookup.PrivateKey)), - Sender: f.sender, - PublicBaseURL: "https://lookup.example", - Logger: discardLogger(), - }) - env := f.request(f.party(), f.subject) - f.counterSignAsVerifier(env, f.subject) - _, err := bare.Registrations().Register(context.Background(), env) - require.NoError(t, err) - // Let the async delivery goroutine finish its Put before Verify - // reads and rewrites the record. - require.NotEmpty(t, f.waitForDeliveries(1)) - require.Empty(t, f.record().Verifier) - - // Simulate a record poisoned with a duplicate discovery link: the - // verify command heals it. - rec := f.record() - rec.CountersignedEnvelope.Head.Links = append(rec.CountersignedEnvelope.Head.Links, - rec.CountersignedEnvelope.Head.Links[0]) - require.NoError(t, f.registry.Put(context.Background(), rec)) - - setup := domain.New(domain.Deps{ - Identity: f.lookup, - Registrations: f.registry, - Client: goblnet.NewClient(goblnet.WithFetcher(f.fetcher)), - Sender: f.sender, - Verifiers: []goblnet.Address{f.verifAddr}, - PublicBaseURL: "https://lookup.example", - Logger: discardLogger(), - }) - rec, err = setup.Registrations().Verify(context.Background(), f.subAddr) - require.NoError(t, err) - assert.Equal(t, f.verifAddr, rec.Verifier) - assert.NotNil(t, rec.VerifiedAt) - assert.Equal(t, 1, linkCount(rec.CountersignedEnvelope)) - require.NoError(t, rec.CountersignedEnvelope.Validate()) - p := f.authority(rec.CountersignedEnvelope) - assert.Equal(t, f.subject.JKT(), p.Confirmation.JKT) - assert.Equal(t, 1, sigCountBy(rec.CountersignedEnvelope, f.lookup.Address())) -} - -func TestVerifyWithoutAcceptedCountersignature(t *testing.T) { - f := newFixture(t) - require.Equal(t, http.StatusAccepted, f.register(f.request(f.party(), f.subject))) - require.NotEmpty(t, f.waitForDeliveries(1)) - - _, err := f.setup().Registrations().Verify(context.Background(), f.subAddr) - require.Error(t, err) - assert.True(t, errors.Is(err, domain.ErrValidation)) -} - func TestInboxChecksTheSendersWho(t *testing.T) { cases := []struct { name string @@ -764,20 +724,6 @@ func TestHealth(t *testing.T) { assert.Equal(t, http.StatusOK, resp.StatusCode) } -// setup returns a domain setup sharing the fixture's store, sender and -// fetcher, accepting the fixture's verifier. -func (f *fixture) setup() *domain.Setup { - return domain.New(domain.Deps{ - Identity: f.lookup, - Registrations: f.registry, - Client: goblnet.NewClient(goblnet.WithFetcher(f.fetcher), goblnet.WithIdentity(f.lookup.Address(), f.lookup.PrivateKey)), - Sender: f.sender, - Verifiers: []goblnet.Address{f.verifAddr}, - PublicBaseURL: "https://lookup.example", - Logger: discardLogger(), - }) -} - // linkCount counts the lookup discovery links on an envelope. func linkCount(env *gobl.Envelope) int { n := 0 From 4506b248b7ed9ee2166e04256236e3fa76647a99 Mon Sep 17 00:00:00 2001 From: Sam Lown Date: Sun, 15 Nov 2026 13:33:51 +0000 Subject: [PATCH 05/11] Address Copilot review comments A key bound before cannot become current again, and /who responses vary by Authorization. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 ++-- go.mod | 2 +- go.sum | 4 ++-- internal/domain/lineage.go | 8 +++++--- internal/interfaces/web/web_test.go | 5 +++++ internal/interfaces/web/who.go | 1 + 6 files changed, 16 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index def20ec..94544df 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,10 +5,10 @@ ### Changed - Registrations follow the latest GOBL Net spec. A request is an ordinary delivery from the subject to the lookup, confirmed by its signature for the lookup, and needs no request token; the subject is its `from` address. The lookup drops the request signature, countersigns with a `cnf` claim binding the subject's key, and addresses the envelope back to the subject. -- The lookup keeps each address's key lineage (`Registration.Lineage`). A request signed with the current and a new key rolls over to the new key; one signed only with an unknown key starts a new lineage, and needs a verification for that key. Rollovers need no new verification, and a new holder of an address cannot inherit its verification. +- The lookup keeps each address's key lineage (`Registration.Lineage`). A request signed with the current and a new key rolls over to the new key; one signed only with an unknown key starts a new lineage, and needs a verification for that key. Rollovers need no new verification, a key bound before cannot become current again, and a new holder of an address cannot inherit its verification. - The lookup registers only verified parties: a registration needs a countersignature from an accepted verifier binding, with `cnf`, a key in the subject's lineage, and is rejected with `403` without one (`503` when the verifier's key cannot be fetched). The `gobl.lookup verify` command is removed; a subject registers again instead. - Verifiers are no longer accepted delivering to the lookup on a subject's behalf; the subject registers again with the verified envelope. The renewal rule based on an unchanged digest is replaced by the lineage check. -- `GET /.well-known/gobl/who` answers with the lookup's party envelope addressed and signed for the requester. +- `GET /.well-known/gobl/who` answers with the lookup's party envelope addressed and signed for the requester, with `Vary: Authorization`. - Deliveries to subjects carry no request token. - Verification is now list-driven and automatic: the registry accepts a configured set of verification providers (`--verifiers` / `VERIFIERS`), and a registration or renewal arriving with a valid countersignature from one of them is verified on arrival — the countersignature is cryptographically checked against the provider's published key before being named (an unreachable key endpoint registers unverified and logs `inbox.auto_verify_unavailable`; the derivation re-runs on renewal). `gobl.lookup verify
` loses the `--verifier` flag and becomes a recovery command that re-derives the verifier from the stored envelope, e.g. after a provider is added to the accepted list. The discovery link stamped on countersigned envelopes uses the standard `verification` category (the previous `authority` value failed envelope validation on re-signing). diff --git a/go.mod b/go.mod index 7e04eb6..7f4aaba 100644 --- a/go.mod +++ b/go.mod @@ -5,7 +5,7 @@ go 1.25.0 require ( github.com/go-kivik/kivik/v4 v4.5.2 github.com/invopop/couch v0.1.0 - github.com/invopop/gobl v0.512.1-0.20261115094341-1c46ab6f09cf + github.com/invopop/gobl v0.512.1-0.20261115133328-2994b8d65d7a github.com/magefile/mage v1.17.2 github.com/spf13/cobra v1.10.2 github.com/stretchr/testify v1.11.1 diff --git a/go.sum b/go.sum index f2d4591..b33dc3d 100644 --- a/go.sum +++ b/go.sum @@ -34,8 +34,8 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/invopop/couch v0.1.0 h1:ctMKLeIxnab9KW11KtEAQSl7RzGgMxndavLphx99LpY= github.com/invopop/couch v0.1.0/go.mod h1:xzBNVglDnLcpf1Z9BJxiIG1liESSIkMuvIczSl4zcls= -github.com/invopop/gobl v0.512.1-0.20261115094341-1c46ab6f09cf h1:lxjJXKZrYST9Qw+Mrpl9tyqjGGz2O0UDS0FaRxCM66E= -github.com/invopop/gobl v0.512.1-0.20261115094341-1c46ab6f09cf/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= +github.com/invopop/gobl v0.512.1-0.20261115133328-2994b8d65d7a h1:X8WIaoDlnXvZ2Pqqr9Xhlb3uo9HsF/fyoty76rMrcRA= +github.com/invopop/gobl v0.512.1-0.20261115133328-2994b8d65d7a/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= github.com/invopop/jsonschema v0.14.0 h1:MHQqLhvpNUZfw+hM3AZDYK7jxO8FZoQeQM77g8iyZjg= github.com/invopop/jsonschema v0.14.0/go.mod h1:ygm6C2EaVNMBDPpaPlnOA2pFAxBnxGjFlMZABxm9n2I= github.com/invopop/yaml v0.3.1 h1:f0+ZpmhfBSS4MhG+4HYseMdJhoeeopbSKbq5Rpeelso= diff --git a/internal/domain/lineage.go b/internal/domain/lineage.go index 71bff2c..94e5936 100644 --- a/internal/domain/lineage.go +++ b/internal/domain/lineage.go @@ -38,10 +38,12 @@ func nextLineage(lineage []*models.LineageKey, keys []*dsig.PublicKey, verified case 2: a, b := keys[0], keys[1] if current != "" { - switch current { - case a.JKT(): + // The other key must be new: a key bound before cannot + // become current again. + switch { + case current == a.JKT() && !inLineage(lineage, b.JKT()): return append(lineage, entry(b)), nil - case b.JKT(): + case current == b.JKT() && !inLineage(lineage, a.JKT()): return append(lineage, entry(a)), nil } return nil, errLineage diff --git a/internal/interfaces/web/web_test.go b/internal/interfaces/web/web_test.go index 15304f1..fd9f5a6 100644 --- a/internal/interfaces/web/web_test.go +++ b/internal/interfaces/web/web_test.go @@ -445,6 +445,10 @@ func TestKeyLineage(t *testing.T) { rec = f.record() require.Len(t, rec.Lineage, 3) assert.Equal(t, f.verifAddr, rec.Verifier) + + // A key bound before cannot become current again. + assert.Equal(t, http.StatusUnprocessableEntity, f.register(f.renewal(third, f.subject))) + assert.Equal(t, third.JKT(), f.record().CurrentKey().JKT) }) t.Run("a new key alone needs a new verification", func(t *testing.T) { @@ -659,6 +663,7 @@ func TestWhoGet(t *testing.T) { defer resp.Body.Close() //nolint:errcheck require.Equal(t, http.StatusOK, resp.StatusCode) assert.Equal(t, "private, max-age=300", resp.Header.Get("Cache-Control"), "authorized response must not land in shared caches") + assert.Equal(t, "Authorization", resp.Header.Get("Vary")) var got gobl.Envelope require.NoError(t, json.NewDecoder(resp.Body).Decode(&got)) diff --git a/internal/interfaces/web/who.go b/internal/interfaces/web/who.go index e08b669..864b0cb 100644 --- a/internal/interfaces/web/who.go +++ b/internal/interfaces/web/who.go @@ -26,6 +26,7 @@ func handleWho(s *domain.Setup, log *slog.Logger) http.HandlerFunc { } log.Info("who.served", "requester", string(requesterFrom(r.Context()))) w.Header().Set("Cache-Control", whoCacheControl) + w.Header().Set("Vary", "Authorization") writeJSON(w, http.StatusOK, body) } } From 98291d8ccf0a962e60170ae3d6cc86dda49e1e8c Mon Sep 17 00:00:00 2001 From: Sam Lown Date: Sun, 15 Nov 2026 13:41:13 +0000 Subject: [PATCH 06/11] Cover key lineage cases and identity signing Co-Authored-By: Claude Opus 5.5 --- go.mod | 2 +- go.sum | 4 +- internal/domain/identity_test.go | 5 ++ internal/domain/lineage_internal_test.go | 82 +++++++++++++++++++++ internal/domain/models/registration_test.go | 16 ++++ 5 files changed, 106 insertions(+), 3 deletions(-) create mode 100644 internal/domain/lineage_internal_test.go create mode 100644 internal/domain/models/registration_test.go diff --git a/go.mod b/go.mod index 7f4aaba..dad681d 100644 --- a/go.mod +++ b/go.mod @@ -5,7 +5,7 @@ go 1.25.0 require ( github.com/go-kivik/kivik/v4 v4.5.2 github.com/invopop/couch v0.1.0 - github.com/invopop/gobl v0.512.1-0.20261115133328-2994b8d65d7a + github.com/invopop/gobl v0.512.1-0.20261115134102-700b886e1a8e github.com/magefile/mage v1.17.2 github.com/spf13/cobra v1.10.2 github.com/stretchr/testify v1.11.1 diff --git a/go.sum b/go.sum index b33dc3d..6df692e 100644 --- a/go.sum +++ b/go.sum @@ -34,8 +34,8 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/invopop/couch v0.1.0 h1:ctMKLeIxnab9KW11KtEAQSl7RzGgMxndavLphx99LpY= github.com/invopop/couch v0.1.0/go.mod h1:xzBNVglDnLcpf1Z9BJxiIG1liESSIkMuvIczSl4zcls= -github.com/invopop/gobl v0.512.1-0.20261115133328-2994b8d65d7a h1:X8WIaoDlnXvZ2Pqqr9Xhlb3uo9HsF/fyoty76rMrcRA= -github.com/invopop/gobl v0.512.1-0.20261115133328-2994b8d65d7a/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= +github.com/invopop/gobl v0.512.1-0.20261115134102-700b886e1a8e h1:fd9n4+gY08Mg2V1M/w+igZIWItZPkBQW4+XZ2MULYyw= +github.com/invopop/gobl v0.512.1-0.20261115134102-700b886e1a8e/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= github.com/invopop/jsonschema v0.14.0 h1:MHQqLhvpNUZfw+hM3AZDYK7jxO8FZoQeQM77g8iyZjg= github.com/invopop/jsonschema v0.14.0/go.mod h1:ygm6C2EaVNMBDPpaPlnOA2pFAxBnxGjFlMZABxm9n2I= github.com/invopop/yaml v0.3.1 h1:f0+ZpmhfBSS4MhG+4HYseMdJhoeeopbSKbq5Rpeelso= diff --git a/internal/domain/identity_test.go b/internal/domain/identity_test.go index 90198de..b48e65a 100644 --- a/internal/domain/identity_test.go +++ b/internal/domain/identity_test.go @@ -36,6 +36,11 @@ func newTestIdentity(t *testing.T) *domain.Identity { return setup.Identity() } +func TestPartyEnvelopeRejectsAnInvalidRequester(t *testing.T) { + _, err := newTestIdentity(t).PartyEnvelope("not an address") + assert.ErrorContains(t, err, "identity: sign party") +} + func TestPartyEnvelopeIsSignedForTheRequester(t *testing.T) { id := newTestIdentity(t) diff --git a/internal/domain/lineage_internal_test.go b/internal/domain/lineage_internal_test.go new file mode 100644 index 0000000..0d76f0c --- /dev/null +++ b/internal/domain/lineage_internal_test.go @@ -0,0 +1,82 @@ +package domain + +import ( + "testing" + "time" + + "github.com/invopop/gobl/dsig" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/invopop/gobl.lookup/internal/domain/models" +) + +func TestNextLineage(t *testing.T) { + now := time.Now() + a, b, c := dsig.NewES256Key(), dsig.NewES256Key(), dsig.NewES256Key() + pub := func(ks ...*dsig.PrivateKey) []*dsig.PublicKey { + out := make([]*dsig.PublicKey, len(ks)) + for i, k := range ks { + out[i] = k.Public() + } + return out + } + lineage := func(ks ...*dsig.PrivateKey) []*models.LineageKey { + out := make([]*models.LineageKey, len(ks)) + for i, k := range ks { + out[i] = &models.LineageKey{JKT: k.JKT(), KID: k.ID()} + } + return out + } + jkts := func(l []*models.LineageKey) []string { + out := make([]string, len(l)) + for i, k := range l { + out[i] = k.JKT + } + return out + } + + t.Run("rolls over with the current key signing second", func(t *testing.T) { + got, err := nextLineage(lineage(a), pub(b, a), nil, now) + require.NoError(t, err) + assert.Equal(t, []string{a.JKT(), b.JKT()}, jkts(got)) + }) + + t.Run("rejects a key bound before becoming current again", func(t *testing.T) { + _, err := nextLineage(lineage(a, b), pub(b, a), nil, now) + assert.ErrorIs(t, err, errLineage) + _, err = nextLineage(lineage(a, b), pub(a, b), nil, now) + assert.ErrorIs(t, err, errLineage) + }) + + t.Run("rejects two keys neither of which is current", func(t *testing.T) { + _, err := nextLineage(lineage(a), pub(b, c), nil, now) + assert.ErrorIs(t, err, errLineage) + }) + + t.Run("orders a first registration by the verified key", func(t *testing.T) { + got, err := nextLineage(nil, pub(a, b), []string{b.JKT()}, now) + require.NoError(t, err) + assert.Equal(t, []string{b.JKT(), a.JKT()}, jkts(got)) + }) + + t.Run("rejects a first registration with both or neither key verified", func(t *testing.T) { + _, err := nextLineage(nil, pub(a, b), []string{a.JKT(), b.JKT()}, now) + assert.ErrorIs(t, err, errLineage) + _, err = nextLineage(nil, pub(a, b), nil, now) + assert.ErrorIs(t, err, errLineage) + }) + + t.Run("rejects more than two keys", func(t *testing.T) { + _, err := nextLineage(lineage(a), pub(a, b, c), nil, now) + assert.ErrorIs(t, err, errLineage) + }) +} + +func TestInLineage(t *testing.T) { + k := dsig.NewES256Key() + l := []*models.LineageKey{{JKT: k.JKT()}} + assert.True(t, inLineage(l, k.JKT())) + assert.False(t, inLineage(l, "")) + assert.False(t, inLineage(l, "other")) +} diff --git a/internal/domain/models/registration_test.go b/internal/domain/models/registration_test.go new file mode 100644 index 0000000..cc38541 --- /dev/null +++ b/internal/domain/models/registration_test.go @@ -0,0 +1,16 @@ +package models_test + +import ( + "testing" + + "github.com/stretchr/testify/assert" + + "github.com/invopop/gobl.lookup/internal/domain/models" +) + +func TestRegistrationCurrentKey(t *testing.T) { + r := new(models.Registration) + assert.Nil(t, r.CurrentKey()) + r.Lineage = []*models.LineageKey{{JKT: "a"}, {JKT: "b"}} + assert.Equal(t, "b", r.CurrentKey().JKT) +} From 4ff83afdb2d17dbdb822478cb7a7810c1894da8f Mon Sep 17 00:00:00 2001 From: Sam Lown Date: Sun, 15 Nov 2026 17:11:27 +0000 Subject: [PATCH 07/11] Serve a public party record with an opt-in listing /parties returns the address, verifier and registration dates of every registered party, adding its name and tax ID when the registration request sets header meta lookup-listing: public. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 1 + README.md | 40 ++++++++++- internal/domain/listing.go | 93 ++++++++++++++++++++++++++ internal/domain/models/registration.go | 16 +++++ internal/domain/registrations.go | 15 ++++- internal/interfaces/web/parties.go | 12 ++-- internal/interfaces/web/web_test.go | 86 +++++++++++++++++++++--- 7 files changed, 241 insertions(+), 22 deletions(-) create mode 100644 internal/domain/listing.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 94544df..ccfd9e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ - The lookup keeps each address's key lineage (`Registration.Lineage`). A request signed with the current and a new key rolls over to the new key; one signed only with an unknown key starts a new lineage, and needs a verification for that key. Rollovers need no new verification, a key bound before cannot become current again, and a new holder of an address cannot inherit its verification. - The lookup registers only verified parties: a registration needs a countersignature from an accepted verifier binding, with `cnf`, a key in the subject's lineage, and is rejected with `403` without one (`503` when the verifier's key cannot be fetched). The `gobl.lookup verify` command is removed; a subject registers again instead. - Verifiers are no longer accepted delivering to the lookup on a subject's behalf; the subject registers again with the verified envelope. The renewal rule based on an unchanged digest is replaced by the lineage check. +- `GET /parties/` returns a public record instead of the countersigned envelope: the party's address, verifier, verification and registration dates, plus its name and tax ID when listed. A registration request lists the party with header meta `lookup-listing: public` and unlists it with `private`; without the key the choice is kept, and new registrations start private. The key is removed before countersigning. - `GET /.well-known/gobl/who` answers with the lookup's party envelope addressed and signed for the requester, with `Vary: Authorization`. - Deliveries to subjects carry no request token. diff --git a/README.md b/README.md index 7aab1b2..355c84b 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,40 @@ works](#how-verification-works)), and then registers it. No new protocol endpoints: registration uses the standard GOBL Net `/inbox` in both directions. +### Listing + +Every registered party has a public record at `/parties/
` +(or `/parties/`): its address, verifier, and registration +dates. A party can also list its name and tax ID there, for discovery, +by setting a key in its registration request's header `meta`: + +```json +"meta": { "lookup-listing": "public" } +``` + +`private` removes them again. A request without the key keeps the +current choice, and a new registration starts private. The lookup +removes the key before countersigning, so it never appears in the +envelope the party publishes. Contacts and other party details are +never listed: they stay behind the party's own `/who`. + +```json +{ + "address": "alice.example", + "verifier": "verify.example", + "verified_at": "2026-11-02T10:14:00Z", + "registered_at": "2026-11-02T10:14:05Z", + "registered_until": "2027-01-31T10:14:05Z", + "public": true, + "name": "Alice SL", + "tax_id": { "country": "ES", "code": "B98602642" } +} +``` + +The record is a discovery and validation aid, not a trust decision: a +receiver still checks the countersignatures on the envelope it gets +from the party's `/who` (spec §7.2). + ### Endorsement lifetime and renewal Every countersignature carries a 90-day `exp` claim, which receivers @@ -209,7 +243,7 @@ The domain never imports the transport layer. | GET | `/.well-known/gobl/who` | token | Lookup's identity, signed for the requester. | | GET | `/.well-known/gobl/keys/` | open | Single published key. | | GET | `/.well-known/jwks.json` | open | Bulk JWK Set (for jwt.io-style tooling). | -| GET | `/parties/
` | open | Public registration record by address. | +| GET | `/parties/
` | open | Public registration record by address ([Listing](#listing)). | | GET | `/parties/` | open | Public registration record by envelope UUID. | | GET | `/healthz` | open | Liveness check. | @@ -220,8 +254,8 @@ issuer's key endpoint is unreachable (retry). The response is addressed and signed for the token's issuer. Inbox deliveries carry no token: the registration subject is the envelope's `from`, confirmed by its signature for the lookup. Key discovery stays open, -and `/parties` remains an open directory of verified — hence -deliberately public — identities. The lookup's own sender `GET /who` +and `/parties` remains an open directory of registrations, listing +party details only where the party chose to ([Listing](#listing)). The lookup's own sender `GET /who` eligibility check authenticates as `lookup.gobl.org`; its deliveries carry no token. Authenticated requests are logged with the requester address, forming the request audit log. diff --git a/internal/domain/listing.go b/internal/domain/listing.go new file mode 100644 index 0000000..4821ba7 --- /dev/null +++ b/internal/domain/listing.go @@ -0,0 +1,93 @@ +package domain + +import ( + "time" + + "github.com/invopop/gobl" + "github.com/invopop/gobl/cbc" + "github.com/invopop/gobl/head" + "github.com/invopop/gobl/org" + + "github.com/invopop/gobl.lookup/internal/domain/models" +) + +// ListingKey is the envelope header meta key in which a registration +// request sets the subject's listing: ListingPublic or ListingPrivate. +// Without it, a registration keeps its listing; a new one is private. +const ListingKey cbc.Key = "lookup-listing" + +// Listing values. +const ( + ListingPublic = "public" + ListingPrivate = "private" +) + +// takeListing reads and removes the listing from env's header meta. +// It returns nil when the request sets none. +func takeListing(env *gobl.Envelope) (*bool, error) { + v, ok := env.Head.Meta[ListingKey] + if !ok { + return nil, nil + } + delete(env.Head.Meta, ListingKey) + if len(env.Head.Meta) == 0 { + env.Head.Meta = nil + } + switch v { + case ListingPublic: + return boolPtr(true), nil + case ListingPrivate: + return boolPtr(false), nil + } + return nil, ErrValidation.WithMessage("meta %s must be %q or %q", ListingKey, ListingPublic, ListingPrivate) +} + +func boolPtr(b bool) *bool { return &b } + +// PartyRecord returns the public view of rec served at /parties: the +// address, verifier and registration dates, and for a public listing +// the party's name and tax ID. It returns nil when rec has no +// countersigned envelope yet. +func (d *Registrations) PartyRecord(rec *models.Registration) *models.PartyRecord { + env := rec.CountersignedEnvelope + if env == nil { + return nil + } + out := &models.PartyRecord{ + Address: rec.Address, + Verifier: rec.Verifier, + VerifiedAt: rec.VerifiedAt, + Public: rec.Public, + } + if p := d.countersignature(env); p != nil { + out.RegisteredAt = unixTime(p.IssuedAt) + out.RegisteredUntil = unixTime(p.ExpiresAt) + } + if rec.Public { + if party, ok := env.Extract().(*org.Party); ok { + out.Name = party.Name + out.TaxID = party.TaxID + } + } + return out +} + +// countersignature returns the payload of the lookup's own +// countersignature on env, or nil. +func (d *Registrations) countersignature(env *gobl.Envelope) *head.SigningPayload { + self := d.identity.Address().String() + for _, sig := range env.Signatures { + if p, err := head.SignedPayload(sig); err == nil && p.Iss == self { + return p + } + } + return nil +} + +func unixTime(s int64) *time.Time { + if s == 0 { + return nil + } + t := time.Unix(s, 0).UTC() + return &t +} diff --git a/internal/domain/models/registration.go b/internal/domain/models/registration.go index 0edd500..8ccff29 100644 --- a/internal/domain/models/registration.go +++ b/internal/domain/models/registration.go @@ -8,6 +8,7 @@ import ( "github.com/invopop/couch" "github.com/invopop/gobl" "github.com/invopop/gobl/net" + "github.com/invopop/gobl/tax" "github.com/invopop/gobl/uuid" ) @@ -51,6 +52,21 @@ type Registration struct { // Lineage lists the subject keys bound in turn since the lineage // last started (spec §7.3); the last is the current one. Lineage []*LineageKey `json:"lineage,omitempty"` + // Public lists the party's name and tax ID in its public record. + Public bool `json:"public,omitempty"` +} + +// PartyRecord is the public view of a registration served at +// /parties. Name and TaxID are set only for a public listing. +type PartyRecord struct { + Address net.Address `json:"address"` + Verifier net.Address `json:"verifier"` + VerifiedAt *time.Time `json:"verified_at,omitempty"` + RegisteredAt *time.Time `json:"registered_at,omitempty"` + RegisteredUntil *time.Time `json:"registered_until,omitempty"` + Public bool `json:"public"` + Name string `json:"name,omitempty"` + TaxID *tax.Identity `json:"tax_id,omitempty"` } // LineageKey is one subject key in a registration's lineage. diff --git a/internal/domain/registrations.go b/internal/domain/registrations.go index 94669a9..6cab6e3 100644 --- a/internal/domain/registrations.go +++ b/internal/domain/registrations.go @@ -96,6 +96,11 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode d.log.Warn("inbox.rejected", "reason", "not_a_party", "caller", string(sender)) return nil, ErrValidation.WithMessage("registration envelope must contain an org.Party") } + public, err := takeListing(env) + if err != nil { + d.log.Warn("inbox.rejected", "reason", "listing", "caller", string(sender)) + return nil, err + } // Any signature claiming to be this lookup's must actually be one: // a renewal carries the previous countersignature, and a broken or @@ -163,7 +168,7 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode // Persist before delivery so the record exists even if the // downstream POST fails. - rec, err := d.upsert(ctx, prev, sender, env, verifier, lineage) + rec, err := d.upsert(ctx, prev, sender, env, verifier, lineage, public) if err != nil { d.log.Error("inbox.persist_failed", "caller", string(sender), "error", err.Error()) return nil, ErrInternal.WithCause(err) @@ -372,8 +377,9 @@ func (d *Registrations) found(rec *models.Registration, err error) (*models.Regi // upsert writes the registration record for sender from the freshly // countersigned envelope, building on prev (nil for a first -// registration, preserving the store's _rev token otherwise). -func (d *Registrations) upsert(ctx context.Context, prev *models.Registration, sender goblnet.Address, env *gobl.Envelope, verifier goblnet.Address, lineage []*models.LineageKey) (*models.Registration, error) { +// registration, preserving the store's _rev token otherwise). A nil +// public keeps the record's listing. +func (d *Registrations) upsert(ctx context.Context, prev *models.Registration, sender goblnet.Address, env *gobl.Envelope, verifier goblnet.Address, lineage []*models.LineageKey, public *bool) (*models.Registration, error) { rec := prev prevVerifier := goblnet.Address("") if rec == nil { @@ -390,6 +396,9 @@ func (d *Registrations) upsert(ctx context.Context, prev *models.Registration, s rec.Status = models.StatusCountersigned rec.CountersignedEnvelope = env rec.Lineage = lineage + if public != nil { + rec.Public = *public + } // The verification timestamp is kept across renewals with the // same verifier, and stamped fresh when another one verifies. if rec.VerifiedAt == nil || verifier != prevVerifier { diff --git a/internal/interfaces/web/parties.go b/internal/interfaces/web/parties.go index 95a4cf3..c183b73 100644 --- a/internal/interfaces/web/parties.go +++ b/internal/interfaces/web/parties.go @@ -11,8 +11,9 @@ import ( // handleParty serves the public registry record at `/parties/`. // `` may be either an address (FQDN form, e.g. `alice.example`) -// or an envelope UUID. Returns the countersigned envelope as -// application/json on success, 404 when no record matches. +// or an envelope UUID. Every registered party gets its address, +// verifier and registration dates; a public listing adds its name and +// tax ID. Returns 404 when no record matches. func handleParty(s *domain.Setup, log *slog.Logger) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { key := r.PathValue("key") @@ -31,20 +32,21 @@ func handleParty(s *domain.Setup, log *slog.Logger) http.HandlerFunc { http.Error(w, "internal error", http.StatusInternalServerError) return } - if rec.CountersignedEnvelope == nil { + out := s.Registrations().PartyRecord(rec) + if out == nil { // Record exists but no countersigned envelope yet // (StatusReceived). Treat as not yet published. log.Info("party.lookup", "key", key, "found", false, "status", string(rec.Status)) http.Error(w, "party record not yet published", http.StatusNotFound) return } - body, err := json.Marshal(rec.CountersignedEnvelope) + body, err := json.Marshal(out) if err != nil { log.Error("party.encode_failed", "key", key, "error", err.Error()) http.Error(w, "internal error", http.StatusInternalServerError) return } - log.Info("party.lookup", "key", key, "found", true) + log.Info("party.lookup", "key", key, "found", true, "public", out.Public) writeJSON(w, http.StatusOK, body) } } diff --git a/internal/interfaces/web/web_test.go b/internal/interfaces/web/web_test.go index fd9f5a6..7b25b41 100644 --- a/internal/interfaces/web/web_test.go +++ b/internal/interfaces/web/web_test.go @@ -19,6 +19,7 @@ import ( "github.com/invopop/gobl/head" goblnet "github.com/invopop/gobl/net" "github.com/invopop/gobl/org" + "github.com/invopop/gobl/tax" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -250,6 +251,17 @@ func (f *fixture) renewal(keys ...*dsig.PrivateKey) *gobl.Envelope { return env } +// partyRecord GETs path and decodes the public party record. +func (f *fixture) partyRecord(path string) *models.PartyRecord { + f.t.Helper() + resp := f.get(path) + defer resp.Body.Close() //nolint:errcheck + require.Equal(f.t, http.StatusOK, resp.StatusCode) + out := new(models.PartyRecord) + require.NoError(f.t, json.NewDecoder(resp.Body).Decode(out)) + return out +} + // waitForDeliveries spins until the mock sender records n deliveries // or two seconds pass. The inbox handler delivers async so the POST // returns immediately. @@ -601,23 +613,27 @@ func TestInboxKeyUnavailable(t *testing.T) { func TestPartiesLookup(t *testing.T) { f := newFixture(t) - env := f.request(f.party(), f.subject) + party := f.party() + party.TaxID = &tax.Identity{Country: "ES", Code: "B98602642"} + env := f.request(party, f.subject) require.Equal(t, http.StatusAccepted, f.register(env)) _ = f.waitForDeliveries(1) - t.Run("by UUID", func(t *testing.T) { - resp := f.get("/parties/" + env.Head.UUID.String()) - defer resp.Body.Close() //nolint:errcheck - require.Equal(t, http.StatusOK, resp.StatusCode) - var got gobl.Envelope - require.NoError(t, json.NewDecoder(resp.Body).Decode(&got)) - assert.Equal(t, env.Head.UUID, got.Head.UUID) + t.Run("a private party by UUID gets the minimal record", func(t *testing.T) { + got := f.partyRecord("/parties/" + env.Head.UUID.String()) + assert.Equal(t, f.subAddr, got.Address) + assert.Equal(t, f.verifAddr, got.Verifier) + assert.False(t, got.Public) + require.NotNil(t, got.VerifiedAt) + require.NotNil(t, got.RegisteredAt) + require.NotNil(t, got.RegisteredUntil) + assert.WithinDuration(t, got.RegisteredAt.Add(90*24*time.Hour), *got.RegisteredUntil, time.Second) + assert.Empty(t, got.Name) + assert.Nil(t, got.TaxID) }) t.Run("by address", func(t *testing.T) { - resp := f.get("/parties/" + string(f.subAddr)) - defer resp.Body.Close() //nolint:errcheck - assert.Equal(t, http.StatusOK, resp.StatusCode) + assert.Equal(t, f.subAddr, f.partyRecord("/parties/"+string(f.subAddr)).Address) }) t.Run("not found", func(t *testing.T) { @@ -627,6 +643,54 @@ func TestPartiesLookup(t *testing.T) { }) } +func TestListing(t *testing.T) { + listing := func(env *gobl.Envelope, v string) *gobl.Envelope { + env.Head.Meta = cbc.Meta{domain.ListingKey: v} + return env + } + + t.Run("a public listing adds the name and tax ID", func(t *testing.T) { + f := newFixture(t) + party := f.party() + party.TaxID = &tax.Identity{Country: "ES", Code: "B98602642"} + require.Equal(t, http.StatusAccepted, f.register(listing(f.request(party, f.subject), domain.ListingPublic))) + assert.True(t, f.record().Public) + got := f.partyRecord("/parties/" + string(f.subAddr)) + assert.True(t, got.Public) + assert.Equal(t, "Alice", got.Name) + require.NotNil(t, got.TaxID) + assert.Equal(t, "B98602642", got.TaxID.Code.String()) + + sent := f.waitForDeliveries(1) + assert.Empty(t, sent[0].env.Head.Meta, "the listing is not passed on") + assert.Empty(t, f.record().CountersignedEnvelope.Head.Meta) + }) + + t.Run("a renewal without a listing keeps it, and private removes it", func(t *testing.T) { + f := newFixture(t) + require.Equal(t, http.StatusAccepted, f.register(listing(f.request(f.party(), f.subject), domain.ListingPublic))) + require.Equal(t, http.StatusAccepted, f.register(f.renewal(f.subject))) + assert.True(t, f.record().Public) + + require.Equal(t, http.StatusAccepted, f.register(listing(f.renewal(f.subject), domain.ListingPrivate))) + assert.False(t, f.record().Public) + assert.Empty(t, f.partyRecord("/parties/"+string(f.subAddr)).Name) + }) + + t.Run("keeps other meta", func(t *testing.T) { + f := newFixture(t) + env := f.request(f.party(), f.subject) + env.Head.Meta = cbc.Meta{domain.ListingKey: domain.ListingPublic, "other": "x"} + require.Equal(t, http.StatusAccepted, f.register(env)) + assert.Equal(t, cbc.Meta{"other": "x"}, f.record().CountersignedEnvelope.Head.Meta) + }) + + t.Run("rejects an unknown listing", func(t *testing.T) { + f := newFixture(t) + assert.Equal(t, http.StatusUnprocessableEntity, f.register(listing(f.request(f.party(), f.subject), "everyone"))) + }) +} + func TestKeysEndpoint(t *testing.T) { f := newFixture(t) kid := f.lookup.PrivateKey.ID() From 5f42170df651ba7e69092d6ebf02935c2da5db10 Mon Sep 17 00:00:00 2001 From: Sam Lown Date: Sun, 15 Nov 2026 22:20:40 +0000 Subject: [PATCH 08/11] Split the changelog by release Entries shipped in v0.1.0, v0.2.0 and v0.4.0 move under those releases, leaving only this branch's changes as unreleased. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ccfd9e3..a5fda98 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,8 +12,11 @@ - `GET /.well-known/gobl/who` answers with the lookup's party envelope addressed and signed for the requester, with `Vary: Authorization`. - Deliveries to subjects carry no request token. -- Verification is now list-driven and automatic: the registry accepts a configured set of verification providers (`--verifiers` / `VERIFIERS`), and a registration or renewal arriving with a valid countersignature from one of them is verified on arrival — the countersignature is cryptographically checked against the provider's published key before being named (an unreachable key endpoint registers unverified and logs `inbox.auto_verify_unavailable`; the derivation re-runs on renewal). `gobl.lookup verify
` loses the `--verifier` flag and becomes a recovery command that re-derives the verifier from the stored envelope, e.g. after a provider is added to the accepted list. The discovery link stamped on countersigned envelopes uses the standard `verification` category (the previous `authority` value failed envelope validation on re-signing). +## [v0.4.0] - 2026-07-30 + +### Changed +- Verification is now list-driven and automatic: the registry accepts a configured set of verification providers (`--verifiers` / `VERIFIERS`), and a registration or renewal arriving with a valid countersignature from one of them is verified on arrival — the countersignature is cryptographically checked against the provider's published key before being named (an unreachable key endpoint registers unverified and logs `inbox.auto_verify_unavailable`; the derivation re-runs on renewal). `gobl.lookup verify
` loses the `--verifier` flag and becomes a recovery command that re-derives the verifier from the stored envelope, e.g. after a provider is added to the accepted list. The discovery link stamped on countersigned envelopes uses the standard `verification` category (the previous `authority` value failed envelope validation on re-signing). - Transient failures now answer `503 Service Unavailable` instead of a definitive 4xx: an unreachable requester key endpoint during token verification (log reason `token_unavailable`), and an @@ -22,7 +25,6 @@ outages must not permanently reject. Outbound deliveries likewise distinguish retryable conditions (transport failures, 429, 5xx → `net.ErrUnavailable`) from definitive inbox rejections. - - Every Authority countersignature now carries a 90-day `exp` claim; parties renew by re-registering before it passes. A renewal with an unchanged party document (same digest) is countersigned with the party's current `verifier` claim — verified stays verified — while changed party data drops the verifier and clears `verified_at`. - The `scope` claim is replaced by structural verification (spec §5.3): a registration countersignature alone asserts a registered identity, and `gobl.lookup verify` re-countersigns with a `verifier` claim naming the KYC/KYB authority. `--verifier` names an external verifying authority (its own countersignature must already be on the stored envelope); the default is the lookup itself, whose single countersignature carries both attestations. The verifier signature's `exp` is independent of the 90-day registration cycle, so verifications can be much longer-lived. `Registration.Verifier` replaces the stored `scope` field. - `/.well-known/gobl/who` is now a `GET` serving the lookup's self-signed party envelope (signed once per process), replacing the authenticated `POST` exchange. Together with `/inbox` it requires a bearer request token (spec §5.5): the requester's token is verified against its published key, audience, and freshness window, and requests without a valid token are rejected with `401` (`auth.rejected` log reasons `token_missing`/`token_invalid`/`token_expired`). The response is served with `Cache-Control: private, max-age=300`; authenticated requests are logged with the requester address as the request audit log. Key discovery and `/parties` stay open. @@ -30,11 +32,14 @@ - Registration now requires the sender to serve its own public identity: the inbox resolves `GET /who` on the sender's address (re-fetching its published key) before countersigning. A `204 No Content` — a receive-only account — or an unresolvable identity rejects the registration with `403 Forbidden`. - Allow-list support (`allow.json`, `models.Identity.Allow`) is removed; the sender `/who` check is the gate on registrations. - Updated to the current `gobl` net API: `Envelope.Sign` options (`head.WithIssuer`/`WithAudience`/`WithVerifier`) and `net.Client.Who`. Signed `iss`/`aud`/`verifier` claims carry bare GOBL Net addresses (FQDNs) rather than `gobl:` URIs; the scheme remains only on `org.Endpoint` URIs. + +## [v0.2.0] - 2026-07-09 + +### Changed + - Identity key files under `keys/` no longer need to be named after their kid — the kid is read from the JWK itself, and any `*.json` file is accepted (`Init` still writes `.json`). This lets a deployment mount the published key at a fixed path (e.g. `keys/public.json`) without encoding the kid in the filename. -- Persistence now uses the shared [`github.com/invopop/couch`](https://github.com/invopop/couch) library: `models.Registration` embeds `couch.Model` (gaining `created_at`/`updated_at` and revision handling), and the CouchDB store uses `couch.Client`/`couch.Store`/`couch.Fetch` and a `couch.Design` for the by-UUID view. The registration database is the couch client's prefix (`COUCHDB_DATABASE`). -- Configuration is now read from the environment (`CONFIG_DIR`, `COUCHDB_URL` or the split `COUCHDB_SCHEME/HOST/PORT/USERNAME/PASSWORD`, `COUCHDB_DATABASE`, `HTTP_PORT`/`PORT`, `PUBLIC_BASE_URL`, `LOG_JSON`) so the service can be configured — and its CouchDB password injected from a secret — the way the cluster provides config. The equivalent CLI flags still work and override the environment. Env var names match the sibling services (silo/access). -- Removed the Fly.io deployment (`fly.toml`); the `Dockerfile` (small, static, non-root) is the deployment artifact for the Kubernetes cluster. -- Restructured the codebase along the standard Invopop layered architecture (cf. `silo`, `access`): business logic now lives in `internal/domain` (orchestrated by `domain.Setup`), data structures in `internal/domain/models`, persistence in `internal/domain/repos`, outbound delivery in `internal/domain/delivery`, and the HTTP layer in `internal/interfaces/web`. The registration and verification flows moved out of the HTTP handlers into the `domain.Registrations` service; handlers are now thin adapters that map domain errors onto HTTP status codes. No change to the wire protocol, endpoints, CouchDB schema, or CLI. + +## [v0.1.0] - 2026-07-09 ### Added @@ -51,6 +56,13 @@ - Async delivery: the `/inbox` POST returns `202 Accepted` once the record is persisted; the actual POST to the sender's `/inbox` happens in a background goroutine. Failures are recorded on the registry record (`Status: failed`, `LastDeliveryError`). - Re-registration semantics: a fresh registration for an existing address drops `scope` back to `registered` and clears `verified_at` (party data may have changed since the last KYC). +### Changed + +- Persistence now uses the shared [`github.com/invopop/couch`](https://github.com/invopop/couch) library: `models.Registration` embeds `couch.Model` (gaining `created_at`/`updated_at` and revision handling), and the CouchDB store uses `couch.Client`/`couch.Store`/`couch.Fetch` and a `couch.Design` for the by-UUID view. The registration database is the couch client's prefix (`COUCHDB_DATABASE`). +- Configuration is now read from the environment (`CONFIG_DIR`, `COUCHDB_URL` or the split `COUCHDB_SCHEME/HOST/PORT/USERNAME/PASSWORD`, `COUCHDB_DATABASE`, `HTTP_PORT`/`PORT`, `PUBLIC_BASE_URL`, `LOG_JSON`) so the service can be configured — and its CouchDB password injected from a secret — the way the cluster provides config. The equivalent CLI flags still work and override the environment. Env var names match the sibling services (silo/access). +- Removed the Fly.io deployment (`fly.toml`); the `Dockerfile` (small, static, non-root) is the deployment artifact for the Kubernetes cluster. +- Restructured the codebase along the standard Invopop layered architecture (cf. `silo`, `access`): business logic now lives in `internal/domain` (orchestrated by `domain.Setup`), data structures in `internal/domain/models`, persistence in `internal/domain/repos`, outbound delivery in `internal/domain/delivery`, and the HTTP layer in `internal/interfaces/web`. The registration and verification flows moved out of the HTTP handlers into the `domain.Registrations` service; handlers are now thin adapters that map domain errors onto HTTP status codes. No change to the wire protocol, endpoints, CouchDB schema, or CLI. + ### Security - Inbox `aud` is required: an envelope POSTed to `/inbox` MUST be signed with `aud` equal to the lookup’s address. Envelopes without an audience, or bound to a different audience, are rejected with 401 (replay protection — mirrors the recent gobl.dev inbox tightening). From 8418b70aef1261ff904bfaa215f044f6e34a4a5f Mon Sep 17 00:00:00 2001 From: Sam Lown Date: Sun, 15 Nov 2026 22:34:00 +0000 Subject: [PATCH 09/11] Require fresh requests and named successors, and follow no redirects 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 --- CHANGELOG.md | 5 +- README.md | 15 +++-- go.mod | 2 +- go.sum | 4 +- internal/domain/delivery/delivery.go | 66 ++++++++++++++++--- internal/domain/delivery/delivery_test.go | 34 ++++++++++ internal/domain/lineage.go | 54 ++++++++-------- internal/domain/lineage_internal_test.go | 77 ++++++++++++++++++----- internal/domain/registrations.go | 32 ++++++++-- internal/interfaces/web/web_test.go | 59 ++++++++++++++++- 10 files changed, 282 insertions(+), 66 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a5fda98..ca4ee7e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,12 +5,13 @@ ### Changed - Registrations follow the latest GOBL Net spec. A request is an ordinary delivery from the subject to the lookup, confirmed by its signature for the lookup, and needs no request token; the subject is its `from` address. The lookup drops the request signature, countersigns with a `cnf` claim binding the subject's key, and addresses the envelope back to the subject. -- The lookup keeps each address's key lineage (`Registration.Lineage`). A request signed with the current and a new key rolls over to the new key; one signed only with an unknown key starts a new lineage, and needs a verification for that key. Rollovers need no new verification, a key bound before cannot become current again, and a new holder of an address cannot inherit its verification. +- The lookup keeps each address's key lineage (`Registration.Lineage`). A request signed with the current key, naming a new key with `cnf`, and with that new key rolls over to the new key; one signed only with an unknown key starts a new lineage, and needs a verification for that key. Rollovers need no new verification, a key bound before cannot become current again, and a new holder of an address cannot inherit its verification. - The lookup registers only verified parties: a registration needs a countersignature from an accepted verifier binding, with `cnf`, a key in the subject's lineage, and is rejected with `403` without one (`503` when the verifier's key cannot be fetched). The `gobl.lookup verify` command is removed; a subject registers again instead. - Verifiers are no longer accepted delivering to the lookup on a subject's behalf; the subject registers again with the verified envelope. The renewal rule based on an unchanged digest is replaced by the lineage check. - `GET /parties/` returns a public record instead of the countersigned envelope: the party's address, verifier, verification and registration dates, plus its name and tax ID when listed. A registration request lists the party with header meta `lookup-listing: public` and unlists it with `private`; without the key the choice is kept, and new registrations start private. The key is removed before countersigning. - `GET /.well-known/gobl/who` answers with the lookup's party envelope addressed and signed for the requester, with `Vary: Authorization`. -- Deliveries to subjects carry no request token. +- Only signatures made within the last 5 minutes count towards a registration request, so an earlier request cannot be replayed (`401` when none is fresh). +- Deliveries to subjects carry no request token, follow no redirects, and refuse every address that is not globally reachable, matching `gobl/net`. ## [v0.4.0] - 2026-07-30 diff --git a/README.md b/README.md index 355c84b..f95a699 100644 --- a/README.md +++ b/README.md @@ -101,14 +101,16 @@ verification before it can renew. The lookup keeps each address's key lineage (spec §7.3): the keys it has bound in turn, by RFC 7638 thumbprint and kid. The keys that -sign a registration request decide what happens: +sign a registration request decide what happens. Only signatures made +within the last 5 minutes count, so an earlier request cannot be +replayed: | Request signed with | Result | |--------------------------------------|------------------------------------------------------------| | the current key (or a first key) | renewal (or first registration): the key stays bound | -| the current key and a new key | rollover: the new key joins the lineage and is bound | +| the current key, naming a new key with `cnf`, and that new key | rollover: the new key joins the lineage and is bound | | only a key that is not the current one | a lost key or a new holder: a new lineage starts, if a verification binds that key | -| two keys at a first registration | the key a verification binds starts the lineage, then rolls over | +| two keys at a first registration | the key a verification binds starts the lineage, then rolls over to the key it names | The lookup registers a party only when a verifier's countersignature binds, with `cnf`, a key in the current lineage. A rollover therefore @@ -352,8 +354,11 @@ arrives from a secret independently of the host). ## Operations - **Renewal and key changes**: a request signed with the current key - renews, stamping a fresh 90-day countersignature; one signed with - the current and a new key rolls over to the new key. Either needs + renews, stamping a fresh 90-day countersignature; one also signed + with a new key, which the current key's signature names with `cnf` + (`goblnet.Sign(env, key, from, to, head.WithConfirmation(next.JKT()))`), + rolls over to the new key. Requests must be signed within the last + 5 minutes. Either needs the request to carry a verification bound to a key in the lineage. Changed party data, or a request signed only with an unknown key, needs a new verification. Records without a lineage diff --git a/go.mod b/go.mod index dad681d..5b91499 100644 --- a/go.mod +++ b/go.mod @@ -5,7 +5,7 @@ go 1.25.0 require ( github.com/go-kivik/kivik/v4 v4.5.2 github.com/invopop/couch v0.1.0 - github.com/invopop/gobl v0.512.1-0.20261115134102-700b886e1a8e + github.com/invopop/gobl v0.512.1-0.20261115223033-d273609a4a78 github.com/magefile/mage v1.17.2 github.com/spf13/cobra v1.10.2 github.com/stretchr/testify v1.11.1 diff --git a/go.sum b/go.sum index 6df692e..95c4a61 100644 --- a/go.sum +++ b/go.sum @@ -34,8 +34,8 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/invopop/couch v0.1.0 h1:ctMKLeIxnab9KW11KtEAQSl7RzGgMxndavLphx99LpY= github.com/invopop/couch v0.1.0/go.mod h1:xzBNVglDnLcpf1Z9BJxiIG1liESSIkMuvIczSl4zcls= -github.com/invopop/gobl v0.512.1-0.20261115134102-700b886e1a8e h1:fd9n4+gY08Mg2V1M/w+igZIWItZPkBQW4+XZ2MULYyw= -github.com/invopop/gobl v0.512.1-0.20261115134102-700b886e1a8e/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= +github.com/invopop/gobl v0.512.1-0.20261115223033-d273609a4a78 h1:wRqOVUJ70XtRbG29DFqy/saGKyOMcOzPCl9OXKeGQ4c= +github.com/invopop/gobl v0.512.1-0.20261115223033-d273609a4a78/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= github.com/invopop/jsonschema v0.14.0 h1:MHQqLhvpNUZfw+hM3AZDYK7jxO8FZoQeQM77g8iyZjg= github.com/invopop/jsonschema v0.14.0/go.mod h1:ygm6C2EaVNMBDPpaPlnOA2pFAxBnxGjFlMZABxm9n2I= github.com/invopop/yaml v0.3.1 h1:f0+ZpmhfBSS4MhG+4HYseMdJhoeeopbSKbq5Rpeelso= diff --git a/internal/domain/delivery/delivery.go b/internal/domain/delivery/delivery.go index 9337382..d0718f0 100644 --- a/internal/domain/delivery/delivery.go +++ b/internal/domain/delivery/delivery.go @@ -1,8 +1,8 @@ // Package delivery POSTs a signed envelope to a remote GOBL Net // inbox (e.g. the sender's own /.well-known/gobl/inbox) after the -// lookup has countersigned it. The transport reuses gobl/net's -// rules: HTTPS only, refuse to dial loopback / private / link-local -// / multicast / unspecified addresses (SSRF defense). The check is +// lookup has countersigned it. The transport follows gobl/net's +// rules (spec §9): it refuses to dial addresses that are not globally +// reachable (SSRF defense) and follows no redirects. The checks are // inlined here rather than imported from gobl/net (the helpers are // unexported there); the canonical implementation lives in // gobl/net/client.go. @@ -58,8 +58,8 @@ type HTTPSender struct { } // New returns an HTTPSender whose transport refuses to dial any -// resolved IP that is loopback, private, link-local, multicast, or -// unspecified. +// resolved IP that is not globally reachable (see isPublicIP) and +// follows no redirects. func New() *HTTPSender { return newSender(false) } @@ -82,7 +82,13 @@ func newSender(allowLoopback bool) *HTTPSender { // No fixed Timeout: the per-request deadline comes from the // caller's context (see Send), keeping it in step with the // domain's delivery timeout. - client: &http.Client{Transport: transport}, + client: &http.Client{ + Transport: transport, + // A redirect could move the delivery to plain HTTP. + CheckRedirect: func(*http.Request, []*http.Request) error { + return http.ErrUseLastResponse + }, + }, } } @@ -117,6 +123,8 @@ func (s *HTTPSender) Send(ctx context.Context, addr net.Address, env *gobl.Envel switch { case resp.StatusCode == http.StatusAccepted: return nil + case resp.StatusCode >= 300 && resp.StatusCode < 400: + return fmt.Errorf("%w: HTTP %d from %s: redirects are not followed", ErrInboxRejected, resp.StatusCode, url) case resp.StatusCode == http.StatusTooManyRequests || resp.StatusCode >= 500: return fmt.Errorf("%w: HTTP %d from %s", ErrUnavailable, resp.StatusCode, url) default: @@ -159,9 +167,11 @@ func safeDialContext(ctx context.Context, network, addr string) (stdnet.Conn, er return nil, lastErr } -// isPublicIP rejects any loopback, private (RFC 1918 / RFC 6598), -// link-local, multicast, or unspecified IP. Mirrors the helper in -// gobl/net/client.go. +// isPublicIP reports whether ip is globally reachable: not loopback, +// private, link-local, multicast or unspecified, and in none of the IANA +// special-purpose ranges that are not globally reachable, nor in a +// translation range (NAT64, 6to4, Teredo) that can reach them. Mirrors +// the helper in gobl/net/client.go. func isPublicIP(ip stdnet.IP) bool { if ip == nil { return false @@ -176,5 +186,43 @@ func isPublicIP(ip stdnet.IP) bool { ip.IsMulticast(): return false } + for _, n := range nonPublicNets { + if n.Contains(ip) { + return false + } + } return true } + +// nonPublicNets lists the ranges the net.IP methods miss, from the IANA +// IPv4 and IPv6 special-purpose address registries. +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) + "192.0.2.0/24", // documentation, TEST-NET-1 (RFC 5737) + "192.88.99.0/24", // 6to4 relay anycast (RFC 7526) + "198.18.0.0/15", // benchmarking (RFC 2544) + "198.51.100.0/24", // documentation, TEST-NET-2 (RFC 5737) + "203.0.113.0/24", // documentation, TEST-NET-3 (RFC 5737) + "240.0.0.0/4", // reserved, and broadcast (RFC 1112) + "64:ff9b::/96", // NAT64 (RFC 6052) + "64:ff9b:1::/48", // local-use NAT64 (RFC 8215) + "100::/64", // discard-only (RFC 6666) + "2001::/23", // IETF protocol assignments, including Teredo (RFC 2928) + "2001:db8::/32", // documentation (RFC 3849) + "2002::/16", // 6to4 (RFC 3056) + "3fff::/20", // documentation (RFC 9637) + "5f00::/16", // segment routing SIDs (RFC 9602) + } + nets := make([]*stdnet.IPNet, len(cidrs)) + for i, c := range cidrs { + _, n, err := stdnet.ParseCIDR(c) + if err != nil { + panic(err) + } + nets[i] = n + } + return nets +}() diff --git a/internal/domain/delivery/delivery_test.go b/internal/domain/delivery/delivery_test.go index 96a5604..3b8239e 100644 --- a/internal/domain/delivery/delivery_test.go +++ b/internal/domain/delivery/delivery_test.go @@ -123,6 +123,16 @@ func TestIsPublicIP(t *testing.T) { "169.254.169.254": false, "0.0.0.0": false, "224.0.0.1": false, + "100.64.0.1": false, + "192.0.2.1": false, + "198.51.100.1": false, + "203.0.113.1": false, + "198.18.0.1": false, + "240.0.0.1": false, + "2001:db8::1": false, + "64:ff9b::a00:1": false, + "2002:a00:1::1": false, + "2a00:1450::1": true, } for ip, want := range cases { t.Run(ip, func(t *testing.T) { @@ -181,6 +191,12 @@ func TestSendRetryableTaxonomy(t *testing.T) { assert.True(t, errors.Is(err, ErrUnavailable)) }) + t.Run("a redirect is a definitive rejection", func(t *testing.T) { + err := send(t, http.StatusTemporaryRedirect) + require.ErrorIs(t, err, ErrInboxRejected) + assert.ErrorContains(t, err, "redirects are not followed") + }) + t.Run("4xx is a definitive rejection", func(t *testing.T) { err := send(t, http.StatusUnauthorized) require.Error(t, err) @@ -188,3 +204,21 @@ func TestSendRetryableTaxonomy(t *testing.T) { assert.False(t, errors.Is(err, ErrUnavailable)) }) } + +func TestSenderFollowsNoRedirects(t *testing.T) { + var followed bool + target := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { + followed = true + })) + defer target.Close() + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + http.Redirect(w, r, target.URL+r.URL.Path, http.StatusTemporaryRedirect) + })) + defer srv.Close() + + resp, err := newSender(true).client.Post(srv.URL+net.InboxPath, "application/json", strings.NewReader(`{}`)) + require.NoError(t, err) + defer resp.Body.Close() //nolint:errcheck + assert.Equal(t, http.StatusTemporaryRedirect, resp.StatusCode) + assert.False(t, followed) +} diff --git a/internal/domain/lineage.go b/internal/domain/lineage.go index 94e5936..2fbfbea 100644 --- a/internal/domain/lineage.go +++ b/internal/domain/lineage.go @@ -5,20 +5,24 @@ import ( "time" "github.com/invopop/gobl/dsig" + goblnet "github.com/invopop/gobl/net" "github.com/invopop/gobl.lookup/internal/domain/models" ) // errLineage is returned when a registration request's keys cannot // extend or start a lineage. -var errLineage = errors.New("registration must be signed with the current key, a new key, or both") +var errLineage = errors.New("registration must be signed with the current key, a new key, " + + "or the current key naming a new one with cnf") -// nextLineage applies the keys confirming a registration request to -// the current lineage (spec §7.3) and returns the resulting one, whose -// last key is bound. verified holds the cnf thumbprints of accepted -// verification countersignatures on the request, which order the keys -// of a first registration signed with two. -func nextLineage(lineage []*models.LineageKey, keys []*dsig.PublicKey, verified []string, now time.Time) ([]*models.LineageKey, error) { +// nextLineage applies the signatures confirming a registration request +// to the current lineage (spec §7.3) and returns the resulting one, +// whose last key is bound. In a key change the current key's signature +// must name the new key as its successor. verified holds the cnf +// thumbprints of accepted verification countersignatures on the +// request, which pick the current key of a first registration signed +// with two. +func nextLineage(lineage []*models.LineageKey, confs []*goblnet.ConfirmingSignature, verified []string, now time.Time) ([]*models.LineageKey, error) { entry := func(k *dsig.PublicKey) *models.LineageKey { return &models.LineageKey{JKT: k.JKT(), KID: k.ID(), AddedAt: now} } @@ -26,9 +30,9 @@ func nextLineage(lineage []*models.LineageKey, keys []*dsig.PublicKey, verified if len(lineage) > 0 { current = lineage[len(lineage)-1].JKT } - switch len(keys) { + switch len(confs) { case 1: - k := keys[0] + k := confs[0].Key if k.JKT() == current { return lineage, nil // renewal } @@ -36,23 +40,23 @@ func nextLineage(lineage []*models.LineageKey, keys []*dsig.PublicKey, verified // a lost key or a new holder of the address starts afresh. return []*models.LineageKey{entry(k)}, nil case 2: - a, b := keys[0], keys[1] - if current != "" { - // The other key must be new: a key bound before cannot - // become current again. - switch { - case current == a.JKT() && !inLineage(lineage, b.JKT()): - return append(lineage, entry(b)), nil - case current == b.JKT() && !inLineage(lineage, a.JKT()): - return append(lineage, entry(a)), nil + // from is the key changed from, to the one it names. + for _, pair := range [][2]*goblnet.ConfirmingSignature{{confs[0], confs[1]}, {confs[1], confs[0]}} { + from, to := pair[0], pair[1] + if from.Successor != to.Key.JKT() { + continue + } + if current != "" { + // The new key must be new: a key bound before cannot + // become current again. + if from.Key.JKT() == current && !inLineage(lineage, to.Key.JKT()) { + return append(lineage, entry(to.Key)), nil + } + continue + } + if contains(verified, from.Key.JKT()) && !contains(verified, to.Key.JKT()) { + return []*models.LineageKey{entry(from.Key), entry(to.Key)}, nil } - return nil, errLineage - } - switch { - case contains(verified, a.JKT()) && !contains(verified, b.JKT()): - return []*models.LineageKey{entry(a), entry(b)}, nil - case contains(verified, b.JKT()) && !contains(verified, a.JKT()): - return []*models.LineageKey{entry(b), entry(a)}, nil } return nil, errLineage } diff --git a/internal/domain/lineage_internal_test.go b/internal/domain/lineage_internal_test.go index 0d76f0c..5a8472f 100644 --- a/internal/domain/lineage_internal_test.go +++ b/internal/domain/lineage_internal_test.go @@ -5,6 +5,7 @@ import ( "time" "github.com/invopop/gobl/dsig" + goblnet "github.com/invopop/gobl/net" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -14,12 +15,18 @@ import ( func TestNextLineage(t *testing.T) { now := time.Now() a, b, c := dsig.NewES256Key(), dsig.NewES256Key(), dsig.NewES256Key() - pub := func(ks ...*dsig.PrivateKey) []*dsig.PublicKey { - out := make([]*dsig.PublicKey, len(ks)) - for i, k := range ks { - out[i] = k.Public() + // conf is a confirming signature by k, naming next (if any) as + // its successor. + conf := func(k, next *dsig.PrivateKey) *goblnet.ConfirmingSignature { + c := &goblnet.ConfirmingSignature{Key: k.Public(), IssuedAt: now} + if next != nil { + c.Successor = next.JKT() } - return out + return c + } + // change is a key change request from k to next. + change := func(k, next *dsig.PrivateKey) []*goblnet.ConfirmingSignature { + return []*goblnet.ConfirmingSignature{conf(next, nil), conf(k, next)} } lineage := func(ks ...*dsig.PrivateKey) []*models.LineageKey { out := make([]*models.LineageKey, len(ks)) @@ -36,43 +43,83 @@ func TestNextLineage(t *testing.T) { return out } - t.Run("rolls over with the current key signing second", func(t *testing.T) { - got, err := nextLineage(lineage(a), pub(b, a), nil, now) + t.Run("renews with the current key", func(t *testing.T) { + got, err := nextLineage(lineage(a), []*goblnet.ConfirmingSignature{conf(a, nil)}, nil, now) + require.NoError(t, err) + assert.Equal(t, []string{a.JKT()}, jkts(got)) + }) + + t.Run("starts afresh with one key that is not current", func(t *testing.T) { + got, err := nextLineage(lineage(a), []*goblnet.ConfirmingSignature{conf(b, nil)}, nil, now) + require.NoError(t, err) + assert.Equal(t, []string{b.JKT()}, jkts(got)) + }) + + t.Run("changes to the key the current key names", func(t *testing.T) { + got, err := nextLineage(lineage(a), change(a, b), nil, now) require.NoError(t, err) assert.Equal(t, []string{a.JKT(), b.JKT()}, jkts(got)) }) - t.Run("rejects a key bound before becoming current again", func(t *testing.T) { - _, err := nextLineage(lineage(a, b), pub(b, a), nil, now) + t.Run("rejects a key change the current key does not name", func(t *testing.T) { + both := []*goblnet.ConfirmingSignature{conf(a, nil), conf(b, nil)} + _, err := nextLineage(lineage(a), both, nil, now) + assert.ErrorIs(t, err, errLineage) + // Naming another key does not count either. + _, err = nextLineage(lineage(a), []*goblnet.ConfirmingSignature{conf(a, c), conf(b, nil)}, nil, now) assert.ErrorIs(t, err, errLineage) - _, err = nextLineage(lineage(a, b), pub(a, b), nil, now) + // Nor does the new key naming the current one. + _, err = nextLineage(lineage(a), change(b, a), nil, now) + assert.ErrorIs(t, err, errLineage) + }) + + t.Run("rejects a key bound before becoming current again", func(t *testing.T) { + _, err := nextLineage(lineage(a, b), change(b, a), nil, now) assert.ErrorIs(t, err, errLineage) }) t.Run("rejects two keys neither of which is current", func(t *testing.T) { - _, err := nextLineage(lineage(a), pub(b, c), nil, now) + _, err := nextLineage(lineage(a), change(b, c), nil, now) assert.ErrorIs(t, err, errLineage) }) t.Run("orders a first registration by the verified key", func(t *testing.T) { - got, err := nextLineage(nil, pub(a, b), []string{b.JKT()}, now) + got, err := nextLineage(nil, change(b, a), []string{b.JKT()}, now) require.NoError(t, err) assert.Equal(t, []string{b.JKT(), a.JKT()}, jkts(got)) }) + t.Run("rejects a first registration whose verified key names no other", func(t *testing.T) { + _, err := nextLineage(nil, []*goblnet.ConfirmingSignature{conf(a, nil), conf(b, nil)}, []string{b.JKT()}, now) + assert.ErrorIs(t, err, errLineage) + _, err = nextLineage(nil, change(a, b), []string{b.JKT()}, now) + assert.ErrorIs(t, err, errLineage) + }) + t.Run("rejects a first registration with both or neither key verified", func(t *testing.T) { - _, err := nextLineage(nil, pub(a, b), []string{a.JKT(), b.JKT()}, now) + _, err := nextLineage(nil, change(a, b), []string{a.JKT(), b.JKT()}, now) assert.ErrorIs(t, err, errLineage) - _, err = nextLineage(nil, pub(a, b), nil, now) + _, err = nextLineage(nil, change(a, b), nil, now) assert.ErrorIs(t, err, errLineage) }) t.Run("rejects more than two keys", func(t *testing.T) { - _, err := nextLineage(lineage(a), pub(a, b, c), nil, now) + _, err := nextLineage(lineage(a), append(change(a, b), conf(c, nil)), nil, now) assert.ErrorIs(t, err, errLineage) }) } +func TestFreshConfirmations(t *testing.T) { + now := time.Now() + at := func(d time.Duration) *goblnet.ConfirmingSignature { + return &goblnet.ConfirmingSignature{Key: dsig.NewES256Key().Public(), IssuedAt: now.Add(d)} + } + fresh, edge, stale := at(-time.Minute), at(-goblnet.MaxRequestAge-requestClockSkew), at(-time.Hour) + got := freshConfirmations([]*goblnet.ConfirmingSignature{fresh, stale, edge}, now) + assert.Equal(t, []*goblnet.ConfirmingSignature{fresh, edge}, got) + assert.Empty(t, freshConfirmations([]*goblnet.ConfirmingSignature{stale}, now)) +} + func TestInLineage(t *testing.T) { k := dsig.NewES256Key() l := []*models.LineageKey{{JKT: k.JKT()}} diff --git a/internal/domain/registrations.go b/internal/domain/registrations.go index 6cab6e3..e7aac01 100644 --- a/internal/domain/registrations.go +++ b/internal/domain/registrations.go @@ -9,8 +9,8 @@ import ( "github.com/invopop/gobl" "github.com/invopop/gobl/head" - "github.com/invopop/gobl/org" goblnet "github.com/invopop/gobl/net" + "github.com/invopop/gobl/org" "github.com/invopop/gobl/uuid" "github.com/invopop/gobl.lookup/internal/domain/delivery" @@ -79,7 +79,7 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode return nil, ErrValidation.WithMessage("envelope failed validation: %s", err.Error()) } - keys, err := d.client.DeliveryKeys(ctx, env, d.identity.Address()) + confs, err := d.client.DeliveryConfirmations(ctx, env, d.identity.Address()) if err != nil { if errors.Is(err, goblnet.ErrUnavailable) { d.log.Warn("inbox.rejected", "reason", "verify_unavailable", "error", err.Error()) @@ -92,6 +92,13 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode if err != nil { return nil, ErrValidation.WithCause(err) } + // Only fresh signatures count (spec §7.3): a replayed earlier + // request does not show that the sender holds its keys now. + confs = freshConfirmations(confs, time.Now()) + if len(confs) == 0 { + d.log.Warn("inbox.rejected", "reason", "stale_request", "caller", string(sender)) + return nil, ErrUnauthorized.WithMessage("registration requests must be signed within the last %s", goblnet.MaxRequestAge) + } if _, ok := env.Extract().(*org.Party); !ok { d.log.Warn("inbox.rejected", "reason", "not_a_party", "caller", string(sender)) return nil, ErrValidation.WithMessage("registration envelope must contain an org.Party") @@ -130,9 +137,9 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode if prev != nil { lineage = prev.Lineage } - lineage, err = nextLineage(lineage, keys, verificationKeys(verifications), time.Now().UTC()) + lineage, err = nextLineage(lineage, confs, verificationKeys(verifications), time.Now().UTC()) if err != nil { - d.log.Warn("inbox.rejected", "reason", "lineage", "caller", string(sender), "keys", len(keys)) + d.log.Warn("inbox.rejected", "reason", "lineage", "caller", string(sender), "keys", len(confs)) return nil, ErrValidation.WithMessage("%s", err.Error()) } verifier := pickVerifier(verifications, lineage) @@ -445,3 +452,20 @@ func (d *Registrations) deliverAsync(sender goblnet.Address, env *gobl.Envelope, ) } } + +// requestClockSkew is the clock skew allowed on a request's signing +// times (spec §6). +const requestClockSkew = 30 * time.Second + +// freshConfirmations returns the confirming signatures made within +// goblnet.MaxRequestAge of now. +func freshConfirmations(confs []*goblnet.ConfirmingSignature, now time.Time) []*goblnet.ConfirmingSignature { + oldest := now.Add(-goblnet.MaxRequestAge - requestClockSkew) + var out []*goblnet.ConfirmingSignature + for _, c := range confs { + if !c.IssuedAt.Before(oldest) { + out = append(out, c) + } + } + return out +} diff --git a/internal/interfaces/web/web_test.go b/internal/interfaces/web/web_test.go index 7b25b41..fd4d727 100644 --- a/internal/interfaces/web/web_test.go +++ b/internal/interfaces/web/web_test.go @@ -171,15 +171,37 @@ func (f *fixture) unverified(party *org.Party, keys ...*dsig.PrivateKey) *gobl.E } // signRequest signs env from the subject to the lookup with each of -// keys, publishing each key at the subject's address. +// keys, publishing each key at the subject's address. With two keys, +// the first names the second as its successor: a key change. func (f *fixture) signRequest(env *gobl.Envelope, keys ...*dsig.PrivateKey) { f.t.Helper() - for _, k := range keys { + for i, k := range keys { f.publish(k) - require.NoError(f.t, goblnet.Sign(env, k, f.subAddr, f.lookup.Address())) + var opts []head.SignOption + if i == 0 && len(keys) == 2 { + opts = append(opts, head.WithConfirmation(keys[1].JKT())) + } + require.NoError(f.t, goblnet.Sign(env, k, f.subAddr, f.lookup.Address(), opts...)) } } +// signRequestAt adds a confirming signature by key from the subject to +// the lookup made at iat, naming successor if not nil. +func (f *fixture) signRequestAt(env *gobl.Envelope, key *dsig.PrivateKey, iat time.Time, successor *dsig.PrivateKey) { + f.t.Helper() + f.publish(key) + p := &head.SigningPayload{ + UUID: env.Head.UUID, Digest: env.Head.Digest, + Iss: f.subAddr.String(), Aud: f.lookup.Address().String(), IssuedAt: iat.Unix(), + } + if successor != nil { + p.Confirmation = &head.Confirmation{JKT: successor.JKT()} + } + sig, err := dsig.NewSignature(key, p) + require.NoError(f.t, err) + env.Signatures = append(env.Signatures, sig) +} + // publish serves key at the subject's key endpoint. func (f *fixture) publish(key *dsig.PrivateKey) { pub, _ := json.Marshal(key.Public()) @@ -463,6 +485,37 @@ func TestKeyLineage(t *testing.T) { assert.Equal(t, third.JKT(), f.record().CurrentKey().JKT) }) + t.Run("a replayed request cannot change the key", func(t *testing.T) { + // A new holder of the address replays an earlier signature by + // the current key and adds its own. + f := newFixture(t) + require.Equal(t, http.StatusAccepted, f.register(f.request(f.party(), f.subject))) + env := f.renewal() + f.signRequestAt(env, f.subject, time.Now().Add(-time.Hour), nil) + attacker := dsig.NewES256Key() + f.signRequest(env, attacker) + assert.Equal(t, http.StatusForbidden, f.register(env), "the attacker's key alone is unverified") + assert.Equal(t, f.subject.JKT(), f.record().CurrentKey().JKT) + require.Len(t, f.record().Lineage, 1) + }) + + t.Run("a request signed only long ago is rejected", func(t *testing.T) { + f := newFixture(t) + require.Equal(t, http.StatusAccepted, f.register(f.request(f.party(), f.subject))) + env := f.renewal() + f.signRequestAt(env, f.subject, time.Now().Add(-goblnet.MaxRequestAge-time.Minute), nil) + assert.Equal(t, http.StatusUnauthorized, f.register(env)) + }) + + t.Run("a key change the current key does not name is rejected", func(t *testing.T) { + f := newFixture(t) + require.Equal(t, http.StatusAccepted, f.register(f.request(f.party(), f.subject))) + env := f.renewal(f.subject) + f.signRequest(env, dsig.NewES256Key()) + assert.Equal(t, http.StatusUnprocessableEntity, f.register(env)) + require.Len(t, f.record().Lineage, 1) + }) + t.Run("a new key alone needs a new verification", func(t *testing.T) { // A lost key, or a new holder of the address: the previous // verification does not carry over. From dd9894939005899d948b0289e9aed278771b765e Mon Sep 17 00:00:00 2001 From: Sam Lown Date: Sun, 15 Nov 2026 23:04:49 +0000 Subject: [PATCH 10/11] Simplify key lineage to renew, change key or start over 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 --- CHANGELOG.md | 2 +- README.md | 14 +++--- go.mod | 2 +- go.sum | 4 +- internal/domain/lineage.go | 54 ++++++++--------------- internal/domain/lineage_internal_test.go | 56 +++++++++++------------- internal/domain/registrations.go | 13 +----- internal/interfaces/web/web_test.go | 40 ++++++++++------- 8 files changed, 80 insertions(+), 105 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ca4ee7e..eab28fb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,7 @@ ### Changed - Registrations follow the latest GOBL Net spec. A request is an ordinary delivery from the subject to the lookup, confirmed by its signature for the lookup, and needs no request token; the subject is its `from` address. The lookup drops the request signature, countersigns with a `cnf` claim binding the subject's key, and addresses the envelope back to the subject. -- The lookup keeps each address's key lineage (`Registration.Lineage`). A request signed with the current key, naming a new key with `cnf`, and with that new key rolls over to the new key; one signed only with an unknown key starts a new lineage, and needs a verification for that key. Rollovers need no new verification, a key bound before cannot become current again, and a new holder of an address cannot inherit its verification. +- The lookup keeps each address's key lineage (`Registration.Lineage`). A request signed with the current key, naming a new key with `cnf`, and with that new key rolls over to the new key; one signed only with an unknown key starts a new lineage, and needs a verification for that key. Rollovers need no new verification, a first registration takes one key, a key bound before cannot become current again, alone or in a key change, and a new holder of an address cannot inherit its verification. - The lookup registers only verified parties: a registration needs a countersignature from an accepted verifier binding, with `cnf`, a key in the subject's lineage, and is rejected with `403` without one (`503` when the verifier's key cannot be fetched). The `gobl.lookup verify` command is removed; a subject registers again instead. - Verifiers are no longer accepted delivering to the lookup on a subject's behalf; the subject registers again with the verified envelope. The renewal rule based on an unchanged digest is replaced by the lineage check. - `GET /parties/` returns a public record instead of the countersigned envelope: the party's address, verifier, verification and registration dates, plus its name and tax ID when listed. A registration request lists the party with header meta `lookup-listing: public` and unlists it with `private`; without the key the choice is kept, and new registrations start private. The key is removed before countersigning. diff --git a/README.md b/README.md index f95a699..c85f62c 100644 --- a/README.md +++ b/README.md @@ -105,12 +105,12 @@ sign a registration request decide what happens. Only signatures made within the last 5 minutes count, so an earlier request cannot be replayed: -| Request signed with | Result | -|--------------------------------------|------------------------------------------------------------| -| the current key (or a first key) | renewal (or first registration): the key stays bound | -| the current key, naming a new key with `cnf`, and that new key | rollover: the new key joins the lineage and is bound | -| only a key that is not the current one | a lost key or a new holder: a new lineage starts, if a verification binds that key | -| two keys at a first registration | the key a verification binds starts the lineage, then rolls over to the key it names | +| Request signed with | Result | +|---|---| +| the current key | renewal: the key stays bound | +| the current key, naming a new key with `cnf`, and that new key (`goblnet.SignKeyChange`) | key change: the new key joins the lineage and is bound | +| one key not in the lineage | first registration, lost key or new holder: a new lineage starts, if a verification binds that key | +| anything else, including two keys at a first registration or an earlier key | rejected with `422` | The lookup registers a party only when a verifier's countersignature binds, with `cnf`, a key in the current lineage. A rollover therefore @@ -356,7 +356,7 @@ arrives from a secret independently of the host). - **Renewal and key changes**: a request signed with the current key renews, stamping a fresh 90-day countersignature; one also signed with a new key, which the current key's signature names with `cnf` - (`goblnet.Sign(env, key, from, to, head.WithConfirmation(next.JKT()))`), + (`goblnet.SignKeyChange`), rolls over to the new key. Requests must be signed within the last 5 minutes. Either needs the request to carry a verification bound to a key in the diff --git a/go.mod b/go.mod index 5b91499..9d058df 100644 --- a/go.mod +++ b/go.mod @@ -5,7 +5,7 @@ go 1.25.0 require ( github.com/go-kivik/kivik/v4 v4.5.2 github.com/invopop/couch v0.1.0 - github.com/invopop/gobl v0.512.1-0.20261115223033-d273609a4a78 + github.com/invopop/gobl v0.512.1-0.20261115230312-9a9b75511db6 github.com/magefile/mage v1.17.2 github.com/spf13/cobra v1.10.2 github.com/stretchr/testify v1.11.1 diff --git a/go.sum b/go.sum index 95c4a61..c7b5723 100644 --- a/go.sum +++ b/go.sum @@ -34,8 +34,8 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/invopop/couch v0.1.0 h1:ctMKLeIxnab9KW11KtEAQSl7RzGgMxndavLphx99LpY= github.com/invopop/couch v0.1.0/go.mod h1:xzBNVglDnLcpf1Z9BJxiIG1liESSIkMuvIczSl4zcls= -github.com/invopop/gobl v0.512.1-0.20261115223033-d273609a4a78 h1:wRqOVUJ70XtRbG29DFqy/saGKyOMcOzPCl9OXKeGQ4c= -github.com/invopop/gobl v0.512.1-0.20261115223033-d273609a4a78/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= +github.com/invopop/gobl v0.512.1-0.20261115230312-9a9b75511db6 h1:tMg5JuYQYa+YPV0c8rljEM95en1J67KQDdiOd1fxYtY= +github.com/invopop/gobl v0.512.1-0.20261115230312-9a9b75511db6/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= github.com/invopop/jsonschema v0.14.0 h1:MHQqLhvpNUZfw+hM3AZDYK7jxO8FZoQeQM77g8iyZjg= github.com/invopop/jsonschema v0.14.0/go.mod h1:ygm6C2EaVNMBDPpaPlnOA2pFAxBnxGjFlMZABxm9n2I= github.com/invopop/yaml v0.3.1 h1:f0+ZpmhfBSS4MhG+4HYseMdJhoeeopbSKbq5Rpeelso= diff --git a/internal/domain/lineage.go b/internal/domain/lineage.go index 2fbfbea..210bad3 100644 --- a/internal/domain/lineage.go +++ b/internal/domain/lineage.go @@ -11,18 +11,16 @@ import ( ) // errLineage is returned when a registration request's keys cannot -// extend or start a lineage. -var errLineage = errors.New("registration must be signed with the current key, a new key, " + - "or the current key naming a new one with cnf") +// renew, change or start a lineage. +var errLineage = errors.New("registration must be signed with the current key, " + + "the current key naming a new one with cnf and that new key, or one new key") // nextLineage applies the signatures confirming a registration request // to the current lineage (spec §7.3) and returns the resulting one, -// whose last key is bound. In a key change the current key's signature -// must name the new key as its successor. verified holds the cnf -// thumbprints of accepted verification countersignatures on the -// request, which pick the current key of a first registration signed -// with two. -func nextLineage(lineage []*models.LineageKey, confs []*goblnet.ConfirmingSignature, verified []string, now time.Time) ([]*models.LineageKey, error) { +// whose last key is bound: the current key alone renews, the current +// key naming a new one with cnf, signed with both, changes key, and one +// key not in the lineage starts a new one. +func nextLineage(lineage []*models.LineageKey, confs []*goblnet.ConfirmingSignature, now time.Time) ([]*models.LineageKey, error) { entry := func(k *dsig.PublicKey) *models.LineageKey { return &models.LineageKey{JKT: k.JKT(), KID: k.ID(), AddedAt: now} } @@ -33,41 +31,25 @@ func nextLineage(lineage []*models.LineageKey, confs []*goblnet.ConfirmingSignat switch len(confs) { case 1: k := confs[0].Key - if k.JKT() == current { + switch { + case k.JKT() == current: return lineage, nil // renewal + case inLineage(lineage, k.JKT()): + return nil, errLineage // a key bound before cannot become current again } - // A first registration, or a key that is not the current one: - // a lost key or a new holder of the address starts afresh. + // A first registration, a lost key, or a new holder of the + // address: a new lineage starts. return []*models.LineageKey{entry(k)}, nil case 2: - // from is the key changed from, to the one it names. + if current == "" { + return nil, errLineage + } for _, pair := range [][2]*goblnet.ConfirmingSignature{{confs[0], confs[1]}, {confs[1], confs[0]}} { from, to := pair[0], pair[1] - if from.Successor != to.Key.JKT() { - continue - } - if current != "" { - // The new key must be new: a key bound before cannot - // become current again. - if from.Key.JKT() == current && !inLineage(lineage, to.Key.JKT()) { - return append(lineage, entry(to.Key)), nil - } - continue - } - if contains(verified, from.Key.JKT()) && !contains(verified, to.Key.JKT()) { - return []*models.LineageKey{entry(from.Key), entry(to.Key)}, nil + if from.Key.JKT() == current && from.Successor == to.Key.JKT() && !inLineage(lineage, to.Key.JKT()) { + return append(lineage, entry(to.Key)), nil } } - return nil, errLineage } return nil, errLineage } - -func contains(list []string, s string) bool { - for _, v := range list { - if v == s { - return true - } - } - return false -} diff --git a/internal/domain/lineage_internal_test.go b/internal/domain/lineage_internal_test.go index 5a8472f..77008ed 100644 --- a/internal/domain/lineage_internal_test.go +++ b/internal/domain/lineage_internal_test.go @@ -43,68 +43,64 @@ func TestNextLineage(t *testing.T) { return out } + one := func(k *dsig.PrivateKey) []*goblnet.ConfirmingSignature { + return []*goblnet.ConfirmingSignature{conf(k, nil)} + } + t.Run("renews with the current key", func(t *testing.T) { - got, err := nextLineage(lineage(a), []*goblnet.ConfirmingSignature{conf(a, nil)}, nil, now) + got, err := nextLineage(lineage(a), one(a), now) require.NoError(t, err) assert.Equal(t, []string{a.JKT()}, jkts(got)) }) - t.Run("starts afresh with one key that is not current", func(t *testing.T) { - got, err := nextLineage(lineage(a), []*goblnet.ConfirmingSignature{conf(b, nil)}, nil, now) + t.Run("starts a lineage with one key not in it", func(t *testing.T) { + got, err := nextLineage(nil, one(a), now) + require.NoError(t, err) + assert.Equal(t, []string{a.JKT()}, jkts(got)) + got, err = nextLineage(lineage(a), one(b), now) require.NoError(t, err) assert.Equal(t, []string{b.JKT()}, jkts(got)) }) + t.Run("rejects a key bound before alone", func(t *testing.T) { + _, err := nextLineage(lineage(a, b), one(a), now) + assert.ErrorIs(t, err, errLineage) + }) + t.Run("changes to the key the current key names", func(t *testing.T) { - got, err := nextLineage(lineage(a), change(a, b), nil, now) + got, err := nextLineage(lineage(a), change(a, b), now) require.NoError(t, err) assert.Equal(t, []string{a.JKT(), b.JKT()}, jkts(got)) }) t.Run("rejects a key change the current key does not name", func(t *testing.T) { - both := []*goblnet.ConfirmingSignature{conf(a, nil), conf(b, nil)} - _, err := nextLineage(lineage(a), both, nil, now) + _, err := nextLineage(lineage(a), []*goblnet.ConfirmingSignature{conf(a, nil), conf(b, nil)}, now) assert.ErrorIs(t, err, errLineage) - // Naming another key does not count either. - _, err = nextLineage(lineage(a), []*goblnet.ConfirmingSignature{conf(a, c), conf(b, nil)}, nil, now) + _, err = nextLineage(lineage(a), []*goblnet.ConfirmingSignature{conf(a, c), conf(b, nil)}, now) assert.ErrorIs(t, err, errLineage) - // Nor does the new key naming the current one. - _, err = nextLineage(lineage(a), change(b, a), nil, now) + _, err = nextLineage(lineage(a), change(b, a), now) assert.ErrorIs(t, err, errLineage) }) t.Run("rejects a key bound before becoming current again", func(t *testing.T) { - _, err := nextLineage(lineage(a, b), change(b, a), nil, now) + _, err := nextLineage(lineage(a, b), change(b, a), now) assert.ErrorIs(t, err, errLineage) }) t.Run("rejects two keys neither of which is current", func(t *testing.T) { - _, err := nextLineage(lineage(a), change(b, c), nil, now) + _, err := nextLineage(lineage(a), change(b, c), now) assert.ErrorIs(t, err, errLineage) }) - t.Run("orders a first registration by the verified key", func(t *testing.T) { - got, err := nextLineage(nil, change(b, a), []string{b.JKT()}, now) - require.NoError(t, err) - assert.Equal(t, []string{b.JKT(), a.JKT()}, jkts(got)) - }) - - t.Run("rejects a first registration whose verified key names no other", func(t *testing.T) { - _, err := nextLineage(nil, []*goblnet.ConfirmingSignature{conf(a, nil), conf(b, nil)}, []string{b.JKT()}, now) - assert.ErrorIs(t, err, errLineage) - _, err = nextLineage(nil, change(a, b), []string{b.JKT()}, now) + t.Run("rejects two keys at a first registration", func(t *testing.T) { + _, err := nextLineage(nil, change(a, b), now) assert.ErrorIs(t, err, errLineage) }) - t.Run("rejects a first registration with both or neither key verified", func(t *testing.T) { - _, err := nextLineage(nil, change(a, b), []string{a.JKT(), b.JKT()}, now) + t.Run("rejects no keys or more than two", func(t *testing.T) { + _, err := nextLineage(lineage(a), nil, now) assert.ErrorIs(t, err, errLineage) - _, err = nextLineage(nil, change(a, b), nil, now) - assert.ErrorIs(t, err, errLineage) - }) - - t.Run("rejects more than two keys", func(t *testing.T) { - _, err := nextLineage(lineage(a), append(change(a, b), conf(c, nil)), nil, now) + _, err = nextLineage(lineage(a), append(change(a, b), conf(c, nil)), now) assert.ErrorIs(t, err, errLineage) }) } diff --git a/internal/domain/registrations.go b/internal/domain/registrations.go index e7aac01..9c25e2b 100644 --- a/internal/domain/registrations.go +++ b/internal/domain/registrations.go @@ -137,7 +137,7 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode if prev != nil { lineage = prev.Lineage } - lineage, err = nextLineage(lineage, confs, verificationKeys(verifications), time.Now().UTC()) + lineage, err = nextLineage(lineage, confs, time.Now().UTC()) if err != nil { d.log.Warn("inbox.rejected", "reason", "lineage", "caller", string(sender), "keys", len(confs)) return nil, ErrValidation.WithMessage("%s", err.Error()) @@ -250,17 +250,6 @@ func (d *Registrations) acceptedVerifications(ctx context.Context, env *gobl.Env return found, unavailable } -// verificationKeys returns the cnf thumbprints of verifications. -func verificationKeys(vs []*goblnet.Verification) []string { - keys := make([]string, 0, len(vs)) - for _, v := range vs { - if v.Key != "" { - keys = append(keys, v.Key) - } - } - return keys -} - // pickVerifier returns the verifier of the most recent verification // whose cnf names a key in lineage, or "". func pickVerifier(vs []*goblnet.Verification, lineage []*models.LineageKey) goblnet.Address { diff --git a/internal/interfaces/web/web_test.go b/internal/interfaces/web/web_test.go index fd4d727..2db850d 100644 --- a/internal/interfaces/web/web_test.go +++ b/internal/interfaces/web/web_test.go @@ -171,17 +171,19 @@ func (f *fixture) unverified(party *org.Party, keys ...*dsig.PrivateKey) *gobl.E } // signRequest signs env from the subject to the lookup with each of -// keys, publishing each key at the subject's address. With two keys, -// the first names the second as its successor: a key change. +// keys, publishing each key at the subject's address. Two keys sign a +// key change from the first to the second. func (f *fixture) signRequest(env *gobl.Envelope, keys ...*dsig.PrivateKey) { f.t.Helper() - for i, k := range keys { + for _, k := range keys { f.publish(k) - var opts []head.SignOption - if i == 0 && len(keys) == 2 { - opts = append(opts, head.WithConfirmation(keys[1].JKT())) - } - require.NoError(f.t, goblnet.Sign(env, k, f.subAddr, f.lookup.Address(), opts...)) + } + if len(keys) == 2 { + require.NoError(f.t, goblnet.SignKeyChange(env, keys[0], keys[1], f.subAddr, f.lookup.Address())) + return + } + for _, k := range keys { + require.NoError(f.t, goblnet.Sign(env, k, f.subAddr, f.lookup.Address())) } } @@ -538,16 +540,22 @@ func TestKeyLineage(t *testing.T) { assert.Equal(t, first, rec.VerifiedAt, "same verifier") }) - t.Run("two keys at a first registration follow the verification", func(t *testing.T) { + t.Run("two keys at a first registration are rejected", func(t *testing.T) { + f := newFixture(t) + assert.Equal(t, http.StatusUnprocessableEntity, f.register(f.request(f.party(), f.subject, dsig.NewES256Key()))) + _, err := f.registry.Get(context.Background(), f.subAddr) + assert.ErrorIs(t, err, repos.ErrNotFound) + }) + + t.Run("a retired key cannot take the address back", func(t *testing.T) { + // The original verification still binds the first key, so a + // lineage restarted with it would be verified. f := newFixture(t) + require.Equal(t, http.StatusAccepted, f.register(f.request(f.party(), f.subject))) next := dsig.NewES256Key() - env := f.request(f.party(), f.subject, next) - require.Equal(t, http.StatusAccepted, f.register(env)) - rec := f.record() - require.Len(t, rec.Lineage, 2) - assert.Equal(t, f.subject.JKT(), rec.Lineage[0].JKT) - assert.Equal(t, next.JKT(), rec.Lineage[1].JKT) - assert.Equal(t, f.verifAddr, rec.Verifier) + require.Equal(t, http.StatusAccepted, f.register(f.renewal(f.subject, next))) + assert.Equal(t, http.StatusUnprocessableEntity, f.register(f.renewal(f.subject))) + assert.Equal(t, next.JKT(), f.record().CurrentKey().JKT) }) t.Run("two keys at a first registration without a verification are rejected", func(t *testing.T) { From 0e98878fc7783280e57ae6b9062f8319b4ccfb4d Mon Sep 17 00:00:00 2001 From: Sam Lown Date: Thu, 19 Nov 2026 14:45:04 +0000 Subject: [PATCH 11/11] Bump gobl and shorten dials to addresses with others left to try Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 +- go.mod | 2 +- go.sum | 4 ++-- internal/domain/delivery/delivery.go | 13 +++++++++++-- 4 files changed, 15 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index eab28fb..12a3677 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ - `GET /parties/` returns a public record instead of the countersigned envelope: the party's address, verifier, verification and registration dates, plus its name and tax ID when listed. A registration request lists the party with header meta `lookup-listing: public` and unlists it with `private`; without the key the choice is kept, and new registrations start private. The key is removed before countersigning. - `GET /.well-known/gobl/who` answers with the lookup's party envelope addressed and signed for the requester, with `Vary: Authorization`. - Only signatures made within the last 5 minutes count towards a registration request, so an earlier request cannot be replayed (`401` when none is fresh). -- Deliveries to subjects carry no request token, follow no redirects, and refuse every address that is not globally reachable, matching `gobl/net`. +- Deliveries to subjects carry no request token, follow no redirects, refuse every address that is not globally reachable, and give each resolved address but the last 2 seconds before trying the next, matching `gobl/net`. ## [v0.4.0] - 2026-07-30 diff --git a/go.mod b/go.mod index 9d058df..e2d7b2a 100644 --- a/go.mod +++ b/go.mod @@ -5,7 +5,7 @@ go 1.25.0 require ( github.com/go-kivik/kivik/v4 v4.5.2 github.com/invopop/couch v0.1.0 - github.com/invopop/gobl v0.512.1-0.20261115230312-9a9b75511db6 + github.com/invopop/gobl v0.512.1-0.20261119144428-6655883e8346 github.com/magefile/mage v1.17.2 github.com/spf13/cobra v1.10.2 github.com/stretchr/testify v1.11.1 diff --git a/go.sum b/go.sum index c7b5723..6b43e47 100644 --- a/go.sum +++ b/go.sum @@ -34,8 +34,8 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/invopop/couch v0.1.0 h1:ctMKLeIxnab9KW11KtEAQSl7RzGgMxndavLphx99LpY= github.com/invopop/couch v0.1.0/go.mod h1:xzBNVglDnLcpf1Z9BJxiIG1liESSIkMuvIczSl4zcls= -github.com/invopop/gobl v0.512.1-0.20261115230312-9a9b75511db6 h1:tMg5JuYQYa+YPV0c8rljEM95en1J67KQDdiOd1fxYtY= -github.com/invopop/gobl v0.512.1-0.20261115230312-9a9b75511db6/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= +github.com/invopop/gobl v0.512.1-0.20261119144428-6655883e8346 h1:QEOdpO+csoPeibcDc/zSSJ5hSVbZuTRIY6uxnSczPVE= +github.com/invopop/gobl v0.512.1-0.20261119144428-6655883e8346/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40= github.com/invopop/jsonschema v0.14.0 h1:MHQqLhvpNUZfw+hM3AZDYK7jxO8FZoQeQM77g8iyZjg= github.com/invopop/jsonschema v0.14.0/go.mod h1:ygm6C2EaVNMBDPpaPlnOA2pFAxBnxGjFlMZABxm9n2I= github.com/invopop/yaml v0.3.1 h1:f0+ZpmhfBSS4MhG+4HYseMdJhoeeopbSKbq5Rpeelso= diff --git a/internal/domain/delivery/delivery.go b/internal/domain/delivery/delivery.go index d0718f0..d25c15a 100644 --- a/internal/domain/delivery/delivery.go +++ b/internal/domain/delivery/delivery.go @@ -28,6 +28,10 @@ import ( // delivery timeout. const dialTimeout = 5 * time.Second +// fallbackDialTimeout bounds a dial to a resolved address with others +// left to try. +const fallbackDialTimeout = 2 * time.Second + // Errors returned by Send. var ( // ErrInboxRejected matches gobl/net's sentinel — the remote @@ -152,9 +156,14 @@ func safeDialContext(ctx context.Context, network, addr string) (stdnet.Conn, er // Dial the IPs we just vetted rather than re-resolving the host at // connect time: a second resolution could return a different, private // address and slip past the check (DNS rebinding / TOCTOU). - d := &stdnet.Dialer{Timeout: dialTimeout} + // Each address but the last gets fallbackDialTimeout, so one that + // drops packets does not hold up the next. var lastErr error - for _, ip := range ips { + for i, ip := range ips { + d := &stdnet.Dialer{Timeout: dialTimeout} + if i < len(ips)-1 { + d.Timeout = fallbackDialTimeout + } conn, err := d.DialContext(ctx, network, stdnet.JoinHostPort(ip.String(), port)) if err == nil { return conn, nil