@quickback-dev/cli 0.50.7 → 0.51.0

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.
@@ -197,14 +197,14 @@ providers: {
197
197
  }
198
198
  ```
199
199
 
200
- For relationship-authorized resource scopes, use the object form:
200
+ For resource-scoped tickets, use the object form. The mint gate is a discriminated `access` union — exactly one arm:
201
201
 
202
202
  ```typescript
203
203
  providers: {
204
204
  database: defineDatabase("cloudflare-d1", {
205
205
  realtime: {
206
206
  wsTicket: {
207
- role: "attendee",
207
+ access: { authzRole: "attendee" }, // or { roles: ["member+"] } or { fga: { relation, object } }
208
208
  requestField: "eventId",
209
209
  scopeTable: "events",
210
210
  },
@@ -215,11 +215,11 @@ providers: {
215
215
 
216
216
  `wsTicket` tells the compiler how to authorize `/broadcast/v1/ws-ticket` and what scope to stamp into the short-lived websocket ticket:
217
217
 
218
- - `role`: an authz role declared under `authz.roles` that uses a direct relationship (`{ via: "..." }`)
218
+ - `access`: the mint gate — one of `{ roles: ["member+"] }` (org-membership roles with hierarchy expansion; also verifies the scope row is in the caller's active org), `{ authzRole: "attendee" }` (an authz role declared under `authz.roles` with a direct relationship `{ via: "..." }`), or `{ fga: { relation: "viewer", object: "event:{id}" } }` (an FGA relation on the object derived from the scope row). The legacy `role: "attendee"` string is the shorthand for `{ authzRole }`.
219
219
  - `requestField`: the JSON body field the client posts to `/broadcast/v1/ws-ticket`
220
220
  - `scopeTable`: the parent resource table that defines the broadcast scope key
221
221
 
222
- In other words: the relationship table proves access, and the `scopeTable` row defines the channel. For an attendee flow, `guests` (or RSVP) would be the relationship evidence and `events` would be the `scopeTable`.
222
+ In other words: the declared gate proves access, and the `scopeTable` row defines the channel. For an attendee flow, `guests` (or RSVP) would be the relationship evidence and `events` would be the `scopeTable`; see [Realtime](/stack/realtime#enabling-realtime) for the full per-arm semantics.
223
223
 
224
224
  Quickback keeps Better Auth as the front door, then mints its own 60-second websocket ticket after the authz check succeeds. The generated `createRealtime()` helper and Broadcaster share the same targeting model:
225
225
 
@@ -100,19 +100,19 @@ This means:
100
100
  The compiler walks every resource, collects unique `(limit, period)` tuples, and emits one Cloudflare binding per tuple to `wrangler.toml`:
101
101
 
102
102
  ```toml
103
- [[unsafe.bindings]]
103
+ [[ratelimits]]
104
104
  name = "RL_1000_60"
105
- type = "ratelimit"
106
- namespace_id = "60001000"
105
+ namespace_id = "60002000"
107
106
  simple = { limit = 1000, period = 60 }
108
107
 
109
- [[unsafe.bindings]]
108
+ [[ratelimits]]
110
109
  name = "RL_200_60"
111
- type = "ratelimit"
112
- namespace_id = "60000200"
110
+ namespace_id = "60001200"
113
111
  simple = { limit = 200, period = 60 }
114
112
  ```
115
113
 
114
+ `namespace_id` is a stable per-tuple integer (`1000 + period * 1_000_000 + limit`), so it survives resource reordering and never drifts across recompiles.
115
+
116
116
  Each generated CRUD handler invokes `c.env.RL_<L>_<P>.limit({ key })` between the auth gate and the access check. Hitting the limit returns:
117
117
 
118
118
  ```http
@@ -171,6 +171,8 @@ Set `rateLimit: false` to opt the action out of enforcement entirely.
171
171
 
172
172
  The `:action:` infix is what keeps `update` (resource bucket) and `approve` (action bucket) from sharing counters when they happen to land on the same binding name.
173
173
 
174
+ A record action's bulk variant (`POST /<resource>/batch/<action>`) shares its single-record sibling's key exactly, so a batch of N records consumes **one** token from the action's bucket per request — not N.
175
+
174
176
  ## Cardinality — how many bindings ship
175
177
 
176
178
  Cloudflare bindings are sized at compile time (limit + period are baked in), so the compiler emits one binding per **unique `(limit, period)` tuple**, not one per resource. A project of 50 resources that all use the defaults still ships exactly two rate-limit bindings.
@@ -191,11 +193,11 @@ Cloudflare bindings are sized at compile time (limit + period are baked in), so
191
193
  | Runtime | Rate limiting |
192
194
  |---------|---------------|
193
195
  | `cloudflare` | Backed by Cloudflare's native [Rate Limiting binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/) |
194
- | `bun` | In-process fixed-window counter (`src/lib/rate-limit-memory.ts`). Same generated check code, same 429 response — single-instance only |
196
+ | non-Cloudflare (`bun`, `node`) | Degrades safely — the check no-ops when the binding is absent from `c.env` |
195
197
 
196
- On Bun, the compiler emits `src/lib/rate-limit-memory.ts` and wires up a per-binding shim in the server's fetch handler. Each `RL_<limit>_<period>` shim delegates to a process-memory token bucket, so the same `c.env.RL_*.limit({ key })` call site that targets the Cloudflare binding works unchanged.
198
+ Every generated rate-limit call site — CRUD middleware and custom actions alike — first looks up `c.env.RL_<limit>_<period>` and only calls `.limit({ key })` when the binding is present. On the Cloudflare runtime it always is. On other runtimes it isn't, so the check no-ops and the request proceeds — generated code never hard-depends on the binding.
197
199
 
198
- **Multi-instance Bun deployments** need either a load balancer with sticky sessions (so the same user keeps hitting the same instance and its bucket) or the Cloudflare runtime (which has cross-instance counters out of the box). The in-memory shim does not coordinate across processes.
200
+ **Roadmap — Bun in-process shim.** An in-memory fixed-window shim (`src/lib/rate-limit-memory.ts`) that backs the same `c.env.RL_*.limit({ key })` call site with a process-memory token bucket is planned but **not yet emitted**. Until it lands, non-Cloudflare deployments that need enforcement should sit behind a Cloudflare WAF rule or an upstream rate limiter. A multi-instance Bun shim would additionally need sticky sessions (same user → same instance → same bucket), since a process-memory counter can't coordinate across processes.
199
201
 
200
202
  ## Compile-time validation
201
203
 
@@ -144,6 +144,10 @@ npx better-auth generate --config ./src/lib/auth.ts --output ./src/auth/schema.t
144
144
  && node scripts/quickback-qualify-auth-schema.mjs
145
145
  ```
146
146
 
147
+ The `better-auth` executable comes from the `auth` devDependency in the
148
+ generated `package.json` — that's the Better Auth CLI package (the
149
+ `better-auth` runtime package ships no bin).
150
+
147
151
  The qualifier script adjusts the CLI output for Postgres schema placement.
148
152
  Don't hand-edit `src/auth/schema.ts` — regenerate it instead.
149
153
 
@@ -42,14 +42,18 @@ export default defineTable(applications, {
42
42
 
43
43
  When any table has realtime enabled, the compiler generates `src/lib/realtime.ts` with helper functions for sending notifications.
44
44
 
45
- At the project level, `providers.database.config.realtime` can stay boolean or become object-shaped when you need relationship-authorized resource tickets:
45
+ At the project level, `providers.database.config.realtime` can stay boolean or become object-shaped when you need resource-scoped tickets. The mint gate accepts three authorization vocabularies via the discriminated `access` form — pick exactly one arm:
46
46
 
47
47
  ```typescript
48
48
  providers: {
49
49
  database: defineDatabase("cloudflare-d1", {
50
50
  realtime: {
51
51
  wsTicket: {
52
- role: "attendee",
52
+ access: { authzRole: "attendee" }, // authz relationship role (legacy shorthand: role: "attendee")
53
+ // access: { roles: ["member+"] }, // org-membership roles — verifies the org role AND that the
54
+ // // scope row is in the caller's ACTIVE org (org column required)
55
+ // access: { fga: { relation: "viewer", object: "event:{id}" } }, // FGA relation on the scope row —
56
+ // // same evaluator + object template as read-path access:{ fga }
53
57
  requestField: "eventId",
54
58
  scopeTable: "events",
55
59
  },
@@ -58,7 +62,7 @@ providers: {
58
62
  }
59
63
  ```
60
64
 
61
- That tells `/broadcast/v1/ws-ticket` to authenticate with Better Auth, verify the `attendee` relationship role against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane.
65
+ That tells `/broadcast/v1/ws-ticket` to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/stack/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
62
66
 
63
67
  ### Namespace-backed tickets (per-matched-lane)
64
68
 
@@ -97,10 +101,11 @@ attendee — their realtime socket now opens.
97
101
  > only target a room whose resource resolves under the caller's tenant (an org-A
98
102
  > admin requesting an org-B `eventId` gets `403`, not a cross-tenant socket). Because
99
103
  > the room *is* the data — there is no firewall between a ticket and a Durable
100
- > Object room — the compiler **rejects at build time** a namespace-backed
101
- > `wsTicket` whose `scopeTable` has `firewall: { exception: true }` or a non-tenant
102
- > (literal-only) firewall with no org/owner/team isolation. Use a tenant-scoped
103
- > `scopeTable`.
104
+ > Object room — the compiler **rejects at build time** a namespace-backed or
105
+ > FGA-gated `wsTicket` whose `scopeTable` has `firewall: { exception: true }` or a
106
+ > non-tenant (literal-only) firewall with no org/owner/team isolation. (The
107
+ > org-membership form binds by the organization column directly, so it requires
108
+ > that column instead.) Use a tenant-scoped `scopeTable`.
104
109
 
105
110
 
106
111
  ## When auto-broadcast fires (and when you call it manually)
@@ -42,7 +42,7 @@ The Broadcaster Durable Object runs **inline** in your main Quickback worker —
42
42
  | Role-based filtering | Only send events to users with matching roles |
43
43
  | Per-role masking | Different users see different field values based on their role |
44
44
  | User-specific targeting | Send events to a specific user within an org |
45
- | Resource-scoped tickets | Reuse authz relationship roles to mint scope-bound ws tickets |
45
+ | Resource-scoped tickets | Mint scope-bound ws tickets gated by org-membership roles, authz relationship roles, or FGA relations |
46
46
  | Custom broadcasts | Arbitrary events beyond CRUD |
47
47
  | Custom namespaces | `defineRealtime()` for type-safe event helpers |
48
48
  | Ticket-based auth | HMAC-signed tickets verified at WebSocket upgrade — no HTTP round-trip |
@@ -99,17 +99,20 @@ providers: {
99
99
  ```
100
100
 
101
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):
102
+ resource-scoped tickets (e.g. an external attendee who may join one event's
103
+ channel, or an org member who may join one project's room). The mint gate is
104
+ declared with `wsTicket.access`, a discriminated union — the arm names the
105
+ authorization vocabulary, so a bare name can never silently mean two things:
106
106
 
107
107
  ```typescript
108
108
  providers: {
109
109
  database: defineDatabase("cloudflare-d1", {
110
110
  realtime: {
111
111
  wsTicket: {
112
- role: "attendee", // authz relationship role, not an org role
112
+ // Pick EXACTLY ONE arm:
113
+ access: { roles: ["member+"] }, // org-membership roles (hierarchy expands)
114
+ // access: { authzRole: "attendee" }, // authz relationship role
115
+ // access: { fga: { relation: "viewer", object: "event:{id}" } }, // FGA relation on the scope row
113
116
  requestField: "eventId",
114
117
  scopeTable: "events",
115
118
  },
@@ -118,7 +121,34 @@ providers: {
118
121
  }
119
122
  ```
120
123
 
121
- With that config, `/broadcast/v1/ws-ticket` can authenticate the caller, verify the declared authz relationship role against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` channel.
124
+ - **`{ roles }` — org-membership roles.** `"member+"` expands via
125
+ `auth.roleHierarchy` (compile error without it). Firewall-consistent: the
126
+ route verifies the caller's org role **and** that the requested `scopeTable`
127
+ row belongs to the caller's *active* organization — an org-A member cannot
128
+ mint a ticket to org B's room. The scope table must therefore carry an
129
+ organization column (compile error otherwise). UPPERCASE pseudo-roles are
130
+ rejected here: a `PUBLIC`/`AUTHENTICATED` ticket factory would hand signed
131
+ room credentials to callers with no org standing.
132
+ - **`{ authzRole }` — a declared `authz.roles` relationship role** (`{ via }`).
133
+ The route probes the relationship table against `body.eventId`; the ticket
134
+ carries the relationship role (e.g. `attendee`). The legacy
135
+ `role: "attendee"` string is the back-compat shorthand for this arm and
136
+ compiles identically. Org-membership names (`member`/`admin`/`owner`) are
137
+ still rejected in this arm — spell those `access: { roles: [...] }`.
138
+ - **`{ fga }` — an FGA relation.** The route loads the `scopeTable` row through
139
+ its own firewall (tenant bind), derives the object from the template
140
+ (`"event:{id}"` — `{field}` tokens read from the row, the same template
141
+ language as the read path's `access: { fga }`), and requires the caller to
142
+ hold `relation` on it via the same org-scoped check evaluator the read path
143
+ uses. Requires `authz.fga`; the object type and relation are validated
144
+ against the model at compile time.
145
+
146
+ Whichever arm you pick, `/broadcast/v1/ws-ticket` authenticates the caller,
147
+ runs that gate against `body.eventId`, and mints a short-lived ticket scoped to
148
+ the resolved `events:<id>` channel. Everything fails closed at compile time:
149
+ a bare name that exists in more than one vocabulary is an ambiguity error
150
+ demanding the explicit arm, and a missing hierarchy, missing FGA model, or
151
+ missing organization column fails the build with an actionable message.
122
152
 
123
153
  ## Pages
124
154