@quickback-dev/cli 0.31.1 → 0.34.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 (41) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +9 -1
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/migrations.d.ts +17 -0
  5. package/dist/commands/migrations.d.ts.map +1 -0
  6. package/dist/commands/migrations.js +328 -0
  7. package/dist/commands/migrations.js.map +1 -0
  8. package/dist/docs/content.d.ts.map +1 -1
  9. package/dist/docs/content.js +15 -10
  10. package/dist/docs/content.js.map +1 -1
  11. package/dist/index.js +7 -1
  12. package/dist/index.js.map +1 -1
  13. package/dist/lib/file-loader.d.ts +15 -0
  14. package/dist/lib/file-loader.d.ts.map +1 -1
  15. package/dist/lib/file-loader.js +27 -0
  16. package/dist/lib/file-loader.js.map +1 -1
  17. package/dist/lib/file-loader.test.js +22 -1
  18. package/dist/lib/file-loader.test.js.map +1 -1
  19. package/dist/skill/docs/changelog.md +758 -0
  20. package/dist/skill/docs/compiler/config/domains.md +26 -0
  21. package/dist/skill/docs/compiler/config/index.md +74 -3
  22. package/dist/skill/docs/compiler/config/single-tenant.md +1 -1
  23. package/dist/skill/docs/compiler/definitions/access.md +161 -9
  24. package/dist/skill/docs/compiler/definitions/actions.md +45 -1
  25. package/dist/skill/docs/stack/account-ui/features/admin.md +2 -2
  26. package/dist/skill/docs/stack/account-ui/hooks.md +4 -0
  27. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
  28. package/dist/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
  29. package/dist/skill/docs/stack/auth/plugins/index.md +32 -0
  30. package/package.json +1 -1
  31. package/src/skill/docs/changelog.md +758 -0
  32. package/src/skill/docs/compiler/config/domains.md +26 -0
  33. package/src/skill/docs/compiler/config/index.md +74 -3
  34. package/src/skill/docs/compiler/config/single-tenant.md +1 -1
  35. package/src/skill/docs/compiler/definitions/access.md +161 -9
  36. package/src/skill/docs/compiler/definitions/actions.md +45 -1
  37. package/src/skill/docs/stack/account-ui/features/admin.md +2 -2
  38. package/src/skill/docs/stack/account-ui/hooks.md +4 -0
  39. package/src/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
  40. package/src/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
  41. package/src/skill/docs/stack/auth/plugins/index.md +32 -0
@@ -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).