26 KiB
26 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 15-external-authentication | 02 | execute | 2 |
|
|
true |
|
|
Purpose: This is the core auth integration -- replacing GearBox's custom user/session management with Logto OIDC. After this plan, browser users authenticate via Logto, API keys work unchanged, and MCP OAuth coexists cleanly.
Output: Refactored middleware, routes, and services implementing three-way authentication.
<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/15-external-authentication/15-CONTEXT.md @.planning/phases/15-external-authentication/15-RESEARCH.md @.planning/phases/15-external-authentication/15-01-SUMMARY.md @src/server/middleware/auth.ts @src/server/services/auth.service.ts @src/server/routes/auth.ts @src/server/routes/oauth.ts @src/server/mcp/index.ts @src/server/index.ts From src/server/services/auth.service.ts (KEEP these): ```typescript export async function createApiKey(db: Db, name: string): Promise<{...}> export async function verifyApiKey(db: Db, rawKey: string): Promise export async function listApiKeys(db: Db): Promise<{...}[]> export async function deleteApiKey(db: Db, id: number): Promise ```From src/server/services/auth.service.ts (REMOVE these):
export async function createUser(db: Db, username: string, password: string)
export async function verifyPassword(db: Db, username: string, password: string)
export async function getUserCount(db: Db): Promise<number>
export async function changePassword(db: Db, ...)
export async function createSession(db: Db, userId: number, ...)
export async function getSession(db: Db, sessionId: string)
export async function deleteSession(db: Db, sessionId: string)
export async function refreshSession(db: Db, sessionId: string, ...)
From src/server/services/oauth.service.ts (KEEP, used by MCP OAuth):
export async function verifyAccessToken(db: Db, token: string): Promise<boolean>
From @hono/oidc-auth (NEW - to be installed):
import { oidcAuthMiddleware, getAuth, revokeSession, processOAuthCallback } from "@hono/oidc-auth";
// getAuth(c) returns { sub: string, email?: string, ... } | null
// oidcAuthMiddleware() redirects to OIDC provider if no session
// processOAuthCallback(c) handles the /callback redirect
// revokeSession(c) clears the OIDC session
**Rewrite `src/server/services/auth.service.ts`:**
- Remove ALL user management functions: `createUser`, `verifyPassword`, `getUserCount`, `changePassword`
- Remove ALL session management functions: `createSession`, `getSession`, `deleteSession`, `refreshSession`
- Remove imports of `users` and `sessions` from schema
- Remove `count` from drizzle-orm imports (only needed by getUserCount)
- KEEP all API key functions unchanged: `createApiKey`, `verifyApiKey`, `listApiKeys`, `deleteApiKey`
- Keep `randomBytes` import (used by createApiKey)
- Keep `eq` from drizzle-orm (used by API key functions)
- Keep `apiKeys` schema import
- Keep the `Db` type alias
The file should export exactly: `createApiKey`, `verifyApiKey`, `listApiKeys`, `deleteApiKey`.
**Rewrite `src/server/middleware/auth.ts`:**
Per D-04, implement three-way auth check. Replace the entire file with:
```typescript
import type { Context, Next } from "hono";
import { getAuth } from "@hono/oidc-auth";
import { verifyApiKey } from "../services/auth.service";
import { verifyAccessToken } from "../services/oauth.service";
export async function requireAuth(c: Context, next: Next) {
const db = c.get("db");
// 1. Check API key (programmatic access) -- per D-10
const apiKey = c.req.header("X-API-Key");
if (apiKey) {
const valid = await verifyApiKey(db, apiKey);
if (valid) return next();
return c.json({ error: "Invalid API key" }, 401);
}
// 2. Check MCP OAuth Bearer token -- per D-12
const authHeader = c.req.header("Authorization");
if (authHeader?.startsWith("Bearer ")) {
const token = authHeader.slice(7);
if (await verifyAccessToken(db, token)) return next();
return c.json({ error: "invalid_token" }, 401);
}
// 3. Check OIDC session (browser users) -- per D-02
const auth = await getAuth(c);
if (auth) return next();
return c.json({ error: "Authentication required" }, 401);
}
```
Key changes from old middleware:
- Removed `getUserCount` check (Pitfall 5) -- first-run setup happens on Logto admin console
- Removed `getCookie`/`getSession`/`refreshSession` -- replaced by `getAuth()` from @hono/oidc-auth
- Added MCP OAuth Bearer token check (was only in MCP routes, now centralized)
- No `hono/cookie` import needed
Per D-05, D-06, D-07: Replace credential-based auth routes with OIDC redirect flow.
Remove:
- `POST /login` (credential login) -- replaced by OIDC redirect
- `POST /setup` (first-time account creation) -- happens on Logto now per D-06
- `PUT /password` (password change) -- managed by Logto now
- All Zod schemas: `loginSchema`, `setupSchema`, `changePasswordSchema`
- All cookie handling (`COOKIE_NAME`, `COOKIE_MAX_AGE`, `setCookie`, `getCookie`, `deleteCookie`)
- Imports of `users` from schema, `verifyPassword`, `createUser`, `changePassword`, `createSession`, `getSession`, `deleteSession`, `getUserCount`
Keep (with modifications):
- `GET /me` -- rewrite to use `getAuth()` from @hono/oidc-auth
- `GET /keys`, `POST /keys`, `DELETE /keys/:id` -- keep unchanged, still protected by requireAuth
Add:
- `GET /login` -- applies `oidcAuthMiddleware()` which redirects to Logto if no session; if session exists, redirects to `/`
- `GET /callback` -- calls `processOAuthCallback(c)` to handle OIDC redirect back from Logto
- `GET /logout` -- calls `revokeSession(c)` then redirects to `/login`
New file structure:
```typescript
import { zValidator } from "@hono/zod-validator";
import { Hono } from "hono";
import { z } from "zod";
import {
oidcAuthMiddleware,
getAuth,
revokeSession,
processOAuthCallback,
} from "@hono/oidc-auth";
import { parseId } from "../lib/params.ts";
import { requireAuth } from "../middleware/auth.ts";
import {
createApiKey,
deleteApiKey,
listApiKeys,
} from "../services/auth.service.ts";
type Env = { Variables: { db?: any } };
const createKeySchema = z.object({ name: z.string().min(1) });
const app = new Hono<Env>();
// ── OIDC Browser Auth ────────────────────────────────────────────────
// Login: redirect to Logto if not authenticated
app.get("/login", oidcAuthMiddleware(), async (c) => {
// Middleware redirects to Logto if no session. If we reach here, user is authenticated.
return c.redirect("/");
});
// Callback: process OIDC redirect from Logto
app.get("/callback", async (c) => {
return processOAuthCallback(c);
});
// Logout: revoke OIDC session and redirect
app.get("/logout", async (c) => {
await revokeSession(c);
return c.redirect("/login");
});
// ── Auth Status ──────────────────────────────────────────────────────
app.get("/me", async (c) => {
const auth = await getAuth(c);
if (auth) {
return c.json({
user: { id: auth.sub, email: auth.email },
authenticated: true,
});
}
return c.json({ user: null, authenticated: false });
});
// ── API Key Management (protected) ───────────────────────────────────
app.get("/keys", requireAuth, async (c) => {
const db = c.get("db");
const keys = await listApiKeys(db);
return c.json(keys);
});
app.post("/keys", requireAuth, zValidator("json", createKeySchema), async (c) => {
const db = c.get("db");
const { name } = c.req.valid("json");
const result = await createApiKey(db, name);
return c.json({ id: result.id, name: result.name, key: result.rawKey, prefix: result.keyPrefix }, 201);
});
app.delete("/keys/:id", requireAuth, async (c) => {
const db = c.get("db");
const id = parseId(c.req.param("id"));
if (!id) return c.json({ error: "Invalid key ID" }, 400);
await deleteApiKey(db, id);
return c.json({ ok: true });
});
export const authRoutes = app;
```
**Update `src/server/index.ts`:**
The OIDC auth routes (`/login`, `/callback`, `/logout`) need to be accessible at the root level, not under `/api/auth`. But API key routes stay at `/api/auth/keys`.
Changes to index.ts:
1. Add a new top-level route group for OIDC browser auth (login, callback, logout):
```typescript
// OIDC browser auth routes (top-level, not under /api)
app.get("/login", ...); // Delegate to authRoutes
app.get("/callback", ...); // Delegate to authRoutes
app.get("/logout", ...); // Delegate to authRoutes
```
Actually, simpler approach: mount authRoutes at root level for the OIDC routes AND at `/api/auth` for the API routes. But since Hono route() mounts all routes under a prefix, we need to split.
Better approach: Keep authRoutes mounted at `/api/auth` for /me, /keys. Create separate top-level routes for /login, /callback, /logout:
```typescript
import { oidcAuthMiddleware, processOAuthCallback, revokeSession } from "@hono/oidc-auth";
// OIDC browser auth (before /api/* middleware)
app.get("/login", oidcAuthMiddleware(), async (c) => c.redirect("/"));
app.get("/callback", async (c) => processOAuthCallback(c));
app.get("/logout", async (c) => { await revokeSession(c); return c.redirect("/login"); });
```
Then remove the /login, /callback, /logout routes from authRoutes (keep only /me and /keys/* in authRoutes).
2. Place these OIDC routes BEFORE the `/api/*` middleware blocks and BEFORE static file serving
3. Keep `app.route("/api/auth", authRoutes)` for /me and /keys endpoints
4. Ensure the auth middleware skip for `/api/auth` still works (it does -- /api/auth/me is GET, /api/auth/keys POST/DELETE go through requireAuth within the route handler)
So the final authRoutes file should NOT contain /login, /callback, /logout. Those go directly in index.ts. authRoutes contains: GET /me, GET /keys, POST /keys, DELETE /keys/:id.
**IMPORTANT (Pattern 2):** Do NOT apply `oidcAuthMiddleware()` globally. Only apply it to the `/login` route. The `/api/*` routes use the custom `requireAuth` middleware.
**Update `src/server/routes/oauth.ts`:**
1. Remove `import { verifyPassword } from "../services/auth.service.ts"` -- this function no longer exists
2. Add `import { getAuth } from "@hono/oidc-auth"`
3. Replace the `POST /authorize` handler logic:
- Instead of parsing username/password from the form and calling `verifyPassword()`, check for an active OIDC session using `getAuth(c)`
- If the user has a valid OIDC session (`getAuth(c)` returns non-null), proceed with authorization code creation
- If no OIDC session, redirect to `/login` with a return URL that brings them back to the authorize page after Logto login
Updated POST /authorize:
```typescript
oauthRoutes.post("/authorize", async (c) => {
const db = c.get("db") ?? prodDb;
// Check for OIDC session instead of username/password
const auth = await getAuth(c);
if (!auth) {
// No session -- redirect to login, then back to authorize
const currentUrl = c.req.url;
return c.redirect(`/login?redirect=${encodeURIComponent(currentUrl)}`);
}
const body = await c.req.parseBody();
const clientId = body.client_id as string;
const redirectUri = body.redirect_uri as string;
const codeChallenge = body.code_challenge as string;
const codeChallengeMethod = body.code_challenge_method as string;
const state = (body.state as string) ?? "";
const client = await getClient(db, clientId);
if (!client) {
return c.json({ error: "Unknown client_id" }, 400);
}
const allowedUris: string[] = JSON.parse(client.redirectUris);
if (!allowedUris.includes(redirectUri)) {
return c.json({ error: "redirect_uri not allowed" }, 400);
}
const { code } = await createAuthorizationCode(
db,
clientId,
codeChallenge,
codeChallengeMethod,
redirectUri,
);
const url = new URL(redirectUri);
url.searchParams.set("code", code);
if (state) url.searchParams.set("state", state);
return c.redirect(url.toString(), 302);
});
```
4. Update the `GET /authorize` handler to also check for OIDC session:
- If user has OIDC session, show a simplified consent screen (just an "Authorize" button, no login form)
- If no OIDC session, redirect to `/login` with return URL
Replace `renderLoginForm` with a simpler `renderConsentForm` that shows the client name and an "Authorize" button (no username/password fields). The consent form POSTs to `/oauth/authorize` with the hidden fields (client_id, redirect_uri, code_challenge, code_challenge_method, state).
If no OIDC session on GET /authorize, redirect:
```typescript
oauthRoutes.get("/authorize", async (c) => {
const auth = await getAuth(c);
if (!auth) {
return c.redirect(`/login?redirect=${encodeURIComponent(c.req.url)}`);
}
// ... show consent form ...
});
```
5. Keep all other oauth routes unchanged: POST /register, POST /token, well-known endpoints
**Update `src/server/mcp/index.ts`:**
Per Pitfall 5, remove the `getUserCount` check from MCP auth middleware.
1. Remove `import { getUserCount } from "../services/auth.service.ts"` (only keep `verifyApiKey`)
2. Remove the `if (getUserCount(db) <= 0) { return next(); }` block
3. The MCP auth middleware should now only check Bearer token and API key -- no "skip if no users" bypass
Updated MCP auth middleware:
```typescript
mcpRoutes.use("/*", async (c, next) => {
const db = c.get("db") ?? prodDb;
// Try Bearer token first (OAuth)
const authHeader = c.req.header("Authorization");
if (authHeader?.startsWith("Bearer ")) {
const token = authHeader.slice(7);
if (await verifyAccessToken(db, token)) {
return next();
}
return c.json({ error: "invalid_token" }, 401);
}
// Try API key
const apiKey = c.req.header("X-API-Key");
if (apiKey) {
const valid = await verifyApiKey(db, apiKey);
if (valid) {
return next();
}
return c.json({ error: "Invalid API key" }, 401);
}
// No auth provided
const baseUrl = (process.env.GEARBOX_URL || new URL(c.req.url).origin).replace(/\/$/, "");
return c.text("Unauthorized", 401, {
"WWW-Authenticate": `Bearer resource_metadata="${baseUrl}/.well-known/oauth-protected-resource"`,
});
});
```
<success_criteria>
- Three-way auth middleware works: API key, MCP Bearer, OIDC session
- Browser auth flow: /login redirects to Logto, /callback processes return, /logout clears session
- /api/auth/me returns OIDC user identity or null
- API key CRUD at /api/auth/keys preserved and functional
- MCP OAuth authorize uses OIDC session instead of removed password verification
- MCP auth middleware has no getUserCount bypass
- No references to removed user/session functions anywhere in src/server/
- TypeScript compiles cleanly </success_criteria>