golem15/summercms
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(19.4): decide OIDC on wristband with golang-jwt

Browse Source 
- Extend the hand-written wristband with an OIDC flavour; reject zitadel/oidc v3 (D-06, D-09, D-14)
- golang-jwt/jwt/v5 v5.3.1 signs id_tokens; JWKs encoded with the standard library
- go-oidc v3.21.0 and x/oauth2 v0.37.0 test-only in sm-oauthserver-plugin
- STACK.md zitadel/oidc row marked superseded
This commit is contained in:
Jakub Zych
2026-10-19 18:06:54 +02:00
parent 95051d26ce
commit 756a97c181
2 changed files with 41 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
.planning/notes/2026-10-19-oidc-on-wristband-golang-jwt.md Normal file
View File

@@ -0,0 +1,40 @@
# Decision: OIDC provider on wristband, id_tokens signed with golang-jwt
**Date:** 2026-10-19
**Status:** Accepted
**Context:** Phase 19.4 (OIDC provider on wristband, SC-1, D-06, D-09, D-14, D-16), 19.4-RESEARCH.md "D-16 decision", Standard Stack and Package Legitimacy Audit
## Decision
The OpenID Connect provider extends the hand-written `wristband` package with an OIDC flavour. It does not put zitadel/oidc behind wristband.
- **One engine, two flavours (D-06).** `wristband.NewServer` keeps building the MCP authorization server exactly as before; a new `wristband.NewOIDCServer` builds a second `*wristband.Server` whose flavour selects the OIDC validation and response code. Both share the primitives that Phase 8 already reviewed: client lookup, redirect matching, PKCE S256, SHA-256 hex hashing, constant-time comparison, random identifiers, the redirect HTML writer and refresh lineage.
- **Additive interfaces (D-09).** OIDC storage arrives through new interfaces (`OIDCBackend`, `OIDCTx`, `KeyStore`) and a host seam for HTML and the signed-in user (`OIDCHost`). `wristband.Backend`, `wristband.Tx` and every MCP signature stay source-compatible, so the existing MCP adapter in the first consuming application compiles unchanged.
- **`github.com/golang-jwt/jwt/v5` at v5.3.1 signs id_tokens** (RS256 and ES256). It is already required in `go.mod` and already used by `bouncer` (HS256) and `flare` (ES256 VAPID tokens), so the framework keeps one JOSE/JWT library. Claims are built as `jwt.MapClaims`, so `aud` stays a JSON string as in the PHP provider; `jwt.RegisteredClaims` would marshal `aud` as an array while the package global `jwt.MarshalSingleStringAsArray` is true, and that global is never touched because `bouncer` shares it.
- **JWKs are encoded with the standard library.** RSA keys publish the minimal big-endian bytes of the modulus and exponent; EC keys publish `x` and `y` from `ecdsa.PublicKey.Bytes()` (the fixed-length uncompressed point, so the left-padding bug cannot happen). About forty lines. `github.com/go-jose/go-jose/v4` was considered for this at runtime and rejected: it would be a second JOSE library next to golang-jwt (RESEARCH assumption A2). It still checks the encoder from the outside, because the test-only relying-party stack below verifies tokens through it.
- **The interop oracle is test-only and lives in the plugin repo.** `github.com/coreos/go-oidc/v3` at v3.21.0 and `golang.org/x/oauth2` at v0.37.0 drive a stock relying party (discovery, authorize URL with PKCE, code exchange, id_token and `at_hash` verification against the served JWKS) in `sm-oauthserver-plugin`. This is the D-16 interop test, the equivalent of the PHP plugin's JumbojettInteropTest. Both modules are installed in plan 19.4-02 only after a blocking human package check, because the package-legitimacy seam cannot check Go modules. The framework keeps a golang-jwt plus standard-library tracer over in-memory fakes, so the framework `go.mod` gains nothing.
**zitadel/oidc v3 was rejected.** v3.51.16 is a certified, maintained provider, and the comparison in 19.4-RESEARCH.md ("D-16 decision: recommendation") was made with that in favour. It fails three locked decisions at once:
- **D-06, one engine.** zitadel's `op` package is its own authorize and token engine. MCP stays on wristband (Phase 8 rejected zitadel for MCP byte parity, `.planning/notes/oauth2-wristband-direct-port.md`), so adopting it would mean two engines side by side.
- **D-09, additive interfaces.** An adapter would have to implement `op.Storage` (AuthStorage, OPStorage and Health, 25 methods) with zitadel-shaped types such as `*oidc.AuthRequest` and `jose.SignatureAlgorithm`, which cannot be added next to the existing adapter without reshaping it.
- **D-14, relying-party-visible parity.** `CreateDiscoveryConfig` always emits introspection, revocation, end-session, check-session and device endpoints that the PHP discovery document does not have, and zitadel owns the error JSON, the redirect building and the login URL contract. The PHP relying parties expect PHP's bytes.
It would also add chi v5, gorilla/securecookie, rs/cors, go-jose v4, a newer OpenTelemetry than the framework pins, golang/mock and more to the runtime module graph.
The trade-off in plain words: the user's standing preference ("recommend the maintained library plus a decision note for protocol and security code") is honoured for the cryptography (golang-jwt signs, go-oidc and go-jose verify in tests). The protocol state machine stays the already-reviewed wristband code, because the certified library cannot meet D-06, D-09 and D-14 together.
This note supersedes the zitadel/oidc row of `.planning/research/STACK.md` for OIDC, as `.planning/notes/oauth2-wristband-direct-port.md` already did for MCP.
## Related dependencies
- **`github.com/coreos/go-oidc/v3` v3.21.0, test-only**, in `sm-oauthserver-plugin` (requires go-jose v4 transitively). Installed after a blocking human package check in plan 19.4-02.
- **`golang.org/x/oauth2` v0.37.0, test-only**, in `sm-oauthserver-plugin`, same check. Its client sends Basic credentials as `url.QueryEscape(id):url.QueryEscape(secret)`, which is why the OIDC token endpoint unescapes both halves (PHP does `urldecode`).
- **Standard library only for the rest:** `crypto/rsa`, `crypto/ecdsa`, `crypto/elliptic`, `crypto/x509`, `encoding/pem`, `math/big` for keys and JWKs; `uuid` (Go 1.27, `uuid.NewV4`) for request identifiers and subjects; `log/slog` for the fixed-reason failure logs.
## Consequences
- The framework `go.mod` gains no module; `grep -E 'zitadel|go-jose|coreos' go.mod` stays empty.
- `wristband` stays a protocol leaf: no ORM, no framework module, no application package. Storage, keys at rest, pages and routes belong to `sm-oauthserver-plugin` (D-01).
- The OIDC flavour owns every byte a relying party sees (discovery field order, redirect encoding, error bodies, headers), so parity with the PHP provider is a matter of tests and `tide` recordings, not of fighting library defaults.
- Replacing golang-jwt later means re-checking the id_token header (`alg`, `kid`) and the string `aud` against the go-oidc interop test.

2
.planning/research/STACK.md
View File

@@ -18,7 +18,7 @@ This extends `.planning/research/go-ecosystem.md` (2026-09-16 GitHub-API-verifie
| GORM | v1.31.2 (Jun 22, 2026) | ORM, Postgres only | Already decided. Current stable line; v1.31.x added generics-based `Count` etc. Confirmed via pkg.go.dev version list. HIGH confidence. |
| gorm.io/driver/postgres | v1.6.3 (Sep 14, 2026) | Postgres driver for GORM | Latest patch release, two days before this research. Its `go.mod` pins `github.com/jackc/pgx/v5 v5.10.0` — GORM's "Postgres driver" is pgx under the hood, not lib/pq. This is the crux of the River pool-sharing question below. HIGH confidence (read go.mod directly). |
| River | v0.47.0 (confirmed via multiple independent 2026 dependabot PRs bumping to this version; GitHub releases page fetch returned stale cached 2024 dates — do not trust that page directly, cross-checked against `riverdriver`/`riverpgxv5`/`riverdatabasesql` sub-package publish dates of Apr–Jul 2026) | Postgres-backed job queue | Already decided. MEDIUM-HIGH confidence on the exact patch version; HIGH confidence it's the current v0.4x line and actively maintained. |
| zitadel/oidc | v3.51.0 (Sep 14, 2026) | OAuth2/OIDC provider | Already decided, and confirmed correct: **v4 exists only as `v4.0.0-next.4` (pre-release, Jul 30, 2026)**. v3 is the maintained stable line (v3.51.0 shipped two days before this research, newer than the v4 pre-release). Stay on v3; do not chase v4 until it ships stable. Flagged explicitly per the quality gate — this does not contradict the existing decision, it confirms it. |
| zitadel/oidc | v3.51.0 (Sep 14, 2026) | OAuth2/OIDC provider | Already decided, and confirmed correct: **v4 exists only as `v4.0.0-next.4` (pre-release, Jul 30, 2026)**. v3 is the maintained stable line (v3.51.0 shipped two days before this research, newer than the v4 pre-release). Stay on v3; do not chase v4 until it ships stable. Flagged explicitly per the quality gate — this does not contradict the existing decision, it confirms it. Superseded: MCP by .planning/notes/oauth2-wristband-direct-port.md, OIDC by .planning/notes/2026-10-19-oidc-on-wristband-golang-jwt.md |
| golang-jwt/jwt | v5.3.1 (Jan 28, 2026), import path `github.com/golang-jwt/jwt/v5` | JWT for the SPA and for signing Centrifugo connection/subscription tokens | Already decided. One library covers both jobs — see Centrifugo section. |
| go-playground/validator | v10.30.4 (Sep 3, 2026), import path `.../validator/v10` | Struct-tag validation from YAML `rules:` | Already decided. Current. |
| cobra | v1.10.2 (Dec 3, 2025) | CLI framework | Already decided. Current stable. |