@quickback-dev/cli 0.72.2 → 0.72.4
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/skill/SKILL.md +64 -0
- package/dist/skill/docs/configure/agents.md +156 -2
- package/dist/skill/docs/configure/tenant-databases.md +53 -7
- package/dist/skill/docs/define/areas.md +3 -1
- package/dist/skill/docs/define/fga.md +220 -23
- package/dist/skill/docs/define/read.md +7 -5
- package/dist/skill/docs/platform/api-contract/index.md +5 -1
- package/dist/skill/docs/platform/auth/plugins/aws-ses.md +25 -0
- package/dist/skill/docs/platform/realtime/durable-objects.md +9 -0
- package/dist/skill/docs/platform/webhooks/outbound.md +1 -0
- package/dist/skill/docs/ui/account/hooks.md +5 -2
- package/dist/skill/docs/ui/admin/connecting.md +3 -3
- package/package.json +1 -1
- package/src/skill/SKILL.md +64 -0
- package/src/skill/docs/configure/agents.md +156 -2
- package/src/skill/docs/configure/tenant-databases.md +53 -7
- package/src/skill/docs/define/areas.md +3 -1
- package/src/skill/docs/define/fga.md +220 -23
- package/src/skill/docs/define/read.md +7 -5
- package/src/skill/docs/platform/api-contract/index.md +5 -1
- package/src/skill/docs/platform/auth/plugins/aws-ses.md +25 -0
- package/src/skill/docs/platform/realtime/durable-objects.md +9 -0
- package/src/skill/docs/platform/webhooks/outbound.md +1 -0
- package/src/skill/docs/ui/account/hooks.md +5 -2
- package/src/skill/docs/ui/admin/connecting.md +3 -3
|
@@ -99,7 +99,11 @@ before the stale-claim takeover, so a foreign caller can neither read nor
|
|
|
99
99
|
overwrite your claim.
|
|
100
100
|
|
|
101
101
|
**Unauthenticated requests carrying the header are rejected (400)** — an
|
|
102
|
-
anonymous caller has no principal to bind the claim to.
|
|
102
|
+
anonymous caller has no principal to bind the claim to. Better Auth's own
|
|
103
|
+
routes (`/auth/v1/*` and `/cli/*`) are the exception: Better Auth
|
|
104
|
+
authenticates them itself, so the header is ignored there rather than
|
|
105
|
+
rejected, and a client can attach it to every write. The operator endpoints
|
|
106
|
+
mounted under the auth prefix still honor it. A PUBLIC standalone
|
|
103
107
|
action may opt in explicitly:
|
|
104
108
|
|
|
105
109
|
```ts title="quickback/features/orders/actions/submitForm.ts"
|
|
@@ -110,6 +110,31 @@ Missing keys fall through to the built-in defaults from the vendored plugin (`sr
|
|
|
110
110
|
|
|
111
111
|
> **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`.
|
|
112
112
|
|
|
113
|
+
### OTP Message Headers
|
|
114
|
+
|
|
115
|
+
Every emailOTP send — default or custom template — carries two headers:
|
|
116
|
+
|
|
117
|
+
| Header | Value | Why |
|
|
118
|
+
|--------|-------|-----|
|
|
119
|
+
| `Auto-Submitted` | `auto-generated` | [RFC 3834](https://www.rfc-editor.org/rfc/rfc3834): machine mail, so vacation responders and ticketing systems don't reply to it. |
|
|
120
|
+
| `OTP-Token` | `"<otp>"; origin="<origin of APP_URL, else ACCOUNT_URL>"` | [draft-goto-otp-token](https://www.ietf.org/archive/id/draft-goto-otp-token-01.html): the code in machine-readable, origin-bound form, so a mail client can offer it only on the site that asked for it. Omitted when the origin is not `http(s)`. |
|
|
121
|
+
|
|
122
|
+
`OTP-Token` is an individual Internet-Draft, not a standard. Gmail's "Copy code" button currently finds codes heuristically, so keep the code near the top of both the HTML and text parts as well.
|
|
123
|
+
|
|
124
|
+
A template can add, replace or drop headers by returning `headers` next to `{ subject, html, text }`. A `null` value removes a default:
|
|
125
|
+
|
|
126
|
+
```typescript
|
|
127
|
+
// quickback/email-templates/sign-in.ts — bind the code to the app the user signs in on
|
|
128
|
+
export default ({ otp, appName, appOrigin }: { otp: string; appName: string; appOrigin: string }) => ({
|
|
129
|
+
subject: `Sign in to ${appName}`,
|
|
130
|
+
html: `<p>Your code: <b>${otp}</b></p>`,
|
|
131
|
+
text: `Your code: ${otp}`,
|
|
132
|
+
headers: { 'OTP-Token': `"${otp}"; origin="${appOrigin}"` },
|
|
133
|
+
});
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
(`appOrigin` here comes from a [`resolve-email-context` hook](/ui/account/hooks), which receives `env`.) Header names the sender owns — `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Subject`, `Date`, `Message-ID`, `MIME-Version`, `Content-*`, `Resent-*`, `Return-Path`, `Received`, `DKIM-Signature` — are ignored, and so is any value that is not one line of printable ASCII. A send with headers goes out through SES `SendRawEmail` (the simple `SendEmail` action cannot set them); sends without headers are unchanged.
|
|
137
|
+
|
|
113
138
|
## Configuration
|
|
114
139
|
|
|
115
140
|
The compiler wires the plugin into `src/lib/auth.ts` automatically. The generated `getSESConfig(env)` maps environment to the vendored plugin's options:
|
|
@@ -878,6 +878,15 @@ for stub errors:
|
|
|
878
878
|
| `Subrequest depth limit exceeded` | Not retried; logged as `durable_object.failed` |
|
|
879
879
|
| anything else | Not retried; logged as `durable_object.failed` |
|
|
880
880
|
|
|
881
|
+
Every call into the Broadcaster (the publish including its one retry, the
|
|
882
|
+
live-view `seq` read, and in separate-Worker mode the service-binding fetch)
|
|
883
|
+
also races a **5-second deadline**. A stalled Broadcaster therefore costs the
|
|
884
|
+
emitting request at most 5 seconds, not the client's whole timeout, even
|
|
885
|
+
though the write has already committed. An expired call is logged like any other
|
|
886
|
+
failed publish (`durable_object.failed` for the inline stub), and the tenant
|
|
887
|
+
outbox treats it as retryable. If the
|
|
888
|
+
first attempt lands late, the publish id dedupes it.
|
|
889
|
+
|
|
881
890
|
Every send carries one **publish id**, and a retry reuses it. The Broadcaster
|
|
882
891
|
remembers its 64 most recent ids. When a retry arrives for a first attempt that
|
|
883
892
|
actually landed (only the reply was lost), it is acknowledged without a second
|
|
@@ -330,6 +330,7 @@ dead letter queue) is identical across providers.
|
|
|
330
330
|
## See Also
|
|
331
331
|
|
|
332
332
|
- [Inbound Webhooks](/platform/webhooks/inbound) — Receive webhooks from external services
|
|
333
|
+
- [MCP Events](/configure/agents#mcp-events) — ChatGPT subscriptions that ride this store and queue
|
|
333
334
|
- [Queues](/platform/queues) — Background processing infrastructure
|
|
334
335
|
|
|
335
336
|
## Standard Webhooks signing
|
|
@@ -34,7 +34,7 @@ Each file has a single default export — an `async (entity, ctx) => ...` functi
|
|
|
34
34
|
| `after-admin-user-create.ts` | `databaseHooks.user.create.after` (filtered) | `User` | `void` |
|
|
35
35
|
| `before-invitation-create.ts` | `organizationHooks.beforeCreateInvitation` | `{ invitation, inviter, organization }` | `void \| { data?: Partial<Invitation> }` |
|
|
36
36
|
| `resolve-oauth-context.ts` | OAuth bearer middleware | OAuth identity + session | Partial `AppContext` tenant fields |
|
|
37
|
-
| `resolve-email-context.ts` | emailOTP `sendVerificationOTP` | `{ email, type, name }` | Extra fields merged into the email template context |
|
|
37
|
+
| `resolve-email-context.ts` | emailOTP `sendVerificationOTP` | `{ email, type, name, env }` | Extra fields merged into the email template context |
|
|
38
38
|
| `before-auth-request.ts` | `hooks.before` (every auth endpoint) | `(ctx, env, { APIError })` | `void` — throw an `APIError` to refuse |
|
|
39
39
|
| `after-auth-request.ts` | `hooks.after` (every auth endpoint) | `(ctx, env)` | `void` — failures are logged, never thrown |
|
|
40
40
|
|
|
@@ -178,7 +178,7 @@ add `quickback/hooks/resolve-email-context.ts`. The emailOTP send calls it for
|
|
|
178
178
|
each recipient and **spreads the returned object into your email templates**.
|
|
179
179
|
|
|
180
180
|
```ts title="quickback/hooks/resolve-email-context.ts"
|
|
181
|
-
export default async ({ email, type, name, db, schema, eq, and }) => {
|
|
181
|
+
export default async ({ email, type, name, env, db, schema, eq, and }) => {
|
|
182
182
|
// Is this recipient a member of any organization?
|
|
183
183
|
const [u] = await db.select({ id: schema.user.id })
|
|
184
184
|
.from(schema.user).where(eq(schema.user.email, email)).limit(1);
|
|
@@ -208,6 +208,9 @@ Notes:
|
|
|
208
208
|
fixed signature; convert a type to a [custom template](/platform/auth/plugins/aws-ses#per-type-template-overrides) to consume the extra context.
|
|
209
209
|
- `db`, `schema`, `eq`, and `and` are passed in (the same Drizzle handle Better
|
|
210
210
|
Auth uses) so you can look the recipient up without an import.
|
|
211
|
+
- `env` is the Worker's bindings, so the context can carry environment-specific
|
|
212
|
+
values — e.g. the origin a template binds its
|
|
213
|
+
[`OTP-Token` header](/platform/auth/plugins/aws-ses#otp-message-headers) to.
|
|
211
214
|
- This is **not** a Better Auth `databaseHook` — it's consumed only by the
|
|
212
215
|
emailOTP send, so it adds no signup/session latency.
|
|
213
216
|
|
|
@@ -120,7 +120,7 @@ export default defineConfig({
|
|
|
120
120
|
```
|
|
121
121
|
|
|
122
122
|
When you run `quickback build`, the CLI:
|
|
123
|
-
1.
|
|
123
|
+
1. Copies the prebuilt CMS SPA into `src/apps/cms/` (the compiler ships one generic bundle; per-project settings reach it at serve time)
|
|
124
124
|
2. Adds `[assets]` config to `wrangler.toml` with `run_worker_first = true`
|
|
125
125
|
3. Generates Worker routing to serve the CMS SPA
|
|
126
126
|
|
|
@@ -139,8 +139,8 @@ This adds a custom domain route to `wrangler.toml`. Both `api.example.com` and `
|
|
|
139
139
|
CMS access defaults to `access: "sysadmin"` — only `user.role === "sysadmin"` (the cross-tenant data-plane tier) can use `/cms/*`. Set `access: "member"` to also admit anyone holding an organization membership. `user.role === "appmanager"` opens the CMS in neither mode: it is the control-plane tier and belongs at `/account/admin`. The gate is enforced at multiple layers:
|
|
140
140
|
|
|
141
141
|
- **Account UI** hides the "Go to CMS" button for callers outside those roles.
|
|
142
|
-
- **CMS SPA shell** — the Worker
|
|
143
|
-
- **`/api/v1/schema`** returns `403
|
|
142
|
+
- **CMS SPA shell** — the Worker redirects unauthenticated requests to login. Sign-in is the only shell-level gate; the app itself is a generic bundle. For a caller `/api/v1/schema` would admit, the Worker also inlines the schema registry in the shell as a non-executing `<script type="application/json" id="__qb-cms-bootstrap">` block, so the CMS starts without fetching it. The block uses the same admission check as `/api/v1/schema`, so it never carries anything that route would refuse. With [Cloudflare Access](/configure/cloudflare-access), it is inlined only when `/api/v1/schema` needs no Access application or the same one the shell request passed. The CMS shell is served `Cache-Control: private, no-store`.
|
|
143
|
+
- **`/api/v1/schema`** returns `401 AUTH_MISSING` to anonymous callers `403 CMS_ACCESS_DENIED` (naming the role required) to signed-in callers outside those roles, and `403 MFA_REQUIRED` to an operator whose session lacks the second factor `auth.operatorMfa` demands, so schema metadata can't be scraped by hitting the API directly.
|
|
144
144
|
- **`custom_view` routes** are gated on `userRole: ["appmanager"]` rather than org membership, so saved views can't be listed or modified without platform-control-plane rights.
|
|
145
145
|
- **In-SPA screen** — a signed-in caller who isn't admitted is served the shell and shown a screen naming what they'd need. There is no wrong-role redirect.
|
|
146
146
|
|