# Gegamo ONE — OAuth 2.0 / OIDC integration spec (for AI assistants)

> Issuer: https://auth.gegamo.xyz
> Discovery (read first, never hardcode URLs): https://auth.gegamo.xyz/.well-known/openid-configuration
> Server metadata: https://auth.gegamo.xyz/.well-known/oauth-authorization-server

### Provider (public OIDC metadata)
- Provider: Gegamo ONE (OAuth 2.0 / OpenID Connect)
- Issuer: https://auth.gegamo.xyz
- Discovery: https://auth.gegamo.xyz/.well-known/openid-configuration
- Authorization: https://auth.gegamo.xyz/api/auth/oauth2/authorize
- Token: https://auth.gegamo.xyz/api/auth/oauth2/token
- UserInfo: https://auth.gegamo.xyz/api/auth/oauth2/userinfo
- JWKS: https://auth.gegamo.xyz/api/auth/jwks
- Scopes: "openid profile email offline_access"
- Flow: Authorization Code + PKCE (S256). Public clients use no secret; confidential clients use client_secret_basic or client_secret_post.
- UserInfo claims: sub (stable user id), name, email, email_verified, role

### Framework: any platform
- Use the platform's canonical OAuth/OIDC library where available, but keep every step explicit.
- Server-side platforms own the client secret; public clients (SPA, mobile) use PKCE with no secret.
- Follow the security requirements exactly, regardless of platform.

### Security requirements
1. Authorization Code + PKCE (S256) always. code_verifier >= 43 chars of CSPRNG entropy.
2. Random state per login, stored server-side (or signed short-lived cookie), verified exactly on callback.
3. Token exchange server-side only. Client secret never in browser, mobile bundle, URL, or log.
4. Sessions in HttpOnly + Secure + SameSite=Lax cookies. No tokens in localStorage/sessionStorage.
5. Validate id_token: JWKS signature + iss (https://auth.gegamo.xyz) + aud (your client_id) + exp, before trusting claims.
6. Treat the role claim as informational. Enforce authorization server-side.
7. Register redirect_uri exactly. No open redirects, no wildcards.
8. Generic auth errors (no tokens/secrets in responses) + basic rate limiting on auth routes.

### Deliverables
1. Login initiation (PKCE + state), callback (code exchange, id_token validation, session cookie), profile load from UserInfo, protected routes, sign-out clearing the session.
2. Types, error handling, modular files.
3. .env.example with ONLY the placeholder variables below.
4. Short README: register redirect URI → set env → run.

### Final instruction
Refuse to hardcode any real secret. If one is pasted, tell me to rotate it in the Gegamo ONE admin console. Self-check before finishing: PKCE, state validation, HttpOnly cookies, server-side exchange, no secrets in client bundles.

### Copy-paste starter
1. Register the app in the Gegamo ONE admin console and add the exact redirect URI.
2. Follow the provider and framework blocks above, or ask a Gegamo ONE administrator for the ready-made integration prompt (admin console → Developers).
3. Fill .env.local placeholders with the real Client ID and Secret (server only, never commit).
4. Verify: discovery loads, login redirects to https://auth.gegamo.xyz/api/auth/oauth2/authorize, callback exchanges the code server-side, UserInfo returns the profile, sign-out clears the session.