epicweb-dev / epicweb-dev/epicflare
Clarify API routing: split /api into /api/internal (cookie) vs /api/public (bearer)
- Dominant language
- TypeScript
- Stars
- 121
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
## Problem
Right now our app mixes multiple auth models (cookie session vs OAuth bearer tokens), but the URL surface area doesn’t make that obvious.
In particular, `/api/*` is currently used for the OAuth provider `apiRoute` (token-protected resource APIs), while our browser-facing JSON endpoints use cookie auth on non-`/api` paths (ex: `/session`, `/auth`, `/logout`, `/chat-agent`). This makes it hard to reason about what belongs in “the API”, what should be CSRF-protected, and which endpoints are intended for 3rd-party / token clients vs same-origin browser clients.
Current examples:
- OAuth protocol endpoints: `/oauth/authorize`, `/oauth/token`, `/oauth/register`, `/oauth/callback`
- OAuth token resource endpoint: `GET /api/me` (handled by OAuth provider `apiRoute`)
- Cookie/session endpoints: `/session`, `/auth`, `/logout`, `/password-reset/*`, `/chat-agent`
- Docs mention `/api/chat`, but code currently routes chat via `/chat-agent`
## Goal
Make endpoint intent + auth requirements obvious from the path so we can:
- Avoid accidental CSRF exposure for cookie-auth JSON endpoints
- Avoid conflating OAuth protocol endpoints with resource APIs
- Set a clear convention for future endpoints (especially chat)
## Proposed Solution
Adopt a consistent API namespace split:
- `/api/internal/*` for same-origin, cookie-session-authenticated endpoints (CSRF-protected as needed)
- `/api/public/*` for bearer-token-authenticated resource endpoints intended for non-browser / 3rd-party clients
Keep OAuth protocol endpoints under `/oauth/*` (authorize/token/register/callback).
## Scope / Tasks
- Decide final routing + naming convention (this issue)
- Update worker routing so OAuth provider `apiRoute` lives at `/api/public/`
- Move (or add) cookie-auth JSON endpoints under `/api/internal/`
- Update any client fetches that should call internal endpoints
- Update docs that reference `/api/chat` to match the chosen route (or implement `/api/public/chat` if that’s the intention)
- Add e2e + unit tests covering:
- internal endpoints require cookie session and are not accidentally bearer-authenticated
- public endpoints require bearer tokens and do not depend on cookies
## Acceptance Criteria
- Every new endpoint clearly falls into either `/api/internal/*` or `/api/public/*`
- `/api/public/*` endpoints are bearer-only (no cookie session assumptions)
- `/api/internal/*` endpoints are cookie-auth only (and have CSRF posture documented/tested)
- Documentation matches the implemented routes
## References
- `worker/index.ts` OAuthProvider is configured with `apiRoute: '/api/'` today
- `worker/oauth-handlers.ts` implements `GET /api/me`
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.