@quickback-dev/cli 0.50.2 → 0.50.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/commands/deploy.d.ts +29 -0
- package/dist/commands/deploy.d.ts.map +1 -0
- package/dist/commands/deploy.js +324 -0
- package/dist/commands/deploy.js.map +1 -0
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +22 -17
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +10 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/config-id-splice.d.ts +68 -0
- package/dist/lib/config-id-splice.d.ts.map +1 -0
- package/dist/lib/config-id-splice.js +364 -0
- package/dist/lib/config-id-splice.js.map +1 -0
- package/dist/lib/config-id-splice.test.d.ts +2 -0
- package/dist/lib/config-id-splice.test.d.ts.map +1 -0
- package/dist/lib/config-id-splice.test.js +246 -0
- package/dist/lib/config-id-splice.test.js.map +1 -0
- package/dist/lib/shell.d.ts +14 -0
- package/dist/lib/shell.d.ts.map +1 -1
- package/dist/lib/shell.js +27 -0
- package/dist/lib/shell.js.map +1 -1
- package/dist/lib/wrangler-resources.d.ts +131 -0
- package/dist/lib/wrangler-resources.d.ts.map +1 -0
- package/dist/lib/wrangler-resources.js +355 -0
- package/dist/lib/wrangler-resources.js.map +1 -0
- package/dist/lib/wrangler-resources.test.d.ts +2 -0
- package/dist/lib/wrangler-resources.test.d.ts.map +1 -0
- package/dist/lib/wrangler-resources.test.js +321 -0
- package/dist/lib/wrangler-resources.test.js.map +1 -0
- package/dist/skill/docs/changelog.md +27 -0
- package/dist/skill/docs/compiler/cloud-compiler/deploy.md +82 -0
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +23 -0
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +2 -0
- package/dist/skill/docs/compiler/config/index.md +5 -0
- package/dist/skill/docs/compiler/config/security.md +1 -0
- package/dist/skill/docs/compiler/definitions/access.md +1 -0
- package/dist/skill/docs/compiler/definitions/actions.md +27 -1
- package/dist/skill/docs/compiler/definitions/encryption.md +1 -0
- package/dist/skill/docs/compiler/definitions/feature.md +2 -0
- package/dist/skill/docs/compiler/definitions/masking.md +1 -0
- package/dist/skill/docs/compiler/getting-started/hand-crafted.md +8 -1
- package/dist/skill/docs/compiler/getting-started/patterns.md +1 -1
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +103 -4
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +1 -0
- package/dist/skill/docs/stack/account-ui/environment-variables.md +11 -0
- package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -0
- package/dist/skill/docs/stack/auth/jwt-optimization.md +9 -0
- package/dist/skill/docs/stack/cms/connecting.md +5 -0
- package/dist/skill/docs/stack/realtime/index.md +23 -5
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +27 -0
- package/src/skill/docs/compiler/cloud-compiler/deploy.md +82 -0
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +23 -0
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +2 -0
- package/src/skill/docs/compiler/config/index.md +5 -0
- package/src/skill/docs/compiler/config/security.md +1 -0
- package/src/skill/docs/compiler/definitions/access.md +1 -0
- package/src/skill/docs/compiler/definitions/actions.md +27 -1
- package/src/skill/docs/compiler/definitions/encryption.md +1 -0
- package/src/skill/docs/compiler/definitions/feature.md +2 -0
- package/src/skill/docs/compiler/definitions/masking.md +1 -0
- package/src/skill/docs/compiler/getting-started/hand-crafted.md +8 -1
- package/src/skill/docs/compiler/getting-started/patterns.md +1 -1
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +103 -4
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +1 -0
- package/src/skill/docs/stack/account-ui/environment-variables.md +11 -0
- package/src/skill/docs/stack/account-ui/with-quickback.md +2 -0
- package/src/skill/docs/stack/auth/jwt-optimization.md +9 -0
- package/src/skill/docs/stack/cms/connecting.md +5 -0
- package/src/skill/docs/stack/realtime/index.md +23 -5
|
@@ -299,6 +299,98 @@ The service-role marker is only ever set by Worker-internal chokepoints
|
|
|
299
299
|
input. Unsafe actions keep their mandatory audit contract: cross-tenant writes
|
|
300
300
|
still land audit events (the `audit` Postgres schema), unchanged from D1.
|
|
301
301
|
|
|
302
|
+
## Reads through a user-anchored relationship
|
|
303
|
+
|
|
304
|
+
Some resources are readable not because you own them or belong to their org, but
|
|
305
|
+
because you are reachable from them through a **chain of tables** anchored on the
|
|
306
|
+
caller's user id. A conference attendee, for example, can read their own
|
|
307
|
+
registrations even though they are not an org member — the grant travels
|
|
308
|
+
`person_account_links.user_id = ctx.userId → people → event_people →
|
|
309
|
+
registrations`.
|
|
310
|
+
|
|
311
|
+
Declare the chain once as an `authz.relationships` entry using the `hops` form
|
|
312
|
+
(each hop names the joined `table`, the column it is joined `on`, and the `prev`
|
|
313
|
+
column on the previous table that points at it). The terminal hop's `table` is
|
|
314
|
+
the **anchor** — the table carrying the caller's user id:
|
|
315
|
+
|
|
316
|
+
```typescript
|
|
317
|
+
// quickback.config.ts
|
|
318
|
+
authz: {
|
|
319
|
+
relationships: {
|
|
320
|
+
attendeeReachable: {
|
|
321
|
+
from: 'person_account_links', // the anchor table
|
|
322
|
+
subject: { column: 'userId', equals: 'ctx.userId' },
|
|
323
|
+
resource: { column: 'eventPersonId' }, // the column on the resource this constrains
|
|
324
|
+
hops: [
|
|
325
|
+
{ table: 'event_people', on: 'id', prev: 'eventPersonId' },
|
|
326
|
+
{ table: 'people', on: 'id', prev: 'personId' },
|
|
327
|
+
{ table: 'person_account_links', on: 'personId', prev: 'id' },
|
|
328
|
+
],
|
|
329
|
+
},
|
|
330
|
+
},
|
|
331
|
+
},
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
A resource opts into the grant by referencing the relationship from its
|
|
335
|
+
`firewall` — typically as one arm of an `any:` group so org members keep their
|
|
336
|
+
own path in:
|
|
337
|
+
|
|
338
|
+
```typescript
|
|
339
|
+
// features/registrations/registrations.ts
|
|
340
|
+
firewall: [
|
|
341
|
+
{
|
|
342
|
+
any: [
|
|
343
|
+
{ field: 'organizationId', equals: 'ctx.activeOrgId' }, // org-member grant
|
|
344
|
+
{ field: 'eventPersonId', via: 'attendeeReachable' }, // reachable-attendee grant
|
|
345
|
+
],
|
|
346
|
+
},
|
|
347
|
+
],
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
### The anchor must be non-forgeable (fail closed on both targets)
|
|
351
|
+
|
|
352
|
+
The reachability chain terminates in `anchor.user_id = ctx.userId`, so whoever
|
|
353
|
+
can **write** an anchor row can mint themselves reachability to a victim's data.
|
|
354
|
+
Quickback therefore refuses to compile a user-anchored multi-hop relationship
|
|
355
|
+
unless the anchor table is:
|
|
356
|
+
|
|
357
|
+
- **caller-read-own on the subject column** — its firewall scopes reads to
|
|
358
|
+
`ctx.userId` (e.g. `firewall: [{ field: 'userId', equals: 'ctx.userId' }]`), and
|
|
359
|
+
- **service-role-write-only** — it exposes no caller-reachable `create` / `update`
|
|
360
|
+
/ `delete` endpoint, so the link can only be created by Worker-internal code.
|
|
361
|
+
|
|
362
|
+
This check is **target-independent**: it fires identically on Neon and D1,
|
|
363
|
+
because the reachability join runs in the app layer on both. A forgeable anchor
|
|
364
|
+
is a compile error everywhere, not a Neon-only concern.
|
|
365
|
+
|
|
366
|
+
### How the read is served
|
|
367
|
+
|
|
368
|
+
On **Neon**, a via-relationship reachability predicate cannot be expressed as an
|
|
369
|
+
RLS policy — the correlated multi-hop join reaches across intermediate tables
|
|
370
|
+
that each `FORCE ROW LEVEL SECURITY`, so caller-claims RLS would deny the attendee
|
|
371
|
+
to *zero* rows before the app-layer WHERE ever runs. Quickback resolves this by
|
|
372
|
+
routing that resource's **read** handlers through the service-role handle
|
|
373
|
+
(`createServiceDb(c.env)`) instead of the caller-claims client. RLS stops denying,
|
|
374
|
+
and the compiled `buildFirewallConditions(...)` reachability WHERE — the exact
|
|
375
|
+
same clause D1 uses — becomes the **sole** row filter.
|
|
376
|
+
|
|
377
|
+
This is the D1 trust model, applied to Neon for exactly these reads: the
|
|
378
|
+
application layer is the firewall, and RLS is a coarse tenant backstop that steps
|
|
379
|
+
aside where it cannot express the grant. It is surgical and fail-closed:
|
|
380
|
+
|
|
381
|
+
- Only the affected resource's reads swap handles. **Org / owner / team reads keep
|
|
382
|
+
caller claims + the RLS backstop** — they resolve to policies RLS *can* express.
|
|
383
|
+
- The swap is gated on a non-empty firewall carrying the reachability predicate;
|
|
384
|
+
a service-handle read with no WHERE is a compile error (it would return every
|
|
385
|
+
tenant's rows). Fail closed.
|
|
386
|
+
- It applies to the **collection `GET /`, `GET /:id`, and views** alike. **Writes
|
|
387
|
+
are unchanged** — creates/updates/deletes keep caller claims and the RLS
|
|
388
|
+
backstop.
|
|
389
|
+
|
|
390
|
+
The **same config compiles identically on D1**, where there is no RLS to bypass:
|
|
391
|
+
the read handlers keep `c.get('db')` and the app-layer reachability WHERE was
|
|
392
|
+
already the whole story.
|
|
393
|
+
|
|
302
394
|
## Webhooks on Neon
|
|
303
395
|
|
|
304
396
|
Webhooks are supported on Neon over HTTP. The store (`webhook_events`,
|
|
@@ -362,10 +454,10 @@ export default defineAction({
|
|
|
362
454
|
input: z.object({ registrationId: z.string() }),
|
|
363
455
|
async execute({ db, input }) {
|
|
364
456
|
return db.transaction(async (tx) => { // tx is fully typed
|
|
365
|
-
const reg = await tx.
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
457
|
+
const [reg] = await tx.select()
|
|
458
|
+
.from(registrations)
|
|
459
|
+
.where(eq(registrations.id, input.registrationId))
|
|
460
|
+
.for("update"); // row lock held to commit
|
|
369
461
|
if (!reg) throw new ActionError("Not found", "NOT_FOUND", 404); // → rollback
|
|
370
462
|
const [updated] = await tx.update(registrations)
|
|
371
463
|
.set({ status: nextStatus(reg) })
|
|
@@ -378,6 +470,13 @@ export default defineAction({
|
|
|
378
470
|
});
|
|
379
471
|
```
|
|
380
472
|
|
|
473
|
+
Note the `tx.select()…for("update")` form: Drizzle's relational query API
|
|
474
|
+
(`tx.query.<table>.findFirst`) is [blocked on the scoped
|
|
475
|
+
`db`/`tx`](/compiler/definitions/actions#relational-queries-are-blocked-fail-closed)
|
|
476
|
+
because the tenant firewall can't be injected into relational queries. The
|
|
477
|
+
select builder gives you the same row lock with scope conditions applied
|
|
478
|
+
automatically.
|
|
479
|
+
|
|
381
480
|
Configure it on the database provider:
|
|
382
481
|
|
|
383
482
|
```ts
|
|
@@ -70,6 +70,7 @@ Missing or invalid authentication tokens.
|
|
|
70
70
|
| `AUTH_INVALID_TOKEN` | Token is malformed or invalid |
|
|
71
71
|
| `AUTH_EXPIRED` | Token has expired |
|
|
72
72
|
| `AUTH_RATE_LIMITED` | Too many auth attempts |
|
|
73
|
+
| `AUTH_SESSION_REQUIRED` | The endpoint requires session (cookie) authentication — returned by `POST /api/v1/token` when called with a JWT, API key, or OAuth bearer, so a stolen or revoked token can't mint its own replacement |
|
|
73
74
|
|
|
74
75
|
### Firewall (403)
|
|
75
76
|
|
|
@@ -2,6 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
Configure the Account UI by setting environment variables in your `.env` file or deployment platform.
|
|
4
4
|
|
|
5
|
+
> **Runtime config takes precedence**
|
|
6
|
+
>
|
|
7
|
+
> Every variable on this page can also be delivered at **serve time** via the worker-injected `window.__QUICKBACK_RUNTIME` blob. When a Quickback-generated worker serves the Account UI (unified `/account`, custom domain, or dev hostnames), it injects the project's values into the HTML shell automatically. Resolution precedence for every per-project field is:
|
|
8
|
+
>
|
|
9
|
+
> 1. `window.__QUICKBACK_RUNTIME.<field>` (injected by the serving worker)
|
|
10
|
+
> 2. Baked `VITE_*` env (this page — set at build time)
|
|
11
|
+
> 3. Built-in default
|
|
12
|
+
>
|
|
13
|
+
> This means a single generic build of the Account UI (no `.env`) behaves identically to a per-project baked build when served by the worker. Baked builds keep working unchanged — the blob simply wins when both are present.
|
|
14
|
+
|
|
15
|
+
|
|
5
16
|
## Quick Setup — Single Variable
|
|
6
17
|
|
|
7
18
|
For the common "unified deployment" where API, Account, and CMS all live on the same Quickback origin, you only need **one** variable:
|
|
@@ -40,6 +40,8 @@ npx wrangler deploy
|
|
|
40
40
|
4. Vite builds the SPA with your settings baked in
|
|
41
41
|
5. Built assets (content-hashed filenames) are placed in the output directory
|
|
42
42
|
|
|
43
|
+
The generated worker **also** injects the same per-project values into every served Account shell as `window.__QUICKBACK_RUNTIME` (URLs, branding, auth feature flags). The SPA prefers that runtime blob over the baked `VITE_*` values, so a generic (no-`.env`) Account build served by the worker behaves identically to the baked build — the bake remains a fallback for serving the assets outside a Quickback worker.
|
|
44
|
+
|
|
43
45
|
When CMS is also enabled, Account assets go to `src/apps/account/` and are served at `/account/`. When Account is the only SPA, assets go to `src/apps/` and are served at root.
|
|
44
46
|
|
|
45
47
|
### Custom Domains
|
|
@@ -109,6 +109,15 @@ When a JWT expires or is invalid:
|
|
|
109
109
|
|
|
110
110
|
`POST /api/v1/token` mints a fresh JWT from the current session. This endpoint goes through normal auth middleware, so the user must have a valid session cookie.
|
|
111
111
|
|
|
112
|
+
**Session authentication is required — and enforced.** A request authenticated
|
|
113
|
+
by a bearer JWT (or an API key / OAuth access token) is rejected with `401
|
|
114
|
+
AUTH_SESSION_REQUIRED` ("Token refresh requires session authentication").
|
|
115
|
+
This is deliberate: only the session path re-validates against Better Auth's
|
|
116
|
+
session store on every request, so bans, member removals, role demotions, and
|
|
117
|
+
sign-outs take effect immediately. If a JWT could mint its own replacement, a
|
|
118
|
+
stolen or revoked token could roll a short-TTL JWT forever without ever
|
|
119
|
+
re-validating — the TTL would bound nothing.
|
|
120
|
+
|
|
112
121
|
**Request:**
|
|
113
122
|
```bash
|
|
114
123
|
curl -X POST https://your-api.example.com/api/v1/token \
|
|
@@ -49,6 +49,11 @@ Set `VITE_QUICKBACK_API_URL` to connect to a real Quickback API:
|
|
|
49
49
|
VITE_QUICKBACK_API_URL=https://api.example.com
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
+
> **Runtime config takes precedence**
|
|
53
|
+
>
|
|
54
|
+
> When a Quickback-generated worker serves the CMS (unified `/cms`, custom domain, or dev hostnames), it injects the project's values into the HTML shell as `window.__QUICKBACK_RUNTIME` — `apiUrl`, `accountUrl`, `cmsAccess`, `cmsSysadmin`, `pinnedOrganizationId`, `enableRealtime`. Every per-project field resolves as **runtime blob → baked `VITE_*` env → default**, so a single generic CMS build (no `.env`) served by the worker behaves identically to a per-project baked build. Baked builds keep working unchanged.
|
|
55
|
+
|
|
56
|
+
|
|
52
57
|
In live mode, the CMS:
|
|
53
58
|
|
|
54
59
|
- Reads the **Better Auth session** from cookies
|
|
@@ -81,17 +81,35 @@ export default defineTable(applications, {
|
|
|
81
81
|
|
|
82
82
|
And enable the realtime **transport** in your database config. This is a
|
|
83
83
|
project-level switch that stands up the Broadcaster Durable Object + the
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
84
|
+
connection route; it does **not** by itself make any resource broadcast
|
|
85
|
+
(that's the per-resource `realtime` block above). The compiler generates the
|
|
86
|
+
Durable Object class, helper functions, and wrangler bindings — all within
|
|
87
|
+
your main worker.
|
|
88
|
+
|
|
89
|
+
For most apps — including org-scoped apps like chat, feeds, and dashboards —
|
|
90
|
+
the boolean form is all you need. Session-authenticated members subscribe
|
|
91
|
+
directly; audiences come from each resource's `realtime.access.roles`:
|
|
92
|
+
|
|
93
|
+
```typescript
|
|
94
|
+
providers: {
|
|
95
|
+
database: defineDatabase("cloudflare-d1", {
|
|
96
|
+
realtime: true,
|
|
97
|
+
}),
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The object form is the **advanced** variant, only needed when you mint
|
|
102
|
+
resource-scoped tickets for relationship-authorized subscribers (e.g. an
|
|
103
|
+
external attendee who may join one event's channel). `wsTicket.role` must be
|
|
104
|
+
an `authz.roles` relationship role — NOT an org-membership role like
|
|
105
|
+
`member`/`admin`/`owner` (those names are reserved and will not compile here):
|
|
88
106
|
|
|
89
107
|
```typescript
|
|
90
108
|
providers: {
|
|
91
109
|
database: defineDatabase("cloudflare-d1", {
|
|
92
110
|
realtime: {
|
|
93
111
|
wsTicket: {
|
|
94
|
-
role: "attendee",
|
|
112
|
+
role: "attendee", // authz relationship role, not an org role
|
|
95
113
|
requestField: "eventId",
|
|
96
114
|
scopeTable: "events",
|
|
97
115
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.50.
|
|
3
|
+
"version": "0.50.4",
|
|
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",
|
|
@@ -2,6 +2,33 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
### Security: three fail-closed fixes in the generated runtime
|
|
6
|
+
|
|
7
|
+
- **Scoped `db` blocks Drizzle's relational query API.** `db.query.<table>.findFirst()` / `findMany()` build their SQL outside the scoped wrapper's reach, so they read across organizations. The scoped `db` handed to actions now **throws** on any `db.query.<table>` access (and the Neon hyperdrive typed `db`/`tx` fails `tsc` on it) with directions to `db.select()` (auto-scoped) or an `unsafe: true` action's `unsafeDb.query` with an explicit scope predicate. Handlers that relied on the unscoped pass-through were reading other tenants' rows and must be updated. See [Relational queries are blocked](/compiler/definitions/actions#relational-queries-are-blocked-fail-closed).
|
|
8
|
+
- **`POST /api/v1/token` requires session authentication.** The auth middleware now stamps `ctx.authMethod` (`'session' | 'jwt' | 'api-key' | 'oauth'`), and the token endpoint rejects anything but `'session'` with `401 AUTH_SESSION_REQUIRED`. Pre-fix, a JWT could mint its own replacement — a stolen or revoked token (banned user, removed member, demoted role) could roll a 180s-TTL token forever without re-validating the session.
|
|
9
|
+
- **Broadcaster DO no longer trusts the `X-Internal-Call` header alone.** Inline-mode `checkAuth` now requires `X-Internal-Secret` to match `BETTER_AUTH_SECRET` (already provisioned; the secret never leaves the worker/DO boundary on a stub call), separate mode compares `ACCESS_TOKEN` constant-time, and every generated internal caller (`lib/realtime.ts` senders, the live-view seq reader, the Better Auth role-change hook) sends the secret. A spoofed header can no longer reach broadcast injection or webhook repointing through any forwarded route.
|
|
10
|
+
|
|
11
|
+
### Neon reads through user-anchored relationships
|
|
12
|
+
|
|
13
|
+
Resources readable via a multi-hop chain anchored on the caller's user id (e.g. a
|
|
14
|
+
conference attendee reaching their own registrations through
|
|
15
|
+
`person_account_links → people → event_people → registrations`) now work on Neon.
|
|
16
|
+
Declare the chain once with the `hops` form on an `authz.relationships` entry and
|
|
17
|
+
reference it from a resource `firewall` via `{ field, via }`. Because the
|
|
18
|
+
correlated multi-hop join reaches across intermediate tables that each `FORCE ROW
|
|
19
|
+
LEVEL SECURITY`, caller-claims RLS would deny such a read to zero rows — so the
|
|
20
|
+
compiler routes **only that resource's read handlers** (collection `GET /`,
|
|
21
|
+
`GET /:id`, and views) through the service-role handle (`createServiceDb`), with
|
|
22
|
+
the compiled app-layer reachability WHERE as the sole row filter. Org/owner/team
|
|
23
|
+
reads are untouched (caller claims + RLS backstop); writes are unchanged. The
|
|
24
|
+
swap is fail-closed — a service-handle read with no firewall WHERE is a compile
|
|
25
|
+
error. The anchor table is required to be caller-read-own on the subject column
|
|
26
|
+
and service-role-write-only (a forgeable link would mint reachability to a
|
|
27
|
+
victim's data); this link-integrity check is target-independent and fails the
|
|
28
|
+
compile on **both** Neon and D1. The same config compiles identically on D1,
|
|
29
|
+
where the app-layer WHERE was already the whole firewall. See
|
|
30
|
+
[Reads through a user-anchored relationship](/compiler/targets/hono-api/database/neon#reads-through-a-user-anchored-relationship).
|
|
31
|
+
|
|
5
32
|
### Neon interactive transactions via Hyperdrive
|
|
6
33
|
|
|
7
34
|
A Neon project can now opt into `connectionMode: 'hyperdrive'` to run its feature
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Deploying
|
|
2
|
+
|
|
3
|
+
A freshly compiled project's `wrangler.toml` contains **placeholder resource ids** — the compiler can't know your D1 database ids or KV namespace id until those resources exist in your Cloudflare account. Historically that meant a manual dance: `wrangler d1 create`, copy the id, paste it into `quickback.config.ts`, repeat for every database, recompile, deploy.
|
|
4
|
+
|
|
5
|
+
`quickback deploy` does the whole dance for you:
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
cd my-app && quickback deploy
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## What it does
|
|
12
|
+
|
|
13
|
+
1. **Preflight** — verifies `wrangler` is runnable (via `npx`) and authenticated with Cloudflare (`wrangler whoami`). Log in with `npx wrangler login` or set `CLOUDFLARE_API_TOKEN`.
|
|
14
|
+
2. **Compiles first if needed** — if the project has never compiled (no `wrangler.toml`), it runs the same flow as `quickback compile` before planning anything.
|
|
15
|
+
3. **Plans from wrangler.toml** — reads the generated `wrangler.toml` and finds every resource whose id is still a placeholder:
|
|
16
|
+
- **D1 databases** — auth, features, files, and webhooks databases (whichever your project's features pull in; split-database projects get one entry each)
|
|
17
|
+
- **KV namespace** — the `KV` binding used for rate limiting and session overflow
|
|
18
|
+
- **R2 buckets** — file-storage buckets (R2 is referenced by name, so buckets are simply ensured to exist)
|
|
19
|
+
4. **Creates what's missing** — `wrangler d1 create <name>`, `wrangler kv namespace create <BINDING>`, `wrangler r2 bucket create <name>`. Resources are named from your project name exactly the way the compiler names them (`my-app-auth`, `my-app-features`, `my-app-files`, `my-app-KV`, …). If a resource with the expected name already exists in your account, its id is reused instead of creating a duplicate.
|
|
20
|
+
5. **Writes ids back into quickback.config.ts** — a surgical, formatting-preserving edit of your `providers.database.config` (and `providers.storage.config` for the KV id when you declare a `cloudflare-kv` storage provider). Comments, indentation, and every other key are left untouched. Works with both authoring styles:
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
// defineDatabase(...) wrapper
|
|
24
|
+
database: defineDatabase("cloudflare-d1", {
|
|
25
|
+
splitDatabases: true,
|
|
26
|
+
authDatabaseId: "…", // ← inserted/updated here
|
|
27
|
+
featuresDatabaseId: "…",
|
|
28
|
+
}),
|
|
29
|
+
|
|
30
|
+
// plain object form
|
|
31
|
+
database: {
|
|
32
|
+
name: "cloudflare-d1",
|
|
33
|
+
config: {
|
|
34
|
+
authDatabaseId: "…", // ← or here
|
|
35
|
+
},
|
|
36
|
+
},
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
6. **Recompiles** — so `wrangler.toml` regenerates with the real ids.
|
|
40
|
+
7. **Applies D1 migrations remotely** — `wrangler d1 migrations apply <db> --remote` for each database that has pending migration files (each database's `migrations_dir` comes straight from `wrangler.toml`).
|
|
41
|
+
8. **Deploys** — `wrangler deploy`, streaming wrangler's output.
|
|
42
|
+
|
|
43
|
+
## Idempotent by design
|
|
44
|
+
|
|
45
|
+
Run it again any time. When every id is real, there's nothing to create — the command goes straight to compile → migrations → deploy. It's a perfectly good everyday "ship it" command, not just a first-deploy tool.
|
|
46
|
+
|
|
47
|
+
## Flags
|
|
48
|
+
|
|
49
|
+
| Flag | Effect |
|
|
50
|
+
|------|--------|
|
|
51
|
+
| `--dry-run` | Print the provisioning plan (what would be created vs. what's already set) and exit. Creates nothing. |
|
|
52
|
+
| `--skip-deploy` | Provision resources + sync ids + recompile, but skip migrations and the deploy itself. |
|
|
53
|
+
| `--force` | Overwrite a config id that differs from what Cloudflare reports. Without it, a mismatch prints both values and aborts — never silently overwritten. |
|
|
54
|
+
| `--verbose` | Detailed remote compile failure output (same as `quickback compile --verbose`). |
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
# See the plan without touching your account
|
|
58
|
+
quickback deploy --dry-run
|
|
59
|
+
|
|
60
|
+
# Provision + write ids only; deploy later
|
|
61
|
+
quickback deploy --skip-deploy
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Conflicting ids
|
|
65
|
+
|
|
66
|
+
If `quickback.config.ts` already carries a real id for a resource and Cloudflare reports a different one for the same-named resource, `quickback deploy` prints both and stops:
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
✖ Config ids differ from what Cloudflare reports:
|
|
70
|
+
providers.database.config.authDatabaseId
|
|
71
|
+
in quickback.config.ts: 13b688c8-…
|
|
72
|
+
from Cloudflare: f6b8f9a0-…
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Re-run with `--force` to take Cloudflare's value, or fix the config by hand.
|
|
76
|
+
|
|
77
|
+
## Notes
|
|
78
|
+
|
|
79
|
+
- **Security-audit database** — projects using unsafe cross-tenant actions require an audit D1 database, and the compiler fails closed at compile time until `auditDatabaseId` is set. Follow the compile error's instructions (create the database, set the id), then re-run `quickback deploy`.
|
|
80
|
+
- **Neon projects** — `quickback deploy` does not apply Postgres migrations. Run `npm run db:migrate` (needs `DATABASE_MIGRATION_URL`) before traffic hits the worker, or use the generated project's `npm run deploy` script which chains both.
|
|
81
|
+
- **Hyperdrive** — a Hyperdrive binding can't be auto-created (it needs your database connection string). Create it with `wrangler hyperdrive create <name> --connection-string=… --caching-disabled` and set `providers.database.config.hyperdrive.id`.
|
|
82
|
+
- **Two logins** — the compile step uses your Quickback account (`quickback login`); resource creation and deploy use your wrangler credentials.
|
|
@@ -17,6 +17,29 @@ The cloud compiler API is hosted at `https://compiler.quickback.dev`.
|
|
|
17
17
|
|
|
18
18
|
The `/compile` endpoint requires either a session token (from `quickback login`) or an API key (via `QUICKBACK_API_KEY` header). See [Authentication](/compiler/cloud-compiler/authentication) for details.
|
|
19
19
|
|
|
20
|
+
## Raw-files mode (`POST /compile`)
|
|
21
|
+
|
|
22
|
+
`/compile` normally expects the parsed `CompilerInput` the CLI assembles client-side. Thin clients (agents, web builders, CI without the CLI) can instead send the project sources verbatim and let the compiler organize them server-side:
|
|
23
|
+
|
|
24
|
+
```json
|
|
25
|
+
{
|
|
26
|
+
"rawFiles": {
|
|
27
|
+
"quickback/quickback.config.ts": "import { defineConfig } from …",
|
|
28
|
+
"quickback/features/todos/todos.ts": "import { feature, q } from …",
|
|
29
|
+
"quickback/features/todos/actions/complete.ts": "…"
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The map uses project-root-relative paths and follows the same layout `quickback compile` reads from disk: `quickback/quickback.config.ts`, `quickback/features/**`, `quickback/services/**`, `quickback/{lib,hooks,plugins,middlewares,email-templates}/**`, plus `quickback/drizzle/**/meta/**` and `wrangler.toml` for incremental builds.
|
|
35
|
+
|
|
36
|
+
Two constraints, both fail-closed:
|
|
37
|
+
|
|
38
|
+
- **The config must be fully static.** The compiler parses `quickback.config.ts` with a literals-only evaluator — it never executes user code. Object/array/string/number/boolean literals, substitution-free template literals, and the `define*` helper calls all work; variables, computed values, and imports-as-values are rejected with a 400 that names the offending construct and line.
|
|
39
|
+
- **Action input schemas are optional.** The CLI harvests `z.toJSONSchema` on your machine; raw-files requests may pass `actionInputSchemas` alongside `rawFiles`, otherwise the compiler's static parser supplies lower-fidelity input schemas.
|
|
40
|
+
|
|
41
|
+
Works with both `?complete=true` and `?complete=false` (validation-only) compiles.
|
|
42
|
+
|
|
20
43
|
## Environment Variables
|
|
21
44
|
|
|
22
45
|
| Variable | Description |
|
|
@@ -74,6 +74,8 @@ The Docker image includes:
|
|
|
74
74
|
|
|
75
75
|
When compiling a project with `cms: true` or `account: true`, the compiler builds the SPAs from source inside the container with the correct Vite environment variables (e.g., `VITE_QUICKBACK_API_URL`, `VITE_QUICKBACK_ACCOUNT_URL`). This ensures each project gets properly configured SPA assets without manual intervention.
|
|
76
76
|
|
|
77
|
+
The generated worker additionally injects the same per-project values into every served SPA shell as `window.__QUICKBACK_RUNTIME`, and the SPAs prefer that runtime blob over the baked env — so the served behavior is identical even with a generic (no-`.env`) SPA build.
|
|
78
|
+
|
|
77
79
|
## Deploying to Cloud
|
|
78
80
|
|
|
79
81
|
After making changes to the compiler, deploy to `compiler.quickback.dev`:
|
|
@@ -8,6 +8,11 @@ import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickb
|
|
|
8
8
|
export default defineConfig({
|
|
9
9
|
name: "my-app",
|
|
10
10
|
template: "hono",
|
|
11
|
+
auth: {
|
|
12
|
+
// Required for "+" role expansion in access rules (e.g. roles: ["member+"]).
|
|
13
|
+
// Lowest → highest. Omit if you always list roles explicitly.
|
|
14
|
+
roleHierarchy: ["member", "admin", "owner"],
|
|
15
|
+
},
|
|
11
16
|
providers: {
|
|
12
17
|
runtime: defineRuntime("cloudflare"),
|
|
13
18
|
database: defineDatabase("cloudflare-d1"),
|
|
@@ -129,6 +129,7 @@ When you opt into a `csp` object, the compiler additively widens directives base
|
|
|
129
129
|
| `cms: true` OR `account: true` | `https://fonts.gstatic.com` | `fontSrc` | The googleapis CSS loads `.woff2` from gstatic |
|
|
130
130
|
| `csp` set (always) | `@trustedOrigins` | `connectSrc` | XHR/fetch must reach the same allowlist `cors()` permits — covers cross-subdomain APIs without re-listing them |
|
|
131
131
|
| `cms: true` OR `account: true` | `https://${domain}` for each `cms.domain` / `account.domain` / `domain` / inferred unified domain | `connectSrc` | The Vite bundle hardcodes `VITE_QUICKBACK_API_URL` at compile time, so the SPA fetches that exact URL even when the page is served from a different origin (e.g. localhost dev hitting prod-baked SPA). Emitted with the host's first letter capitalised (`https://Api.example.com`) so `wrangler dev`'s response-header rewrite can't mangle it — see [the `wrangler dev` note below](#why-the-spa-baked-origin-shows-up-capitalised-in-csp). |
|
|
132
|
+
| `cms: true` OR `account: true` | `'sha256-…'` (one exact hash per bundled SPA) | `scriptSrc` | The worker injects `<script>window.__QUICKBACK_RUNTIME={...}</script>` into every served SPA shell (runtime-configured SPAs). The blob is fixed at compile time, so an exact script hash keeps strict `script-src` policies intact — no `'unsafe-inline'`. |
|
|
132
133
|
|
|
133
134
|
**Scaffold rule:** if you set `defaultSrc` but omit the target directive (e.g. you wrote `defaultSrc: ['@self']` and nothing for `connectSrc`), auto-config creates the new directive seeded with your `defaultSrc` values plus the addition. `defaultSrc` itself stays clean. So `defaultSrc: ['@self']` + auto-config produces:
|
|
134
135
|
|
|
@@ -278,6 +278,7 @@ access: { userRole: ["appmanager"] }
|
|
|
278
278
|
access: { roles: ["SYSADMIN"] }
|
|
279
279
|
|
|
280
280
|
// Org-membership roles with hierarchy expansion
|
|
281
|
+
// ("+" requires auth.roleHierarchy in quickback.config.ts — see Role Hierarchy above)
|
|
281
282
|
access: { roles: ["member+"] } // expands to ["member", "admin", "owner"]
|
|
282
283
|
access: { roles: ["admin+"] } // expands to ["admin", "owner"]
|
|
283
284
|
access: { roles: ["admin"] } // exact match (no expansion)
|
|
@@ -41,7 +41,10 @@ features/applications/
|
|
|
41
41
|
| `actions/<name>.ts` | The feature's primary table (table file matching the feature name), or standalone if `path:` is set. |
|
|
42
42
|
| `actions/<table>/<name>.ts` | The sibling table file `<table>.ts` at the feature root. Standalone actions inside a subdir ignore the binding. |
|
|
43
43
|
|
|
44
|
-
The action's filename (sans `.ts`) is the action name and the URL segment
|
|
44
|
+
The action's filename (sans `.ts`) is the action name and the URL segment, and
|
|
45
|
+
it must be a valid **camelCase identifier** — `sendMessage.ts`, not
|
|
46
|
+
`send-message.ts` (hyphenated names are a compile error, since the name becomes
|
|
47
|
+
a generated identifier).
|
|
45
48
|
Uniqueness is enforced per `(bound table, name)` pair — sibling-bound
|
|
46
49
|
actions on **different** tables may share a verb (`actions/episodes/publish.ts`
|
|
47
50
|
and `actions/shows/publish.ts` mount at `/episodes/:id/publish` and
|
|
@@ -657,6 +660,29 @@ async execute({ db, ctx, input }) {
|
|
|
657
660
|
- **Masking** — actions are backend code that may need raw data
|
|
658
661
|
- **Access** — already checked before action execution
|
|
659
662
|
|
|
663
|
+
### Relational queries are blocked (fail-closed)
|
|
664
|
+
|
|
665
|
+
Drizzle's relational query API — `db.query.<table>.findFirst()` /
|
|
666
|
+
`findMany()` (including nested `with:` relations) — builds its SQL from the
|
|
667
|
+
relations config and your `where` alone, so the scoped wrapper cannot inject
|
|
668
|
+
the org/owner/team firewall into it. Rather than silently returning rows from
|
|
669
|
+
every tenant, the scoped `db` **throws** on any `db.query.<table>` access:
|
|
670
|
+
|
|
671
|
+
```typescript
|
|
672
|
+
async execute({ db, input }) {
|
|
673
|
+
// ❌ Throws: relational queries aren't org-scoped
|
|
674
|
+
const item = await db.query.media.findFirst({ where: eq(media.id, input.id) });
|
|
675
|
+
|
|
676
|
+
// ✅ Scoped builder — firewall conditions injected automatically
|
|
677
|
+
const [item] = await db.select().from(media).where(eq(media.id, input.id));
|
|
678
|
+
}
|
|
679
|
+
```
|
|
680
|
+
|
|
681
|
+
If you genuinely need the relational API, declare the action `unsafe: true`
|
|
682
|
+
and query `unsafeDb.query` with an **explicit** scope predicate in the WHERE
|
|
683
|
+
(e.g. `eq(media.organizationId, ctx.activeOrgId)`), exactly like any other
|
|
684
|
+
unsafe read.
|
|
685
|
+
|
|
660
686
|
### Unsafe Mode
|
|
661
687
|
|
|
662
688
|
Actions that need to bypass scoped DB filters (for example, platform-level support operations) can enable unsafe mode.
|
|
@@ -11,6 +11,7 @@ export default feature('guests', {
|
|
|
11
11
|
emergencyContact: q.text().encrypted(),
|
|
12
12
|
dietaryNotes: q.text().encrypted(),
|
|
13
13
|
},
|
|
14
|
+
// "+" role expansion requires auth.roleHierarchy in quickback.config.ts
|
|
14
15
|
read: { access: { roles: ['member+'] } },
|
|
15
16
|
create: { access: { roles: ['member+'] } },
|
|
16
17
|
});
|
|
@@ -16,6 +16,7 @@ export const contacts = q.table("contacts", {
|
|
|
16
16
|
|
|
17
17
|
export default defineTable(contacts, {
|
|
18
18
|
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
19
|
+
// "+" role expansion requires auth.roleHierarchy in quickback.config.ts
|
|
19
20
|
read: { access: { roles: ["member+"] } },
|
|
20
21
|
create: { access: { roles: ["member+"] } },
|
|
21
22
|
update: { access: { roles: ["member+"] } },
|
|
@@ -39,6 +40,7 @@ export default feature("contacts", {
|
|
|
39
40
|
name: q.text().optional(),
|
|
40
41
|
},
|
|
41
42
|
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
43
|
+
// "+" role expansion requires auth.roleHierarchy in quickback.config.ts
|
|
42
44
|
read: { access: { roles: ["member+"] } },
|
|
43
45
|
create: { access: { roles: ["member+"] } },
|
|
44
46
|
update: { access: { roles: ["member+"] } },
|
|
@@ -39,7 +39,14 @@ import { defineConfig } from "@quickback/compiler";
|
|
|
39
39
|
export default defineConfig({
|
|
40
40
|
name: "my-app",
|
|
41
41
|
template: "hono",
|
|
42
|
-
features:
|
|
42
|
+
features: {
|
|
43
|
+
organizations: true,
|
|
44
|
+
},
|
|
45
|
+
auth: {
|
|
46
|
+
// Required for "+" role expansion in access rules (e.g. roles: ["member+"]).
|
|
47
|
+
// Lowest → highest. Omit if you always list roles explicitly.
|
|
48
|
+
roleHierarchy: ["member", "admin", "owner"],
|
|
49
|
+
},
|
|
43
50
|
providers: {
|
|
44
51
|
runtime: { name: "cloudflare", config: {} },
|
|
45
52
|
database: {
|
|
@@ -134,7 +134,7 @@ import { projects } from "../projects";
|
|
|
134
134
|
export default defineAction({
|
|
135
135
|
description: "Assign a project to an org member",
|
|
136
136
|
input: z.object({ assigneeId: z.string() }),
|
|
137
|
-
access: { roles: ["member+"] },
|
|
137
|
+
access: { roles: ["member+"] }, // "+" requires auth.roleHierarchy in quickback.config.ts
|
|
138
138
|
async execute({ db, record, input, ctx, c, whereRecord }) {
|
|
139
139
|
const role = await getOrgMemberRole(c.get("authDb"), input.assigneeId, ctx.activeOrgId!);
|
|
140
140
|
if (!role) {
|