Skip to content
Open
Show file tree
Hide file tree
Changes from all 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
33 changes: 27 additions & 6 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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).
- 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.
Comment thread
samlown marked this conversation as resolved.
Resolved
- 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/<key>` 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 <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
a definitive 4xx: an unreachable requester key endpoint during
token verification (log reason `token_unavailable`), and an
Expand All @@ -14,19 +26,21 @@
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.
- Outbound requests authenticate as the lookup itself: the sender `GET /who` eligibility check and countersigned-envelope deliveries carry bearer request tokens. A registrant answering its own `/who` with `202` (deferred disclosure) is rejected with `403` — senders must disclose openly to register.
- 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 `<kid>.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

Expand All @@ -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).
Expand Down
Loading
Loading