barycenter/docs/next-iteration-plan.md

### Next Iteration Plan — OpenID Connect OP (dated 2025-11-24 16:48)

This plan builds on the current implementation (Authorization Code + PKCE, ID Token signing, UserInfo, client_secret_post and client_secret_basic, discovery, JWKS, dynamic registration). The goal of this iteration is to harden compliance, improve interoperability, and introduce a minimal authentication stub to replace the fixed demo subject.

Objectives
- Compliance hardening: headers, error models, metadata accuracy.
- Authentication stub: minimal user login and session handling to issue codes for a real subject instead of the demo placeholder.
- Documentation updates and basic validation scripts/tests.

Scope and tasks
1. Token endpoint response hygiene
   - Add headers per OAuth 2.0 recommendations:
     - Cache-Control: no-store
     - Pragma: no-cache
   - Ensure JSON error bodies conform to RFC 6749 (error, error_description, error_uri optional). Keep existing WWW-Authenticate for invalid_client. 

2. ID Token claims improvements
   - Include auth_time when the OP has a known authentication time for the end-user session (see task 3 for session stub).
   - Ensure kid in JWS header is set (already implemented) and alg matches discovery. Verify exp/iat handling and clock skew tolerance notes for verifiers (doc).

3. Minimal authentication + consent stub
   - Introduce a basic login flow used by /authorize:
     - GET /login renders a simple page (or JSON instruction) to submit username (subject) and a fixed password placeholder.
     - POST /login sets a secure, HTTP-only cookie session with subject and auth_time; redirects back to the original /authorize request (preserve request params via a return_to parameter).
     - If an active session cookie is present at /authorize, skip login.
   - Consent: for MVP, auto-consent to requested scopes; record a TODO for explicit consent later.
   - Optionally, persist sessions in-memory for this iteration; a DB table can be added in a later iteration.

4. Error handling and redirects at /authorize
   - Continue using redirect-based error responses per OIDC (error, error_description, state passthrough).
   - Validate and return errors for: missing/invalid parameters, unsupported response_type, scope lacking openid, PKCE missing/invalid.

5. Discovery metadata accuracy
   - Verify discovery includes: userinfo_endpoint, token_endpoint_auth_methods_supported [client_secret_post, client_secret_basic], code_challenge_methods_supported [S256], response_types_supported [code], id_token_signing_alg_values_supported [RS256]. (Current implementation already does this; re-check after changes.)

6. Documentation updates
   - Update docs/oidc-conformance.md to mention client_secret_basic support and the new login/session stub behavior.
   - Add a short README snippet or docs/flows.md with example end-to-end curl/browser steps including the login step.

7. Basic validation scripts/tests
   - Add a scripts/ directory (or docs snippets) with curl commands to verify:
     - Discovery document fields.
     - Authorization + login + token exchange (with PKCE S256) producing a valid ID Token and access token.
     - UserInfo with Bearer access token and proper WWW-Authenticate on failure.

Non-goals (deferred)
- Refresh tokens, rotation, revocation and introspection.
- Rich user model and persistence (beyond minimal session stub).
- OpenID Federation trust chain validation.
- Key rotation and multi-key JWKS.

Acceptance criteria
- /token responses include Cache-Control: no-store and Pragma: no-cache for both success and error responses.
- /token invalid_client responses continue to include a proper WWW-Authenticate: Basic realm header.
- ID Token includes auth_time when the user logs in during the flow (based on the session stub’s auth_time); includes nonce when provided; includes at_hash.
- /authorize uses the logged-in user from the new session cookie; if no session, prompts to login and returns to continue the flow; redirects carry state on error.
- Discovery still advertises capabilities accurately after changes.
- Docs updated to reflect client_secret_basic and the login/session stub.
- Example commands or scripts demonstrate a complete code flow using PKCE with a login step and successful token exchange and userinfo call.

Implementation notes
- Keep the session cookie scoped to the IdP origin; mark HttpOnly, Secure in production, SameSite=Lax.
- Use S256 exclusively for PKCE (plain not supported).
- Continue to generate/sign with RS256; ensure kid header is present and published in JWKS.
- Keep the issuer stable via server.public_base_url in production deployments.

Timeline and effort
- Estimated effort: 1–2 short iterations.
  - Day 1: headers, error refinements, discovery verification, docs updates.
  - Day 2: login/session stub, auth_time claim, validation scripts.