Security model
Understand the trust boundaries and application responsibilities around Better Convex Nuxt.
Better Convex Nuxt transports identity; it does not replace application authorization. Every protected Convex function must verify the caller and enforce access to the requested resource.
Trust boundaries
| Boundary | Responsibility |
|---|---|
| Nuxt UI | Display state and capabilities; never final authorization |
| Nuxt server | Request-scoped rendering, server routes, and the bounded same-origin auth proxy |
| Better Auth | Sessions, sign-in, sign-out, and account recovery |
| Convex token exchange | Turn the checked session into a Convex session token |
| Convex functions | Access checks, tenant isolation, validation, and bounded data access |
Route middleware improves navigation UX. Hiding a button improves UX. Neither protects data.
Use auth.requireUser(ctx) or auth.getUser(ctx) from createBetterConvexAuth.
They accept only a Convex session token whose Better Auth session still exists.
When Better Auth revokes all sessions of a user, for example on a password
reset with revokeSessionsOnPasswordReset, every older token stops working at
once. A password reset ends all older sessions by default
(revokeSessionsOnPasswordReset is true), a password change ends the others,
and proving an email address ends every session that existed before the proof.
ctx.auth.getUserIdentity() alone does not check revocation.
Company identity provider. With the oidc option, the identity provider
(IdP) decides who signs in and when the sessions of an IdP user end: through
back-channel logout, or when it refuses the refresh token before the app
issues a Convex or MCP token. The IdP never decides what a user may do; roles
that oidc.onSignIn copies into your tables are checked by your functions. Authorization stays in your Convex functions. See
Company sign-in.
The factory turns on no sign-in method by itself. Password sign-in needs
emailAndPassword and requires a verified address unless you pass
requireEmailVerification: false. A user with an unverified address is created
only by password sign-up or as an anonymous guest. One gap remains for an app
that decides access by email: use email codes (emailOTP) for it. See
Password sign-in and access by email.
export const remove = mutation({
args: { projectId: v.id('projects') },
handler: async (ctx, { projectId }) => {
const user = await auth.requireUser(ctx)
const project = await ctx.db.get(projectId)
if (!project || project.ownerId !== user.id) {
throw new ConvexError({ code: 'FORBIDDEN' })
}
await ctx.db.delete(projectId)
},
})Auth proxy contract
The module exposes one /api/auth proxy. Sign-in, session, consent, administration, authorize, revoke, and plugin routes accept same-origin requests only. It accepts only the supported Better Auth cookie namespace, GET and POST requests, bounded bodies, and a validated upstream origin. It does not follow upstream redirects with credentials attached.
The narrow browser OAuth exception is the exact public-client form token route:
cross-origin POST /api/auth/oauth2/token and its exact OPTIONS preflight,
without a query, Cookie, Authorization, proxy authorization, DPoP, or
credentialed CORS. Its form body is independently bounded, upstream CORS headers
cannot widen the response, and a token response that tries to set a cookie is
rejected. The public authorization-server and protected-resource metadata
documents use wildcard non-credentialed CORS because they contain no secret or
user state.
The proxy also signs its configured auth.origin with BCN_AUTH_PROXY_IP_SECRET. Convex accepts that origin only when the signature is valid and the origin is SITE_URL or listed in siteOrigins, so one deployment can serve several sites. Request headers never choose it: the proxy removes every incoming x-bcn-* header first.
Do not widen its cookie allowlist, add caller-controlled forwarding headers, or introduce a second token-exchange path. If a Better Auth plugin requires cookies outside the supported namespace, it is not compatible with this boundary.
Browser risk
The browser holds a Convex session token so Convex subscriptions can authenticate. An XSS flaw or a compromised script on your origin can act as the user and copy that token until it expires, after at most 15 minutes. Use safe Vue rendering, a strict Content Security Policy, and few third-party scripts. High-risk operations should load the current state again in Convex before they change anything.
Operator responsibilities
You are responsible for TLS, host validation, secret storage, OAuth provider settings, recovery email, CSP, log access, dependency updates, access rules, backups, and incident response.
With company sign-in, you are also responsible for these IdP settings:
- exact redirect and post-logout URIs, with no wildcards;
- the back-channel logout URL;
- the client secret, stored only in the Convex environment;
- a pinned issuer (
KC_HOSTNAMEin Keycloak); - multi-factor sign-in at the IdP;
- the audience of the access token for each of your services;
- an access-token lifetime between 2 and 15 minutes.
The repository security policy lists what the library protects and the known remaining risks.
If a Better Auth secret, the proxy signing secret, a session, an OAuth client, a consent or token, a signing key, or a package may be compromised, follow the policy's incident steps.
Report suspected vulnerabilities through the private channel described in that policy, not a public issue.