@lupinum/better-convex-functions 0.1.0-rc.0 → 0.1.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/README.md +49 -0
  2. package/dist/agent/AGENTS.md +2 -2
  3. package/dist/agent/pages/docs/build/agents/mcp-application.md +1 -1
  4. package/dist/agent/pages/docs/build/agents/mcp-apps.md +1 -1
  5. package/dist/agent/pages/docs/build/agents/mcp.md +2 -2
  6. package/dist/agent/pages/docs/build/application-behavior/logging.md +1 -1
  7. package/dist/agent/pages/docs/build/authentication/auth-state-and-user.md +1 -1
  8. package/dist/agent/pages/docs/build/authentication/better-auth-plugin-support.md +3 -3
  9. package/dist/agent/pages/docs/build/authentication/better-auth-plugins.md +2 -0
  10. package/dist/agent/pages/docs/build/authentication/better-auth-setup.md +54 -20
  11. package/dist/agent/pages/docs/build/authentication/cacheable-public-pages.md +6 -3
  12. package/dist/agent/pages/docs/build/authentication/custom-user-fields.md +4 -1
  13. package/dist/agent/pages/docs/build/authentication/delegated-oauth-and-mcp.md +3 -3
  14. package/dist/agent/pages/docs/build/authentication/multiple-site-origins.md +45 -1
  15. package/dist/agent/pages/docs/build/authentication/overview.md +1 -1
  16. package/dist/agent/pages/docs/build/authentication/route-protection.md +2 -2
  17. package/dist/agent/pages/docs/build/authentication/sign-in-and-sign-out.md +49 -2
  18. package/dist/agent/pages/docs/build/authentication/social-sign-in.md +2 -0
  19. package/dist/agent/pages/docs/build/authentication/transactional-email.md +26 -7
  20. package/dist/agent/pages/docs/build/files/storage-urls.md +35 -15
  21. package/dist/agent/pages/docs/build/files/upload-files.md +87 -3
  22. package/dist/agent/pages/docs/build/functions/start-here.md +1 -1
  23. package/dist/agent/pages/docs/build/queries/pagination.md +13 -1
  24. package/dist/agent/pages/docs/build/queries/ssr-options.md +1 -1
  25. package/dist/agent/pages/docs/build/server/credentials-and-security.md +1 -1
  26. package/dist/agent/pages/docs/build/server/server-routes.md +7 -1
  27. package/dist/agent/pages/docs/build/server/webhooks-and-jobs.md +3 -1
  28. package/dist/agent/pages/docs/build/write-data/actions.md +2 -0
  29. package/dist/agent/pages/docs/get-started/add-a-mutation.md +2 -0
  30. package/dist/agent/pages/docs/get-started/add-authentication.md +13 -7
  31. package/dist/agent/pages/docs/get-started/choose-your-path.md +6 -21
  32. package/dist/agent/pages/docs/get-started/first-realtime-page.md +2 -0
  33. package/dist/agent/pages/docs/get-started/plain-vue.md +22 -0
  34. package/dist/agent/pages/docs/get-started/protect-data.md +29 -1
  35. package/dist/agent/pages/docs/operations/before-launch.md +1 -1
  36. package/dist/agent/pages/docs/operations/deploy-to-vercel.md +1 -1
  37. package/dist/agent/pages/docs/operations/deployment.md +5 -0
  38. package/dist/agent/pages/docs/operations/release-compatibility.md +7 -7
  39. package/dist/agent/pages/docs/operations/security-model.md +10 -1
  40. package/dist/agent/pages/docs/operations/upgrade-to-1-0.md +20 -8
  41. package/dist/agent/pages/docs/overview/comparison.md +1 -1
  42. package/dist/agent/pages/docs/overview/limitations.md +1 -1
  43. package/dist/agent/pages/docs/overview/who-it-is-for.md +3 -3
  44. package/dist/agent/pages/docs/recipes/error-messages.md +8 -1
  45. package/dist/agent/pages/docs/recipes/file-upload-form.md +6 -6
  46. package/dist/agent/pages/docs/recipes/guest-users.md +28 -6
  47. package/dist/agent/pages/docs/recipes/multiple-file-uploads.md +22 -4
  48. package/dist/agent/pages/docs/recipes/organization-permissions.md +16 -12
  49. package/dist/agent/pages/docs/recipes/realtime-feed.md +8 -1
  50. package/dist/agent/pages/docs/reference/api-surface.md +1 -1
  51. package/dist/agent/pages/docs/reference/module-configuration.md +3 -3
  52. package/dist/agent/pages/docs/reference/server-api.md +1 -1
  53. package/dist/index.d.mts +1 -1
  54. package/dist/index.d.ts +1 -1
  55. package/dist/internal.d.mts +2 -2
  56. package/dist/internal.d.ts +2 -2
  57. package/dist/shared/{better-convex-functions.DB87b11u.d.mts → better-convex-functions.AOeEX0Gw.d.mts} +4 -4
  58. package/dist/shared/{better-convex-functions.cKweSRF2.d.ts → better-convex-functions.D89tXIyj.d.ts} +4 -4
  59. package/package.json +1 -1
package/README.md CHANGED
@@ -112,6 +112,55 @@ export const { query, mutation, internalQuery, internalMutation, internalAction,
112
112
 
113
113
  Spread `libraryTables` into your schema. A table without a rule is a type error.
114
114
 
115
+ <!-- BEGIN:consumer-onboarding -->
116
+
117
+ ## Agent setup
118
+
119
+ `@lupinum/better-convex-functions` ships its documentation inside the package for coding
120
+ agents such as Claude Code, Codex and Cursor. The pages match the installed
121
+ version, so an agent does not follow the website for a different version.
122
+
123
+ To set it up, give your coding agent this task:
124
+
125
+ ```text
126
+ Set up @lupinum/better-convex-functions for coding agents as described under "Agent setup" in its README.
127
+ ```
128
+
129
+ ### Steps for the agent
130
+
131
+ 1. Find `node_modules/@lupinum/better-convex-functions/dist/agent/AGENTS.md`. Look in the
132
+ directory of the project that depends on `@lupinum/better-convex-functions` first, then
133
+ in its parent directories up to the repository root (workspaces can hoist
134
+ packages). Read it; it lists the documentation pages.
135
+ 2. Add the section below to the project's agent instructions: `AGENTS.md`, or
136
+ `CLAUDE.md` if the project has only that file. If it has neither, create
137
+ `AGENTS.md`. Write the path relative to the repository root, through
138
+ `node_modules/@lupinum/better-convex-functions` (for example
139
+ `apps/web/node_modules/@lupinum/better-convex-functions/...` in a workspace). Never write
140
+ a resolved path such as `node_modules/.pnpm/...`: it contains the version and
141
+ breaks after an upgrade. If a section for `@lupinum/better-convex-functions` already
142
+ exists, leave it as it is.
143
+
144
+ Use the path you found in place of the sample path:
145
+
146
+ ```md
147
+ ## @lupinum/better-convex-functions
148
+
149
+ Before you change code that uses @lupinum/better-convex-functions, read
150
+ `node_modules/@lupinum/better-convex-functions/dist/agent/AGENTS.md` and the pages it
151
+ lists. They document the installed version. Prefer them over what you
152
+ remember about this package and over the website.
153
+ ```
154
+
155
+ 3. Do not copy the documentation into the project and do not install a skill.
156
+ The section points into the installed package, so it stays correct after
157
+ every upgrade or downgrade.
158
+
159
+ If the file does not exist, the installed version has no packaged
160
+ documentation. Read the package README and its TypeScript types instead.
161
+
162
+ <!-- END:consumer-onboarding -->
163
+
115
164
  ## Entry points
116
165
 
117
166
  | Import | Contents |
@@ -1,6 +1,6 @@
1
- # @lupinum/better-convex-functions 0.1.0-rc.0 documentation
1
+ # @lupinum/better-convex-functions 0.1.0-rc.2 documentation
2
2
 
3
- These pages describe the installed version 0.1.0-rc.0. Prefer them over the
3
+ These pages describe the installed version 0.1.0-rc.2. Prefer them over the
4
4
  website and over knowledge of earlier versions: the API changed during the 1.0 betas.
5
5
 
6
6
  ## Start here
@@ -31,7 +31,7 @@ every rule that the profile sets.
31
31
  ## Install the packages
32
32
 
33
33
  ```bash
34
- pnpm add @lupinum/better-convex-agents@next @lupinum/better-convex-functions@next @modelcontextprotocol/server@2.2.0 zod@4.6.5
34
+ pnpm add @lupinum/better-convex-agents@next @lupinum/better-convex-functions@next @modelcontextprotocol/server@2.3.1 zod@4.6.5
35
35
  ```
36
36
 
37
37
  `@better-auth/oauth-provider` is already installed with Better Auth support.
@@ -32,7 +32,7 @@ that page.
32
32
  ## Install the packages
33
33
 
34
34
  ```bash
35
- pnpm add @modelcontextprotocol/ext-apps@2.0.0 @modelcontextprotocol/client@2.2.0 @modelcontextprotocol/core@2.2.0
35
+ pnpm add @modelcontextprotocol/ext-apps@2.0.3 @modelcontextprotocol/client@2.3.1 @modelcontextprotocol/core@2.3.1
36
36
  pnpm add -D vite @vitejs/plugin-vue vite-plugin-singlefile
37
37
  ```
38
38
 
@@ -26,7 +26,7 @@ publishes them through the same transport: see [Tools and approvals](./tools-and
26
26
  and [The MCP door](./mcp-door.md).
27
27
 
28
28
  This page describes the 1.0 release candidate (the `next` dist-tag). It implements the
29
- final MCP `2026-07-28` contract through exact `@modelcontextprotocol/server@2.2.0`.
29
+ final MCP `2026-07-28` contract through exact `@modelcontextprotocol/server@2.3.1`.
30
30
  The protocol is stable; this integration remains prerelease until the 1.0
31
31
  release.
32
32
 
@@ -64,7 +64,7 @@ mutation, action, tool result, log, or iframe.
64
64
  ## Install
65
65
 
66
66
  ```bash
67
- pnpm add @lupinum/better-convex-agents@next @lupinum/better-convex-functions@next @modelcontextprotocol/server@2.2.0 zod@4.6.5
67
+ pnpm add @lupinum/better-convex-agents@next @lupinum/better-convex-functions@next @modelcontextprotocol/server@2.3.1 zod@4.6.5
68
68
  ```
69
69
 
70
70
  `@modelcontextprotocol/server` is an exact peer dependency of
@@ -42,7 +42,7 @@ Auth diagnostics use the same root log level as every other runtime boundary:
42
42
  convex: {
43
43
  logging: 'debug',
44
44
  auth: {
45
- origin: process.env.SITE_URL ?? 'http://localhost:3000'
45
+ origin: process.env.SITE_URL
46
46
  }
47
47
  }
48
48
  ```
@@ -23,7 +23,7 @@ const { status, pending, user, error, client, ready } = useConvexAuth()
23
23
 
24
24
  `status` tells you whether a user is signed in, as Convex accepted it. `pending` is `true` while `status` is `'pending'`, which happens only before the first result. A sign-in or user switch keeps the previous `status` until Convex accepts the new session.
25
25
 
26
- Use these refs for the signed-in user. They live as long as the app. With Better Auth 1.7.6, do not mount `client.useSession()` in route components; remounting it can leave session state stale. `client` is the one integrated Better Auth client for sign-in, sign-out, and inferred plugin methods. It is never `null`, so you can destructure and read it anywhere. The real client exists only in the browser after the Convex runtime starts. During server rendering and before that point, calling one of its methods throws a `ConvexCallError` with code `CLIENT_UNAVAILABLE`. Call it from browser event handlers or `onMounted()`.
26
+ Use these refs for the signed-in user. They live as long as the app. With Better Auth 1.7.7, do not mount `client.useSession()` in route components; remounting it can leave session state stale. `client` is the one integrated Better Auth client for sign-in, sign-out, and inferred plugin methods. It is never `null`, so you can destructure and read it anywhere. The real client exists only in the browser after the Convex runtime starts. During server rendering and before that point, calling one of its methods throws a `ConvexCallError` with code `CLIENT_UNAVAILABLE`. Call it from browser event handlers or `onMounted()`.
27
27
 
28
28
  ```vue
29
29
  <template>
@@ -22,9 +22,9 @@ The browser client accepts only the matching client plugins in
22
22
 
23
23
  | Plugin | Server option | Client plugin | Status | Notes |
24
24
  | --- | --- | --- | --- | --- |
25
- | Organization | `organization` | `organizationClient()` from `better-auth/client/plugins` | Supported | Needs a local auth component. Teams work with `teams: { enabled: true }`. Invitation email goes through the `email` hook. |
26
- | Two-factor | `twoFactor` | `twoFactorClient()` from `better-auth/client/plugins` | Supported | Needs a local auth component. One-time codes go through the `email` hook. |
27
- | Email OTP | `emailOTP` | `emailOTPClient()` from `better-auth/client/plugins` | Supported | Requires the `email` hook. Adds no tables. |
25
+ | Organization | `organization` | `organizationClient()` from `better-auth/client/plugins` | Supported | Needs a local auth component. Teams work with `teams: { enabled: true }`. Invitation email goes through the `email` hook. Accepting an invitation needs a verified email by default. |
26
+ | Two-factor | `twoFactor` | `twoFactorClient()` from `better-auth/client/plugins` | Supported | Needs a local auth component. One-time codes go through the `email` hook. Rejected together with `emailOTP` or `socialProviders`, because those sign-ins skip the second factor. |
27
+ | Email OTP | `emailOTP` | `emailOTPClient()` from `better-auth/client/plugins` | Supported | Needs the `email` hook (a loopback `SITE_URL` logs codes instead). Codes are stored hashed. `changeEmail` and unknown keys are rejected. Adds no tables. |
28
28
  | OAuth provider | `oauth.mcp` | `oauthProviderClient()` from `@better-auth/oauth-provider/client` | Supported for MCP | Only the MCP profile. A local auth component also needs it in the schema plugins. Dynamic client registration, UserInfo, and OpenID Connect discovery are off. See [Delegated OAuth and MCP](./delegated-oauth-and-mcp.md). |
29
29
  | JWT | None | None | Built in | The library always installs it. It stores the keys that sign Convex session tokens and OAuth access tokens. You cannot configure it. |
30
30
  | Anonymous | `experimental.anonymous` | `anonymousClient()` from `better-auth/client/plugins` | Experimental | Needs a local auth component. Cannot be combined with `twoFactor`. See [Guest users](../../recipes/guest-users.md). |
@@ -78,6 +78,8 @@ export function createAuthSchemaPlugins(authIssuer: string) {
78
78
  }
79
79
  ```
80
80
 
81
+ The default of `requireEmailVerificationOnInvitation` is `true`. Setting it to `false` lets a person accept an invitation without proving the address; see [Organization permissions](../../recipes/organization-permissions.md).
82
+
81
83
  Keep the `jwt` entry exactly as `better-convex init` wrote it. The library
82
84
  uses the same JWT settings at runtime.
83
85
 
@@ -37,42 +37,71 @@ The session cookie stays on the Nuxt origin. Better Auth stores its data in Conv
37
37
 
38
38
  The complete minimal versions are in [Add authentication](../../get-started/add-authentication.md). Start from those files. Add your own settings as options of `createBetterConvexAuth`.
39
39
 
40
+ ## Choose the sign-in methods
41
+
42
+ The factory turns on no sign-in method by itself. Name the ones your app uses:
43
+
44
+ | Option | Sign-in method | Default when you pass it |
45
+ | --- | --- | --- |
46
+ | `emailAndPassword` | Email and password | Verified address required; a reset ends all other sessions |
47
+ | `emailOTP` | One-time code sent by email | Codes stored hashed |
48
+ | `socialProviders` | GitHub, Google, or another provider | Only verified provider emails create a user |
49
+
50
+ Leave `emailAndPassword` out and `/api/auth/sign-up/email` and
51
+ `/api/auth/sign-in/email` answer with an error. An app that signs in by email
52
+ code or social login has no password sign-in. See
53
+ [Sign in and sign out](./sign-in-and-sign-out.md) for the
54
+ password options.
55
+
40
56
  ## Approve new users
41
57
 
42
58
  Use `beforeUserCreate` when the application must approve each new Better Auth
43
59
  user against its own Convex data. The callback can deny the new user. It can
44
- also replace the new user's `id` and normalized `email`, and nothing else.
60
+ also replace the new user's `id` with a fresh one. Nothing else. It cannot
61
+ change the `email`: the factory rejects a different address and stores the
62
+ address in lower case.
45
63
 
46
64
  ```ts [convex/auth.ts]
47
65
  export const auth = createBetterConvexAuth<DataModel>(components.betterAuth, {
66
+ emailOTP: {},
67
+ email: sendAuthEmail, // your `email` hook
48
68
  beforeUserCreate: async ({ ctx, user }) => {
69
+ // Never decide access from an address the person has not proven.
70
+ if (!user.emailVerified) return { allowed: false }
71
+
49
72
  const invite = await ctx.runQuery(internal.members.findInvite, {
50
73
  email: user.email.trim().toLowerCase(),
51
74
  })
52
75
 
53
- if (!invite) return { allowed: false }
54
-
55
- return {
56
- allowed: true,
57
- user: {
58
- email: invite.email,
59
- ...(invite.existingUserId ? { id: invite.existingUserId } : {}),
60
- },
61
- }
76
+ return invite ? { allowed: true } : { allowed: false }
62
77
  },
63
78
  })
64
79
  ```
65
80
 
66
- `internal.members.findInvite` is your own internal query. The callback
81
+ **Warning:** Decide access by `user.email` only when `user.emailVerified` is
82
+ `true`, and sign in with email codes. A password sign-up does not prove the
83
+ address. See
84
+ [Password sign-in and access by email](./sign-in-and-sign-out.md#password-sign-in-and-access-by-email).
85
+
86
+ `sendAuthEmail` is your own `email` hook. See
87
+ [Transactional auth email](./transactional-email.md#add-the-email-hook)
88
+ for a complete one. `internal.members.findInvite` is your own internal query. The callback
67
89
  receives a read-only copy of the new user: `email`, `emailVerified`, `name`,
68
90
  and `image`. It has no `id` yet, because Better Auth assigns it after the
69
- callback.
91
+ callback. If you return an `id`, it must be a value that no Better Auth user
92
+ has; do not use it to attach a sign-up to an existing user.
93
+
94
+ Better Auth creates a user with an unverified address only through password
95
+ sign-up (`/sign-up/email`) or as an anonymous guest. A social provider that reports an unverified email
96
+ is refused before this callback runs.
70
97
 
71
98
  A denial, a thrown error, or an invalid `id` or `email` rejects the sign-up:
72
- no user is created and no email is sent. The browser still receives Better
73
- Auth's generic sign-up response, the same one it gets for a new or an existing
74
- address, so nobody can find out who may sign up. Tell people in your sign-up
75
- screen to check their email, not that their account exists. A thrown error or
99
+ no user is created. For a password sign-up, no email is sent and the browser
100
+ still receives Better Auth's generic sign-up response, the same one it gets for
101
+ a new or an existing address, so nobody can find out who may sign up. Tell
102
+ people in your sign-up screen to check their email, not that their account
103
+ exists. With email codes, the code mail is already sent when the check runs,
104
+ and `/sign-in/email-otp` answers with an error. A thrown error or
76
105
  an invalid identity is logged on the server as `AUTH_USER_CREATE_REJECTED`
77
106
  with a sub-code; a thrown error also logs its sanitized message. A denial is
78
107
  not logged.
@@ -119,8 +148,13 @@ setup.
119
148
  ## Unsupported options fail at startup
120
149
 
121
150
  `createBetterConvexAuth` rejects an unknown option key when the module loads.
122
- This includes unknown keys in `session`, `account`, and
123
- `account.accountLinking`. The factory sets `plugins`, `database`,
151
+ This includes unknown keys in `session`, `account`, `account.accountLinking`,
152
+ and `emailOTP` (`emailOTP.changeEmail` is rejected). It also rejects
153
+ `twoFactor` together with `emailOTP` or `socialProviders`, because those
154
+ sign-ins skip the second factor. A deployment that must send mail (email codes,
155
+ password verification or reset, organization invitations) and has no `email`
156
+ option fails here too, unless `SITE_URL` is a loopback origin; see
157
+ [Transactional email](./transactional-email.md). The factory sets `plugins`, `database`,
124
158
  `databaseHooks`, `user`, `advanced`, `rateLimit`, `baseURL`, and `basePath`.
125
159
 
126
160
  ## Diagnose configuration errors
@@ -179,7 +213,7 @@ Set these for the Nuxt build/runtime:
179
213
  | `BCN_AUTH_PROXY_IP_SECRET` | Same private proxy secret configured in Convex |
180
214
  | `BCN_AUTH_TRUSTED_CLIENT_IP_HEADER` | Header your host sets to one client IP; required outside loopback |
181
215
 
182
- `SITE_URL` must be an exact origin. Use HTTPS outside loopback development. Do not include a path, query, or fragment.
216
+ `SITE_URL` is required and has no default. Put `SITE_URL=http://localhost:3000` in `.env.local` for local work. It must be an exact origin. Use HTTPS outside loopback development. Do not include a path, query, or fragment.
183
217
 
184
218
  ## Proxy behavior
185
219
 
@@ -230,7 +264,7 @@ these limits. `trustedClientIpHeader` is the only proxy option:
230
264
  ```ts
231
265
  convex: {
232
266
  auth: {
233
- origin: process.env.SITE_URL ?? 'http://localhost:3000',
267
+ origin: process.env.SITE_URL,
234
268
  trustedClientIpHeader: process.env.BCN_AUTH_TRUSTED_CLIENT_IP_HEADER,
235
269
  }
236
270
  }
@@ -32,15 +32,18 @@ Set the `convex.ssrAuth` route rule:
32
32
  export default defineNuxtConfig({
33
33
  modules: ['@lupinum/better-convex-nuxt'],
34
34
  convex: {
35
- auth: { origin: process.env.SITE_URL ?? 'http://localhost:3000' },
35
+ auth: { origin: process.env.SITE_URL },
36
36
  },
37
37
  routeRules: {
38
- '/**': { isr: 86400, convex: { ssrAuth: false } },
38
+ '/api/**': { isr: false, cache: false },
39
39
  '/admin/**': { isr: false, convex: { ssrAuth: true } },
40
+ '/**': { isr: 86400, convex: { ssrAuth: false } },
40
41
  },
41
42
  })
42
43
  ```
43
44
 
45
+ The rule `'/**'` also matches `/api/**`, which includes the sign-in routes under `/api/auth`. A cache must never store a response from these routes, because it could serve the session of one user to another visitor. List only your public page paths, not `'/**'`. The `/api/**` rule is a second guard that turns caching off for the auth routes.
46
+
44
47
  ## Turn it off for all routes
45
48
 
46
49
  Set `auth.ssr: false`. A route rule with `convex: { ssrAuth: true }` turns it on again for matching routes.
@@ -48,7 +51,7 @@ Set `auth.ssr: false`. A route rule with `convex: { ssrAuth: true }` turns it on
48
51
  ```ts [nuxt.config.ts]
49
52
  export default defineNuxtConfig({
50
53
  convex: {
51
- auth: { origin: process.env.SITE_URL ?? 'http://localhost:3000', ssr: false },
54
+ auth: { origin: process.env.SITE_URL, ssr: false },
52
55
  },
53
56
  routeRules: {
54
57
  '/account/**': { convex: { ssrAuth: true } },
@@ -65,6 +65,7 @@ export const auth = createBetterConvexAuth<DataModel>(components.betterAuth, {
65
65
  defineSessionClaims: ({ user, session }) => ({
66
66
  name: user.name,
67
67
  email: user.email,
68
+ emailVerified: user.emailVerified,
68
69
  // Display hint only. Authorize organization access from member rows.
69
70
  activeOrganizationId:
70
71
  typeof session.activeOrganizationId === 'string' ? session.activeOrganizationId : null,
@@ -73,7 +74,9 @@ export const auth = createBetterConvexAuth<DataModel>(components.betterAuth, {
73
74
  ```
74
75
 
75
76
  In Convex functions, prefer `auth.getUser(ctx)`. It reads the live user row,
76
- so it never shows a stale name or email.
77
+ so it never shows a stale name or email. Claims are for display. The email can
78
+ be unverified, and the token is a snapshot, so authorize from rows in Convex,
79
+ not from a claim.
77
80
 
78
81
  The library sets the registered JWT claims, `sid`, and `token_use`. A custom
79
82
  claim with one of these names fails the token request. The serialized claims
@@ -39,7 +39,7 @@ Install Better Auth and the OAuth provider at the exact versions that the
39
39
  module declares as peers:
40
40
 
41
41
  ```bash
42
- pnpm add better-auth@1.7.6 @better-auth/core@1.7.6 @better-auth/oauth-provider@1.7.6
42
+ pnpm add better-auth@1.7.7 @better-auth/core@1.7.7 @better-auth/oauth-provider@1.7.7
43
43
  ```
44
44
 
45
45
  Do not install another OAuth provider version or patch it in your
@@ -67,7 +67,7 @@ export default defineNuxtConfig({
67
67
  url: process.env.NUXT_PUBLIC_CONVEX_URL,
68
68
  siteUrl: process.env.NUXT_PUBLIC_CONVEX_SITE_URL,
69
69
  auth: {
70
- origin: process.env.SITE_URL ?? 'http://localhost:3000',
70
+ origin: process.env.SITE_URL,
71
71
  trustedClientIpHeader: process.env.BCN_AUTH_TRUSTED_CLIENT_IP_HEADER,
72
72
  },
73
73
  },
@@ -183,7 +183,7 @@ only for a signed-in OAuth administrator. A missing session or user, `false`,
183
183
  `undefined`, a thrown error, or a timeout denies the request. The factory fails
184
184
  at startup when either profile does not keep the rules above.
185
185
 
186
- Better Auth 1.7.6 encrypts provider access and refresh tokens, but not every
186
+ Better Auth 1.7.7 encrypts provider access and refresh tokens, but not every
187
187
  provider ID token. The library encrypts ID tokens before it writes them to the
188
188
  component and decrypts them only inside Better Auth. Your application code and
189
189
  the browser cannot read provider tokens.
@@ -57,6 +57,50 @@ Without `BCN_AUTH_PROXY_IP_SECRET`, the proxy sends no origin, and Convex uses `
57
57
 
58
58
  - The OAuth provider and MCP (`oauth`, `oauthProvider`) always use `SITE_URL` as the issuer. `createBetterConvexAuth` rejects `siteOrigins` together with them.
59
59
  - Social sign-in providers need the callback URL of every site, for example `https://bakery.example/api/auth/callback/google`.
60
- - Users and sessions are shared by the deployment. A session cookie is set per domain, so a user signs in on each site separately. Check in every Convex function that the user is a member of the site that the function changes.
60
+ - Users and sessions are shared by the deployment. A session cookie is set per domain, so a user signs in on each site separately. Check in every Convex function that the user is a member of the site that the function changes. See the example below.
61
61
  - A session is not bound to one site. A session cookie copied from one site works on another. Cookies are separated by host name, not by port, so treat every service on a site's host name as trusted.
62
62
  - Do not set `BETTER_AUTH_TRUSTED_ORIGINS`. Better Auth would add those origins next to the verified one, so the auth setup rejects it.
63
+
64
+ ## Check site membership in every function
65
+
66
+ A signed-in user may belong to one site and not another. Keep the site in your
67
+ data (`sites` and `siteMembers` tables) and pass the site as an argument. Never
68
+ read the site from a request header or the browser origin.
69
+
70
+ ```ts [convex/lib/sites.ts]
71
+ import { ConvexError } from 'convex/values'
72
+
73
+ import type { Id } from '../_generated/dataModel'
74
+ import type { MutationCtx, QueryCtx } from '../_generated/server'
75
+ import { auth } from '../auth'
76
+
77
+ export async function requireSiteMember(ctx: QueryCtx | MutationCtx, siteId: Id<'sites'>) {
78
+ const user = await auth.requireUser(ctx)
79
+ const member = await ctx.db
80
+ .query('siteMembers')
81
+ .withIndex('by_site_and_user', (q) => q.eq('siteId', siteId).eq('userId', user.id))
82
+ .unique()
83
+ if (!member) throw new ConvexError({ code: 'FORBIDDEN', message: 'Not a member of this site' })
84
+ return { user, member }
85
+ }
86
+ ```
87
+
88
+ ```ts [convex/pages.ts]
89
+ import { ConvexError, v } from 'convex/values'
90
+
91
+ import { mutation } from './_generated/server'
92
+ import { requireSiteMember } from './lib/sites'
93
+
94
+ export const publish = mutation({
95
+ args: { siteId: v.id('sites'), pageId: v.id('pages') },
96
+ handler: async (ctx, args) => {
97
+ await requireSiteMember(ctx, args.siteId)
98
+ const page = await ctx.db.get(args.pageId)
99
+ if (!page || page.siteId !== args.siteId) throw new ConvexError('Page not found')
100
+ await ctx.db.patch(page._id, { published: true })
101
+ },
102
+ })
103
+ ```
104
+
105
+ The second check matters as much as the first: a member of site A must not
106
+ change a page of site B by passing a page ID from B with their own `siteId`.
@@ -38,7 +38,7 @@ Auth is enabled only by an options object with one exact public origin:
38
38
  ```ts
39
39
  convex: {
40
40
  auth: {
41
- origin: process.env.SITE_URL ?? 'http://localhost:3000'
41
+ origin: process.env.SITE_URL
42
42
  }
43
43
  }
44
44
  ```
@@ -22,7 +22,7 @@ export default defineNuxtConfig({
22
22
  modules: ['@lupinum/better-convex-nuxt'],
23
23
  convex: {
24
24
  auth: {
25
- origin: process.env.SITE_URL ?? 'http://localhost:3000',
25
+ origin: process.env.SITE_URL,
26
26
  redirectTo: '/auth/sign-in',
27
27
  },
28
28
  },
@@ -90,7 +90,7 @@ To protect every page by default, set `routes: 'protected'`:
90
90
  export default defineNuxtConfig({
91
91
  convex: {
92
92
  auth: {
93
- origin: process.env.SITE_URL ?? 'http://localhost:3000',
93
+ origin: process.env.SITE_URL,
94
94
  redirectTo: '/auth/sign-in',
95
95
  routes: 'protected',
96
96
  },
@@ -17,7 +17,24 @@ source: "ginko-content"
17
17
 
18
18
  `client` is always present. Call its methods from browser event handlers. During server rendering, a method call throws a `ConvexCallError` with code `CLIENT_UNAVAILABLE`. For GitHub and Google, see [Social sign-in](./social-sign-in.md).
19
19
 
20
- ## Email sign-in
20
+ ## Email and password sign-in
21
+
22
+ Password sign-in is off until you name it. Pass an object to turn it on:
23
+
24
+ ```ts [convex/auth.ts]
25
+ export const auth = createBetterConvexAuth<DataModel>(components.betterAuth, {
26
+ emailAndPassword: {},
27
+ email: sendAuthEmail,
28
+ })
29
+ ```
30
+
31
+ With `emailAndPassword: {}`, a person must verify the address before sign-in
32
+ (`requireEmailVerification` is `true`), a password reset ends every other
33
+ session (`revokeSessionsOnPasswordReset` is `true`), and a password change ends
34
+ the other sessions. Pass `requireEmailVerification: false` only when your app
35
+ has no mail provider and never decides access by email. `sendAuthEmail` is
36
+ your `email` hook. See
37
+ [Transactional auth email](./transactional-email.md#add-the-email-hook).
21
38
 
22
39
  ```ts
23
40
  const { client } = useConvexAuth()
@@ -53,7 +70,37 @@ const result = await client.signUp.email({
53
70
  })
54
71
  ```
55
72
 
56
- Sign-up does not sign the user in, because `createBetterConvexAuth` always sets `autoSignIn: false`. Send the user to the sign-in page next. With `emailAndPassword.requireEmailVerification`, the user must verify the email address first. Together, email verification and `autoSignIn` determine the next product step. Passwords need at least 15 characters.
73
+ Sign-up does not sign the user in, because `createBetterConvexAuth` always sets `autoSignIn: false`. By default the user must verify the email address before the first sign-in, so tell the person to check their email. With `requireEmailVerification: false` the user can sign in right away with any address, verified or not. Passwords need at least 15 characters.
74
+
75
+ ## Password sign-in and access by email
76
+
77
+ Anyone can start a password sign-up for an address they do not own. When the
78
+ real owner later proves the address, the library ends every session that
79
+ existed before the proof, but it cannot tell the owner from a victim who opens
80
+ the verification mail of a stranger's sign-up. The password of that first
81
+ sign-up survives. So an app that decides access by email (invitations, allow
82
+ lists, company domains) should sign people in with email codes (`emailOTP`)
83
+ instead of passwords. If you keep passwords, check `emailVerified` when you
84
+ decide access and accept that residual risk. Write the verification mail so it
85
+ says: "If you did not create an account, ignore this email."
86
+
87
+ ## Email code sign-in
88
+
89
+ Turn on `emailOTP: {}` (a deployment needs the `email` hook; locally, codes go to the dev outbox in the `convex dev` log) and add `emailOTPClient()` to
90
+ [the client definition](./better-auth-plugins.md).
91
+
92
+ ```ts
93
+ const { client } = useConvexAuth()
94
+
95
+ await client.emailOtp.sendVerificationOtp({ email: email.value, type: 'sign-in' })
96
+ // Show a code field, then:
97
+ const result = await client.signIn.emailOtp({ email: email.value, otp: code.value })
98
+ if (result.error) formError.value = 'Sign in could not be completed'
99
+ ```
100
+
101
+ A code proves the address, so a person who signs in this way replaces any
102
+ password or session an earlier sign-up left on that address. Codes are stored
103
+ hashed.
57
104
 
58
105
  ## Sign-out
59
106
 
@@ -84,6 +84,8 @@ export const auth = createBetterConvexAuth<DataModel>(components.betterAuth, {
84
84
  })
85
85
  ```
86
86
 
87
+ **Note:** A provider that reports an unverified email cannot create a user. Better Convex refuses it, because an account holder could choose that address freely at some providers. Do not combine `socialProviders` with `twoFactor`; the factory rejects it.
88
+
87
89
  Keep your other options, such as `emailAndPassword` or `email`, in the same
88
90
  call. Nothing changes in `nuxt.config.ts`: the auth proxy already forwards
89
91
  `/api/auth/callback/*`.
@@ -69,16 +69,35 @@ a public endpoint that accepts arbitrary recipients or links.
69
69
  | `organization-invitation` | The `organization` capability invites a member | `invitationId`, `role`, `organization`, `inviter` |
70
70
  | `delete-account` | `deleteUser` is enabled and a person deletes | `url`, `token`, `user` |
71
71
 
72
- `purpose` is `sign-in`, `email-verification`, `forget-password`, or
73
- `change-email`. `user` and `inviter` contain `id`, `email`, and `name`. An
72
+ `purpose` is `sign-in`, `email-verification`, or `forget-password`. `user` and `inviter` contain `id`, `email`, and `name`. An
74
73
  invitation has no link. Build it from your application origin and
75
74
  `invitationId`, for example with `requireAuthOrigin('SITE_URL')`.
76
75
 
77
- When you set `email`, email verification is enabled for `emailAndPassword`.
78
- Password reset is opt-in: set `emailAndPassword.passwordReset: true` to offer
79
- `/request-password-reset` and receive `reset-password` messages. Enabling it
80
- without `email` is a configuration error. Handle every type that your enabled
81
- capabilities can send.
76
+ The `email` option only gives Better Auth a way to send mail. Whether password
77
+ sign-in waits for a verified address is set by `emailAndPassword`:
78
+ `requireEmailVerification` is `true` unless you pass `false`. Link-based password reset is
79
+ opt-in: set `emailAndPassword.passwordReset: true` to offer
80
+ `/request-password-reset` and receive `reset-password` messages. With
81
+ `emailOTP`, the code-based reset routes (`/email-otp/request-password-reset`
82
+ and `/email-otp/reset-password`) are blocked unless `passwordReset` is `true`. Handle every
83
+ type that your enabled capabilities can send.
84
+
85
+ Write the `verify-email` message so it says: "If you did not create an account,
86
+ ignore this email." See
87
+ [Password sign-in and access by email](./sign-in-and-sign-out.md#password-sign-in-and-access-by-email).
88
+
89
+ ### No `email` option
90
+
91
+ Without the `email` option, mail depends on `SITE_URL`:
92
+
93
+ - **Loopback `SITE_URL`** (`http://localhost:3000`, `http://127.0.0.1:3000`):
94
+ the dev outbox writes each code and link to the Convex function log, as
95
+ `[better-convex dev outbox] email-otp to you@example.com: code 123456`.
96
+ Read it with `pnpm exec better-convex convex logs`. `NODE_ENV` plays no part.
97
+ - **Any other `SITE_URL`**: `createBetterConvexAuth` throws when the deployment
98
+ must send mail (`emailOTP`, password verification or reset, organization
99
+ invitations). The deploy fails and the previous version keeps running. Add the
100
+ `email` option, or leave those features out.
82
101
 
83
102
  ## Submit durable work
84
103
 
@@ -17,53 +17,73 @@ Store Convex storage IDs in product data. Resolve a URL with `useConvexQuery` wh
17
17
 
18
18
  ## Backend query
19
19
 
20
- ```ts [convex/files.ts]
21
- import { query } from './_generated/server'
20
+ ```ts [convex/documents.ts]
22
21
  import { v } from 'convex/values'
22
+ import { query } from './_generated/server'
23
+ import { auth } from './auth'
23
24
 
24
- export const getUrl = query({
25
- args: { storageId: v.id('_storage') },
25
+ export const getFileUrl = query({
26
+ args: { documentId: v.id('documents') },
26
27
  handler: async (ctx, args) => {
27
- return await ctx.storage.getUrl(args.storageId)
28
+ const user = await auth.requireUser(ctx)
29
+ const document = await ctx.db.get(args.documentId)
30
+ // The same result for a missing document and for a document of another user.
31
+ if (!document || document.ownerId !== user.id || !document.storageId) return null
32
+ return await ctx.storage.getUrl(document.storageId)
28
33
  },
29
34
  })
30
35
  ```
31
36
 
32
- Add identity and document-ownership checks before returning URLs for private files.
37
+ The query takes a document ID, not a storage ID. Anyone who knows a storage ID could otherwise read the file. The query checks the owner of the document and then resolves the URL of its file.
33
38
 
34
39
  ## Reactive URL
35
40
 
36
41
  ```ts
37
42
  import type { Id } from '~~/convex/_generated/dataModel'
38
43
 
39
- const storageId = ref<Id<'_storage'> | undefined>()
40
- const urlArgs = computed(() => (storageId.value ? { storageId: storageId.value } : 'skip'))
44
+ const documentId = ref<Id<'documents'> | undefined>()
45
+ const urlArgs = computed(() => (documentId.value ? { documentId: documentId.value } : 'skip'))
41
46
 
42
47
  const {
43
48
  data: imageUrl,
44
49
  status,
45
50
  error,
46
- } = useConvexQuery(api.files.getUrl, urlArgs, {
51
+ } = useConvexQuery(api.documents.getFileUrl, urlArgs, {
47
52
  auth: 'required',
48
53
  })
49
54
  ```
50
55
 
51
- The query is idle until a storage ID exists and runs again when it changes. Use `auth: 'required'` for private files and keep the authorization check in the Convex query.
56
+ The query is idle until a document ID exists and runs again when it changes. Use `auth: 'required'` for private files and keep the authorization check in the Convex query.
52
57
 
53
58
  ## Display after upload
54
59
 
55
60
  ```ts
56
- const { upload, data: uploaded } = useConvexFileUpload(api.files.generateUploadUrl)
57
- const urlArgs = computed(() => (uploaded.value ? { storageId: uploaded.value.storageId } : 'skip'))
58
- const { data: imageUrl } = useConvexQuery(api.files.getUrl, urlArgs, { auth: 'required' })
61
+ import type { UploadCompleteContext } from '@lupinum/better-convex-nuxt'
62
+ import type { Id } from '~~/convex/_generated/dataModel'
63
+
64
+ const props = defineProps<{ documentId: Id<'documents'> }>()
65
+
66
+ const { upload, data: uploaded } = useConvexFileUpload(api.files.generateUploadUrl, {
67
+ complete: (
68
+ op,
69
+ { storageId, context: documentId }: UploadCompleteContext<string, Id<'documents'>>,
70
+ ) => op.mutation(api.documents.attachFile, { documentId, storageId }),
71
+ })
72
+ const urlArgs = computed(() => (uploaded.value ? { documentId: props.documentId } : 'skip'))
73
+ const { data: imageUrl } = useConvexQuery(api.documents.getFileUrl, urlArgs, {
74
+ auth: 'required',
75
+ })
76
+
77
+ // Later, in the change handler of the file input:
78
+ await upload(file, { context: props.documentId })
59
79
  ```
60
80
 
61
81
  ```vue
62
82
  <img v-if="imageUrl" :src="imageUrl" alt="Uploaded preview" />
63
83
  ```
64
84
 
65
- `undefined` means the URL query has no value yet. A `null` result is a successful response meaning Convex cannot resolve a URL for that storage object.
85
+ `undefined` means the URL query has no value yet. A `null` result is a successful response. It means that the document does not exist, belongs to another user, or has no file.
66
86
 
67
87
  ## URL lifetime
68
88
 
69
- Treat the resolved URL as presentation data. Store the branded storage ID as the durable reference and resolve again when needed.
89
+ Treat the resolved URL as presentation data. Store the branded storage ID on the document as the durable reference and resolve again when needed. See [Upload files](./upload-files.md#attach-the-file-safely) for `attachFile`.