diff --git a/CHANGELOG.md b/CHANGELOG.md
index ef5b8f7..12a3677 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,8 +4,20 @@
### 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).
+- 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 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.
+- `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, 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
+
+### 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
@@ -14,7 +26,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.
@@ -22,11 +33,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
@@ -43,6 +57,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).
diff --git a/README.md b/README.md
index bd1aa42..c85f62c 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,72 +17,126 @@ 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.
+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
+ `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, 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, `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 identity with
+ `net.Client.VerifyEndorsement` / `net.Client.VerifySender`.
+
+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`:
-### Endorsement lifetime and renewal
+```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).
-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.
+### Endorsement lifetime and renewal
+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 party needs a new
+verification before it can renew.
+
+### 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. Only signatures made
+within the last 5 minutes count, so an earlier request cannot be
+replayed:
+
+| 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
+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
@@ -98,13 +153,12 @@ 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, 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
+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
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,53 +172,45 @@ 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. **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 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 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
@@ -177,14 +223,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
@@ -195,26 +241,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 address ([Listing](#listing)). |
| 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 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.
## Quickstart (local dev)
@@ -258,7 +303,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..." }
+ ]
}
```
@@ -272,7 +320,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
@@ -280,7 +327,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.
@@ -306,17 +353,21 @@ 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 also signed
+ with a new key, which the current key's signature names with `cnf`
+ (`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
+ 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/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/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 60f4c65..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.504.1-0.20260811215754-c231ee2feae5
+ 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
@@ -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
diff --git a/go.sum b/go.sum
index 85f05ed..6b43e47 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,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.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/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/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/delivery/delivery.go b/internal/domain/delivery/delivery.go
index 09943ac..d25c15a 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.
@@ -19,7 +19,6 @@ import (
"time"
"github.com/invopop/gobl"
- "github.com/invopop/gobl/dsig"
"github.com/invopop/gobl/net"
)
@@ -29,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
@@ -51,25 +54,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)
+// resolved IP that is not globally reachable (see isPublicIP) and
+// follows no redirects.
+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,
@@ -84,9 +86,13 @@ func newSender(self net.Address, key *dsig.PrivateKey, allowLoopback bool) *HTTP
// 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},
- self: self,
- key: key,
+ client: &http.Client{
+ Transport: transport,
+ // A redirect could move the delivery to plain HTTP.
+ CheckRedirect: func(*http.Request, []*http.Request) error {
+ return http.ErrUseLastResponse
+ },
+ },
}
}
@@ -111,11 +117,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
@@ -126,6 +127,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:
@@ -153,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
@@ -168,9 +176,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
@@ -185,5 +195,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 4ac414b..3b8239e 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)
@@ -129,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) {
@@ -145,11 +149,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 +164,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
})},
@@ -218,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)
@@ -225,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/identity.go b/internal/domain/identity.go
index a0a1688..3ba2b8b 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. Required.
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,14 @@ func (d *Identity) CounterSign(env *gobl.Envelope, opts CounterSignOptions) erro
sigs = append(sigs, sig)
}
env.Signatures = sigs
- signOpts := []head.SignOption{
- head.WithIssuer(d.Address().String()),
- head.WithAudience(opts.Subject.String()),
- head.WithExpiration(time.Now().Add(endorsementTTL)),
+ if opts.Key == "" {
+ return errors.New("identity: cannot countersign without a subject key")
}
- if opts.Verifier != "" {
- signOpts = append(signOpts, head.WithVerifier(opts.Verifier.String()))
+ if opts.Verifier == "" {
+ return errors.New("identity: cannot countersign without a verifier")
}
- return env.Sign(d.model.PrivateKey, signOpts...)
+ return goblnet.Sign(env, d.model.PrivateKey, d.Address(), opts.Subject,
+ head.WithExpiration(time.Now().Add(endorsementTTL)),
+ head.WithConfirmation(opts.Key),
+ head.WithVerifier(opts.Verifier.String()))
}
diff --git a/internal/domain/identity_test.go b/internal/domain/identity_test.go
index c086129..b48e65a 100644
--- a/internal/domain/identity_test.go
+++ b/internal/domain/identity_test.go
@@ -36,25 +36,36 @@ func newTestIdentity(t *testing.T) *domain.Identity {
return setup.Identity()
}
-func TestPartyEnvelopeIsSelfSigned(t *testing.T) {
+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)
- 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)
- assert.Equal(t, data, again)
+ 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, "bob.example", pb.Aud)
}
func TestCounterSign(t *testing.T) {
@@ -72,15 +83,35 @@ 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", 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/lineage.go b/internal/domain/lineage.go
new file mode 100644
index 0000000..210bad3
--- /dev/null
+++ b/internal/domain/lineage.go
@@ -0,0 +1,55 @@
+package domain
+
+import (
+ "errors"
+ "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
+// 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: 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}
+ }
+ var current string
+ if len(lineage) > 0 {
+ current = lineage[len(lineage)-1].JKT
+ }
+ switch len(confs) {
+ case 1:
+ k := confs[0].Key
+ 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, a lost key, or a new holder of the
+ // address: a new lineage starts.
+ return []*models.LineageKey{entry(k)}, nil
+ case 2:
+ 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.Key.JKT() == current && from.Successor == to.Key.JKT() && !inLineage(lineage, to.Key.JKT()) {
+ return append(lineage, entry(to.Key)), nil
+ }
+ }
+ }
+ return nil, errLineage
+}
diff --git a/internal/domain/lineage_internal_test.go b/internal/domain/lineage_internal_test.go
new file mode 100644
index 0000000..77008ed
--- /dev/null
+++ b/internal/domain/lineage_internal_test.go
@@ -0,0 +1,125 @@
+package domain
+
+import (
+ "testing"
+ "time"
+
+ "github.com/invopop/gobl/dsig"
+ goblnet "github.com/invopop/gobl/net"
+ "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()
+ // 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 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))
+ 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
+ }
+
+ 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), one(a), now)
+ require.NoError(t, err)
+ assert.Equal(t, []string{a.JKT()}, jkts(got))
+ })
+
+ 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), 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) {
+ _, err := nextLineage(lineage(a), []*goblnet.ConfirmingSignature{conf(a, nil), conf(b, nil)}, now)
+ assert.ErrorIs(t, err, errLineage)
+ _, err = nextLineage(lineage(a), []*goblnet.ConfirmingSignature{conf(a, c), conf(b, nil)}, now)
+ assert.ErrorIs(t, err, errLineage)
+ _, 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), 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), now)
+ assert.ErrorIs(t, err, errLineage)
+ })
+
+ 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 no keys or more than two", func(t *testing.T) {
+ _, err := nextLineage(lineage(a), nil, now)
+ assert.ErrorIs(t, err, errLineage)
+ _, err = nextLineage(lineage(a), append(change(a, b), conf(c, 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()}}
+ assert.True(t, inLineage(l, k.JKT()))
+ assert.False(t, inLineage(l, ""))
+ assert.False(t, inLineage(l, "other"))
+}
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 4ce73ae..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"
)
@@ -48,6 +49,42 @@ 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"`
+ // 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.
+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/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)
+}
diff --git a/internal/domain/registrations.go b/internal/domain/registrations.go
index 5816c69..9c25e2b 100644
--- a/internal/domain/registrations.go
+++ b/internal/domain/registrations.go
@@ -10,6 +10,7 @@ import (
"github.com/invopop/gobl"
"github.com/invopop/gobl/head"
goblnet "github.com/invopop/gobl/net"
+ "github.com/invopop/gobl/org"
"github.com/invopop/gobl/uuid"
"github.com/invopop/gobl.lookup/internal/domain/delivery"
@@ -61,12 +62,16 @@ 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, 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
+// 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,75 +79,77 @@ 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)
+ confs, err := d.client.DeliveryConfirmations(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)
+ }
+ // 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")
+ }
+ 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 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)
+ 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)
}
- // 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 {
- // 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())
+ // 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)
+ var lineage []*models.LineageKey
+ if prev != nil {
+ lineage = prev.Lineage
+ }
+ 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())
+ }
+ 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:
@@ -151,12 +158,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 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{
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 +175,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, public)
if err != nil {
d.log.Error("inbox.persist_failed", "caller", string(sender), "error", err.Error())
return nil, ErrInternal.WithCause(err)
@@ -174,7 +184,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,124 +197,105 @@ func (d *Registrations) Register(ctx context.Context, env *gobl.Envelope) (*mode
return rec, nil
}
-// 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.
-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)
+// 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
}
- if err != nil {
- return nil, ErrInternal.WithCause(err)
- }
- if rec.CountersignedEnvelope == nil {
- return nil, ErrValidation.WithMessage("registration for %s has no countersigned envelope", addr)
+ // 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")
}
- env := rec.CountersignedEnvelope
-
- verifier, aerr := d.acceptedVerifier(ctx, env)
- 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)
- }
-
- // 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,
- 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)
+ 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.Info("verified registration",
- "address", string(addr),
- "envelope", env.Head.UUID.String(),
- "verifier", string(verifier),
- )
- return rec, nil
+ d.log.Warn("inbox.rejected", "reason", reason, "caller", string(sender), "error", err.Error())
+ return ErrForbidden.WithMessage("%s", msg)
}
-// 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).
+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 {
+ vs, err := d.client.FindVerifications(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, vs...)
+ }
+ return found, unavailable
+}
+
+// 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
}
- if best == "" && unavailable != nil {
- return "", unavailable
+ for _, k := range lineage {
+ if k.JKT == jkt {
+ return true
+ }
+ }
+ 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 +371,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
+// 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). 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 {
+ 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
}
- 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
+ rec.Verifier = verifier
+ rec.Status = models.StatusCountersigned
+ rec.CountersignedEnvelope = env
+ rec.Lineage = lineage
+ if public != nil {
+ rec.Public = *public
}
- 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
- // 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:
+ // 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()
- 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
@@ -486,3 +441,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/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/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.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..2db850d 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"
@@ -20,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"
@@ -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,159 @@ 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, 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()
- 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. 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 _, k := range keys {
+ f.publish(k)
}
- require.NoError(f.t, env.Sign(f.subject, 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()))
+ }
+}
+
+// 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())
+ 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
+ }
+ }
+ 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
+// 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.
-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 +301,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 +309,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 +334,422 @@ 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)
+ 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)
+
+ // The request signature is dropped; the lookup's countersignature
+ // addresses the envelope back to the subject.
+ out := rec.CountersignedEnvelope
+ 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)
- 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.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())
// 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)
+ })
- 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("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)
+ })
-// 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
+ 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")
}
-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 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
- // 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))
-
- // 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)
+ 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, 2, "request signature dropped, own countersignature superseded")
+ assert.Equal(t, 1, linkCount(rec.CountersignedEnvelope), "restamped, not duplicated")
+ require.NoError(t, rec.CountersignedEnvelope.Validate())
+ })
- rec2, err := f.registry.Get(context.Background(), f.subAddr)
- 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")
+ t.Run("rollover signed with both keys keeps the verifier", func(t *testing.T) {
+ f := newFixture(t)
+ env := f.request(f.party(), 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)
+
+ // 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)
+ })
- // 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])
- 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())
+ 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.
+ f := newFixture(t)
+ require.Equal(t, http.StatusAccepted, f.register(f.request(f.party(), f.subject)))
+ first := f.record().VerifiedAt
+
+ newHolder := dsig.NewES256Key()
+ 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.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 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()
+ 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) {
+ f := newFixture(t)
+ env := f.unverified(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 TestPartiesLookupByUUID(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)
+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)
+ 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)
+ })
- 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)
+ t.Run("survives renewal of the delivered envelope", func(t *testing.T) {
+ f := newFixture(t)
+ env := f.request(f.party(), 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))
+ })
+
+ 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())
+ },
+ "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("rejects a verification "+name, func(t *testing.T) {
+ f := newFixture(t)
+ env := f.unverified(f.party(), f.subject)
+ stamp(f, env)
+ assert.Equal(t, http.StatusForbidden, f.register(env))
+ })
+ }
}
-func TestPartiesLookupByAddress(t *testing.T) {
+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)))
+ })
+ }
+}
+
+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.signPartyEnvelope(f.subAddr.String(), f.lookup.Address().String())
- body, _ := json.Marshal(env)
- f.post(goblnet.InboxPath, body).Body.Close() //nolint:errcheck
+ 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 TestPartiesLookup(t *testing.T) {
+ f := newFixture(t)
+ 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("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)
+ })
- resp := f.get("/parties/" + string(f.subAddr))
- defer resp.Body.Close() //nolint:errcheck
- assert.Equal(t, http.StatusOK, resp.StatusCode)
+ t.Run("by address", func(t *testing.T) {
+ assert.Equal(t, f.subAddr, f.partyRecord("/parties/"+string(f.subAddr)).Address)
+ })
+
+ 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 TestPartiesLookupNotFound(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)
+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) {
@@ -475,14 +788,17 @@ 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))
+ 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 +810,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 +825,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 +847,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,302 +854,6 @@ 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{
- 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 = 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.
func linkCount(env *gobl.Envelope) int {
n := 0
@@ -859,71 +865,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 +877,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..864b0cb 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)
@@ -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)
}
}