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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* reiterate on tests

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Amruth Pillai <im.amruth@gmail.com>

src/utils/color.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { parseColorString } from "./color";
+
+describe("parseColorString", () => {
+  it("should parse a 6-digit hex color", () => {
+    expect(parseColorString("#ff8800")).toEqual({ r: 255, g: 136, b: 0, a: 1 });
+  });
+
+  it("should parse a 3-digit hex color", () => {
+    expect(parseColorString("#f80")).toEqual({ r: 255, g: 136, b: 0, a: 1 });
+  });
+
+  it("should be case-insensitive for hex", () => {
+    expect(parseColorString("#FF8800")).toEqual(parseColorString("#ff8800"));
+  });
+
+  it("should parse rgb()", () => {
+    expect(parseColorString("rgb(10, 20, 30)")).toEqual({ r: 10, g: 20, b: 30, a: 1 });
+  });
+
+  it("should parse rgba() with alpha", () => {
+    expect(parseColorString("rgba(10, 20, 30, 0.5)")).toEqual({ r: 10, g: 20, b: 30, a: 0.5 });
+  });
+
+  it("should handle whitespace around the value", () => {
+    expect(parseColorString("  #000000  ")).toEqual({ r: 0, g: 0, b: 0, a: 1 });
+  });
+
+  it("should return null for invalid input", () => {
+    expect(parseColorString("not-a-color")).toBeNull();
+  });
+
+  it("should return null for empty string", () => {
+    expect(parseColorString("")).toBeNull();
+  });
+
+  it("should return null for incomplete hex", () => {
+    expect(parseColorString("#ff")).toBeNull();
+  });
+});

src/utils/file.test.ts

@@ -1,31 +1,23 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it } from "vite-plus/test";
 
 import { generateFilename } from "./file";
 
 describe("generateFilename", () => {
-  it("should return name with extension", () => {
+  it("should slugify the prefix and append the extension", () => {
     expect(generateFilename("My Resume", "docx")).toBe("my-resume.docx");
   });
 
-  it("should return name without extension when none provided", () => {
+  it("should return slugified name without extension when none provided", () => {
     expect(generateFilename("My Resume")).toBe("my-resume");
   });
 
-  it("should preserve the exact resume name with special characters", () => {
-    expect(generateFilename("John Doe - CS Base - Program Coordinator", "docx")).toBe(
-      "john-doe-cs-base-program-coordinator.docx",
-    );
-  });
-
-  it("should work with pdf extension", () => {
+  it("should handle special characters in the prefix", () => {
     expect(generateFilename("John Doe - CS Base - Program Coordinator", "pdf")).toBe(
       "john-doe-cs-base-program-coordinator.pdf",
     );
   });
 
-  it("should work with json extension", () => {
-    expect(generateFilename("John Doe - CS Base - Program Coordinator", "json")).toBe(
-      "john-doe-cs-base-program-coordinator.json",
-    );
+  it("should handle empty prefix", () => {
+    expect(generateFilename("", "pdf")).toBe(".pdf");
   });
 });

src/utils/locale.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+
+// Mock @lingui/core/macro since the `msg` macro requires babel transformation
+vi.mock("@lingui/core/macro", () => ({
+  msg: (strings: TemplateStringsArray) => ({ id: strings[0] }),
+}));
+
+// Import after mock setup
+const { isLocale, isRTL } = await import("./locale");
+
+describe("isLocale", () => {
+  it("should return true for valid locales", () => {
+    expect(isLocale("en-US")).toBe(true);
+    expect(isLocale("fr-FR")).toBe(true);
+    expect(isLocale("zh-CN")).toBe(true);
+  });
+
+  it("should return false for invalid locales", () => {
+    expect(isLocale("xx-YY")).toBe(false);
+    expect(isLocale("english")).toBe(false);
+    expect(isLocale("")).toBe(false);
+  });
+});
+
+describe("isRTL", () => {
+  it("should return true for RTL languages", () => {
+    expect(isRTL("ar-SA")).toBe(true);
+    expect(isRTL("he-IL")).toBe(true);
+    expect(isRTL("fa-IR")).toBe(true);
+    expect(isRTL("ur-PK")).toBe(true);
+  });
+
+  it("should return false for LTR languages", () => {
+    expect(isRTL("en-US")).toBe(false);
+    expect(isRTL("fr-FR")).toBe(false);
+    expect(isRTL("zh-CN")).toBe(false);
+  });
+});

src/utils/resume/docx/builder.test.ts

@@ -1,7 +1,5 @@
-// @vitest-environment jsdom
-
 import { Document } from "docx";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it } from "vite-plus/test";
 
 import type { ResumeData } from "@/schema/resume/data";
 

src/utils/resume/docx/html-to-docx.test.ts

@@ -1,7 +1,5 @@
-// @vitest-environment jsdom
-
 import { ExternalHyperlink, Paragraph, TextRun } from "docx";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it } from "vite-plus/test";
 
 import { htmlToParagraphs } from "./html-to-docx";
 

src/utils/resume/tailor.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it } from "vite-plus/test";
 
 import type { ResumeData } from "@/schema/resume/data";
 import type { TailorOutput } from "@/schema/tailor";

src/utils/sanitize.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { isObject, sanitizeCss, sanitizeHtml } from "./sanitize";
+
+describe("sanitizeHtml", () => {
+  it("should return empty string for empty input", () => {
+    expect(sanitizeHtml("")).toBe("");
+  });
+
+  it("should allow safe tags", () => {
+    const html = "<p>Hello <strong>World</strong></p>";
+    expect(sanitizeHtml(html)).toBe(html);
+  });
+
+  it("should strip script tags", () => {
+    expect(sanitizeHtml('<script>alert("xss")</script>')).toBe("");
+  });
+
+  it("should strip event handlers", () => {
+    expect(sanitizeHtml('<img onerror="alert(1)" src="x">')).toBe("");
+  });
+
+  it("should allow links with href", () => {
+    const html = '<a href="https://example.com">link</a>';
+    expect(sanitizeHtml(html)).toContain('href="https://example.com"');
+  });
+
+  it("should strip javascript: hrefs", () => {
+    const result = sanitizeHtml('<a href="javascript:alert(1)">click</a>');
+    expect(result).not.toContain("javascript:");
+  });
+
+  it("should allow list elements", () => {
+    const html = "<ul><li>one</li><li>two</li></ul>";
+    expect(sanitizeHtml(html)).toBe(html);
+  });
+
+  it("should allow table elements", () => {
+    const html = "<table><tr><td>cell</td></tr></table>";
+    expect(sanitizeHtml(html)).toContain("<table>");
+  });
+});
+
+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);
+  });
+});

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("<p>Hello <b>World</b></p>")).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("<div><ul><li>item</li></ul></div>")).toBe("item");
+  });
+});