Skip to content
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@

### Changed

- Registrations follow the latest GOBL Net spec. A request is an ordinary delivery from the subject to the lookup, confirmed by its signature for the lookup, and needs no request token; the subject is its `from` address. The lookup drops the request signature, countersigns with a `cnf` claim binding the subject's key, and addresses the envelope back to the subject.
- The lookup keeps each address's key lineage (`Registration.Lineage`). A request signed with the current and a new key rolls over to the new key; one signed only with an unknown key starts a new lineage. A verifier is named only when its countersignature binds, with `cnf`, a key in the lineage, so rollovers keep a party verified and a new holder of an address cannot inherit its verification.
- Verifiers are no longer accepted delivering to the lookup on a subject's behalf; the subject registers again with the verified envelope. The renewal rule based on an unchanged digest is replaced by the lineage check.
- `GET /.well-known/gobl/who` answers with the lookup's party envelope addressed and signed for the requester.
- Deliveries to subjects carry no request token.

- Verification is now list-driven and automatic: the registry accepts a configured set of verification providers (`--verifiers` / `VERIFIERS`), and a registration or renewal arriving with a valid countersignature from one of them is verified on arrival — the countersignature is cryptographically checked against the provider's published key before being named (an unreachable key endpoint registers unverified and logs `inbox.auto_verify_unavailable`; the derivation re-runs on renewal). `gobl.lookup verify <address>` 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
Expand Down
207 changes: 111 additions & 96 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,49 +16,63 @@ Copyright 2026 [Invopop S.L.](https://invopop.com).

## How registration works

1. A GOBL Net node (e.g. a `gobl.dev` operator at
`alice.example`) signs an envelope containing its `org.Party`
and POSTs it to lookup's `/.well-known/gobl/inbox`. The
envelope's signed `iss=alice.example`,
`aud=lookup.gobl.org` (signed claims carry bare addresses — GOBL
Net is implied).
2. Lookup verifies the signature, then confirms the sender checks
out as a *sending* participant: it performs `GET /who` on
`alice.example` (re-fetching her published key in the process)
and requires a verified, self-signed party. A `204 No Content`
marks a receive-only account and rejects the registration with
`403 Forbidden`.
3. Lookup persists the envelope in CouchDB, countersigns it with
an Authority signature (`iss=lookup.gobl.org`,
`aud=alice.example`, `exp` = 90 days
out), and POSTs the **countersigned** envelope back to
`https://alice.example/.well-known/gobl/inbox` as a follow-up
message. The original POST is acknowledged with the standard
empty `202 Accepted` used for all inbox deliveries.
4. Alice publishes the countersigned envelope on her `/who`. Any
GOBL Net verifier can now confirm that lookup has attested to
her registration via `net.Client.VerifyAuthority` /
`net.Client.VerifySender`.

No new protocol endpoints — registration uses the standard GOBL
Net `/inbox` POST in both directions. Marking a registration as
verified (spec §5.3, the `verifier` claim) happens automatically
when the envelope carries a countersignature from an accepted
verification provider; the full self-service flow is specified in
[How verification works](#how-verification-works) below.
1. A GOBL Net node (e.g. a `gobl.dev` operator at `alice.example`)
sends its party envelope to lookup's `/.well-known/gobl/inbox`
as an ordinary delivery: `from` is `gobl:alice.example`, `to` is
`gobl:lookup.gobl.org`, and Alice signs it with `iss=alice.example`
and `aud=lookup.gobl.org`. No request token is needed; the
signature is the authentication.
2. Lookup verifies the delivery (`net.Client.DeliveryKeys`), then
confirms the sender is a *sending* participant: it performs
`GET /who` on `alice.example` and requires a verified party. A
`204 No Content` marks a receive-only account and rejects the
registration with `403 Forbidden`.
3. Lookup updates Alice's [key lineage](#key-lineage) from the keys
that signed the request, drops Alice's request signature,
countersigns as the Authority (`iss=lookup.gobl.org`,
`aud=alice.example`, `cnf` naming Alice's current key, `exp` = 90
days out), and addresses the envelope back (`from`
`gobl:lookup.gobl.org`, `to` `gobl:alice.example`). It persists
the record and acknowledges the POST with `202 Accepted`.
4. Lookup delivers the countersigned envelope to
`https://alice.example/.well-known/gobl/inbox`.
5. Alice publishes the envelope at her `/who`, signing each response
for its requester with the key the countersignature binds. Any
GOBL Net participant can now confirm her registration with
`net.Client.VerifyAuthority` / `net.Client.VerifySender`.

No new protocol endpoints: registration uses the standard GOBL Net
`/inbox` in both directions.

### Endorsement lifetime and renewal

Every countersignature carries a 90-day `exp` claim — verifiers
reject it after that, so parties renew by re-registering before it
passes (Let's Encrypt style). A renewal that re-submits the
**unchanged** party document (same digest) is countersigned with
the party's current `verifier` claim: verified stays verified,
while the verifier's own longer-lived countersignature (a year or
more, in the spirit of EV certificates) continues to evidence the
KYC. Submitting changed party data is a fresh registration — the
verifier is dropped and KYC must be repeated.

Every countersignature carries a 90-day `exp` claim, which receivers
reject after it passes, so parties renew by registering again before
then, Let's Encrypt style: submitting the envelope they hold,
countersignatures and all, signed for the lookup. The lookup
supersedes its own earlier countersignature. Changing the party
document changes its digest, so a verifier's countersignature on the
old document no longer applies and the registration starts
unverified.

### Key lineage

The lookup keeps each address's key lineage (spec §7.3): the keys it
has bound in turn, by RFC 7638 thumbprint and kid. The keys that
sign a registration request decide what happens:

| Request signed with | Result |
|--------------------------------------|------------------------------------------------------------|
| the current key (or a first key) | renewal (or first registration): the key stays bound |
| the current key and a new key | rollover: the new key joins the lineage and is bound |
| only a key that is not the current one | a lost key or a new holder: a new lineage starts |
| two keys at a first registration | the key a verification binds starts the lineage, then rolls over |

The lookup names a verifier only when its countersignature binds,
with `cnf`, a key in the current lineage. A rollover therefore keeps
a party verified with no work from its verifier, while a new holder
of a lapsed domain can register the address but cannot be verified
as its previous holder. Parties should rotate keys at renewal.

## How verification works

Expand Down Expand Up @@ -100,11 +114,10 @@ inbox deliveries.
inspectable up front.
4. **Session hand-off.** Lookup POSTs the party's **stored,
countersigned envelope** to the verifier's session API in the
background, authenticated with a request token for
`lookup.gobl.org` (spec §5.5). Sending the stored envelope
pins the verification to an exact `uuid` + `dig`: the verifier
MUST countersign those bytes, so the checks and the eventual
signature cannot drift apart. The verifier answers with an
background. Sending the stored envelope pins the verification to
an exact `uuid` + `dig`: the verifier MUST countersign those
bytes, so the checks and the eventual signature cannot drift
apart. The verifier answers with an
opaque, single-use session URL (or an error if it cannot serve
the party's jurisdiction); lookup redirects the user's browser
to it. Session URLs are unguessable on purpose —
Expand All @@ -118,35 +131,33 @@ inbox deliveries.
on the verifier's side: the registry stays free. From here the
provider runs its usual process (document checks, liveness,
registry/UBO lookups, AML screening).
6. **Countersign and return.** On success the verifier
countersigns the envelope from step 4 (`iss=<verifier>`,
`aud=<subject>`, `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=<that address>`
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=<verifier>`, `aud=<subject>`, `cnf` naming that key, `exp`
a year or more — spec §7.1) and delivers it to the **subject's**
inbox, `from` the verifier `to` the subject. Verifiers never
deliver to the lookup: GOBL Net has no forwarding. Failed or
abandoned sessions simply never produce a countersignature;
sessions expire after a few days.
7. **Renew with the verification.** The subject registers again
with the envelope it received. Lookup finds the valid
countersignature from a verifier on its trusted list, checks its
`cnf` names a key in the subject's lineage, and countersigns
with `verifier=<that address>` — the same act as
`gobl.lookup verify`, without the operator. The stored record
gains `verifier` + `verified_at`.
8. **Deliver and publish.** The countersigned envelope (verifier
countersignature and lookup countersignature naming the
verifier) is delivered to the subject's inbox, which publishes
it at its `/who`; only then do receivers see the verified
status.

Renewals keep the verifier as long as the subject presents the
verifier's countersignature and it binds a key in the lineage;
changed party data, or a lineage restarted by a lost key, drops it
and the party goes through verification again.

**Implementation gaps** (in rough order):

Expand Down Expand Up @@ -195,26 +206,25 @@ The domain never imports the transport layer.

| Method | Path | Auth | Purpose |
|--------|-------------------------------------|-------|----------------------------------------------------------|
| POST | `/.well-known/gobl/inbox` | token | Registration entry — must carry an `org.Party` document. |
| GET | `/.well-known/gobl/who` | token | Lookup's identity (self-signed party envelope). |
| POST | `/.well-known/gobl/inbox` | signature | Registration entry — must carry an `org.Party` document. |
| GET | `/.well-known/gobl/who` | token | Lookup's identity, signed for the requester. |
| GET | `/.well-known/gobl/keys/<kid>` | open | Single published key. |
| GET | `/.well-known/jwks.json` | open | Bulk JWK Set (for jwt.io-style tooling). |
| GET | `/parties/<address>` | open | Public registration record by address. |
| GET | `/parties/<uuid>` | open | Public registration record by envelope UUID. |
| GET | `/healthz` | open | Liveness check. |

The who and inbox endpoints require a bearer request token (spec
§5.5) minted from the caller's own published key; requests without
a valid token get `401`, and `503` when the token cannot be checked
because the issuer's key endpoint is unreachable (retry). The token's issuer may be a trusted
intermediary transmitting on the registrant's behalf — the
registration subject always comes from the envelope's own
signature. Key discovery stays open (it is what makes token
verification possible), and `/parties` remains an open directory of
registered — hence deliberately public — identities. The lookup's
own outbound requests (the sender `GET /who` eligibility check and
countersigned-envelope deliveries) authenticate the same way, as
`lookup.gobl.org`. Authenticated requests are logged with the
The who endpoint requires a bearer request token (spec §6) minted
from the caller's own published key; requests without a valid token
get `401`, and `503` when the token cannot be checked because the
issuer's key endpoint is unreachable (retry). The response is
addressed and signed for the token's issuer. Inbox deliveries carry
no token: the registration subject is the envelope's `from`,
confirmed by its signature for the lookup. Key discovery stays open,
and `/parties` remains an open directory of registered — hence
deliberately public — identities. The lookup's own sender `GET /who`
eligibility check authenticates as `lookup.gobl.org`; its deliveries
carry no token. Authenticated requests are logged with the
requester address, forming the request audit log.

## Quickstart (local dev)
Expand Down Expand Up @@ -258,7 +268,10 @@ registered address with id `registration:<address>`:
"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..." }
]
}
```

Expand Down Expand Up @@ -306,13 +319,15 @@ arrives from a secret independently of the host).

## Operations

- **Re-registration vs renewal**: re-submitting the unchanged party
document (same digest) is a renewal — it keeps the current
`verifier` and `verified_at`, stamping a fresh 90-day
countersignature. Submitting **changed** party data drops the
`verifier` and clears `verified_at`; verifying again requires
another `gobl.lookup verify <address>` call. Audit trail lives in
CouchDB revisions.
- **Renewal and key changes**: a request signed with the current key
renews, stamping a fresh 90-day countersignature; one signed with
the current and a new key rolls over to the new key. Either keeps
`verifier` and `verified_at` while the request carries a
verification bound to a key in the lineage. Changed party data, or
a request signed only with an unknown key, drops the `verifier`
and clears `verified_at`. Records without a lineage (registered
before key lineage) need one fresh registration. Audit trail lives
in CouchDB revisions.
- **Delivery failures**: the inbox handler responds `202` once the
record is persisted; delivery to the sender's `/inbox` happens
asynchronously. Failures land on `Record.LastDeliveryError`;
Expand Down
6 changes: 3 additions & 3 deletions cmd/gobl.lookup/setup.go
Original file line number Diff line number Diff line change
Expand Up @@ -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://<domain> when empty.
PublicBaseURL: strings.TrimRight(cfg.PublicBaseURL, "/"),
Logger: slog.Default(),
Expand Down
4 changes: 2 additions & 2 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ go 1.25.0
require (
github.com/go-kivik/kivik/v4 v4.5.2
github.com/invopop/couch v0.1.0
github.com/invopop/gobl v0.504.1-0.20260811215754-c231ee2feae5
github.com/invopop/gobl v0.512.1-0.20261113224301-2cdeefbda13a
github.com/magefile/mage v1.17.2
github.com/spf13/cobra v1.10.2
github.com/stretchr/testify v1.11.1
Expand All @@ -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
Expand Down
8 changes: 4 additions & 4 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -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=
Expand All @@ -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.20261113224301-2cdeefbda13a h1:ZOnidhzJBDS+5JAAw67twrNj4N8czVlTADDPOVXP8ac=
github.com/invopop/gobl v0.512.1-0.20261113224301-2cdeefbda13a/go.mod h1:7xBxkslYmW2MdNvanWiVPUYIvR3Se+2dKLYA6Tg+A40=
github.com/invopop/jsonschema v0.14.0 h1:MHQqLhvpNUZfw+hM3AZDYK7jxO8FZoQeQM77g8iyZjg=
github.com/invopop/jsonschema v0.14.0/go.mod h1:ygm6C2EaVNMBDPpaPlnOA2pFAxBnxGjFlMZABxm9n2I=
github.com/invopop/yaml v0.3.1 h1:f0+ZpmhfBSS4MhG+4HYseMdJhoeeopbSKbq5Rpeelso=
Expand Down
Loading
Loading