Auth stack, and how Discord roles and bans reach the app

[vdvman1]

Question

What is the auth stack, and how do Discord identity, roles, and bans reach the application?

Settled going in: better-auth with Discord OAuth. Membership of the MCC Discord guild is the gate for writing annotations. Discord roles and bans drive moderation. Reading is always public and never personalised — that is what keeps article pages cacheable. Whether to adopt better-convex (kitcn) is open.

Decide:

• Adopt better-convex/kitcn, cherry-pick from it, or wire better-auth up directly? Informed by the research ticket.
• How Convex verifies identity. Annotations are written client-side straight to Convex, so Convex must authenticate the caller itself. Pin down the mechanism and what ctx.auth sees.
• Guild membership check. At sign-in only, or re-checked? What happens when someone leaves or is banned after signing in — is their session invalidated, are their existing annotations hidden?
• Role sync. Which Discord roles map to which elevated capabilities (promoting a correction inline, resolving threads, deleting, forcing a refetch). Push from the bot, pull on demand, or snapshot at login? How stale can it be?
• Ban sync. Same question, but the freshness bar is higher — a Discord ban should take effect quickly.
• What the site stores about a user — Discord id, display name, avatar. Bear in mind annotations are public and permanent, and people change Discord usernames.
• Sessions and the cached-page constraint. Nothing user-specific may leak into a cached article render. Confirm the chosen stack cannot accidentally make a page dynamic.

Blocked on the better-auth research. Produces the requirements the commanderbot-py change has to satisfy.

[vdvman1]

Constraint added from #33 (Convex preview deployments).

With @convex-dev/better-auth, Better Auth runs on the Convex .convex.site domain — so a preview deployment has two unstable origins, and Discord will not wildcard OAuth redirect URIs. Better Auth's oAuthProxy plugin solves this, and does so without a database write on production, preserving preview isolation.

Requirements that fall out, for this decision to absorb:

• One Discord app with a single production redirect URI; productionURL set to the production Convex site origin.
• A shared proxy secret across all environments, set as a Convex preview default env var — a mismatch produces state_mismatch.
• trustedOrigins wildcarding https://*.vercel.app in previews only, never in production config.
• Use a dedicated proxy secret rather than BETTER_AUTH_SECRET, so a leak only allows hijacking flows inside the 60 s maxAge window instead of forging sessions globally.

Also flagged: each preview starts with an empty user table, so Discord guild membership and roles must be re-derived on first sign-in rather than read from seeded rows.

Full write-up: docs/research/convex-preview-deployments.md

[vdvman1]

Findings from #34 (better-auth on Convex research). Full write-up: docs/research/better-auth-convex.md

One sub-decision is now answered: reject kitcn. better-convex was archived and renamed to udecode/kitcn; the npm package is frozen at 0.11.0 since March and not marked deprecated. It is not a template — it is a runtime framework (cRPC, a Drizzle-style ORM with RLS, TanStack Query bindings, its own auth adapter), so adopting it dictates how every server function, the schema, and every client read are written. Its TanStack Query client path collides directly with this map's PPR + live-islands plan. Decisive: since v0.13.0 it forks @convex-dev/better-auth rather than depending on it, kept in sync by one person manually re-syncing from a personal fork. 1,838 weekly downloads vs 151,335 for the official component, with breaking changes every minor by stated policy. Use @convex-dev/better-auth directly.

Server-side identity verification is solved, with one trap. Better Auth runs inside Convex as HTTP actions on the .convex.site domain; its convex() plugin mints an RS256 JWT signed from the component's jwks table, and convex/auth.config.ts registers it as a customJwt provider. Convex validates signature, iss, aud and exp before our handler runs — Next.js is not in the trust path, so client-written annotations are safe.

The trap: ctx.auth.getUserIdentity() trusts the JWT and does not check the session, so revocation lags by up to the 15-minute token lifetime. authComponent.getAuthUser(ctx) does a real session-table lookup. Write paths must use the latter — this is exactly the difference between a Discord ban taking effect now and taking effect in fifteen minutes.

Discord data access constrains the design more than expected:

• Roles are a sign-in snapshot. Readable via guilds.members.read + /users/@me/guilds/{id}/member (role IDs only). There is no push mechanism Convex can host — Discord Webhook Events don't cover member/role/ban changes, and anything else needs a persistent Gateway connection, which Convex cannot run.
• Bans require a bot token with BAN_MEMBERS (404 means not banned) — not obtainable through the OAuth flow.

Both of those land the role/ban feed on commanderbot-py (#45), which already holds a persistent Gateway connection. That makes #45 load-bearing rather than incidental — decide here what interface you want from it.

Convex Auth stays ruled out: still 0.0.94, self-described beta, Next.js support experimental.

Caveat recorded rather than glossed: Better Auth is not listed on docs.convex.dev/auth, which steers toward Clerk/WorkOS/Auth0 — the component lives at labs.convex.dev. Weigh that as a support risk.