Home Explore Help
Register Sign In
efren
/
testing-proxy
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: bfc057bbd4
Branches Tags
testing-proxy
/
docs
/
PLAN-OAUTH-21-SERVER.md

PLAN-OAUTH-21-SERVER.md 20 KB
History Raw

oauth-21-server - Work Plan

TL;DR (For humans)

What you'll get: A fully compliant OAuth 2.1 authorization server with a discovery endpoint, PKCE-mandatory authorization flows, opaque tokens stored in Redis, and a login/consent UI. All endpoints follow RFC 8414 metadata and OAuth 2.1 draft-15 with the highest security posture — no legacy grants, no plain PKCE, exact redirect URI matching, and HTTPS enforcement.

Why this approach: Using ioredis for all expiring data (tokens, auth codes, sessions) and SQLite3 only for persistent records (clients, users, scopes) cleanly separates concerns and leverages Redis TTL for automatic expiration. SvelteKit's +server.js handlers provide a clean API layer on the existing Node.js adapter.

What it will NOT do: It will not support JWT tokens, implicit grants, password grants, client_credentials grants, or query-string bearer tokens. It will not persist auth codes or tokens in SQLite3. It does not include OpenID Connect.

Effort: Large Risk: Medium — Redis dependency adds operational surface; PKCE and PAR enforcement must be exact Decisions to sanity-check: Token format (opaque), grant types (authorization_code + refresh_token only), Redis as sole store for expiring data.

Your next move: Start work with /start-work.

TL;DR (machine): Large effort, Medium risk — OAuth 2.1 AS with discovery, PKCE, PAR, opaque tokens in Redis, sqlite3 for persistent data, SvelteKit +server.js handlers.

Scope

Must have

  • /.well-known/oauth-authorization-server metadata endpoint (RFC 8414)
  • OAuth 2.1 core protocol endpoints: /oauth/authorize, /oauth/token, /oauth/introspect, /oauth/revoke
  • Client registration endpoint /oauth/register (RFC 7591)
  • PKCE S256 mandatory enforcement (no plain)
  • Pushed Authorization Requests (PAR) endpoint /oauth/par (RFC 9126) with require_pushed_authorization_requests: true
  • Opaque token generation and storage in Redis with TTL
  • Authorization code generation and storage in Redis with TTL
  • Refresh token generation and storage in Redis with TTL
  • Client authentication at token endpoint: client_secret_basic, client_secret_post, private_key_jwt, tls_client_auth
  • Introspection endpoint with client auth (not bearer-only)
  • Exact redirect URI matching
  • User login page (/oauth/login)
  • User consent page (/oauth/consent)
  • config.json updates: baseUrl, redis connection options (host, port, password, database number)
  • ioredis dependency and Redis client module
  • SQLite3 schema extension: clients table only
  • scopes_supported dynamically from SQLite3 scopes table
  • ui_locales_supported: ["en-US", "es-MX"]
  • Documentation moved from .omo/ulw-research/ to docs/

Must NOT have (guardrails, anti-slop, scope boundaries)

  • JWT access tokens (opaque only)
  • Implicit grant (response_type=token)
  • Resource Owner Password Credentials grant
  • client_credentials grant
  • plain PKCE method
  • Auth codes, access tokens, or refresh tokens stored in SQLite3
  • Bearer tokens in query strings
  • Wildcard or prefix redirect URI matching
  • OpenID Connect (ID tokens, userinfo endpoint)
  • Device authorization grant (RFC 8628)
  • CORS on authorization endpoint

Verification strategy

Zero human intervention - all verification is agent-executed.

  • Test decision: tests-after + agent-executed QA via curl/httpie against running dev server
  • Evidence: .omo/evidence/task-<N>-oauth-21-server.<ext>

Execution strategy

Parallel execution waves

Target 5-8 todos per wave.

Wave 1: Foundation — Config, dependencies, Redis client, database schema Wave 2: Discovery & Client Registration — Metadata endpoint, client registration Wave 3: Core OAuth Flow — Authorization, token, introspection, revocation endpoints Wave 4: User UI & Security Hardening — Login/consent pages, PAR, JWKS Wave 5: Documentation & Final QA — Move docs, integration testing

Dependency matrix

Todo Depends on Blocks Can parallelize with
1 — 2,3,4,5 —
2 1 6,7,8,9,10 3,4,5
3 1 6,7,8,9,10 2,4,5
4 1 6,7,8,9,10 2,3,5
5 1 — 2,3,4
6 2,3,4 7 —
7 6 8,9,10 —
8 7 — 9,10
9 7 — 8,10
10 7 — 8,9
11 1 12 —
12 11 — —
13 — — all
14 all — —

Todos

  • [x] 1. Update config.json.example with baseUrl and redis sections What to do / Must NOT do: Add baseUrl (string, e.g., https://localhost:3000) and redis object with host, port, password, db (database number) to config.json.example. Must NOT remove existing database/password sections. Parallelization: Wave 1 | Blocked by: — | Blocks: 2,3,4,5 References: config.json.example:1-25, src/lib/config.js:1-19 Acceptance criteria: cat config.json.example | grep -q baseUrl && cat config.json.example | grep -q redis QA scenarios: Verify JSON is valid (node -e "JSON.parse(require('fs').readFileSync('config.json.example'))"). Happy: valid JSON. Failure: invalid JSON syntax. Commit: Y | feat(config): add baseUrl and redis connection options

  • [x] 2. Install ioredis dependency and create Redis client module What to do / Must NOT do: pnpm add ioredis. Create src/lib/redis.js exporting a configured ioredis client using config.redis. Must NOT use redis (node-redis) package. Must handle connection errors gracefully. Parallelization: Wave 1 | Blocked by: 1 | Blocks: 6,7,8,9,10 References: package.json:29-32, src/lib/config.js:1-19, ioredis docs Acceptance criteria: node -e "import('./src/lib/redis.js').then(m => console.log(typeof m.default))" returns "object" or similar QA scenarios: Happy: Redis client connects and responds to PING. Failure: Invalid config throws error with helpful message. Commit: Y | feat(redis): add ioredis client module

  • [x] 3. Extend SQLite3 schema with clients table What to do / Must NOT do: Add clients table creation to seedInfo() in src/lib/sqlite3/database.js. Schema: id, client_id (TEXT UNIQUE), client_secret (TEXT), redirect_uris (TEXT, JSON array), grant_types (TEXT), response_types (TEXT), scope (TEXT), token_endpoint_auth_method (TEXT), registration_access_token (TEXT), created_at, updated_at. Must NOT create auth_codes, access_tokens, or refresh_tokens tables in SQLite3. Parallelization: Wave 1 | Blocked by: 1 | Blocks: 6,7,8,9,10 References: src/lib/sqlite3/database.js:16-47 Acceptance criteria: After rm data/app.db && npm run dev, clients table exists with correct columns. QA scenarios: Happy: Fresh DB initializes with clients table. Failure: Duplicate table creation does not error (idempotent). Commit: Y | feat(db): add clients table for OAuth 2.1

  • [x] 4. Create token generation utilities What to do / Must NOT do: Create src/lib/oauth/tokens.js with functions: generateAuthorizationCode(), generateAccessToken(), generateRefreshToken() — all return cryptographically random strings (use crypto.randomBytes). Must NOT use Math.random(). Must NOT create JWTs. Parallelization: Wave 1 | Blocked by: 1 | Blocks: 6,7,8,9,10 References: Node.js crypto module docs, src/lib/crypto.js:1-13 Acceptance criteria: node -e "import('./src/lib/oauth/tokens.js').then(m => console.log(m.generateAccessToken().length > 20))" prints true QA scenarios: Happy: Generated tokens are unique across 1000 calls. Failure: Tokens are predictable or too short. Commit: Y | feat(oauth): add opaque token generation utilities

  • [x] 5. Create PKCE validation utilities What to do / Must NOT do: Create src/lib/oauth/pkce.js with generateCodeChallenge(verifier) (S256 SHA256 base64url) and verifyCodeChallenge(verifier, challenge) (constant-time comparison). Must NOT support plain method. Must use crypto.createHash('sha256'). Parallelization: Wave 1 | Blocked by: 1 | Blocks: 6,7 References: RFC 7636 Section 4, Node.js crypto docs Acceptance criteria: node -e "import('./src/lib/oauth/pkce.js').then(m => m.verifyCodeChallenge('test', m.generateCodeChallenge('test')))" prints true QA scenarios: Happy: Valid verifier matches challenge. Failure: Invalid verifier fails, wrong method fails, timing attack resistant. Commit: Y | feat(oauth): add PKCE S256 utilities

  • [x] 6. Create /.well-known/oauth-authorization-server endpoint What to do / Must NOT do: Create src/routes/.well-known/oauth-authorization-server/+server.js returning JSON metadata. Must query scopes_supported from SQLite3 scopes table dynamically. Must use config.baseUrl for all endpoint URLs. Must include: issuer, authorization_endpoint, token_endpoint, revocation_endpoint, introspection_endpoint, registration_endpoint, pushed_authorization_request_endpoint, require_pushed_authorization_requests (true), response_types_supported (["code"]), grant_types_supported (["authorization_code", "refresh_token"]), token_endpoint_auth_methods_supported, revocation_endpoint_auth_methods_supported, introspection_endpoint_auth_methods_supported, code_challenge_methods_supported (["S256"]), scopes_supported, service_documentation, ui_locales_supported (["en-US", "es-MX"]). Must NOT include "plain" in code_challenge_methods_supported. Must NOT include "bearer" alone in introspection auth methods. Parallelization: Wave 2 | Blocked by: 2,3 | Blocks: 7 References: src/lib/config.js:1-19, src/lib/sqlite3/database.js:1-91, RFC 8414 Section 2 Acceptance criteria: curl -s http://localhost:3000/.well-known/oauth-authorization-server | jq '.issuer' returns non-null QA scenarios: Happy: Returns valid JSON with all required fields. Failure: Missing baseUrl config throws 500. Scopes query returns correct list from DB. Commit: Y | feat(oauth): add OAuth 2.1 discovery metadata endpoint

  • [x] 7. Create /oauth/register client registration endpoint What to do / Must NOT do: Create src/routes/oauth/register/+server.js handling POST for dynamic client registration (RFC 7591). Store clients in SQLite3 clients table. Generate client_id, client_secret (if confidential client), registration_access_token. Return client metadata with client_id_issued_at. Must validate redirect_uris (exact, HTTPS). Must NOT allow http:// except localhost. Must NOT register clients with unsupported grant types. Parallelization: Wave 2 | Blocked by: 2,3 | Blocks: 8,9,10 References: RFC 7591, src/lib/sqlite3/database.js, src/routes/.well-known/oauth-authorization-server/+server.js Acceptance criteria: curl -s -X POST http://localhost:3000/oauth/register -H "Content-Type: application/json" -d '{"redirect_uris":["https://example.com/callback"],"client_name":"Test"}' | jq '.client_id' returns non-null QA scenarios: Happy: Valid registration returns client_id. Failure: Missing redirect_uris returns 400. Invalid redirect URI returns 400. HTTP redirect URI (non-localhost) returns 400. Commit: Y | feat(oauth): add dynamic client registration endpoint

  • [x] 8. Create /oauth/authorize authorization endpoint What to do / Must NOT do: Create src/routes/oauth/authorize/+server.js handling GET. Validate response_type=code, client_id, redirect_uri (exact match against registered), scope (must be subset of registered), code_challenge (S256 only, required), code_challenge_method (must be "S256"). Store auth code in Redis with TTL (10 minutes) keyed by code. Value includes: client_id, redirect_uri, user_id, scope, code_challenge, expires_at. Redirect to redirect_uri with ?code=...&state=...&iss=... (RFC 9207). Must NOT support response_type=token. Must NOT accept missing code_challenge. Parallelization: Wave 3 | Blocked by: 5,6,7 | Blocks: 9 References: draft-ietf-oauth-v2-1-15 Section 3.1, RFC 7636, src/lib/oauth/pkce.js, src/lib/redis.js Acceptance criteria: curl -s "http://localhost:3000/oauth/authorize?response_type=code&client_id=TEST&redirect_uri=https://example.com/callback&scope=user&code_challenge=abc123&code_challenge_method=S256&state=xyz" -w "%{http_code}" returns 302 QA scenarios: Happy: Valid request redirects with code. Failure: Missing PKCE returns 400. Invalid redirect_uri returns 400. Unsupported response_type returns 400. Expired client_id returns 400. Commit: Y | feat(oauth): add authorization endpoint with mandatory PKCE

  • [x] 9. Create /oauth/token token endpoint What to do / Must NOT do: Create src/routes/oauth/token/+server.js handling POST. Support grant_type=authorization_code and refresh_token. For authorization_code: validate code (from Redis), client auth, redirect_uri (required if in auth request), verify PKCE code_verifier against stored code_challenge. Issue opaque access_token and refresh_token, store in Redis with TTL. Return JSON with access_token, token_type, expires_in, refresh_token, scope. Must NOT support password grant. Must NOT support implicit. Must NOT issue tokens for invalid PKCE. Parallelization: Wave 3 | Blocked by: 6,7,8 | Blocks: 10 References: draft-ietf-oauth-v2-1-15 Section 3.2, src/lib/oauth/tokens.js, src/lib/redis.js, src/lib/oauth/pkce.js Acceptance criteria: curl -s -X POST http://localhost:3000/oauth/token -d "grant_type=authorization_code&code=VALID_CODE&redirect_uri=https://example.com/callback&client_id=TEST&code_verifier=VERIFIER" | jq '.access_token' returns non-null QA scenarios: Happy: Valid code exchange returns tokens. Failure: Invalid code returns 400. Missing code_verifier returns 400. Wrong redirect_uri returns 400. Expired code returns 400. Invalid client auth returns 401. Commit: Y | feat(oauth): add token endpoint with PKCE verification

  • [x] 10. Create /oauth/introspect and /oauth/revoke endpoints What to do / Must NOT do: Create src/routes/oauth/introspect/+server.js (POST) and src/routes/oauth/revoke/+server.js (POST). Introspection: authenticate client, look up token in Redis, return {active: true/false, ...} with token metadata if active. Revocation: authenticate client, delete token from Redis, return 200. Both must use client auth methods (client_secret_basic, client_secret_post). Must NOT accept bearer-only auth on introspection. Parallelization: Wave 3 | Blocked by: 6,7,9 | Blocks: — References: RFC 7662, RFC 7009, src/lib/redis.js Acceptance criteria: curl -s -X POST http://localhost:3000/oauth/introspect -u "CLIENT_ID:SECRET" -d "token=VALID_TOKEN" | jq '.active' returns true/false QA scenarios: Happy: Valid token introspection returns active=true with metadata. Valid revocation deletes token. Failure: Missing client auth returns 401. Invalid token returns active=false. Revoked token introspection returns active=false. Commit: Y | feat(oauth): add token introspection and revocation endpoints

  • [x] 11. Create /oauth/par Pushed Authorization Request endpoint What to do / Must NOT do: Create src/routes/oauth/par/+server.js handling POST. Accepts same parameters as authorize endpoint. Stores request in Redis with TTL (short-lived, e.g., 60s). Returns request_uri (urn:ietf:params:oauth:request_uri:...). Authorize endpoint must accept request_uri parameter and lookup stored request. Must set require_pushed_authorization_requests: true in discovery metadata. Parallelization: Wave 4 | Blocked by: 6,8 | Blocks: 12 References: RFC 9126, src/lib/redis.js, src/routes/oauth/authorize/+server.js Acceptance criteria: curl -s -X POST http://localhost:3000/oauth/par -d "client_id=TEST&response_type=code&redirect_uri=https://example.com/callback&scope=user&code_challenge=abc123&code_challenge_method=S256" | jq '.request_uri' returns non-null QA scenarios: Happy: PAR request returns request_uri. Authorize with request_uri redirects with code. Failure: Invalid client_id returns 400. Expired request_uri returns invalid_request. Commit: Y | feat(oauth): add PAR endpoint

  • [x] 12. Create /oauth/login and /oauth/consent UI pages What to do / Must NOT do: Create src/routes/oauth/login/+page.svelte and src/routes/oauth/consent/+page.svelte. Login: email/password form, validate against SQLite3 users table using existing Argon2id. Consent: display client name, requested scopes, allow/deny buttons. On allow, redirect to authorize endpoint with user context. Use Svelte 5 runes. Must NOT use TypeScript. Must use Flowbite components where appropriate. Parallelization: Wave 4 | Blocked by: 1 | Blocks: — References: src/routes/+page.svelte:1-39, src/lib/crypto.js:1-13, src/lib/sqlite3/database.js:1-91 Acceptance criteria: curl -s http://localhost:3000/oauth/login returns HTML with login form. curl -s http://localhost:3000/oauth/consent returns HTML with consent UI. QA scenarios: Happy: Valid credentials log in. Consent allow redirects to authorize. Consent deny returns access_denied. Failure: Invalid credentials show error. Missing session redirects to login. Commit: Y | feat(ui): add OAuth login and consent pages

  • [ ] 13. Move .omo/ulw-research/ artifacts to docs/ What to do / Must NOT do: Copy or move files from .omo/ulw-research/ to docs/oauth-research/. Must NOT delete originals (they are under .omo/ which may be gitignored). Must ensure docs are readable. Parallelization: Wave 5 | Blocked by: — | Blocks: — References: .omo/ulw-research/ Acceptance criteria: ls docs/oauth-research/ shows files from .omo/ulw-research/ QA scenarios: Happy: Files present in docs. Failure: Missing files or broken paths. Commit: Y | docs: move OAuth research to docs directory

  • [ ] 14. Final integration QA and security verification What to do / Must NOT do: Run dev server. Execute full OAuth 2.1 flow: register client -> PAR -> authorize (with login/consent) -> token exchange -> introspect -> revoke. Verify discovery metadata matches implementation. Verify no unsupported grants work. Verify no plain PKCE accepted. Verify tokens are opaque (not JWT). Must NOT skip negative testing. Parallelization: Wave 5 | Blocked by: all previous | Blocks: — References: All endpoint files, src/routes/.well-known/oauth-authorization-server/+server.js Acceptance criteria: Full flow completes successfully from register to revoke. QA scenarios: Happy: Complete end-to-end OAuth 2.1 flow. Failure: Unsupported grant returns 400. Plain PKCE rejected. Missing PKCE rejected. Invalid redirect URI rejected. Token stored in Redis (not sqlite3). Commit: Y | test(qa): verify full OAuth 2.1 integration

Final verification wave

Runs in parallel after ALL todos. ALL must APPROVE.

  • F1. Plan compliance audit — Verify every must-have is implemented and every must-not-have is absent
  • F2. Code quality review — Verify Svelte 5 runes, consistent patterns, no hardcoded secrets
  • F3. Real manual QA — Execute full OAuth 2.1 flow end-to-end with curl/httpie
  • F4. Scope fidelity — Confirm no scope creep, no JWTs, no implicit grant, no sqlite3 token storage

Commit strategy

  • One commit per todo (atomic commits)
  • Prefix: feat(config):, feat(redis):, feat(db):, feat(oauth):, feat(ui):, docs:, test(qa):
  • Clear, descriptive messages referencing the component

Success criteria

  1. /.well-known/oauth-authorization-server returns valid RFC 8414 metadata with scopes_supported from DB and ui_locales_supported: ["en-US", "es-MX"]
  2. /oauth/authorize enforces PKCE S256 and exact redirect URI matching
  3. /oauth/token issues opaque tokens stored in Redis with TTL
  4. /oauth/introspect and /oauth/revoke require client authentication
  5. /oauth/par accepts pushed authorization requests and returns request_uri
  6. /oauth/register creates clients in SQLite3 with valid redirect URIs
  7. Login and consent pages render and handle auth flow correctly
  8. No auth codes, access tokens, or refresh tokens exist in SQLite3
  9. Redis is the sole store for all expiring OAuth data
  10. Full end-to-end flow executes successfully from registration to token revocation