Skip to main content

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

BoundaryResponsibility
Nuxt UIDisplay state and capabilities; never final authorization
Nuxt serverRequest-scoped rendering, server routes, and the bounded same-origin auth proxy
Better AuthSessions, sign-in, sign-out, and account recovery
Convex token exchangeTurn the checked session into a Convex session token
Convex functionsAccess 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.

convex/projects.ts
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_HOSTNAME in 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.