oauth-oidc

name	oauth-oidc
description	OAuth 2.1 / OIDC rules for QAuth. Use when working with authorization endpoints, token flows, PKCE, JWKS, OIDC discovery, or spec compliance (RFC 9700, OIDC Core 1.0). Covers endpoint behaviour, email claim rules, and token security.

OAuth 2.1 / OIDC Rules

You are working in the QAuth OAuth/OIDC implementation.

Spec References

• OAuth 2.1 (draft-ietf-oauth-v2-1) — PKCE mandatory for all authorization code flows
• OIDC Core 1.0 — sub is stable UUID, email is optional and omitted when unverified
• RFC 7662 — Token introspection (compliance feature, client auth required)
• RFC 7517 — JSON Web Key (JWKS)
• RFC 9700 — OAuth 2.0 Security Best Current Practice

Endpoints

Endpoint	Description
POST /auth/register	Registration — creates user, credential, attribute, verification token
POST /auth/login	Password login — looks up user_credentials by (realm_id, 'password', external_sub) where external_sub is the normalised email
GET /auth/verify	Email verification — marks credential_data.email_verified=true and user_attributes.verified=true
POST /auth/resend-verification	Resend verification email
GET /oauth/authorize	Authorization Code Flow initiation
POST /oauth/token	Token endpoint (authorization_code, refresh_token grants)
POST /oauth/introspect	RFC 7662 introspection (client auth required)
GET /oauth/userinfo	OIDC userinfo — reads sub from JWT, returns verified email from user_attributes
GET /.well-known/jwks.json	JWKS endpoint
GET /.well-known/openid-configuration	OIDC discovery

Introspection

POST /oauth/introspect is a compliance feature, not a primary usage path. Modern applications validate JWT tokens locally via JWKS.

Client authentication is required on this endpoint — not optional. This prevents token enumeration attacks. The endpoint must return {"active":false} for any unauthenticated request rather than an error, per RFC 7662.

OIDC Discovery

/.well-known/openid-configuration must always reflect the current set of supported grant types, response types, and signing algorithms.

When the wallet-federation flow (T4, Epic #231 — now active) is implemented, update to advertise:

• subject_types_supported: ["public", "pairwise"]
• request_object_signing_alg_values_supported — still required, but for JAR ([RFC 9101] signed requests), not SIOPv2. HAIP 1.0 §5.1 mandates signed authorization requests via JAR with request_uri; SIOPv2 is not the mechanism (see ADR-004 § Spec status (2026-07-20)). Note HAIP 1.0 §7 requires ES256 at minimum, which QAuth does not support today (#298).

Do not add these fields until the WalletProvider presentation flow is implemented and tested (T4, Epic #231) — the skeleton (#232) does not authenticate anyone yet.

Email Claim Behaviour

The email claim in ID tokens and userinfo responses:

• Released only when the email scope was granted — userinfo since #229, ID tokens since #259; without the scope the claims are omitted even for a verified email (access-token convenience claims are not scope-gated)
• Present only when user_attributes has a verified email (verified=true)
• Absent (not null) when no verified email exists
• Sourced from the highest-trust attribute source (wallet > oidc_* > self_reported); the schema and auth-engine skills own the claim-resolution trust order.

This is intentional and correct per OIDC Core 1.0. Applications that assume email is always present in the userinfo response are not OIDC-compliant.

PKCE

PKCE is mandatory (S256 only; plain rejected) for all authorization code flows. For the flow, verifier/challenge mechanics, and grant-type rules, see the auth-oauth skill — this skill covers only OIDC-specific endpoint behaviour.

Token Security (QAuth specifics)

QAuth's token implementation (generic OAuth token-handling rules are in the auth-oauth skill):

• Access tokens: JWT, signed with Ed25519 (Phase 1), hybrid ML-DSA-65+Ed25519 (Phase 5 — post-quantum)
• Refresh tokens: opaque random tokens, SHA-256 hashed before storage
• Verification tokens: opaque random tokens, SHA-256 hashed before storage
• All token hashes stored as 64-character hex strings (SHA-256 output)

Related

• OAuth flows, PKCE, grant types: auth-oauth skill
• Claim resolution & identity model: schema, auth-engine skills
• Timing-safe / secrets / rate limiting: security skill