pollinator/consent
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

added: a public protocol package, client versions on integrations, and auth debug logging #11

Merged
jak merged 6 commits from integration-protocol into main 2026-10-26 02:41:18 -04:00
Conversation 0 Commits 6 Files changed 44 +1822 -657
jak commented 2026-10-24 18:42:34 -04:00
Owner
Copy link

When an app's client library spoke a different protocol than the Consent server, sign-in failed silently. Consent issued tokens the app could not decode, and nothing on either side said why. This PR makes that kind of mismatch visible and fixable, and adds a few operator conveniences.

Changes

  • Administrator command. consent api admins create HANDLE creates the user, adds them to admin, and prints a password link. make compose-admin uses it and no longer needs jq. While the admin group is empty, consent init prints the command to run.
  • Debug logging of authorization events. consent serve --verbose logs sign-ins, authorization requests, authorization codes, token exchanges, userinfo calls and sign-outs, with the reason for each refusal. Default logging is unchanged.
  • pkg/protocol. A new public package for the contract between Consent and its apps: the protocol version, the endpoints apps call with their bodies, and the integration manifest. It imports only the standard library. pkg/client builds on it, re-exports the types apps use, and no longer imports internal/api, so apps stop linking Consent's server code.
  • Client library versions on integrations. Manifests are now version 2 and declare protocol and client_version. Consent rejects a manifest whose protocol differs from its own, and says which side to upgrade. It records both values with each registration: migration 2 adds the columns, and existing registrations start at protocol 0. The Integrations page marks outdated registrations, and consent init warns about them on every start.
  • Migration policy. AGENTS.md now requires a migration for every schema change and forbids editing a released one.

What operators and integrations must do

  • Apps: upgrade git.sr.ht/~jakintosh/consent and redeploy. Then refresh each integration from its manifest in the admin UI. Registrations made before this change show as needing an upgrade until you do. Apps that use client.UserInfo or client.IntegrationManifest need no source changes; those names remain as aliases.
  • Code calling client.DecodeIntegrationManifest or using the manifest errors: switch to pkg/protocol.
  • Operators: the database upgrades in place. Add --verbose to CONSENT_SERVE_FLAGS to see authorization events.

Testing

  • make test passes on every commit.
  • New tests cover: the admin check; the logged events and their reasons; protocol rejection; recorded client versions and their diff; outdated detection in the service, database and web UI; upgrading a version-1 database; and the protocol paths matching the server's routes.
  • I smoke-tested admins create, the init hint and warnings, --verbose output, and import of an old manifest against a local server.

🤖 Generated with Claude Code

When an app's client library spoke a different protocol than the Consent server, sign-in failed silently. Consent issued tokens the app could not decode, and nothing on either side said why. This PR makes that kind of mismatch visible and fixable, and adds a few operator conveniences. ## Changes - **Administrator command.** `consent api admins create HANDLE` creates the user, adds them to `admin`, and prints a password link. `make compose-admin` uses it and no longer needs `jq`. While the `admin` group is empty, `consent init` prints the command to run. - **Debug logging of authorization events.** `consent serve --verbose` logs sign-ins, authorization requests, authorization codes, token exchanges, userinfo calls and sign-outs, with the reason for each refusal. Default logging is unchanged. - **`pkg/protocol`.** A new public package for the contract between Consent and its apps: the protocol version, the endpoints apps call with their bodies, and the integration manifest. It imports only the standard library. `pkg/client` builds on it, re-exports the types apps use, and no longer imports `internal/api`, so apps stop linking Consent's server code. - **Client library versions on integrations.** Manifests are now version 2 and declare `protocol` and `client_version`. Consent rejects a manifest whose protocol differs from its own, and says which side to upgrade. It records both values with each registration: migration 2 adds the columns, and existing registrations start at protocol 0. The Integrations page marks outdated registrations, and `consent init` warns about them on every start. - **Migration policy.** `AGENTS.md` now requires a migration for every schema change and forbids editing a released one. ## What operators and integrations must do - **Apps:** upgrade `git.sr.ht/~jakintosh/consent` and redeploy. Then refresh each integration from its manifest in the admin UI. Registrations made before this change show as needing an upgrade until you do. Apps that use `client.UserInfo` or `client.IntegrationManifest` need no source changes; those names remain as aliases. - **Code calling `client.DecodeIntegrationManifest` or using the manifest errors:** switch to `pkg/protocol`. - **Operators:** the database upgrades in place. Add `--verbose` to `CONSENT_SERVE_FLAGS` to see authorization events. ## Testing - `make test` passes on every commit. - New tests cover: the admin check; the logged events and their reasons; protocol rejection; recorded client versions and their diff; outdated detection in the service, database and web UI; upgrading a version-1 database; and the protocol paths matching the server's routes. - I smoke-tested `admins create`, the `init` hint and warnings, `--verbose` output, and import of an old manifest against a local server. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Deployments now update in place, so a deployment's data has to survive
upgrades. We replaced the rule against versioned migrations with one that
adds a migration for every schema change and never edits a released one.
Other interfaces still favor a clean break, now with a note on what operators
and integrations must do.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
'consent api admins create HANDLE' creates the user, adds them to the admin
group, and prints a link where they choose their password. 'make
compose-admin' runs it in Docker Compose and no longer needs jq.

While the admin group is empty, 'consent init' ends by printing the command
to run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A sign-in that failed inside an app left no trace in Consent's logs. With
'consent serve --verbose', the server now logs sign-ins, authorization
requests, authorization codes, token exchanges, userinfo calls and sign-outs
at debug level, with the reason for each refusal. Tokens and passwords are
never logged. Without the flag, logging is unchanged.

In Docker Compose, operators set CONSENT_SERVE_FLAGS=--verbose in .env.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Coco's sign-in failed silently after Consent changed its token header types,
because Coco still used the older client library. Nothing in Consent showed
that the two no longer matched.

We added 'pkg/protocol' for the contract between Consent and its apps: a
protocol version, the endpoints apps call with their request and response
bodies, and the integration manifest. It imports only the standard library.
'pkg/client' builds on it and re-exports the types apps use, such as
'client.UserInfo' and 'client.IntegrationManifest'. The client library no
longer imports 'internal/api', so apps stop linking Consent's server code.

Manifests are now version 2 and declare 'protocol' and 'client_version',
which 'client.HandleIntegrationManifest' fills in. Consent refuses to register
an app whose protocol differs from its own and says which side to upgrade.
It records both values with each registration and shows them on the
integration's page. A new migration adds them to existing databases, where
earlier registrations start at protocol 0. The Integrations page marks
registrations from another protocol as needing an upgrade, and 'consent init'
warns about them on every start.

Apps must upgrade the client library and then refresh their registration from
the manifest. Code that called 'client.DecodeIntegrationManifest' or used the
manifest errors must switch to 'pkg/protocol'.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
jak force-pushed integration-protocol from befd6174f7 to b6b2018d18 2026-10-25 16:06:20 -04:00 Compare 
The authorization logging had split several service methods into a public
wrapper that logged and a private copy of the original body. We returned each
method to a single body and moved its logging into a deferred check on the
named error result. We also wrote the manifest size limit as '64 * 1024'.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
jak merged commit 1526cd078e into main 2026-10-26 02:41:18 -04:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
pollinator/consent!11
No description provided.