OAuth provider for first-party apps (Mindmap first)

[nhyiramante1]

Summary

Makes the backend an OAuth 2.1 provider for first-party apps: Better Auth's oauthProvider issues tokens under /api/auth/oauth2/*, and the OpenAI proxy is the resource server that accepts them. The first and only client is the standalone Mindmap (https://mindmap.thoughtful-ai.com), which can then make AI calls billed to the signed-in user.

Mindmap's side lives in AIToolsLab/mindmap. Mindmap gets no document access: users paste text in by hand. The only capability granted is openai:chat. See docs/oauth-provider.md.

This is not a port of #594. It keeps only the generic OAuth pieces, and the room model is not carried over.

What it does

• Adds @better-auth/oauth-provider 1.6.22 plus jwt().
• Authorization code + PKCE (S256) only. Exact redirect URI match, 12-hour JWT access tokens, no refresh tokens. Consent is skipped for this first-party client only.
• One fixed public client, configured by MINDMAP_OAUTH_CLIENT_ID / MINDMAP_OAUTH_REDIRECT_URIS and provisioned idempotently through Better Auth's adapter when the server starts. There's no secret and no code defaults (scripts/get_env.py supplies the dev values).
• The OpenAI proxy (/api/openai/chat/completions and /api/openai/responses) accepts the client's bearer token. It checks the token in-process (auth.api.verifyJWT against the jwt plugin's keys in our database, with no HTTP fetch of our own JWKS):
  • signature, expiry, issuer <origin>/api/auth, and audience = the backend origin (via RFC 8707 resource);
  • scope openai:chat, and azp must be a configured client;
  • session liveness: the session named by sid, which authorized the token, must still exist, be unexpired, and belong to sub. Signing out in the browser that did the Mindmap login therefore revokes the token straight away.
• OAuth tokens are accepted only by the proxy, never by the shared resolveUser, so they can't reach logging, consent, erasure, Realtime or /api/handoff. A presented bearer authenticates only that bearer, never a co-sent cookie session.
• 401 vs 403:
  • An invalid, expired, revoked or foreign token gets 401. It never falls through to the demo key or a cookie session.
  • A valid token for an account outside the beta allowlist gets 403, checked before any spend.
  • Both carry X-Writing-Tools-Error: platform-auth, which CORS exposes.
• Client management is closed. Registration flags alone only close /oauth2/register. The plugin also exposes session-authenticated create-client / update-client / delete-client / get-clients / rotate-secret, so clientPrivileges: () => false denies them.

Deployment

• Safe to merge before infra changes. Both Mindmap variables are optional. If either is unset, the server logs a warning, provisions nothing, and accepts no OAuth tokens; everything else runs normally.

• To enable Mindmap in prod, add to the app container in the k8s helm chart (Infrastructure_k8s_thoughtfulai, thoughtfulai-app values):

  • MINDMAP_OAUTH_CLIENT_ID=writing-tools-mindmap
  • MINDMAP_OAUTH_REDIRECT_URIS=https://mindmap.thoughtful-ai.com/

  Only the main container needs these; the migrate-auth initContainer no longer provisions clients. Staging doesn't need them.

• BETTER_AUTH_URL must be the origin the Mindmap bundle targets (https://app.thoughtful-ai.com, which the chart already sets). Issuer and audience checks compare against it exactly.

• Emergency cut-off: unset the variables and redeploy. Every Mindmap token is then rejected, since tokens aren't stored and the proxy only accepts configured clients.

Dependency note

The rebase onto main conflicted with the @hono/node-server v2 bump; resolved by keeping both. npm then wanted @better-auth/core 1.7.6 to satisfy the new plugin's peer range, which clashes with the pinned better-auth 1.6.22. The plugin's lockfile entry was carried over from the pre-rebase commit, where it resolved against 1.6.22. npm ci accepts it, and there is a single deduplicated @better-auth/core@1.6.22.

npm audit reports 5 advisories. Four (hono, vitest, nanoid via vitest) come from main, not this PR. The fifth is on the new plugin: GHSA-p2fr-6hmx-4528. The token endpoint lets a client choose any allow-listed resource, even one it wasn't authorized for. The 1.6.x line won't be patched; the fix is in 1.7.x, a breaking change with a schema migration. This deployment isn't exposed: it matches the advisory's workarounds exactly. validAudiences has a single entry, and our guard requires exactly one resource equal to the origin at the token endpoint. There are no refresh tokens, and the proxy accepts only that one audience. Worth upgrading when we move to better-auth 1.7.

Tests

npx tsc --noEmit is clean, and npx vitest run passes 131/131, run outside a directory with a local backend/.env (a real key there overrides the test env; being fixed separately). The integration suite (oauth-provider.integration.test.ts) runs the production verification path, and covers:

• the full login round trip, with the resulting token accepted by both proxies
• a byte-exact resource on both the authorize and token requests
• missing PKCE, a wrong PKCE verifier, wrong redirect URIs and unknown clients are refused
• invalid, wrong-audience, wrong-scope, expired, foreign-azp, wrong-issuer and tampered-signature tokens get 401 and never reach the provider
• jwt-plugin session JWTs (GET /api/auth/token) are refused at the proxy
• tokens with a missing, unknown or other user's sid are refused, and signing out revokes an issued token
• unset Mindmap config means provisioning does nothing and tokens are refused
• the allowlist returns 403
• OAuth tokens are rejected on every non-proxy route
• client management is refused, with the client table left unchanged
• provisioning is idempotent, respects an operational disable, and clears a stale secret

Note: on a cold first run after a fresh npm ci, erasure.test.ts can time out (5s limit, slow first import); it passes on rerun. It's unrelated to this change, but CI may see it.

🤖 Generated with Claude Code

[kcarnold]

A few quick comments as I'm scrolling through.