@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.
- package/README.md +49 -0
- package/dist/agent/AGENTS.md +2 -2
- package/dist/agent/pages/docs/build/agents/mcp-application.md +1 -1
- package/dist/agent/pages/docs/build/agents/mcp-apps.md +1 -1
- package/dist/agent/pages/docs/build/agents/mcp.md +2 -2
- package/dist/agent/pages/docs/build/application-behavior/logging.md +1 -1
- package/dist/agent/pages/docs/build/authentication/auth-state-and-user.md +1 -1
- package/dist/agent/pages/docs/build/authentication/better-auth-plugin-support.md +3 -3
- package/dist/agent/pages/docs/build/authentication/better-auth-plugins.md +2 -0
- package/dist/agent/pages/docs/build/authentication/better-auth-setup.md +54 -20
- package/dist/agent/pages/docs/build/authentication/cacheable-public-pages.md +6 -3
- package/dist/agent/pages/docs/build/authentication/custom-user-fields.md +4 -1
- package/dist/agent/pages/docs/build/authentication/delegated-oauth-and-mcp.md +3 -3
- package/dist/agent/pages/docs/build/authentication/multiple-site-origins.md +45 -1
- package/dist/agent/pages/docs/build/authentication/overview.md +1 -1
- package/dist/agent/pages/docs/build/authentication/route-protection.md +2 -2
- package/dist/agent/pages/docs/build/authentication/sign-in-and-sign-out.md +49 -2
- package/dist/agent/pages/docs/build/authentication/social-sign-in.md +2 -0
- package/dist/agent/pages/docs/build/authentication/transactional-email.md +26 -7
- package/dist/agent/pages/docs/build/files/storage-urls.md +35 -15
- package/dist/agent/pages/docs/build/files/upload-files.md +87 -3
- package/dist/agent/pages/docs/build/functions/start-here.md +1 -1
- package/dist/agent/pages/docs/build/queries/pagination.md +13 -1
- package/dist/agent/pages/docs/build/queries/ssr-options.md +1 -1
- package/dist/agent/pages/docs/build/server/credentials-and-security.md +1 -1
- package/dist/agent/pages/docs/build/server/server-routes.md +7 -1
- package/dist/agent/pages/docs/build/server/webhooks-and-jobs.md +3 -1
- package/dist/agent/pages/docs/build/write-data/actions.md +2 -0
- package/dist/agent/pages/docs/get-started/add-a-mutation.md +2 -0
- package/dist/agent/pages/docs/get-started/add-authentication.md +13 -7
- package/dist/agent/pages/docs/get-started/choose-your-path.md +6 -21
- package/dist/agent/pages/docs/get-started/first-realtime-page.md +2 -0
- package/dist/agent/pages/docs/get-started/plain-vue.md +22 -0
- package/dist/agent/pages/docs/get-started/protect-data.md +29 -1
- package/dist/agent/pages/docs/operations/before-launch.md +1 -1
- package/dist/agent/pages/docs/operations/deploy-to-vercel.md +1 -1
- package/dist/agent/pages/docs/operations/deployment.md +5 -0
- package/dist/agent/pages/docs/operations/release-compatibility.md +7 -7
- package/dist/agent/pages/docs/operations/security-model.md +10 -1
- package/dist/agent/pages/docs/operations/upgrade-to-1-0.md +20 -8
- package/dist/agent/pages/docs/overview/comparison.md +1 -1
- package/dist/agent/pages/docs/overview/limitations.md +1 -1
- package/dist/agent/pages/docs/overview/who-it-is-for.md +3 -3
- package/dist/agent/pages/docs/recipes/error-messages.md +8 -1
- package/dist/agent/pages/docs/recipes/file-upload-form.md +6 -6
- package/dist/agent/pages/docs/recipes/guest-users.md +28 -6
- package/dist/agent/pages/docs/recipes/multiple-file-uploads.md +22 -4
- package/dist/agent/pages/docs/recipes/organization-permissions.md +16 -12
- package/dist/agent/pages/docs/recipes/realtime-feed.md +8 -1
- package/dist/agent/pages/docs/reference/api-surface.md +1 -1
- package/dist/agent/pages/docs/reference/module-configuration.md +3 -3
- package/dist/agent/pages/docs/reference/server-api.md +1 -1
- package/dist/index.d.mts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/internal.d.mts +2 -2
- package/dist/internal.d.ts +2 -2
- package/dist/shared/{better-convex-functions.DB87b11u.d.mts → better-convex-functions.AOeEX0Gw.d.mts} +4 -4
- package/dist/shared/{better-convex-functions.cKweSRF2.d.ts → better-convex-functions.D89tXIyj.d.ts} +4 -4
- 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 |
|
package/dist/agent/AGENTS.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# @lupinum/better-convex-functions 0.1.0-rc.
|
|
1
|
+
# @lupinum/better-convex-functions 0.1.0-rc.2 documentation
|
|
2
2
|
|
|
3
|
-
These pages describe the installed version 0.1.0-rc.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
@@ -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.
|
|
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 |
|
|
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`
|
|
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
|
-
|
|
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
|
-
`
|
|
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
|
|
73
|
-
Auth's generic sign-up response, the same one it gets for
|
|
74
|
-
address, so nobody can find out who may sign up. Tell
|
|
75
|
-
screen to check their email, not that their account
|
|
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`,
|
|
123
|
-
`
|
|
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
|
|
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
|
|
35
|
+
auth: { origin: process.env.SITE_URL },
|
|
36
36
|
},
|
|
37
37
|
routeRules: {
|
|
38
|
-
'/**': { isr:
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
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`.
|
|
@@ -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
|
|
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
|
|
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`.
|
|
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`,
|
|
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
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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/
|
|
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
|
|
25
|
-
args: {
|
|
25
|
+
export const getFileUrl = query({
|
|
26
|
+
args: { documentId: v.id('documents') },
|
|
26
27
|
handler: async (ctx, args) => {
|
|
27
|
-
|
|
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
|
-
|
|
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
|
|
40
|
-
const urlArgs = computed(() => (
|
|
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.
|
|
51
|
+
} = useConvexQuery(api.documents.getFileUrl, urlArgs, {
|
|
47
52
|
auth: 'required',
|
|
48
53
|
})
|
|
49
54
|
```
|
|
50
55
|
|
|
51
|
-
The query is idle until a
|
|
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
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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
|
|
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`.
|