@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.
Files changed (70) hide show
  1. package/dist/commands/deploy.d.ts +29 -0
  2. package/dist/commands/deploy.d.ts.map +1 -0
  3. package/dist/commands/deploy.js +324 -0
  4. package/dist/commands/deploy.js.map +1 -0
  5. package/dist/docs/content.d.ts.map +1 -1
  6. package/dist/docs/content.js +22 -17
  7. package/dist/docs/content.js.map +1 -1
  8. package/dist/index.js +10 -1
  9. package/dist/index.js.map +1 -1
  10. package/dist/lib/config-id-splice.d.ts +68 -0
  11. package/dist/lib/config-id-splice.d.ts.map +1 -0
  12. package/dist/lib/config-id-splice.js +364 -0
  13. package/dist/lib/config-id-splice.js.map +1 -0
  14. package/dist/lib/config-id-splice.test.d.ts +2 -0
  15. package/dist/lib/config-id-splice.test.d.ts.map +1 -0
  16. package/dist/lib/config-id-splice.test.js +246 -0
  17. package/dist/lib/config-id-splice.test.js.map +1 -0
  18. package/dist/lib/shell.d.ts +14 -0
  19. package/dist/lib/shell.d.ts.map +1 -1
  20. package/dist/lib/shell.js +27 -0
  21. package/dist/lib/shell.js.map +1 -1
  22. package/dist/lib/wrangler-resources.d.ts +131 -0
  23. package/dist/lib/wrangler-resources.d.ts.map +1 -0
  24. package/dist/lib/wrangler-resources.js +355 -0
  25. package/dist/lib/wrangler-resources.js.map +1 -0
  26. package/dist/lib/wrangler-resources.test.d.ts +2 -0
  27. package/dist/lib/wrangler-resources.test.d.ts.map +1 -0
  28. package/dist/lib/wrangler-resources.test.js +321 -0
  29. package/dist/lib/wrangler-resources.test.js.map +1 -0
  30. package/dist/skill/docs/changelog.md +27 -0
  31. package/dist/skill/docs/compiler/cloud-compiler/deploy.md +82 -0
  32. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +23 -0
  33. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +2 -0
  34. package/dist/skill/docs/compiler/config/index.md +5 -0
  35. package/dist/skill/docs/compiler/config/security.md +1 -0
  36. package/dist/skill/docs/compiler/definitions/access.md +1 -0
  37. package/dist/skill/docs/compiler/definitions/actions.md +27 -1
  38. package/dist/skill/docs/compiler/definitions/encryption.md +1 -0
  39. package/dist/skill/docs/compiler/definitions/feature.md +2 -0
  40. package/dist/skill/docs/compiler/definitions/masking.md +1 -0
  41. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +8 -1
  42. package/dist/skill/docs/compiler/getting-started/patterns.md +1 -1
  43. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +103 -4
  44. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +1 -0
  45. package/dist/skill/docs/stack/account-ui/environment-variables.md +11 -0
  46. package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -0
  47. package/dist/skill/docs/stack/auth/jwt-optimization.md +9 -0
  48. package/dist/skill/docs/stack/cms/connecting.md +5 -0
  49. package/dist/skill/docs/stack/realtime/index.md +23 -5
  50. package/package.json +1 -1
  51. package/src/skill/docs/changelog.md +27 -0
  52. package/src/skill/docs/compiler/cloud-compiler/deploy.md +82 -0
  53. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +23 -0
  54. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +2 -0
  55. package/src/skill/docs/compiler/config/index.md +5 -0
  56. package/src/skill/docs/compiler/config/security.md +1 -0
  57. package/src/skill/docs/compiler/definitions/access.md +1 -0
  58. package/src/skill/docs/compiler/definitions/actions.md +27 -1
  59. package/src/skill/docs/compiler/definitions/encryption.md +1 -0
  60. package/src/skill/docs/compiler/definitions/feature.md +2 -0
  61. package/src/skill/docs/compiler/definitions/masking.md +1 -0
  62. package/src/skill/docs/compiler/getting-started/hand-crafted.md +8 -1
  63. package/src/skill/docs/compiler/getting-started/patterns.md +1 -1
  64. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +103 -4
  65. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +1 -0
  66. package/src/skill/docs/stack/account-ui/environment-variables.md +11 -0
  67. package/src/skill/docs/stack/account-ui/with-quickback.md +2 -0
  68. package/src/skill/docs/stack/auth/jwt-optimization.md +9 -0
  69. package/src/skill/docs/stack/cms/connecting.md +5 -0
  70. 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.query.registrations.findFirst({
366
- where: eq(registrations.id, input.registrationId),
367
- lock: "for update", // row lock held to commit
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
- ws-ticket connection route; it does **not** by itself make any resource
85
- broadcast (that's the per-resource `realtime` block above). The compiler
86
- generates the Durable Object class, helper functions, and wrangler bindings —
87
- all within your main worker.
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
  },