@quickback-dev/cli 0.64.2 → 0.65.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/index.js +1 -1
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +6 -1
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/action-harvest.test.js +19 -0
- package/dist/lib/action-harvest.test.js.map +1 -1
- package/dist/lib/compiler-stubs.d.ts +10 -0
- package/dist/lib/compiler-stubs.d.ts.map +1 -1
- package/dist/lib/compiler-stubs.js +16 -0
- package/dist/lib/compiler-stubs.js.map +1 -1
- package/dist/lib/file-writer.js +23 -0
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/file-writer.test.js +25 -0
- package/dist/lib/file-writer.test.js.map +1 -1
- package/dist/skill/docs/api/actions.md +6 -20
- package/dist/skill/docs/changelog/index.md +53 -2
- package/dist/skill/docs/configure/bindings.md +1 -1
- package/dist/skill/docs/configure/domains.md +15 -2
- package/dist/skill/docs/configure/variables.md +2 -2
- package/dist/skill/docs/define/actions/defining.md +12 -0
- package/dist/skill/docs/define/sealed-protocol.md +1 -1
- package/dist/skill/docs/platform/auth/plugins/aws-ses.md +6 -18
- package/dist/skill/docs/platform/auth/plugins/aws-sns.md +4 -4
- package/dist/skill/docs/platform/auth/plugins/index.md +10 -3
- package/dist/skill/docs/platform/realtime/index.md +2 -1
- package/dist/skill/docs/platform/realtime/using-realtime.md +7 -5
- package/dist/skill/docs/platform/storage/r2.md +12 -0
- package/dist/skill/docs/start/template-cloudflare.md +1 -1
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +6 -20
- package/src/skill/docs/changelog/index.md +53 -2
- package/src/skill/docs/configure/bindings.md +1 -1
- package/src/skill/docs/configure/domains.md +15 -2
- package/src/skill/docs/configure/variables.md +2 -2
- package/src/skill/docs/define/actions/defining.md +12 -0
- package/src/skill/docs/define/sealed-protocol.md +1 -1
- package/src/skill/docs/platform/auth/plugins/aws-ses.md +6 -18
- package/src/skill/docs/platform/auth/plugins/aws-sns.md +4 -4
- package/src/skill/docs/platform/auth/plugins/index.md +10 -3
- package/src/skill/docs/platform/realtime/index.md +2 -1
- package/src/skill/docs/platform/realtime/using-realtime.md +7 -5
- package/src/skill/docs/platform/storage/r2.md +12 -0
- package/src/skill/docs/start/template-cloudflare.md +1 -1
|
@@ -145,6 +145,18 @@ evaluated for real, so a derivation in that file happens to work. Whether it
|
|
|
145
145
|
works depends on unrelated content in the table file — declare the shape
|
|
146
146
|
instead.
|
|
147
147
|
|
|
148
|
+
**`output` describes the success path only.** Error responses never pass
|
|
149
|
+
through it: throw
|
|
150
|
+
[`ActionError`](/api/actions#error-handling) and the route returns
|
|
151
|
+
`{ error, code, details }` with your status code — that error envelope is part
|
|
152
|
+
of the generated contract already, so do not fold error variants into
|
|
153
|
+
`output`. The one exception is an endpoint whose *success* body is
|
|
154
|
+
deliberately a status report (a webhook receiver acknowledging
|
|
155
|
+
`{ received: false, reason }`, say) — that is a union of success shapes, and
|
|
156
|
+
declaring it as `z.discriminatedUnion(...)` in `output` is correct. Do not
|
|
157
|
+
return an error object (or a `Response`) from `execute` to signal failure —
|
|
158
|
+
see [Error Handling](/api/actions#error-handling) for what actually happens.
|
|
159
|
+
|
|
148
160
|
Parameterized standalone paths use Hono's `:param` syntax in authored source,
|
|
149
161
|
for example `path: "/events/:eventId/check-in"`. The harvest planner converts
|
|
150
162
|
those segments to the OpenAPI `{param}` form before applying the schema, so
|
|
@@ -269,7 +269,7 @@ When the passkey plugin is enabled, `/reveal` verifies a WebAuthn assertion whos
|
|
|
269
269
|
| Field | Value |
|
|
270
270
|
|---|---|
|
|
271
271
|
| `challenge` | the `/challenge` `nonce` **as the base64url string** (the client signs the b64url text, the server passes `expectedChallenge = nonce`) |
|
|
272
|
-
| `rpID` | the passkey plugin's `rpID` — i.e. `crossSubDomainCookies.domain` (leading dot stripped) when configured, else the host of `env.ACCOUNT_URL
|
|
272
|
+
| `rpID` | the passkey plugin's `rpID` — i.e. `crossSubDomainCookies.domain` (leading dot stripped) when configured, else the registrable host of `env.ACCOUNT_URL`, else the compile-time account origin (both emissions share one resolution, so they cannot skew) |
|
|
273
273
|
| `userVerification` | **required** (`requireUserVerification: true` — a reveal is a deliberate re-auth) |
|
|
274
274
|
| origin | the resolved account origin (mirrors the `passkey({ rpID, origin })` plugin) |
|
|
275
275
|
|
|
@@ -1,16 +1,14 @@
|
|
|
1
1
|
# AWS SES Plugin
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Quickback's AWS SES plugin sends transactional emails via AWS SES. It handles AWS Signature V4 signing, HTML/text email templates, and rate limiting — designed to work in Cloudflare Workers (no Node.js `aws-sdk` dependency).
|
|
4
4
|
|
|
5
5
|
> **Cloudflare Email is the default.** As of the Cloudflare Email Sending public beta, the zero-config `send_email` binding is Quickback's default transport for Cloudflare deploys — no API keys, no SES setup. See [Email Configuration](/configure#email-configuration). Use AWS SES when you need it (non-Cloudflare runtimes, existing SES infra, or specific deliverability/compliance requirements).
|
|
6
6
|
|
|
7
7
|
## Installation
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
npm install @quickback-dev/better-auth-aws-ses
|
|
11
|
-
```
|
|
9
|
+
None. The compiler bundles the plugin source and emits it into your project at `src/plugins/aws-ses/` — it is **not** an npm dependency, and upgrades arrive by recompiling, not by `npm update`.
|
|
12
10
|
|
|
13
|
-
|
|
11
|
+
The plugin is wired up only when you explicitly opt in via `email.provider: 'aws-ses'` in your Quickback config. Without that, `email.provider` defaults to `'cloudflare'` and the Cloudflare Email helper is used instead.
|
|
14
12
|
|
|
15
13
|
## Email Types
|
|
16
14
|
|
|
@@ -95,16 +93,16 @@ Recognized keys:
|
|
|
95
93
|
| `'forget-password'` | Password reset request — and admin-bootstrap if `welcome` isn't set |
|
|
96
94
|
| `'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`. |
|
|
97
95
|
|
|
98
|
-
Missing keys fall through to the built-in defaults from
|
|
96
|
+
Missing keys fall through to the built-in defaults from the vendored plugin (`src/plugins/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.
|
|
99
97
|
|
|
100
98
|
> **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`.
|
|
101
99
|
|
|
102
100
|
## Configuration
|
|
103
101
|
|
|
104
|
-
|
|
102
|
+
The compiler wires the plugin into `src/lib/auth.ts` automatically. The generated `getSESConfig(env)` maps environment to the vendored plugin's options:
|
|
105
103
|
|
|
106
104
|
```typescript
|
|
107
|
-
import { awsSESPlugin } from "
|
|
105
|
+
import { awsSESPlugin } from "../plugins/aws-ses";
|
|
108
106
|
|
|
109
107
|
const auth = betterAuth({
|
|
110
108
|
plugins: [
|
|
@@ -122,16 +120,6 @@ const auth = betterAuth({
|
|
|
122
120
|
});
|
|
123
121
|
```
|
|
124
122
|
|
|
125
|
-
### Client Plugin
|
|
126
|
-
|
|
127
|
-
```typescript
|
|
128
|
-
import { awsSESClientPlugin } from "@quickback-dev/better-auth-aws-ses/client";
|
|
129
|
-
|
|
130
|
-
const authClient = createAuthClient({
|
|
131
|
-
plugins: [awsSESClientPlugin()],
|
|
132
|
-
});
|
|
133
|
-
```
|
|
134
|
-
|
|
135
123
|
## Required Environment Variables
|
|
136
124
|
|
|
137
125
|
| Variable | Description |
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# AWS SNS Plugin (SMS OTP)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The AWS SNS transport is what Quickback wires into Better Auth's built-in `phoneNumber` plugin when you opt in to SMS OTP. The compiler emits its source into your project at `src/plugins/aws-sns/` — it is not an npm dependency. It signs SNS `Publish` requests with AWS Signature V4 using the Web Crypto API — zero AWS SDK dependency, runs on Cloudflare Workers.
|
|
4
4
|
|
|
5
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
6
|
|
|
7
7
|
## What it provides
|
|
8
8
|
|
|
9
|
-
The
|
|
9
|
+
The transport 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
10
|
|
|
11
11
|
| Export | Purpose |
|
|
12
12
|
|--------|---------|
|
|
@@ -40,7 +40,7 @@ export default defineConfig({
|
|
|
40
40
|
|
|
41
41
|
The compiler:
|
|
42
42
|
|
|
43
|
-
1.
|
|
43
|
+
1. Emits the plugin source into `src/plugins/aws-sns/` — vendored, not an npm dependency; upgrades arrive by recompiling.
|
|
44
44
|
2. Emits a `getSNSConfig(env)` helper in `src/lib/auth.ts`.
|
|
45
45
|
3. Wires the `phoneNumber` plugin with `sendOTP`, `sendPasswordResetOTP`, and `phoneNumberValidator: isValidE164`.
|
|
46
46
|
4. Drops `AWS_SNS_REGION` / `APP_NAME` (and `SMS_SENDER_ID` / `SMS_TYPE` when set) into `[vars]` in `wrangler.toml`.
|
|
@@ -116,7 +116,7 @@ Your <AppName> code is 123456. Expires in 5 min. Don't share it.
|
|
|
116
116
|
After compile, check the generated `src/lib/auth.ts`:
|
|
117
117
|
|
|
118
118
|
```ts
|
|
119
|
-
import { sendSMSWithSNS, smsTemplates, isValidE164 } from "
|
|
119
|
+
import { sendSMSWithSNS, smsTemplates, isValidE164 } from "../plugins/aws-sns";
|
|
120
120
|
|
|
121
121
|
function getSNSConfig(env: CloudflareBindings | undefined): SNSConfig { /* ... */ }
|
|
122
122
|
|
|
@@ -76,7 +76,7 @@ auth: defineAuth("better-auth", {
|
|
|
76
76
|
|
|
77
77
|
### SMS OTP (with AWS SNS)
|
|
78
78
|
|
|
79
|
-
When `phoneNumber` is enabled, the compiler wires Better Auth's built-in `phoneNumber` plugin to AWS SNS for SMS delivery via [
|
|
79
|
+
When `phoneNumber` is enabled, the compiler wires Better Auth's built-in `phoneNumber` plugin to AWS SNS for SMS delivery via the vendored [AWS SNS transport](/platform/auth/plugins/aws-sns) (emitted into `src/plugins/aws-sns/`, not installed from npm). 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.
|
|
80
80
|
|
|
81
81
|
**Enable in config:**
|
|
82
82
|
|
|
@@ -193,8 +193,15 @@ auth: defineAuth("better-auth", {
|
|
|
193
193
|
}),
|
|
194
194
|
```
|
|
195
195
|
|
|
196
|
-
**
|
|
197
|
-
|
|
196
|
+
**Relying party resolution:**
|
|
197
|
+
|
|
198
|
+
WebAuthn needs a relying party ID and origin. The generated plugin resolves them in this order:
|
|
199
|
+
|
|
200
|
+
1. `advanced.crossSubDomainCookies.domain` (leading dot stripped) becomes the `rpID` when configured — credentials then work across sibling subdomains.
|
|
201
|
+
2. The `ACCOUNT_URL` env var, when set on the deploy target: `rpID` is its registrable hostname (`account.example.com` → `example.com`; a two-label host like `example.com` is kept whole) and the origin is its **bare origin** — a path suffix such as `/account` is dropped, so the same variable can keep serving as the email link base.
|
|
202
|
+
3. The compile-time account origin — `account.domain` when configured, else the project's unified host. Baked automatically; no env var required.
|
|
203
|
+
|
|
204
|
+
`rpID: 'localhost'` applies only when the project has no configured domain at all (pure local dev). If passkey registration returns 500 on a deployed worker, check that one of the three sources above resolves to the hostname the Account UI is actually served from.
|
|
198
205
|
|
|
199
206
|
**Endpoints:**
|
|
200
207
|
- `POST /auth/v1/passkey/register/options` - Get registration challenge
|
|
@@ -197,7 +197,8 @@ There are **three declarative emission surfaces** — pick by what did the write
|
|
|
197
197
|
## CloudEvents (contract v2) + AsyncAPI (any contract)
|
|
198
198
|
|
|
199
199
|
On the v2 contract, realtime data frames are delivered as CloudEvents 1.0
|
|
200
|
-
envelopes
|
|
200
|
+
envelopes (control frames stay raw); the path stays wherever `contract.routes`
|
|
201
|
+
mounts it. See
|
|
201
202
|
[Using Realtime](/platform/realtime/using-realtime#cloudevents-envelopes-contract-v2)
|
|
202
203
|
for the frame mapping.
|
|
203
204
|
|
|
@@ -214,11 +214,13 @@ new_classes = ["Broadcaster"]
|
|
|
214
214
|
|
|
215
215
|
## CloudEvents envelopes (contract v2)
|
|
216
216
|
|
|
217
|
-
On `contract: { version: "v2" }`
|
|
218
|
-
`/broadcast/v2` and every **data frame** is wrapped in a
|
|
217
|
+
On `contract: { version: "v2" }` every **data frame** is wrapped in a
|
|
219
218
|
[CloudEvents 1.0](https://cloudevents.io) envelope at the Durable Object's
|
|
220
|
-
send boundary.
|
|
221
|
-
|
|
219
|
+
send boundary. The endpoint does **not** move — the path segment tracks
|
|
220
|
+
`contract.routes` (so `/broadcast/v1` unless you also set `routes: "v2"`);
|
|
221
|
+
`version` changes only the frame format. Control frames (`pong`, `error`,
|
|
222
|
+
`reauth_ok`) stay raw on both versions, and pinned-v1 projects keep the raw
|
|
223
|
+
frames byte-identically.
|
|
222
224
|
|
|
223
225
|
| v1 frame | CloudEvents `type` | `data` | extensions |
|
|
224
226
|
|---|---|---|---|
|
|
@@ -241,7 +243,7 @@ as a normal `postgres_changes` frame on the table's room.
|
|
|
241
243
|
```json
|
|
242
244
|
{ "specversion": "1.0",
|
|
243
245
|
"id": "evt_9f2…",
|
|
244
|
-
"source": "/broadcast/
|
|
246
|
+
"source": "/broadcast/v1/websocket",
|
|
245
247
|
"type": "event.mobile-bundle.changed",
|
|
246
248
|
"time": "2026-07-20T12:00:00Z",
|
|
247
249
|
"datacontenttype": "application/json",
|
|
@@ -76,6 +76,7 @@ export default {
|
|
|
76
76
|
fileStorage: {
|
|
77
77
|
name: 'cloudflare-r2',
|
|
78
78
|
config: {
|
|
79
|
+
managed: true,
|
|
79
80
|
binding: 'R2_BUCKET',
|
|
80
81
|
bucketName: 'my-app-files',
|
|
81
82
|
filesBinding: 'FILES_DB',
|
|
@@ -87,6 +88,17 @@ export default {
|
|
|
87
88
|
};
|
|
88
89
|
```
|
|
89
90
|
|
|
91
|
+
> `managed: true` is what turns on everything on this page — the `/storage/v1/*`
|
|
92
|
+
> routes, the files worker, and the `FILES_DB` metadata database. Without it R2
|
|
93
|
+
> file storage is **presign-only**: the compiler signs requests against the
|
|
94
|
+
> bucket by name and emits **no** bucket binding into `wrangler.toml`, so
|
|
95
|
+
> `binding` and `filesBinding` are ignored and `env.R2_BUCKET` is `undefined`
|
|
96
|
+
> at runtime (the compile warns when you set them anyway).
|
|
97
|
+
>
|
|
98
|
+
> To read the bucket directly from your own code in presign-only mode, declare
|
|
99
|
+
> it yourself under [`bindings.r2Buckets`](/configure/bindings).
|
|
100
|
+
|
|
101
|
+
|
|
90
102
|
## API Endpoints
|
|
91
103
|
|
|
92
104
|
### Storage API (api.yourdomain.com/storage/v1)
|
|
@@ -204,7 +204,7 @@ Depending on your configuration, the compiler may also generate bindings for:
|
|
|
204
204
|
|
|
205
205
|
| Binding | Type | When Generated |
|
|
206
206
|
|---------|------|----------------|
|
|
207
|
-
| `R2_BUCKET` | R2 Bucket | `fileStorage`
|
|
207
|
+
| `R2_BUCKET` | R2 Bucket | **managed** `fileStorage` — `{ managed: true }` (presign-only emits no binding) |
|
|
208
208
|
| `AI` | Workers AI | `embeddings` configured on any feature |
|
|
209
209
|
| `VECTORIZE` | Vectorize Index | `embeddings` configured |
|
|
210
210
|
| `EMBEDDINGS_QUEUE` | Queue | `embeddings` configured |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.65.1",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
|
@@ -462,24 +462,8 @@ await db.update(applications).set({ deletedAt: now, modifiedAt: now })
|
|
|
462
462
|
|
|
463
463
|
### Error Handling
|
|
464
464
|
|
|
465
|
-
**
|
|
466
|
-
|
|
467
|
-
Since action handlers receive the Hono context (`c`), you can return error responses directly:
|
|
468
|
-
|
|
469
|
-
```typescript
|
|
470
|
-
async execute({ ctx, record, input, c }) {
|
|
471
|
-
if (record.stage === 'hired') {
|
|
472
|
-
return c.json({
|
|
473
|
-
error: 'Cannot modify a hired application',
|
|
474
|
-
code: 'ALREADY_HIRED',
|
|
475
|
-
details: { currentStage: record.stage },
|
|
476
|
-
}, 400);
|
|
477
|
-
}
|
|
478
|
-
// ... continue
|
|
479
|
-
}
|
|
480
|
-
```
|
|
481
|
-
|
|
482
|
-
**Option 2: Throw an ActionError**
|
|
465
|
+
**Throw an `ActionError`.** The route handler catches it by name and returns
|
|
466
|
+
`{ error, code, details }` with your `statusCode`:
|
|
483
467
|
|
|
484
468
|
```typescript
|
|
485
469
|
import { ActionError } from "@quickback/compiler";
|
|
@@ -494,9 +478,11 @@ async execute({ ctx, record, input }) {
|
|
|
494
478
|
}
|
|
495
479
|
```
|
|
496
480
|
|
|
497
|
-
The `ActionError` constructor signature is `(message, code, statusCode = 400, details?)`. The compile step rewrites the `@quickback/compiler` import to the generated runtime class (`src/lib/types.ts`)
|
|
481
|
+
The `ActionError` constructor signature is `(message, code, statusCode = 400, details?)`. The compile step rewrites the `@quickback/compiler` import to the generated runtime class (`src/lib/types.ts`); the generated per-feature helper (`.quickback/define-action`) re-exports the same classes, so importing `ActionError` from the same module as `defineAction` also works.
|
|
482
|
+
|
|
483
|
+
**Do not return an error response from `execute`.** The generated route wraps whatever `execute` resolves to in the success response — `c.json(result)` — so a returned `c.json({ error }, 400)` is not passed through: the `Response` object itself is JSON-serialized and the client receives `{}` with status **200**. A raw `Response` return is honored only when the action declares `responseType: 'stream'` or `'file'`. Errors leave `execute` by throwing; the declared [`output`](/define/actions#declaring-action-outputs) describes the success body only.
|
|
498
484
|
|
|
499
|
-
> Do **not** throw Hono's `HTTPException` from an action — the route handler doesn't unwrap it, so it surfaces as an unhandled **500 ACTION_EXECUTION_FAILED**. Use `ActionError`
|
|
485
|
+
> Do **not** throw Hono's `HTTPException` from an action — the route handler doesn't unwrap it, so it surfaces as an unhandled **500 ACTION_EXECUTION_FAILED**. Use `ActionError` for clean 4xx responses.
|
|
500
486
|
|
|
501
487
|
|
|
502
488
|
## See Also
|
|
@@ -8,6 +8,54 @@ The current release series. Older entries are archived by version range:
|
|
|
8
8
|
- [v0.20 – v0.29](/changelog/v0.2x)
|
|
9
9
|
- [v0.18 and earlier](/changelog/v0.1x)
|
|
10
10
|
|
|
11
|
+
## v0.65.x — August 16, 2026
|
|
12
|
+
|
|
13
|
+
### Passkeys no longer silently degrade to `rpID: 'localhost'`
|
|
14
|
+
|
|
15
|
+
The generated passkey plugin (and the SEALED reveal step-up, which must verify
|
|
16
|
+
against the same relying party) now bakes a compile-time fallback derived from
|
|
17
|
+
your configured domain — `account.domain` when set, else the unified host.
|
|
18
|
+
`ACCOUNT_URL` remains a runtime override, and its **bare origin** is now used
|
|
19
|
+
for WebAuthn even when the value carries a path (`https://host/account`), so
|
|
20
|
+
one variable serves both the email link base and the relying-party origin.
|
|
21
|
+
The rpID derivation also stops stripping two-label hostnames to a bare TLD
|
|
22
|
+
(`example.com` no longer became rpID `com`). `localhost` now applies only to
|
|
23
|
+
projects with no configured domain at all.
|
|
24
|
+
|
|
25
|
+
### `APP_URL` — per-deploy override for `account.appUrl`
|
|
26
|
+
|
|
27
|
+
`account.appUrl` is baked at compile time into the Account SPA runtime config
|
|
28
|
+
and the "Go To App" email CTAs, which pointed preview/dev deploys at
|
|
29
|
+
production. Set `APP_URL` on the deploy target to override both at serve
|
|
30
|
+
time — same one-bundle-several-hostnames pattern as `EXTRA_APP_HOSTS` and
|
|
31
|
+
`BETTER_AUTH_URL`.
|
|
32
|
+
|
|
33
|
+
### Account SPA keeps its `/account` basepath through login redirects
|
|
34
|
+
|
|
35
|
+
On path-mounted deployments, a post-login redirect could navigate to a bare
|
|
36
|
+
path (`/dashboard` instead of `/account/dashboard`) and fall through to a
|
|
37
|
+
tenant route. The callback sanitizer now re-applies the basepath to
|
|
38
|
+
same-origin paths, covering every sign-in flow (password, passkey, email OTP,
|
|
39
|
+
signup) and social-link callbacks.
|
|
40
|
+
|
|
41
|
+
## v0.65.0 — August 16, 2026
|
|
42
|
+
|
|
43
|
+
### All Quickback auth plugins are now bundled — zero `@quickback-dev/*` npm dependencies
|
|
44
|
+
|
|
45
|
+
The compiler now vendors the AWS SES, AWS SNS, combo-auth, and
|
|
46
|
+
upgrade-anonymous plugin sources into generated projects at
|
|
47
|
+
`src/plugins/<name>/`, completing what the subscriptions plugin started in
|
|
48
|
+
v0.64: **no generated project installs a `@quickback-dev/*` package from npm.**
|
|
49
|
+
The plugin code ships with the compiler that wires it, so the emitted callers
|
|
50
|
+
(`getSESConfig`, OTP callbacks, `upgradeAnonymous()` calls) can never skew from
|
|
51
|
+
the plugin version they were generated against — and upgrades arrive by
|
|
52
|
+
recompiling, not by `npm update`.
|
|
53
|
+
|
|
54
|
+
Recompile and the dependencies disappear from `package.json`; no config
|
|
55
|
+
changes needed. The `@quickback-dev/better-auth-*` npm packages are being
|
|
56
|
+
retired from the registry — the vendored source in your project is the
|
|
57
|
+
supported copy.
|
|
58
|
+
|
|
11
59
|
## v0.64.0 — August 15, 2026
|
|
12
60
|
|
|
13
61
|
### `contract.version` defaults to v2 — and no longer moves your URLs
|
|
@@ -53,8 +101,11 @@ URLs do not move. These do:
|
|
|
53
101
|
- `?include=`, aggregate changesets (`owns`), and delegated principals become
|
|
54
102
|
available without a pin.
|
|
55
103
|
|
|
56
|
-
Pin `contract: { version: "v1" }` to opt out.
|
|
57
|
-
`contract.version` unset
|
|
104
|
+
Pin `contract: { version: "v1" }` to opt out. A pre-v0.64 project that leaves
|
|
105
|
+
`contract.version` unset gets a one-time notice naming what changed — the
|
|
106
|
+
generated `wrangler.toml` header records the resolved version in a
|
|
107
|
+
`# quickback:contract` stamp, so new projects and projects that have already
|
|
108
|
+
compiled on v2 stay warning-free without restating the default.
|
|
58
109
|
|
|
59
110
|
### Action-schema harvest no longer keys on contract version
|
|
60
111
|
|
|
@@ -234,7 +234,7 @@ Binding names that clash with compiler-owned bindings are rejected at validation
|
|
|
234
234
|
| `AUDIT_DB` | always (cross-tenant unsafe-action audit) |
|
|
235
235
|
| `WEBHOOKS_DB`, `WEBHOOKS_QUEUE` | a webhooks binding is configured |
|
|
236
236
|
| `KV` | always |
|
|
237
|
-
| `R2_BUCKET`, `FILES_DB` | `
|
|
237
|
+
| `R2_BUCKET`, `FILES_DB` | **managed** file storage — `defineFileStorage("cloudflare-r2", { managed: true })`. Presign-only R2 (the default) emits no bucket binding, so both names stay free for you to declare here. |
|
|
238
238
|
| `VECTORIZE` | a Vectorize index is configured |
|
|
239
239
|
| `BROADCASTER` | realtime is enabled |
|
|
240
240
|
| `EMAIL` | `email: { provider: "cloudflare" }` |
|
|
@@ -264,7 +264,9 @@ Each target's `BETTER_AUTH_URL` also defaults to the hostname it claims (unified
|
|
|
264
264
|
The same compiled bundle can be deployed to additional hostnames — preview environments, staging, per-PR URLs — without recompiling. Set the `EXTRA_APP_HOSTS` env var on the deploy target (a comma-separated list of hostnames) and the worker treats each one like an entry in `apps[*].domain`:
|
|
265
265
|
|
|
266
266
|
- Apps hostname middleware serves the SPA at root.
|
|
267
|
-
- CORS
|
|
267
|
+
- CORS trusts requests whose `Origin` hostname matches.
|
|
268
|
+
- Better Auth's own origin check (independent of CORS) trusts each hostname as
|
|
269
|
+
an `https://` origin — an entry with an explicit scheme is used verbatim.
|
|
268
270
|
|
|
269
271
|
Empty or unset means no extension and zero behavior change for production.
|
|
270
272
|
|
|
@@ -278,13 +280,24 @@ EXTRA_APP_HOSTS = "app-preview.example.com,pr-42.example.com"
|
|
|
278
280
|
wrangler secret put EXTRA_APP_HOSTS --env preview
|
|
279
281
|
```
|
|
280
282
|
|
|
281
|
-
Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed worker auto-trusts its own configured base origin without needing an explicit `trustedOrigins` entry. With `EXTRA_APP_HOSTS`, one env var extends
|
|
283
|
+
Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed worker auto-trusts its own configured base origin without needing an explicit `trustedOrigins` entry. With `EXTRA_APP_HOSTS`, one env var extends all three allowlists — apps, CORS, and Better Auth's `trustedOrigins`. (Earlier v0.64 output stopped at the CORS layer: preflight passed, then Better Auth's own check rejected the origin. On older output, recompile — or set `BETTER_AUTH_URL` on the deploy target, since Better Auth always trusts its own base URL.)
|
|
282
284
|
|
|
283
285
|
> **Multi-app deploys**
|
|
284
286
|
>
|
|
285
287
|
> When more than one app is hostname-mounted, extras attach to the first registered apps middleware (Hono runs middleware in registration order and terminates on first match). If you need extras to route to a specific app in a multi-app deploy, set `apps[*].domain` directly and recompile rather than using this env var.
|
|
286
288
|
|
|
287
289
|
|
|
290
|
+
### Per-deploy app URL
|
|
291
|
+
|
|
292
|
+
`account.appUrl` is baked at compile time into the Account SPA's runtime config and used as the "Go To App" link base in transactional emails — so a preview or dev worker would send emails and render links pointing at production. Set `APP_URL` on the deploy target to override both at serve time: the worker merges it into the runtime config injected into every served shell, and email templates prefer it over `ACCOUNT_URL`.
|
|
293
|
+
|
|
294
|
+
```toml title="wrangler.preview.toml"
|
|
295
|
+
[vars]
|
|
296
|
+
APP_URL = "https://app-preview.example.com"
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
Unset means zero behavior change. (Setting it changes the injected runtime-config bytes, so a strict-CSP deploy relying on the precomputed script hash should keep it unset on the production target — the same tradeoff as named-dev host injection.)
|
|
300
|
+
|
|
288
301
|
## See Also
|
|
289
302
|
|
|
290
303
|
- [Configuration](/configure) — CMS and Account config options
|
|
@@ -50,13 +50,13 @@ These are configured as bindings in `wrangler.toml`, not environment variables.
|
|
|
50
50
|
| `DB` | D1 Database | Feature tables (dual mode) |
|
|
51
51
|
| `DATABASE` | D1 Database | All tables (single DB mode) |
|
|
52
52
|
| `KV` | KV Namespace | Key-value storage |
|
|
53
|
-
| `R2_BUCKET` | R2 Bucket | File storage (
|
|
53
|
+
| `R2_BUCKET` | R2 Bucket | File storage (managed mode only — `managed: true`) |
|
|
54
54
|
| `AI` | Workers AI | Embedding generation (if configured) |
|
|
55
55
|
| `VECTORIZE` | Vectorize | Vector similarity search (if configured) |
|
|
56
56
|
| `EMBEDDINGS_QUEUE` | Queue | Async embedding jobs (if configured) |
|
|
57
57
|
| `WEBHOOKS_DB` | D1 Database | Webhook events (if configured) |
|
|
58
58
|
| `WEBHOOKS_QUEUE` | Queue | Webhook delivery (if configured) |
|
|
59
|
-
| `FILES_DB` | D1 Database | File metadata (
|
|
59
|
+
| `FILES_DB` | D1 Database | File metadata (managed mode only — `managed: true`) |
|
|
60
60
|
| `BROADCASTER` | Durable Object | Realtime Broadcaster DO (if configured) |
|
|
61
61
|
| `EMAIL` | send_email | Cloudflare Email Service (if email configured) |
|
|
62
62
|
|
|
@@ -145,6 +145,18 @@ evaluated for real, so a derivation in that file happens to work. Whether it
|
|
|
145
145
|
works depends on unrelated content in the table file — declare the shape
|
|
146
146
|
instead.
|
|
147
147
|
|
|
148
|
+
**`output` describes the success path only.** Error responses never pass
|
|
149
|
+
through it: throw
|
|
150
|
+
[`ActionError`](/api/actions#error-handling) and the route returns
|
|
151
|
+
`{ error, code, details }` with your status code — that error envelope is part
|
|
152
|
+
of the generated contract already, so do not fold error variants into
|
|
153
|
+
`output`. The one exception is an endpoint whose *success* body is
|
|
154
|
+
deliberately a status report (a webhook receiver acknowledging
|
|
155
|
+
`{ received: false, reason }`, say) — that is a union of success shapes, and
|
|
156
|
+
declaring it as `z.discriminatedUnion(...)` in `output` is correct. Do not
|
|
157
|
+
return an error object (or a `Response`) from `execute` to signal failure —
|
|
158
|
+
see [Error Handling](/api/actions#error-handling) for what actually happens.
|
|
159
|
+
|
|
148
160
|
Parameterized standalone paths use Hono's `:param` syntax in authored source,
|
|
149
161
|
for example `path: "/events/:eventId/check-in"`. The harvest planner converts
|
|
150
162
|
those segments to the OpenAPI `{param}` form before applying the schema, so
|
|
@@ -269,7 +269,7 @@ When the passkey plugin is enabled, `/reveal` verifies a WebAuthn assertion whos
|
|
|
269
269
|
| Field | Value |
|
|
270
270
|
|---|---|
|
|
271
271
|
| `challenge` | the `/challenge` `nonce` **as the base64url string** (the client signs the b64url text, the server passes `expectedChallenge = nonce`) |
|
|
272
|
-
| `rpID` | the passkey plugin's `rpID` — i.e. `crossSubDomainCookies.domain` (leading dot stripped) when configured, else the host of `env.ACCOUNT_URL
|
|
272
|
+
| `rpID` | the passkey plugin's `rpID` — i.e. `crossSubDomainCookies.domain` (leading dot stripped) when configured, else the registrable host of `env.ACCOUNT_URL`, else the compile-time account origin (both emissions share one resolution, so they cannot skew) |
|
|
273
273
|
| `userVerification` | **required** (`requireUserVerification: true` — a reveal is a deliberate re-auth) |
|
|
274
274
|
| origin | the resolved account origin (mirrors the `passkey({ rpID, origin })` plugin) |
|
|
275
275
|
|
|
@@ -1,16 +1,14 @@
|
|
|
1
1
|
# AWS SES Plugin
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Quickback's AWS SES plugin sends transactional emails via AWS SES. It handles AWS Signature V4 signing, HTML/text email templates, and rate limiting — designed to work in Cloudflare Workers (no Node.js `aws-sdk` dependency).
|
|
4
4
|
|
|
5
5
|
> **Cloudflare Email is the default.** As of the Cloudflare Email Sending public beta, the zero-config `send_email` binding is Quickback's default transport for Cloudflare deploys — no API keys, no SES setup. See [Email Configuration](/configure#email-configuration). Use AWS SES when you need it (non-Cloudflare runtimes, existing SES infra, or specific deliverability/compliance requirements).
|
|
6
6
|
|
|
7
7
|
## Installation
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
npm install @quickback-dev/better-auth-aws-ses
|
|
11
|
-
```
|
|
9
|
+
None. The compiler bundles the plugin source and emits it into your project at `src/plugins/aws-ses/` — it is **not** an npm dependency, and upgrades arrive by recompiling, not by `npm update`.
|
|
12
10
|
|
|
13
|
-
|
|
11
|
+
The plugin is wired up only when you explicitly opt in via `email.provider: 'aws-ses'` in your Quickback config. Without that, `email.provider` defaults to `'cloudflare'` and the Cloudflare Email helper is used instead.
|
|
14
12
|
|
|
15
13
|
## Email Types
|
|
16
14
|
|
|
@@ -95,16 +93,16 @@ Recognized keys:
|
|
|
95
93
|
| `'forget-password'` | Password reset request — and admin-bootstrap if `welcome` isn't set |
|
|
96
94
|
| `'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`. |
|
|
97
95
|
|
|
98
|
-
Missing keys fall through to the built-in defaults from
|
|
96
|
+
Missing keys fall through to the built-in defaults from the vendored plugin (`src/plugins/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.
|
|
99
97
|
|
|
100
98
|
> **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`.
|
|
101
99
|
|
|
102
100
|
## Configuration
|
|
103
101
|
|
|
104
|
-
|
|
102
|
+
The compiler wires the plugin into `src/lib/auth.ts` automatically. The generated `getSESConfig(env)` maps environment to the vendored plugin's options:
|
|
105
103
|
|
|
106
104
|
```typescript
|
|
107
|
-
import { awsSESPlugin } from "
|
|
105
|
+
import { awsSESPlugin } from "../plugins/aws-ses";
|
|
108
106
|
|
|
109
107
|
const auth = betterAuth({
|
|
110
108
|
plugins: [
|
|
@@ -122,16 +120,6 @@ const auth = betterAuth({
|
|
|
122
120
|
});
|
|
123
121
|
```
|
|
124
122
|
|
|
125
|
-
### Client Plugin
|
|
126
|
-
|
|
127
|
-
```typescript
|
|
128
|
-
import { awsSESClientPlugin } from "@quickback-dev/better-auth-aws-ses/client";
|
|
129
|
-
|
|
130
|
-
const authClient = createAuthClient({
|
|
131
|
-
plugins: [awsSESClientPlugin()],
|
|
132
|
-
});
|
|
133
|
-
```
|
|
134
|
-
|
|
135
123
|
## Required Environment Variables
|
|
136
124
|
|
|
137
125
|
| Variable | Description |
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# AWS SNS Plugin (SMS OTP)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The AWS SNS transport is what Quickback wires into Better Auth's built-in `phoneNumber` plugin when you opt in to SMS OTP. The compiler emits its source into your project at `src/plugins/aws-sns/` — it is not an npm dependency. It signs SNS `Publish` requests with AWS Signature V4 using the Web Crypto API — zero AWS SDK dependency, runs on Cloudflare Workers.
|
|
4
4
|
|
|
5
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
6
|
|
|
7
7
|
## What it provides
|
|
8
8
|
|
|
9
|
-
The
|
|
9
|
+
The transport 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
10
|
|
|
11
11
|
| Export | Purpose |
|
|
12
12
|
|--------|---------|
|
|
@@ -40,7 +40,7 @@ export default defineConfig({
|
|
|
40
40
|
|
|
41
41
|
The compiler:
|
|
42
42
|
|
|
43
|
-
1.
|
|
43
|
+
1. Emits the plugin source into `src/plugins/aws-sns/` — vendored, not an npm dependency; upgrades arrive by recompiling.
|
|
44
44
|
2. Emits a `getSNSConfig(env)` helper in `src/lib/auth.ts`.
|
|
45
45
|
3. Wires the `phoneNumber` plugin with `sendOTP`, `sendPasswordResetOTP`, and `phoneNumberValidator: isValidE164`.
|
|
46
46
|
4. Drops `AWS_SNS_REGION` / `APP_NAME` (and `SMS_SENDER_ID` / `SMS_TYPE` when set) into `[vars]` in `wrangler.toml`.
|
|
@@ -116,7 +116,7 @@ Your <AppName> code is 123456. Expires in 5 min. Don't share it.
|
|
|
116
116
|
After compile, check the generated `src/lib/auth.ts`:
|
|
117
117
|
|
|
118
118
|
```ts
|
|
119
|
-
import { sendSMSWithSNS, smsTemplates, isValidE164 } from "
|
|
119
|
+
import { sendSMSWithSNS, smsTemplates, isValidE164 } from "../plugins/aws-sns";
|
|
120
120
|
|
|
121
121
|
function getSNSConfig(env: CloudflareBindings | undefined): SNSConfig { /* ... */ }
|
|
122
122
|
|
|
@@ -76,7 +76,7 @@ auth: defineAuth("better-auth", {
|
|
|
76
76
|
|
|
77
77
|
### SMS OTP (with AWS SNS)
|
|
78
78
|
|
|
79
|
-
When `phoneNumber` is enabled, the compiler wires Better Auth's built-in `phoneNumber` plugin to AWS SNS for SMS delivery via [
|
|
79
|
+
When `phoneNumber` is enabled, the compiler wires Better Auth's built-in `phoneNumber` plugin to AWS SNS for SMS delivery via the vendored [AWS SNS transport](/platform/auth/plugins/aws-sns) (emitted into `src/plugins/aws-sns/`, not installed from npm). 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.
|
|
80
80
|
|
|
81
81
|
**Enable in config:**
|
|
82
82
|
|
|
@@ -193,8 +193,15 @@ auth: defineAuth("better-auth", {
|
|
|
193
193
|
}),
|
|
194
194
|
```
|
|
195
195
|
|
|
196
|
-
**
|
|
197
|
-
|
|
196
|
+
**Relying party resolution:**
|
|
197
|
+
|
|
198
|
+
WebAuthn needs a relying party ID and origin. The generated plugin resolves them in this order:
|
|
199
|
+
|
|
200
|
+
1. `advanced.crossSubDomainCookies.domain` (leading dot stripped) becomes the `rpID` when configured — credentials then work across sibling subdomains.
|
|
201
|
+
2. The `ACCOUNT_URL` env var, when set on the deploy target: `rpID` is its registrable hostname (`account.example.com` → `example.com`; a two-label host like `example.com` is kept whole) and the origin is its **bare origin** — a path suffix such as `/account` is dropped, so the same variable can keep serving as the email link base.
|
|
202
|
+
3. The compile-time account origin — `account.domain` when configured, else the project's unified host. Baked automatically; no env var required.
|
|
203
|
+
|
|
204
|
+
`rpID: 'localhost'` applies only when the project has no configured domain at all (pure local dev). If passkey registration returns 500 on a deployed worker, check that one of the three sources above resolves to the hostname the Account UI is actually served from.
|
|
198
205
|
|
|
199
206
|
**Endpoints:**
|
|
200
207
|
- `POST /auth/v1/passkey/register/options` - Get registration challenge
|
|
@@ -197,7 +197,8 @@ There are **three declarative emission surfaces** — pick by what did the write
|
|
|
197
197
|
## CloudEvents (contract v2) + AsyncAPI (any contract)
|
|
198
198
|
|
|
199
199
|
On the v2 contract, realtime data frames are delivered as CloudEvents 1.0
|
|
200
|
-
envelopes
|
|
200
|
+
envelopes (control frames stay raw); the path stays wherever `contract.routes`
|
|
201
|
+
mounts it. See
|
|
201
202
|
[Using Realtime](/platform/realtime/using-realtime#cloudevents-envelopes-contract-v2)
|
|
202
203
|
for the frame mapping.
|
|
203
204
|
|
|
@@ -214,11 +214,13 @@ new_classes = ["Broadcaster"]
|
|
|
214
214
|
|
|
215
215
|
## CloudEvents envelopes (contract v2)
|
|
216
216
|
|
|
217
|
-
On `contract: { version: "v2" }`
|
|
218
|
-
`/broadcast/v2` and every **data frame** is wrapped in a
|
|
217
|
+
On `contract: { version: "v2" }` every **data frame** is wrapped in a
|
|
219
218
|
[CloudEvents 1.0](https://cloudevents.io) envelope at the Durable Object's
|
|
220
|
-
send boundary.
|
|
221
|
-
|
|
219
|
+
send boundary. The endpoint does **not** move — the path segment tracks
|
|
220
|
+
`contract.routes` (so `/broadcast/v1` unless you also set `routes: "v2"`);
|
|
221
|
+
`version` changes only the frame format. Control frames (`pong`, `error`,
|
|
222
|
+
`reauth_ok`) stay raw on both versions, and pinned-v1 projects keep the raw
|
|
223
|
+
frames byte-identically.
|
|
222
224
|
|
|
223
225
|
| v1 frame | CloudEvents `type` | `data` | extensions |
|
|
224
226
|
|---|---|---|---|
|
|
@@ -241,7 +243,7 @@ as a normal `postgres_changes` frame on the table's room.
|
|
|
241
243
|
```json
|
|
242
244
|
{ "specversion": "1.0",
|
|
243
245
|
"id": "evt_9f2…",
|
|
244
|
-
"source": "/broadcast/
|
|
246
|
+
"source": "/broadcast/v1/websocket",
|
|
245
247
|
"type": "event.mobile-bundle.changed",
|
|
246
248
|
"time": "2026-07-20T12:00:00Z",
|
|
247
249
|
"datacontenttype": "application/json",
|