@quickback-dev/cli 0.18.0 → 0.34.1
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/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +25 -1
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/migrations.d.ts +17 -0
- package/dist/commands/migrations.d.ts.map +1 -0
- package/dist/commands/migrations.js +328 -0
- package/dist/commands/migrations.js.map +1 -0
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +33 -63
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +7 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.d.ts +17 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-loader.d.ts +39 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +73 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +22 -1
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/skill/docs/changelog.md +1118 -1
- package/dist/skill/docs/compiler/config/domains.md +70 -10
- package/dist/skill/docs/compiler/config/index.md +74 -3
- package/dist/skill/docs/compiler/config/output.md +1 -1
- package/dist/skill/docs/compiler/config/providers.md +6 -12
- package/dist/skill/docs/compiler/config/single-tenant.md +1 -1
- package/dist/skill/docs/compiler/config/variables.md +0 -30
- package/dist/skill/docs/compiler/definitions/access.md +357 -3
- package/dist/skill/docs/compiler/definitions/actions.md +85 -8
- package/dist/skill/docs/compiler/definitions/schema.md +6 -10
- package/dist/skill/docs/compiler/index.md +15 -34
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
- package/dist/skill/docs/compiler/targets/index.md +6 -34
- package/dist/skill/docs/index.md +2 -5
- package/dist/skill/docs/stack/account-ui/customization.md +2 -14
- package/dist/skill/docs/stack/account-ui/environment-variables.md +7 -1
- package/dist/skill/docs/stack/account-ui/features/admin.md +2 -2
- package/dist/skill/docs/stack/account-ui/features/avatars.md +2 -4
- package/dist/skill/docs/stack/account-ui/features/index.md +1 -1
- package/dist/skill/docs/stack/account-ui/features/organizations.md +31 -11
- package/dist/skill/docs/stack/account-ui/hooks.md +4 -0
- package/dist/skill/docs/stack/account-ui/index.md +5 -43
- package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -75
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
- package/dist/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +106 -0
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +1057 -0
- package/src/skill/docs/compiler/config/domains.md +26 -0
- package/src/skill/docs/compiler/config/index.md +74 -3
- package/src/skill/docs/compiler/config/providers.md +6 -12
- package/src/skill/docs/compiler/config/single-tenant.md +1 -1
- package/src/skill/docs/compiler/config/variables.md +0 -30
- package/src/skill/docs/compiler/definitions/access.md +357 -3
- package/src/skill/docs/compiler/definitions/actions.md +85 -8
- package/src/skill/docs/compiler/definitions/schema.md +6 -10
- package/src/skill/docs/compiler/index.md +15 -34
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
- package/src/skill/docs/compiler/targets/index.md +6 -34
- package/src/skill/docs/index.md +2 -5
- package/src/skill/docs/stack/account-ui/customization.md +2 -14
- package/src/skill/docs/stack/account-ui/environment-variables.md +7 -1
- package/src/skill/docs/stack/account-ui/features/admin.md +2 -2
- package/src/skill/docs/stack/account-ui/features/avatars.md +2 -4
- package/src/skill/docs/stack/account-ui/features/index.md +1 -1
- package/src/skill/docs/stack/account-ui/features/organizations.md +31 -11
- package/src/skill/docs/stack/account-ui/hooks.md +4 -0
- package/src/skill/docs/stack/account-ui/index.md +5 -43
- package/src/skill/docs/stack/account-ui/with-quickback.md +2 -75
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
- package/src/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
- package/src/skill/docs/stack/auth/plugins/index.md +32 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
- package/dist/skill/docs/stack/account-ui/library-usage.md +0 -257
- package/dist/skill/docs/stack/account-ui/standalone.md +0 -149
- package/dist/skill/docs/stack/account-ui/worker.md +0 -362
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
- package/src/skill/docs/stack/account-ui/library-usage.md +0 -257
- package/src/skill/docs/stack/account-ui/standalone.md +0 -149
- package/src/skill/docs/stack/account-ui/worker.md +0 -362
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Quickback Account UI
|
|
2
2
|
|
|
3
|
-
A complete authentication and account management frontend. It handles login, signup, password reset, profile management, device sessions, passkeys, organizations, and admin — so you don't have to build any of it.
|
|
3
|
+
A complete authentication and account management frontend that ships with the Quickback Stack. It handles login, signup, password reset, profile management, device sessions, passkeys, organizations, and admin — so you don't have to build any of it.
|
|
4
4
|
|
|
5
5
|
## What's Included
|
|
6
6
|
|
|
@@ -20,9 +20,9 @@ Dashboard with org switching, org creation, member invitations, role management,
|
|
|
20
20
|
|
|
21
21
|
User management dashboard — view all users, search, create accounts, ban/unban, reset passwords, and manage sessions. Only accessible to users with the `admin` role. Can be served on its own domain (e.g., `admin.example.com`) via the `adminDomain` config.
|
|
22
22
|
|
|
23
|
-
##
|
|
23
|
+
## How to Enable
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
Add `account` to your `quickback.config.ts` and compile. The compiler builds the SPA from source with your project-specific settings baked in and bundles it into your Worker.
|
|
26
26
|
|
|
27
27
|
```typescript title="quickback/quickback.config.ts"
|
|
28
28
|
export default {
|
|
@@ -53,7 +53,7 @@ That's it. The compiler:
|
|
|
53
53
|
2. Generates a `.env` file with the correct `VITE_*` variables
|
|
54
54
|
3. Builds the SPA from source with Vite (inside Docker)
|
|
55
55
|
4. Excludes routes for disabled features (compile-time tree shaking)
|
|
56
|
-
5.
|
|
56
|
+
5. Bundles the built assets into your Worker alongside the API
|
|
57
57
|
|
|
58
58
|
No manual `.env` configuration needed. No separate deployment.
|
|
59
59
|
|
|
@@ -91,42 +91,6 @@ Auth feature flags control which pages are included in the bundle:
|
|
|
91
91
|
|
|
92
92
|
When a flag is `false`, the corresponding route files are **removed before the Vite build** — they never appear in the JavaScript bundle. This keeps production bundles minimal.
|
|
93
93
|
|
|
94
|
-
## Standalone Usage
|
|
95
|
-
|
|
96
|
-
Account UI also works outside of Quickback:
|
|
97
|
-
|
|
98
|
-
### Template (own the source)
|
|
99
|
-
|
|
100
|
-
Clone the repo and customize directly:
|
|
101
|
-
|
|
102
|
-
```bash
|
|
103
|
-
npx degit Kardoe-com/quickback-better-auth-account-ui my-account-app
|
|
104
|
-
cd my-account-app
|
|
105
|
-
npm install
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
Configure via `.env` files and deploy as a standalone Cloudflare Worker. See [Standalone Usage](/stack/account-ui/standalone) for Better Auth backends or [With Quickback](/stack/account-ui/with-quickback) for Quickback-compiled backends.
|
|
109
|
-
|
|
110
|
-
### Library (npm package)
|
|
111
|
-
|
|
112
|
-
Install as a dependency:
|
|
113
|
-
|
|
114
|
-
```bash
|
|
115
|
-
npm install quickback-better-auth-account-ui
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
```tsx
|
|
119
|
-
import { AuthApp, setAppConfig } from 'quickback-better-auth-account-ui';
|
|
120
|
-
import 'quickback-better-auth-account-ui/styles.css';
|
|
121
|
-
|
|
122
|
-
setAppConfig({
|
|
123
|
-
authRoute: 'quickback',
|
|
124
|
-
name: 'My App',
|
|
125
|
-
});
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
See [Library Usage](/stack/account-ui/library-usage) for details.
|
|
129
|
-
|
|
130
94
|
## Features
|
|
131
95
|
|
|
132
96
|
- **Authentication** — Email/password, passkeys (WebAuthn), email OTP, magic links, email verification, password reset
|
|
@@ -138,9 +102,7 @@ See [Library Usage](/stack/account-ui/library-usage) for details.
|
|
|
138
102
|
|
|
139
103
|
## Next Steps
|
|
140
104
|
|
|
141
|
-
- **[With Quickback](/stack/account-ui/with-quickback)** —
|
|
142
|
-
- **[Standalone Usage](/stack/account-ui/standalone)** — Use with any Better Auth backend
|
|
143
|
-
- **[Library Usage](/stack/account-ui/library-usage)** — Import as an npm package
|
|
105
|
+
- **[With Quickback](/stack/account-ui/with-quickback)** — Configuration reference for the `account` block
|
|
144
106
|
- **[Feature Flags](/stack/account-ui/features)** — Enable and disable features
|
|
145
107
|
- **[Environment Variables](/stack/account-ui/environment-variables)** — Configuration reference
|
|
146
108
|
- **[Customization](/stack/account-ui/customization)** — Branding, labels, and theming
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# With Quickback
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Account UI is part of the Quickback Stack. The compiler builds it from source and bundles it into your Worker — there is no separate npm package or standalone deploy path.
|
|
4
4
|
|
|
5
|
-
## Compiler-Embedded
|
|
5
|
+
## Compiler-Embedded
|
|
6
6
|
|
|
7
7
|
Add `account` to your `quickback.config.ts`:
|
|
8
8
|
|
|
@@ -77,79 +77,6 @@ auth: {
|
|
|
77
77
|
|
|
78
78
|
Disabled features are excluded at compile time — their route files are removed before the Vite build. See [Configuration](/compiler/config) for all options.
|
|
79
79
|
|
|
80
|
-
## Manual Deployment
|
|
81
|
-
|
|
82
|
-
If you need Account UI as a separate Worker (not embedded in the API Worker), you can deploy it standalone.
|
|
83
|
-
|
|
84
|
-
### 1. Clone the Template
|
|
85
|
-
|
|
86
|
-
```bash
|
|
87
|
-
npx degit Kardoe-com/quickback-better-auth-account-ui my-account-app
|
|
88
|
-
cd my-account-app
|
|
89
|
-
npm install
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
### 2. Configure for Quickback
|
|
93
|
-
|
|
94
|
-
Set the auth route mode to `quickback` to match Quickback's API paths:
|
|
95
|
-
|
|
96
|
-
```bash title=".env"
|
|
97
|
-
VITE_AUTH_ROUTE=quickback
|
|
98
|
-
# One variable points at the Quickback origin — API, Account, and CMS are all derived from it.
|
|
99
|
-
VITE_QUICKBACK_URL=https://secure.example.com
|
|
100
|
-
VITE_ACCOUNT_APP_URL=https://account.example.com
|
|
101
|
-
VITE_QUICKBACK_APP_URL=https://app.example.com
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
In Quickback mode, Account UI routes requests to three API paths:
|
|
105
|
-
|
|
106
|
-
| Path | Purpose | Examples |
|
|
107
|
-
|------|---------|---------|
|
|
108
|
-
| `/auth/v1/*` | Authentication | Login, signup, sessions, passkeys |
|
|
109
|
-
| `/api/v1/*` | Data API | Organizations, API keys |
|
|
110
|
-
| `/storage/v1/*` | File storage | Avatar uploads, file management |
|
|
111
|
-
|
|
112
|
-
### 3. Configure Features
|
|
113
|
-
|
|
114
|
-
Match your `quickback.config.ts` plugins:
|
|
115
|
-
|
|
116
|
-
```bash title=".env"
|
|
117
|
-
VITE_APP_NAME=My App
|
|
118
|
-
VITE_APP_TAGLINE=Build faster, ship sooner
|
|
119
|
-
ENABLE_SIGNUP=true
|
|
120
|
-
ENABLE_ORGANIZATIONS=true
|
|
121
|
-
ENABLE_PASSKEY=true
|
|
122
|
-
ENABLE_ADMIN=true
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
### 4. Build and Deploy
|
|
126
|
-
|
|
127
|
-
```bash
|
|
128
|
-
npm run build
|
|
129
|
-
npx wrangler deploy
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
## Library Mode
|
|
133
|
-
|
|
134
|
-
Install as a dependency instead of cloning:
|
|
135
|
-
|
|
136
|
-
```bash
|
|
137
|
-
npm install quickback-better-auth-account-ui
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
```tsx
|
|
141
|
-
import { AuthApp, setAppConfig } from 'quickback-better-auth-account-ui';
|
|
142
|
-
import 'quickback-better-auth-account-ui/styles.css';
|
|
143
|
-
|
|
144
|
-
setAppConfig({
|
|
145
|
-
authRoute: 'quickback',
|
|
146
|
-
name: 'My App',
|
|
147
|
-
companyName: 'My Company',
|
|
148
|
-
});
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
See [Library Usage](/stack/account-ui/library-usage) for the complete guide.
|
|
152
|
-
|
|
153
80
|
## Next Steps
|
|
154
81
|
|
|
155
82
|
- [Configuration](/compiler/config) — CMS and Account config reference
|
|
@@ -44,6 +44,66 @@ Each email type has both HTML and plain text templates. Templates include:
|
|
|
44
44
|
- Fallback plain text versions for all email clients
|
|
45
45
|
- XSS prevention via HTML escaping and URL sanitization
|
|
46
46
|
|
|
47
|
+
### Per-Type Template Overrides
|
|
48
|
+
|
|
49
|
+
Override the default subject + HTML + text for any OTP type without forking the package. Drop a `.ts` file into `quickback/email-templates/` and reference it from `plugins.emailOtp.templates`:
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
// quickback/quickback.config.ts
|
|
53
|
+
defineAuth("better-auth", {
|
|
54
|
+
plugins: {
|
|
55
|
+
emailOtp: {
|
|
56
|
+
templates: {
|
|
57
|
+
'forget-password': './email-templates/forget-password',
|
|
58
|
+
'welcome': './email-templates/welcome',
|
|
59
|
+
},
|
|
60
|
+
},
|
|
61
|
+
},
|
|
62
|
+
});
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Each template module default-exports a function that returns `{ subject, html, text }`:
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
// quickback/email-templates/welcome.ts
|
|
69
|
+
interface Input {
|
|
70
|
+
email: string;
|
|
71
|
+
otp: string;
|
|
72
|
+
type: 'sign-in' | 'email-verification' | 'forget-password' | 'welcome';
|
|
73
|
+
name?: string;
|
|
74
|
+
appName: string;
|
|
75
|
+
appUrl: string;
|
|
76
|
+
supportEmail?: string;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export default function welcomeTemplate({ otp, name, appName, appUrl }: Input) {
|
|
80
|
+
const greeting = name ? `Hi ${name},` : 'Hi,';
|
|
81
|
+
return {
|
|
82
|
+
subject: `Welcome to ${appName} — set your password`,
|
|
83
|
+
html: `
|
|
84
|
+
<h1>Welcome to ${appName}</h1>
|
|
85
|
+
<p>${greeting} your account is ready. Use this code to set your password and sign in:</p>
|
|
86
|
+
<p style="font-size:32px;letter-spacing:8px"><b>${otp}</b></p>
|
|
87
|
+
<p>Visit <a href="${appUrl}/set-password">${appUrl}/set-password</a> to finish setup.</p>
|
|
88
|
+
`,
|
|
89
|
+
text: `${greeting}\n\nYour ${appName} code: ${otp}\n\nFinish setup at ${appUrl}/set-password`,
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Recognized keys:
|
|
95
|
+
|
|
96
|
+
| Key | When it fires |
|
|
97
|
+
|-----|---------------|
|
|
98
|
+
| `'sign-in'` | OTP sign-in flow |
|
|
99
|
+
| `'email-verification'` | Signup email verification |
|
|
100
|
+
| `'forget-password'` | Password reset request — and admin-bootstrap if `welcome` isn't set |
|
|
101
|
+
| `'welcome'` | **Synthetic** — routed when `forget-password` fires for a user with no credential row yet (the admin-plugin → bootstrap flow). Without it, those sends fall through to `forget-password`. |
|
|
102
|
+
|
|
103
|
+
Missing keys fall through to the built-in defaults from `@quickback-dev/better-auth-aws-ses`. The compiler stages each referenced file into `src/email-templates/<name>.ts` and wires the default import in `src/lib/auth.ts` — the template function is called inline from `sendVerificationOTP`, so it has access to whatever modules the file imports.
|
|
104
|
+
|
|
105
|
+
> **Provider scope.** Overrides are only honored when `email.provider: 'aws-ses'`. The Cloudflare Email path uses the helper's own template pipeline and ignores `plugins.emailOtp.templates`.
|
|
106
|
+
|
|
47
107
|
## Configuration
|
|
48
108
|
|
|
49
109
|
### Server Plugin
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# AWS SNS Plugin (SMS OTP)
|
|
2
|
+
|
|
3
|
+
`@quickback-dev/better-auth-aws-sns` is the SMS transport package Quickback wires into Better Auth's built-in `phoneNumber` plugin when you opt in to SMS OTP. It signs SNS `Publish` requests with AWS Signature V4 using the Web Crypto API — zero AWS SDK dependency, runs on Cloudflare Workers.
|
|
4
|
+
|
|
5
|
+
> **Why SMS?** Corporate email gateways aggressively filter or rewrite transactional auth emails (link previews, click-tracking, MITM scanners). For some user bases SMS is the most reliable channel for a six-digit code that has to land in under a minute.
|
|
6
|
+
|
|
7
|
+
## What it provides
|
|
8
|
+
|
|
9
|
+
The package itself does **not** register a Better Auth plugin. Better Auth's builtin [`phoneNumber`](https://www.better-auth.com/docs/plugins/phone-number) plugin owns the endpoints (`/auth/v1/phone-number/send-otp`, `/verify`, `/sign-in/phone-number`, password reset). This package fills the `sendOTP` / `sendPasswordResetOTP` callbacks and the `phoneNumberValidator` hook.
|
|
10
|
+
|
|
11
|
+
| Export | Purpose |
|
|
12
|
+
|--------|---------|
|
|
13
|
+
| `sendSMSWithSNS(config, { to, message })` | Publish to SNS with SigV4 + in-memory rate limit + E.164 validation. |
|
|
14
|
+
| `smsTemplates.otp` / `smsTemplates.passwordReset` | Short transactional SMS bodies (single GSM-7 segment). |
|
|
15
|
+
| `isValidE164(phone)` / `normalizeE164(phone)` | Phone number validators. Wired into Better Auth's `phoneNumberValidator`. |
|
|
16
|
+
|
|
17
|
+
## Enable in config
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { defineAuth, defineConfig, defineDatabase, defineRuntime } from "@quickback/compiler";
|
|
21
|
+
|
|
22
|
+
export default defineConfig({
|
|
23
|
+
name: "my-app",
|
|
24
|
+
sms: {
|
|
25
|
+
provider: "aws-sns",
|
|
26
|
+
region: "us-east-1",
|
|
27
|
+
senderId: "MyApp", // optional — non-US countries only
|
|
28
|
+
smsType: "Transactional", // default
|
|
29
|
+
},
|
|
30
|
+
providers: {
|
|
31
|
+
runtime: defineRuntime("cloudflare"),
|
|
32
|
+
database: defineDatabase("cloudflare-d1"),
|
|
33
|
+
auth: defineAuth("better-auth", {
|
|
34
|
+
emailAndPassword: { enabled: true },
|
|
35
|
+
plugins: { phoneNumber: true },
|
|
36
|
+
}),
|
|
37
|
+
},
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The compiler:
|
|
42
|
+
|
|
43
|
+
1. Adds `@quickback-dev/better-auth-aws-sns` to the generated `package.json`.
|
|
44
|
+
2. Emits a `getSNSConfig(env)` helper in `src/lib/auth.ts`.
|
|
45
|
+
3. Wires the `phoneNumber` plugin with `sendOTP`, `sendPasswordResetOTP`, and `phoneNumberValidator: isValidE164`.
|
|
46
|
+
4. Drops `AWS_SNS_REGION` / `APP_NAME` (and `SMS_SENDER_ID` / `SMS_TYPE` when set) into `[vars]` in `wrangler.toml`.
|
|
47
|
+
5. Forwards `c.executionCtx` from the Hono handler so OTP sends use `waitUntil(...)` — Better Auth advises **not** awaiting `sendOTP` to keep SMS latency out of the response.
|
|
48
|
+
|
|
49
|
+
## What you get from Better Auth's `phoneNumber` plugin
|
|
50
|
+
|
|
51
|
+
Schema (added to your user table):
|
|
52
|
+
|
|
53
|
+
| Column | Type | Notes |
|
|
54
|
+
|--------|------|-------|
|
|
55
|
+
| `phoneNumber` | `string \| null` | E.164 format |
|
|
56
|
+
| `phoneNumberVerified` | `boolean` | Set on successful verify |
|
|
57
|
+
|
|
58
|
+
Endpoints:
|
|
59
|
+
|
|
60
|
+
| Method | Path | Purpose |
|
|
61
|
+
|--------|------|---------|
|
|
62
|
+
| `POST` | `/auth/v1/phone-number/send-otp` | Trigger an OTP SMS |
|
|
63
|
+
| `POST` | `/auth/v1/phone-number/verify` | Verify the OTP code |
|
|
64
|
+
| `POST` | `/auth/v1/sign-in/phone-number` | Phone + password sign-in |
|
|
65
|
+
| `POST` | `/auth/v1/phone-number/request-password-reset` | Send a reset OTP |
|
|
66
|
+
| `POST` | `/auth/v1/phone-number/reset-password` | Complete password reset |
|
|
67
|
+
|
|
68
|
+
Defaults: 6-digit codes, 300s expiry, 3 verify attempts (exceeding deletes the OTP and returns 403). See the [Better Auth plugin docs](https://www.better-auth.com/docs/plugins/phone-number) for the full option surface.
|
|
69
|
+
|
|
70
|
+
## Required environment variables
|
|
71
|
+
|
|
72
|
+
Wrangler `[vars]` (non-secret, emitted by the compiler):
|
|
73
|
+
|
|
74
|
+
| Name | Default | Notes |
|
|
75
|
+
|------|---------|-------|
|
|
76
|
+
| `AWS_SNS_REGION` | `us-east-1` | Any SNS-enabled region. |
|
|
77
|
+
| `APP_NAME` | `<your config.name>` | Appears in the SMS body. |
|
|
78
|
+
| `SMS_SENDER_ID` | — | Optional. Set only for non-US/CA traffic. |
|
|
79
|
+
| `SMS_TYPE` | `Transactional` | Override only to send promotional traffic. |
|
|
80
|
+
|
|
81
|
+
Secrets (set with `wrangler secret put`):
|
|
82
|
+
|
|
83
|
+
| Name | Required | Notes |
|
|
84
|
+
|------|----------|-------|
|
|
85
|
+
| `AWS_ACCESS_KEY_ID` | yes | IAM key with `sns:Publish`. Shared with SES if used. |
|
|
86
|
+
| `AWS_SECRET_ACCESS_KEY` | yes | Companion secret. |
|
|
87
|
+
|
|
88
|
+
## AWS prerequisites
|
|
89
|
+
|
|
90
|
+
Before SMS will actually deliver in production, do this in the AWS console:
|
|
91
|
+
|
|
92
|
+
1. **Pull out of the SNS sandbox.** New accounts can only send to verified numbers and have a low monthly cap. Submit a "Request production access" case from the SNS SMS Preferences page.
|
|
93
|
+
2. **Set a monthly spend cap.** SMS gets expensive fast — set a limit before you go live.
|
|
94
|
+
3. **US A2P (10DLC).** Long codes sending app-to-person SMS to US numbers must be registered with TCR (The Campaign Registry) via Pinpoint SMS Voice v2. Carrier filtering rejects unregistered A2P traffic. Allow several weeks for approval.
|
|
95
|
+
4. **Sender ID support.** Alphanumeric sender IDs work in many countries (UK, France, Germany, India, etc.) but **not** the US or Canada. Pick origination identities per country.
|
|
96
|
+
5. **IAM policy.** The access key needs `sns:Publish` on `*` plus `sns:SetSMSAttributes` if you want to manage the spend cap programmatically.
|
|
97
|
+
|
|
98
|
+
## Validation and rate limiting
|
|
99
|
+
|
|
100
|
+
- **E.164 only.** `isValidE164` rejects anything that's not `+[country code][7–14 digits]`. There is no automatic country-code inference — capture the country in your UI (e.g. `react-phone-number-input`).
|
|
101
|
+
- **Send-side rate limit.** The package's in-memory map caps sends per phone (hourly + daily) when `rateLimit` is set on the config. It's an isolate-local guard; for stricter limits put a KV-backed limiter in front of `/auth/v1/phone-number/send-otp`.
|
|
102
|
+
- **Verify-side rate limit.** Better Auth's `phoneNumber` plugin enforces 3 attempts before deleting the OTP. You can additionally tighten Quickback's per-route limit on `/auth/v1/phone-number/send-otp` via `auth.rateLimit.customRules`.
|
|
103
|
+
|
|
104
|
+
## Carrier filtering
|
|
105
|
+
|
|
106
|
+
Keep the SMS body short, transactional, and link-free. The default template is:
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
Your <AppName> code is 123456. Expires in 5 min. Don't share it.
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
— under 80 characters, no URL, no marketing copy. Carriers filter long messages, links, and brand-imitation prefixes aggressively. If you customize the body, keep it under one GSM-7 segment (160 chars) to avoid multi-segment billing.
|
|
113
|
+
|
|
114
|
+
## Verifying the wiring
|
|
115
|
+
|
|
116
|
+
After compile, check the generated `src/lib/auth.ts`:
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
import { sendSMSWithSNS, smsTemplates, isValidE164 } from "@quickback-dev/better-auth-aws-sns";
|
|
120
|
+
|
|
121
|
+
function getSNSConfig(env: CloudflareBindings | undefined): SNSConfig { /* ... */ }
|
|
122
|
+
|
|
123
|
+
function createAuth(env, cf, executionCtx) {
|
|
124
|
+
const fireAndForget = (p) => { /* waitUntil(p) */ };
|
|
125
|
+
|
|
126
|
+
return betterAuth({
|
|
127
|
+
plugins: [
|
|
128
|
+
phoneNumber({
|
|
129
|
+
phoneNumberValidator: isValidE164,
|
|
130
|
+
sendOTP: async ({ phoneNumber, code }) => {
|
|
131
|
+
fireAndForget(sendSMSWithSNS(getSNSConfig(env), {
|
|
132
|
+
to: phoneNumber,
|
|
133
|
+
message: smsTemplates.otp.message({ code, appName: ... }),
|
|
134
|
+
}));
|
|
135
|
+
},
|
|
136
|
+
// ...
|
|
137
|
+
}),
|
|
138
|
+
],
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
That's the contract: callbacks are fire-and-forget via `executionCtx.waitUntil`, never `await`ed.
|
|
144
|
+
|
|
145
|
+
## Sign-in flow
|
|
146
|
+
|
|
147
|
+
```ts
|
|
148
|
+
// 1. Request OTP
|
|
149
|
+
await fetch('/auth/v1/phone-number/send-otp', {
|
|
150
|
+
method: 'POST',
|
|
151
|
+
headers: { 'Content-Type': 'application/json' },
|
|
152
|
+
body: JSON.stringify({ phoneNumber: '+14155550100' }),
|
|
153
|
+
});
|
|
154
|
+
|
|
155
|
+
// 2. Verify the code the user types in
|
|
156
|
+
const res = await fetch('/auth/v1/phone-number/verify', {
|
|
157
|
+
method: 'POST',
|
|
158
|
+
headers: { 'Content-Type': 'application/json' },
|
|
159
|
+
body: JSON.stringify({ phoneNumber: '+14155550100', code: '123456' }),
|
|
160
|
+
});
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
For Better Auth's signed-in client SDK, use `authClient.phoneNumber.sendOtp(...)` / `authClient.phoneNumber.verify(...)`.
|
|
164
|
+
|
|
165
|
+
## Compliance reminders
|
|
166
|
+
|
|
167
|
+
- **TCPA (US).** Capture explicit opt-in for transactional SMS at signup; keep an audit trail. STOP / HELP keyword handling is mandatory for A2P traffic — SNS handles standard keywords automatically on registered origination numbers, but verify it's enabled.
|
|
168
|
+
- **GDPR (EU).** Phone numbers are personal data. Use Quickback's masking pillar to redact them in CMS views where appropriate.
|
|
169
|
+
- **Don't use SMS as your only second factor.** SIM-swap attacks are real; pair phone OTP with passkeys / TOTP for high-value accounts.
|
|
@@ -64,6 +64,38 @@ auth: defineAuth("better-auth", {
|
|
|
64
64
|
|
|
65
65
|
**Note:** If you send `Content-Type: application/json`, include a body (an empty `{}` is fine). This avoids request parsing errors in some clients.
|
|
66
66
|
|
|
67
|
+
### SMS OTP (with AWS SNS)
|
|
68
|
+
|
|
69
|
+
When `phoneNumber` is enabled, the compiler wires Better Auth's built-in `phoneNumber` plugin to AWS SNS for SMS delivery via [`@quickback-dev/better-auth-aws-sns`](/stack/auth/plugins/aws-sns). The plugin adds `phoneNumber` / `phoneNumberVerified` columns to the user table, handles OTP generation + storage + verify-attempt limits, and exposes endpoints for phone-only sign-in, phone+password sign-in, and password reset via SMS.
|
|
70
|
+
|
|
71
|
+
**Enable in config:**
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
export default defineConfig({
|
|
75
|
+
name: "my-app",
|
|
76
|
+
sms: {
|
|
77
|
+
provider: "aws-sns",
|
|
78
|
+
region: "us-east-1",
|
|
79
|
+
},
|
|
80
|
+
providers: {
|
|
81
|
+
runtime: defineRuntime("cloudflare"),
|
|
82
|
+
database: defineDatabase("cloudflare-d1"),
|
|
83
|
+
auth: defineAuth("better-auth", {
|
|
84
|
+
plugins: { phoneNumber: true },
|
|
85
|
+
}),
|
|
86
|
+
},
|
|
87
|
+
});
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**Endpoints (managed by Better Auth):**
|
|
91
|
+
- `POST /auth/v1/phone-number/send-otp`
|
|
92
|
+
- `POST /auth/v1/phone-number/verify`
|
|
93
|
+
- `POST /auth/v1/sign-in/phone-number`
|
|
94
|
+
- `POST /auth/v1/phone-number/request-password-reset`
|
|
95
|
+
- `POST /auth/v1/phone-number/reset-password`
|
|
96
|
+
|
|
97
|
+
**Why use SMS:** corporate email gateways frequently break transactional auth emails (link rewriting, click-tracking, MITM scanners). SMS is the most reliable channel for a six-digit code that has to land in under a minute. See the [AWS SNS plugin page](/stack/auth/plugins/aws-sns) for IAM, 10DLC registration, and sender-ID details.
|
|
98
|
+
|
|
67
99
|
### AWS SES Plugin
|
|
68
100
|
|
|
69
101
|
This is a Quickback-provided Better Auth plugin for Email OTP and other transactional emails. It handles SES signing and delivery over the Web Crypto API so it runs in Cloudflare Workers without the AWS SDK. It is wired up only when you opt in via `email.provider: 'aws-ses'` — the default transport is Cloudflare Email Sending (`send_email` binding).
|
|
@@ -1,55 +0,0 @@
|
|
|
1
|
-
# Quickback for Supabase RLS
|
|
2
|
-
|
|
3
|
-
**Quickback for Supabase RLS** compiles the same `defineTable()` definitions into PostgreSQL Row Level Security policies for Supabase. You keep Supabase Auth, Storage, and Realtime — Quickback adds the database-level security layer.
|
|
4
|
-
|
|
5
|
-
## Who this is for
|
|
6
|
-
|
|
7
|
-
You're already on Supabase (or want to be) and you want:
|
|
8
|
-
|
|
9
|
-
- **Database-level security** — RLS policies enforced even if a service role key leaks
|
|
10
|
-
- **A type-safe DSL** — write security rules in TypeScript, compile to SQL
|
|
11
|
-
- **One source of truth** — the same `firewall` and `access` config that powers a Quickback Hono API also generates RLS policies
|
|
12
|
-
|
|
13
|
-
What you don't get from this target: generated API routes, batch endpoints, OpenAPI spec, MCP server. Those live with [Quickback for Hono API](/compiler/targets/hono-api). For Supabase you bring your own application code (PostgREST, Edge Functions, or your own server) and the RLS policies enforce security beneath it.
|
|
14
|
-
|
|
15
|
-
## What compiles to RLS
|
|
16
|
-
|
|
17
|
-
| Definition | Compiles to |
|
|
18
|
-
|------------|-------------|
|
|
19
|
-
| `defineTable({ schema })` | `CREATE TABLE` + Drizzle schema |
|
|
20
|
-
| `firewall: [...]` | `FOR ALL USING` policies (data isolation) |
|
|
21
|
-
| `access.roles: [...]` | `FOR SELECT/INSERT/UPDATE/DELETE USING` policies (role checks) |
|
|
22
|
-
| `defineActions()` | **Not compiled** — implement in Edge Functions or your app |
|
|
23
|
-
| `views` | **Not compiled** — use Postgres views or column lists |
|
|
24
|
-
| `masking` | **Not compiled** — runtime concern, handle in app code |
|
|
25
|
-
| `guards` | **Not compiled** — runtime concern, handle in app code |
|
|
26
|
-
|
|
27
|
-
See [Mappings](/compiler/targets/supabase-rls/mappings) for full examples and [Limitations](/compiler/targets/supabase-rls/limitations) for what to handle in app code.
|
|
28
|
-
|
|
29
|
-
## Quick start
|
|
30
|
-
|
|
31
|
-
```typescript title="quickback/quickback.config.ts"
|
|
32
|
-
import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickback/compiler";
|
|
33
|
-
|
|
34
|
-
export default defineConfig({
|
|
35
|
-
name: "my-app",
|
|
36
|
-
providers: {
|
|
37
|
-
runtime: defineRuntime("supabase"),
|
|
38
|
-
database: defineDatabase("supabase"),
|
|
39
|
-
auth: defineAuth("supabase-auth"),
|
|
40
|
-
},
|
|
41
|
-
});
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
|
-
quickback compile
|
|
46
|
-
supabase db push
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
The compiler emits RLS migrations under `supabase/migrations/`. See [Setup](/compiler/targets/supabase-rls/setup) for the full flow.
|
|
50
|
-
|
|
51
|
-
## In this section
|
|
52
|
-
|
|
53
|
-
- **[Setup](/compiler/targets/supabase-rls/setup)** — Configure the target, compile, apply migrations
|
|
54
|
-
- **[Mappings](/compiler/targets/supabase-rls/mappings)** — Which definitions become which RLS policies
|
|
55
|
-
- **[Limitations](/compiler/targets/supabase-rls/limitations)** — What doesn't compile and how to handle it
|
|
@@ -1,48 +0,0 @@
|
|
|
1
|
-
# Limitations
|
|
2
|
-
|
|
3
|
-
The Supabase target compiles **schema, firewall, and access** to RLS. The other Quickback primitives are runtime concerns that RLS can't express. This page lists what doesn't compile and where to handle it.
|
|
4
|
-
|
|
5
|
-
## Actions
|
|
6
|
-
|
|
7
|
-
`defineActions()` describes custom endpoints with input validation, role checks, and side effects. RLS only governs row access, not arbitrary procedures.
|
|
8
|
-
|
|
9
|
-
**Where to handle them:**
|
|
10
|
-
|
|
11
|
-
- **Supabase Edge Functions** — port the action body to a TypeScript Deno function. Role checks happen in the function; the underlying database mutations still pass through your RLS policies.
|
|
12
|
-
- **Postgres functions** — for simple state transitions, write a `CREATE FUNCTION` and call it via `supabase.rpc()`. Use `SECURITY INVOKER` (the default) so RLS still applies.
|
|
13
|
-
- **Your application server** — any backend you already run can host the action, with the JWT forwarded to Supabase for the underlying writes.
|
|
14
|
-
|
|
15
|
-
## Views
|
|
16
|
-
|
|
17
|
-
Quickback `views` define column-level projections per role (e.g. "members see name + email; admins also see salary"). RLS gates rows, not columns.
|
|
18
|
-
|
|
19
|
-
**Where to handle them:**
|
|
20
|
-
|
|
21
|
-
- **Postgres views** — `CREATE VIEW` with `SELECT` lists matching each Quickback view. Apply RLS to the view or the underlying table.
|
|
22
|
-
- **Column lists in queries** — pass the projection at the application layer: `supabase.from('users').select('id, name, email')`.
|
|
23
|
-
- **Column-level grants** — `GRANT SELECT (col1, col2) ON table TO role` for fine-grained server-side restriction.
|
|
24
|
-
|
|
25
|
-
## Masking
|
|
26
|
-
|
|
27
|
-
Masking redacts sensitive fields per role at response time (email → `j***@example.com`, SSN → `***-**-1234`). This is purely a runtime transformation — the data is in the row, RLS just decides whether the row is returned.
|
|
28
|
-
|
|
29
|
-
**Where to handle it:**
|
|
30
|
-
|
|
31
|
-
- **Edge Functions or your server** — apply the mask in the layer that serializes the response.
|
|
32
|
-
- **Postgres functions** — for SQL-driven masking, write a wrapper view or function that applies the mask conditionally on `auth.jwt() ->> 'role'`.
|
|
33
|
-
|
|
34
|
-
## Guards
|
|
35
|
-
|
|
36
|
-
`guards` block field modifications based on row state, role, or external context (e.g. "members can change `notes` but not `status`; only admins can set `archived`"). Some of this can be expressed with RLS `WITH CHECK`, but the full Quickback guard model is richer than RLS supports.
|
|
37
|
-
|
|
38
|
-
**Where to handle them:**
|
|
39
|
-
|
|
40
|
-
- **`WITH CHECK` clauses** — simple field-level guards (e.g. "only admins can set `archived = true`") can sometimes be expressed via more granular `FOR UPDATE` policies.
|
|
41
|
-
- **Triggers** — `BEFORE UPDATE` triggers can `RAISE EXCEPTION` if a guarded field is modified by a non-eligible role.
|
|
42
|
-
- **Edge Functions / app server** — for anything stateful or context-dependent, validate guards in the layer that issues the update.
|
|
43
|
-
|
|
44
|
-
## Generated API routes, batch ops, OpenAPI, MCP
|
|
45
|
-
|
|
46
|
-
These are Hono-target features. The Supabase target doesn't generate application code — your app talks to Supabase directly (PostgREST, Edge Functions, or your own server).
|
|
47
|
-
|
|
48
|
-
If you want generated routes alongside RLS, consider compiling to the [Hono target with Neon](/compiler/targets/hono-api/database/neon), which gives you both the generated API and database-level RLS.
|
|
@@ -1,99 +0,0 @@
|
|
|
1
|
-
# Mappings
|
|
2
|
-
|
|
3
|
-
This page shows how each Quickback primitive maps to RLS policy SQL. The same `firewall` and `access` config used by the [Hono target](/compiler/targets/hono-api) generates these policies — no Supabase-specific re-authoring required.
|
|
4
|
-
|
|
5
|
-
## Schema → Tables
|
|
6
|
-
|
|
7
|
-
`defineTable({ schema })` compiles to a Drizzle PostgreSQL schema and a `CREATE TABLE` statement. RLS is enabled on the table by default:
|
|
8
|
-
|
|
9
|
-
```sql
|
|
10
|
-
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
## Firewall → `FOR ALL USING`
|
|
14
|
-
|
|
15
|
-
Firewall rules isolate data by tenant or owner. They become a single `FOR ALL USING` policy applied to every operation.
|
|
16
|
-
|
|
17
|
-
**Org-scoped:**
|
|
18
|
-
|
|
19
|
-
```typescript
|
|
20
|
-
firewall: [
|
|
21
|
-
{ field: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
22
|
-
]
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
```sql
|
|
26
|
-
CREATE POLICY "projects_firewall" ON projects FOR ALL
|
|
27
|
-
USING (organization_id = public.get_active_org_id());
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
**User-scoped:**
|
|
31
|
-
|
|
32
|
-
```typescript
|
|
33
|
-
firewall: [
|
|
34
|
-
{ field: 'userId', equals: 'ctx.userId' },
|
|
35
|
-
]
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
```sql
|
|
39
|
-
CREATE POLICY "preferences_firewall" ON preferences FOR ALL
|
|
40
|
-
USING (user_id = auth.uid());
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
## Access → `FOR SELECT/INSERT/UPDATE/DELETE USING`
|
|
44
|
-
|
|
45
|
-
Access rules layer role-based checks on top of the firewall. Each operation gets its own policy.
|
|
46
|
-
|
|
47
|
-
```typescript
|
|
48
|
-
access: {
|
|
49
|
-
roles: ['admin', 'member'],
|
|
50
|
-
list: { roles: ['admin', 'member'] },
|
|
51
|
-
create: { roles: ['admin'] },
|
|
52
|
-
update: { roles: ['admin'] },
|
|
53
|
-
delete: { roles: ['admin'] },
|
|
54
|
-
}
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
```sql
|
|
58
|
-
CREATE POLICY "projects_select" ON projects FOR SELECT
|
|
59
|
-
USING (
|
|
60
|
-
organization_id = public.get_active_org_id()
|
|
61
|
-
AND public.has_any_role(ARRAY['admin', 'member'])
|
|
62
|
-
);
|
|
63
|
-
|
|
64
|
-
CREATE POLICY "projects_insert" ON projects FOR INSERT
|
|
65
|
-
WITH CHECK (
|
|
66
|
-
organization_id = public.get_active_org_id()
|
|
67
|
-
AND public.has_any_role(ARRAY['admin'])
|
|
68
|
-
);
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
## Defense in depth — anon deny
|
|
72
|
-
|
|
73
|
-
Every generated table gets an explicit deny policy for the `anon` role:
|
|
74
|
-
|
|
75
|
-
```sql
|
|
76
|
-
CREATE POLICY "projects_deny_anon" ON projects FOR ALL
|
|
77
|
-
TO anon
|
|
78
|
-
USING (false);
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
Unauthenticated requests are blocked at the database level even if a policy elsewhere is misconfigured.
|
|
82
|
-
|
|
83
|
-
## Helper functions
|
|
84
|
-
|
|
85
|
-
Quickback emits a set of helper functions in `0100_create_rls_helpers.sql` that the policies reference:
|
|
86
|
-
|
|
87
|
-
| Function | Purpose |
|
|
88
|
-
|----------|---------|
|
|
89
|
-
| `get_active_org_id()` | Returns the user's active organization from `user_sessions` |
|
|
90
|
-
| `has_any_role(roles[])` | Checks if the user has any of the listed roles in the active org |
|
|
91
|
-
| `has_org_role(role)` | Checks for a single specific role |
|
|
92
|
-
| `is_org_member()` | Checks org membership |
|
|
93
|
-
| `get_user_role()` | Returns the user's role in the active org |
|
|
94
|
-
|
|
95
|
-
These are used by the generated policies but you can also call them from views, triggers, or stored procedures.
|
|
96
|
-
|
|
97
|
-
## What does not compile
|
|
98
|
-
|
|
99
|
-
`defineActions()`, `views`, `masking`, and runtime `guards` do **not** become RLS — see [Limitations](/compiler/targets/supabase-rls/limitations).
|