From b4aaf9712f868699f8b58bd8d8173dcaef74f2a3 Mon Sep 17 00:00:00 2001 From: Christian Pojoni <34570565+5queezer@users.noreply.github.com> Date: Tue, 24 Mar 2026 11:03:56 +0100 Subject: [PATCH] feat(mcp): add OAuth 2.1 for claude.ai MCP connector (#2829) * feat(mcp): add OAuth 2.1 authentication for claude.ai MCP connector Enable OAuth 2.1 (RFC 8414 + RFC 7591) for the MCP endpoint using better-auth's MCP plugin. This allows claude.ai and other MCP clients to authenticate via Dynamic Client Registration and Authorization Code flow with PKCE, using the existing login page. - Add `mcp()` plugin to better-auth config with login page redirect - Add `.well-known/oauth-authorization-server` discovery endpoint - Add `.well-known/oauth-protected-resource` metadata endpoint - Update MCP handler to accept Bearer tokens via `getMcpSession` - Retain `x-api-key` fallback for backward compatibility - Return proper HTTP 401 + WWW-Authenticate header for unauthed requests - Add `oauthApplication`, `oauthAccessToken`, `oauthConsent` tables Co-Authored-By: Claude Opus 4.6 (1M context) * fix(mcp): use typed AuthError and suppress noisy verifyApiKey throws - Replace string-matching error detection with instanceof AuthError - Wrap verifyApiKey in try-catch to avoid logging malformed key errors - Move console.error below auth check so 401s don't pollute logs Co-Authored-By: Claude Opus 4.6 (1M context) * feat(mcp): add database migration for OAuth tables Creates oauth_application, oauth_access_token, and oauth_consent tables required for MCP OAuth 2.1 Dynamic Client Registration flow. Co-Authored-By: Claude Opus 4.6 (1M context) * fix(mcp): resolve OAuth Bearer token auth for oRPC tool calls The oRPC context only checked session cookies and API keys, causing MCP tool calls from OAuth clients (claude.ai) to fail with Unauthorized even though the MCP endpoint itself authenticated successfully. Co-Authored-By: Claude Opus 4.6 (1M context) * fix(mcp): look up user by userId from OAuth access token getMcpSession returns OAuthAccessToken (with userId), not a session object with a user property. Must query the user table by userId. Co-Authored-By: Claude Opus 4.6 (1M context) * refactor(mcp): migrate from deprecated mcp() plugin to @better-auth/oauth-provider The better-auth MCP plugin is marked for deprecation in favor of the OAuth Provider plugin. This refactors the entire OAuth 2.1 flow to use @better-auth/oauth-provider with JWT-based token verification, replacing the opaque token lookup via getMcpSession(). Key changes: - Replace mcp() with jwt() + oauthProvider() in auth config - Replace getMcpSession() with verifyAccessToken() (JWT/JWKS) - Replace oauthApplication table with oauthClient (RFC 7591 compliant) - Add oauthRefreshToken table and jwks table for JWT signing keys - Extract shared authBaseUrl and verifyOAuthToken helper - Hoist McpServer to module scope (avoid per-request reconstruction) - Update .well-known discovery endpoints for OAuth Provider Co-Authored-By: Claude Opus 4.6 (1M context) * fix(mcp): resolve OAuth 2.1 flow for claude.ai MCP connector Multiple fixes required to make the full MCP OAuth flow work with claude.ai's implementation: - Add RFC 8414 discovery route at /.well-known/oauth-authorization-server/api/auth (claude.ai appends the issuer path per spec) - Add /auth/oauth server route to handle login/consent flow (generates auth codes directly, bypassing h3 cookie issues) - Default token_endpoint_auth_method to "none" via onRequest plugin hook (claude.ai omits this field, causing confidential client rejection) - Strip prompt=consent from authorize requests via onRequest hook (better-auth checks prompt before skipConsent, causing redirect loops) - Add validAudiences for MCP resource URL (JWT aud claim contains the MCP URL, not the base URL) - Disable CSRF check for cross-origin OAuth flows - Log token endpoint errors for debugging - Set skipConsent on OAuth clients via /auth/oauth route Co-Authored-By: Claude Opus 4.6 (1M context) * fix(mcp): harden OAuth security and enforce lock on delete - Scope CSRF bypass to OAuth2 paths only instead of disabling globally - Validate redirect_uri against registered client URIs (prevents code interception) - Use pathname matching instead of fragile url.includes() for route guards - Replace biased modulo code generation with crypto.randomBytes - Enforce resume lock check on delete (previously silently ignored) - Remove debug console.error logging of OAuth token response bodies - Use Response.json() consistently for MCP 401 response Co-Authored-By: Claude Opus 4.6 (1M context) * Update dependencies, refine ignore patterns, and enhance documentation - Updated various dependencies in package.json and pnpm-lock.yaml for improved stability and features. - Adjusted ignore patterns in knip.json to include specific component directories. - Enhanced documentation for the MCP server, clarifying authentication methods and configuration options. - Made minor adjustments to VSCode settings for better code organization. * fix(mcp): resolve OAuth client registration and stale token handling Claude.ai sends token_endpoint_auth_method: "client_secret_post" without a client_secret during Dynamic Client Registration, causing Better Auth to reject it as an unauthenticated confidential client. Force to "none" for unauthenticated registrations. Also catch JWKS verification errors (e.g. key rotation after redeployment) so stale Bearer tokens return 401 instead of 200 with an error body, allowing clients to re-initiate the OAuth flow. Co-Authored-By: Claude Opus 4.6 (1M context) * reiterate on tests --------- Co-authored-by: Claude Opus 4.6 (1M context) Co-authored-by: Amruth Pillai --- .github/workflows/autofix.yml | 4 +- .gitignore | 1 + .vscode/settings.json | 1 + AGENTS.md | 185 +- docs/guides/using-the-mcp-server.mdx | 138 +- knip.json | 2 +- locales/af-ZA.po | 33 - locales/am-ET.po | 33 - locales/ar-SA.po | 33 - locales/az-AZ.po | 33 - locales/bg-BG.po | 33 - locales/bn-BD.po | 33 - locales/ca-ES.po | 33 - locales/cs-CZ.po | 33 - locales/da-DK.po | 33 - locales/de-DE.po | 33 - locales/el-GR.po | 33 - locales/en-GB.po | 33 - locales/en-US.po | 32 - locales/es-ES.po | 33 - locales/fa-IR.po | 33 - locales/fi-FI.po | 33 - locales/fr-FR.po | 33 - locales/he-IL.po | 33 - locales/hi-IN.po | 33 - locales/hu-HU.po | 33 - locales/id-ID.po | 33 - locales/it-IT.po | 33 - locales/ja-JP.po | 33 - locales/km-KH.po | 33 - locales/kn-IN.po | 33 - locales/ko-KR.po | 33 - locales/lt-LT.po | 33 - locales/lv-LV.po | 33 - locales/ml-IN.po | 33 - locales/mr-IN.po | 33 - locales/ms-MY.po | 33 - locales/ne-NP.po | 33 - locales/nl-NL.po | 33 - locales/no-NO.po | 33 - locales/or-IN.po | 33 - locales/pl-PL.po | 33 - locales/pt-BR.po | 33 - locales/pt-PT.po | 33 - locales/ro-RO.po | 33 - locales/ru-RU.po | 33 - locales/sk-SK.po | 33 - locales/sl-SI.po | 33 - locales/sq-AL.po | 33 - locales/sr-SP.po | 33 - locales/sv-SE.po | 33 - locales/ta-IN.po | 33 - locales/te-IN.po | 33 - locales/th-TH.po | 33 - locales/tr-TR.po | 33 - locales/uk-UA.po | 33 - locales/uz-UZ.po | 33 - locales/vi-VN.po | 33 - locales/zh-CN.po | 33 - locales/zh-TW.po | 33 - locales/zu-ZA.po | 32 - .../migration.sql | 92 + .../snapshot.json | 3049 +++++++++++++++++ package.json | 53 +- pnpm-lock.yaml | 1404 ++++---- src/components/ai/chat.tsx | 422 --- .../input/visually-hidden-input.tsx | 138 - src/components/level/combobox.tsx | 2 +- src/components/ui/badge.tsx | 2 +- src/components/ui/button-group.tsx | 2 +- src/components/ui/combobox.tsx | 8 +- src/components/ui/tabs.tsx | 2 +- src/components/ui/toggle.tsx | 2 +- src/integrations/auth/client.ts | 4 + src/integrations/auth/config.ts | 34 +- src/integrations/drizzle/schema.ts | 209 +- src/integrations/jobs/factory.test.ts | 29 - .../jobs/providers/jsearch.test.ts | 2 +- src/integrations/orpc/context.ts | 21 +- src/integrations/orpc/services/jobs.test.ts | 2 +- src/integrations/orpc/services/resume.ts | 8 + src/routeTree.gen.ts | 159 + src/routes/$username/$slug.tsx | 3 - .../oauth-authorization-server.$.ts | 14 + .../oauth-authorization-server.ts | 14 + .../oauth-protected-resource.$.ts | 25 + .../[.]well-known/oauth-protected-resource.ts | 25 + .../[.]well-known/openid-configuration.ts | 14 + src/routes/api/auth.$.ts | 77 +- src/routes/auth/oauth.ts | 103 + .../builder/$resumeId/-components/dock.tsx | 2 - .../-components/search-filters.test.ts | 2 +- src/routes/mcp/index.ts | 51 +- src/schema/jobs.test.ts | 2 +- src/utils/color.test.ts | 41 + src/utils/file.test.ts | 20 +- src/utils/locale.test.ts | 38 + src/utils/resume/docx/builder.test.ts | 4 +- src/utils/resume/docx/html-to-docx.test.ts | 4 +- src/utils/resume/tailor.test.ts | 2 +- src/utils/sanitize.test.ts | 89 + src/utils/string.test.ts | 72 + vite.config.ts | 5 + 103 files changed, 5221 insertions(+), 3174 deletions(-) create mode 100644 migrations/20260323204916_strange_the_order/migration.sql create mode 100644 migrations/20260323204916_strange_the_order/snapshot.json delete mode 100644 src/components/ai/chat.tsx delete mode 100644 src/components/input/visually-hidden-input.tsx delete mode 100644 src/integrations/jobs/factory.test.ts create mode 100644 src/routes/[.]well-known/oauth-authorization-server.$.ts create mode 100644 src/routes/[.]well-known/oauth-authorization-server.ts create mode 100644 src/routes/[.]well-known/oauth-protected-resource.$.ts create mode 100644 src/routes/[.]well-known/oauth-protected-resource.ts create mode 100644 src/routes/[.]well-known/openid-configuration.ts create mode 100644 src/routes/auth/oauth.ts create mode 100644 src/utils/color.test.ts create mode 100644 src/utils/locale.test.ts create mode 100644 src/utils/sanitize.test.ts create mode 100644 src/utils/string.test.ts diff --git a/.github/workflows/autofix.yml b/.github/workflows/autofix.yml index 953980b3a..751ccad27 100644 --- a/.github/workflows/autofix.yml +++ b/.github/workflows/autofix.yml @@ -22,7 +22,7 @@ jobs: - run: vp install - - run: vp fmt - - run: vp lint --fix + - run: vp test + - run: vp check --fix - uses: autofix-ci/action@7a166d7532b277f34e16238930461bf77f9d7ed8 diff --git a/.gitignore b/.gitignore index 31a64b97e..a30d18add 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ dist .output .vercel .cursor +.claude TODO.md coverage .netlify diff --git a/.vscode/settings.json b/.vscode/settings.json index 4df46df87..024298fdf 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -3,6 +3,7 @@ "editor.defaultFormatter": "oxc.oxc-vscode" }, "editor.codeActionsOnSave": { + "source.organizeImports": "explicit", "source.fixAll.oxc": "explicit" }, "editor.defaultFormatter": "oxc.oxc-vscode", diff --git a/AGENTS.md b/AGENTS.md index 6403965c5..12a582364 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,71 @@ # AGENTS.md -## Cursor Cloud specific instructions +## Overview -### Overview +Reactive Resume is a single-package full-stack TypeScript app (not a monorepo) built with [TanStack Start](https://tanstack.com/start/latest/docs/framework/react/overview) (React, Vite, Nitro). It serves both frontend and API on port 3000. -Reactive Resume is a single-package full-stack TypeScript app (not a monorepo) built with TanStack Start (React 19, Vite, Nitro). It serves both frontend and API on port 3000. +This project uses [Vite+](https://vite.dev/blog/announcing-viteplus), a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. All modules should be imported from the `vite-plus` dependency (e.g., `import { defineConfig } from 'vite-plus'` or `import { expect, test, vi } from 'vite-plus/test'`). -### Infrastructure services +## Key Libraries + +| Area | Library | Docs | +| -------------------- | ------------------------------------------------------------------------ | ---------------------------------- | +| Frontend framework | React | https://react.dev | +| Full-stack framework | TanStack Start | https://tanstack.com/start/latest | +| Router | TanStack React Router | https://tanstack.com/router/latest | +| Server state | TanStack React Query | https://tanstack.com/query/latest | +| Client state | Zustand (+ Zundo for undo/redo, Immer for immutable updates) | https://zustand.docs.pmnd.rs | +| Type-safe API | oRPC | https://orpc.unnoq.com | +| Database ORM | Drizzle ORM (PostgreSQL) | https://orm.drizzle.team | +| Authentication | Better Auth (+ Drizzle adapter, OAuth provider, API keys, 2FA, Passkeys) | https://www.better-auth.com | +| Styling | Tailwind CSS | https://tailwindcss.com | +| UI Components | shadcn/ui (built on Base UI) | https://ui.shadcn.com | +| Icons | Phosphor Icons | https://phosphoricons.com | +| Forms | React Hook Form (+ Zod resolvers) | https://react-hook-form.com | +| Rich text editor | Tiptap | https://tiptap.dev | +| Validation | Zod | https://zod.dev | +| AI | Vercel AI SDK (OpenAI, Anthropic, Google, Ollama providers) | https://ai-sdk.dev | +| MCP | Model Context Protocol SDK | https://modelcontextprotocol.io | +| i18n | Lingui | https://lingui.dev | +| Animations | Motion (Framer Motion) | https://motion.dev | +| PDF export | Puppeteer Core (via Browserless) | https://pptr.dev | +| Drag and drop | dnd-kit | https://dndkit.com | +| Server engine | Nitro | https://nitro.build | +| PWA | Vite PWA Plugin | https://vite-pwa-org.netlify.app | +| Unused deps | Knip | https://knip.dev | + +## Project Structure + +``` +src/ + components/ UI, resume, layout, animation, theme, locale components + routes/ File-based routing (TanStack React Router) + integrations/ Feature modules (auth, drizzle, orpc, ai, email, jobs, mcp, storage) + schema/ Zod schemas for resume data validation + utils/ Utility functions (locale, theme, env, resume processing) + dialogs/ Modal/dialog components + hooks/ Custom React hooks + styles/ CSS and Tailwind configuration + stores/ Zustand stores (resume, AI, dialog, command palette) +migrations/ Drizzle database migrations +locales/ Lingui i18n message catalogs (47+ locales) +``` + +### Key Config Files + +- `vite.config.ts` — Vite + Nitro + TanStack Start + PWA + Tailwind + Lingui +- `drizzle.config.ts` — PostgreSQL dialect, schema at `./src/integrations/drizzle/schema.ts` +- `tsconfig.json` — ES2022, strict mode, path alias `@/*` → `./src/*` +- `lingui.config.ts` — i18n extraction and locale configuration +- `components.json` — shadcn CLI configuration + +### API Architecture + +- **oRPC API** (`/api/rpc/*`) — Type-safe RPC with routers for: `ai`, `auth`, `resume`, `storage`, `printer`, `jobs`, `statistics`, `flags`. Three procedure types: `publicProcedure`, `protectedProcedure`, `serverOnlyProcedure`. +- **Better Auth API** (`/api/auth/*`) — OAuth, session management, social provider callbacks. +- **MCP Server** (`/mcp/`) — Model Context Protocol with OAuth Bearer tokens and API key auth. Exposes resumes as resources and tools for resume CRUD. + +## Infrastructure Services Before running the dev server, Docker must be running with at least PostgreSQL. Start services via `compose.dev.yml`: @@ -18,7 +77,7 @@ sudo docker compose -f compose.dev.yml up -d postgres browserless - **PostgreSQL** (port 5432) — required. The app auto-runs Drizzle migrations on startup via a Nitro plugin. - **Browserless** (port 4000) — required for PDF export. Maps container port 3000 to host port 4000. -### Environment variables +## Environment Variables Copy `.env.example` to `.env` if not present. Key notes for local dev: @@ -28,99 +87,47 @@ Copy `.env.example` to `.env` if not present. Key notes for local dev: - `DATABASE_URL` — PostgreSQL connection using `postgres:postgres` credentials on localhost:5432. - S3/Storage and SMTP vars can be left empty — the app falls back to local filesystem and console-logged emails. -### Common commands +## Common Commands -See `scripts` in `package.json`. Key ones: +`vp` is the global CLI for Vite+. Do not use pnpm/npm/yarn directly — Vite+ wraps the underlying package manager. -| Task | Command | -| -------------- | --------------------------------------------------------------- | -| Dev server | `pnpm dev` (port 3000) | -| Lint (Oxlint) | `pnpm lint` | -| Format (Oxfmt) | `pnpm fmt` | -| Typecheck | `pnpm typecheck` | -| DB migrations | `pnpm db:generate` / `pnpm db:migrate` (auto-runs on dev start) | +| Task | Command | +| -------------------------- | --------------------------------------------------------------- | +| Install dependencies | `vp install` | +| Dev server (port 3000) | `vp dev` | +| Lint (Oxlint, type-aware) | `vp lint --type-aware` | +| Format (Oxfmt) | `vp fmt` | +| Check (lint + fmt + types) | `vp check` | +| Typecheck | `pnpm typecheck` (uses tsgo) | +| Run tests | `vp test` | +| DB migrations | `pnpm db:generate` / `pnpm db:migrate` (auto-runs on dev start) | +| DB studio | `pnpm db:studio` | +| i18n extraction | `pnpm lingui:extract` | +| Add a dependency | `vp add ` | +| Remove a dependency | `vp remove ` | +| One-off binary | `vp dlx ` | +| Build for production | `vp build` | +| Preview production build | `vp preview` | +| Start production server | `pnpm start` | -### Gotchas +## Vite+ Pitfalls + +- **Do not use pnpm/npm/yarn directly** for package operations — use `vp add`, `vp remove`, `vp install`, etc. +- **Do not run `vp vitest` or `vp oxlint`** — they don't exist. Use `vp test` and `vp lint`. +- **Do not install Vitest, Oxlint, Oxfmt, or tsdown directly** — Vite+ bundles them. +- **Import from `vite-plus`**, not from `vite` or `vitest` directly (e.g., `import { defineConfig } from 'vite-plus'`). +- **Vite+ commands take precedence** over `package.json` scripts. If there's a naming conflict, use `vp run ')).toBe(""); + }); + + it("should strip event handlers", () => { + expect(sanitizeHtml('')).toBe(""); + }); + + it("should allow links with href", () => { + const html = 'link'; + expect(sanitizeHtml(html)).toContain('href="https://example.com"'); + }); + + it("should strip javascript: hrefs", () => { + const result = sanitizeHtml('click'); + expect(result).not.toContain("javascript:"); + }); + + it("should allow list elements", () => { + const html = "
  • one
  • two
"; + expect(sanitizeHtml(html)).toBe(html); + }); + + it("should allow table elements", () => { + const html = "
cell
"; + expect(sanitizeHtml(html)).toContain(""); + }); +}); + +describe("sanitizeCss", () => { + it("should return empty string for empty input", () => { + expect(sanitizeCss("")).toBe(""); + }); + + it("should pass through normal CSS", () => { + expect(sanitizeCss("color: red;")).toBe("color: red;"); + }); + + it("should strip javascript: expressions", () => { + expect(sanitizeCss("background: javascript:alert(1)")).not.toContain("javascript:"); + }); + + it("should strip expression() calls", () => { + expect(sanitizeCss("width: expression(alert(1))")).not.toContain("expression("); + }); + + it("should strip behavior: property", () => { + expect(sanitizeCss("behavior: url(evil.htc)")).not.toContain("behavior:"); + }); + + it("should strip -moz-binding", () => { + expect(sanitizeCss("-moz-binding: url(evil.xml)")).not.toContain("-moz-binding:"); + }); +}); + +describe("isObject", () => { + it("should return true for plain objects", () => { + expect(isObject({})).toBe(true); + expect(isObject({ a: 1 })).toBe(true); + }); + + it("should return false for arrays", () => { + expect(isObject([])).toBe(false); + }); + + it("should return false for null", () => { + expect(isObject(null)).toBe(false); + }); + + it("should return false for primitives", () => { + expect(isObject("string")).toBe(false); + expect(isObject(42)).toBe(false); + expect(isObject(undefined)).toBe(false); + }); +}); diff --git a/src/utils/string.test.ts b/src/utils/string.test.ts new file mode 100644 index 000000000..694fbd050 --- /dev/null +++ b/src/utils/string.test.ts @@ -0,0 +1,72 @@ +import { describe, expect, it } from "vite-plus/test"; + +import { getInitials, slugify, stripHtml, toUsername } from "./string"; + +describe("slugify", () => { + it("should lowercase and hyphenate spaces", () => { + expect(slugify("Hello World")).toBe("hello-world"); + }); + + it("should strip special characters", () => { + expect(slugify("Résumé & CV!")).toBe("resume-and-cv"); + }); + + it("should not decamelize camelCase strings", () => { + expect(slugify("camelCase")).toBe("camelcase"); + }); + + it("should return empty string for empty input", () => { + expect(slugify("")).toBe(""); + }); +}); + +describe("getInitials", () => { + it("should return up to two uppercase initials", () => { + expect(getInitials("John Doe")).toBe("JD"); + }); + + it("should return one initial for a single name", () => { + expect(getInitials("Alice")).toBe("A"); + }); + + it("should take only the first two words", () => { + expect(getInitials("John Michael Doe")).toBe("JM"); + }); +}); + +describe("toUsername", () => { + it("should lowercase and strip disallowed characters", () => { + expect(toUsername("John Doe!")).toBe("johndoe"); + }); + + it("should keep dots, hyphens, and underscores", () => { + expect(toUsername("john.doe-name_ok")).toBe("john.doe-name_ok"); + }); + + it("should trim whitespace", () => { + expect(toUsername(" alice ")).toBe("alice"); + }); + + it("should truncate to 64 characters", () => { + const long = "a".repeat(100); + expect(toUsername(long)).toHaveLength(64); + }); +}); + +describe("stripHtml", () => { + it("should remove HTML tags and trim", () => { + expect(stripHtml("

Hello World

")).toBe("Hello World"); + }); + + it("should return empty string for undefined", () => { + expect(stripHtml(undefined)).toBe(""); + }); + + it("should return empty string for empty string", () => { + expect(stripHtml("")).toBe(""); + }); + + it("should handle nested tags", () => { + expect(stripHtml("
  • item
")).toBe("item"); + }); +}); diff --git a/vite.config.ts b/vite.config.ts index 877803658..9e08775a1 100644 --- a/vite.config.ts +++ b/vite.config.ts @@ -222,6 +222,11 @@ const config = defineConfig({ tsconfigPaths: true, }, + test: { + environment: "jsdom", + reporters: process.env.GITHUB_ACTIONS ? ["github-actions"] : ["dot"], + }, + build: { sourcemap: true, chunkSizeWarningLimit: 10 * 1024, // 10mb