@quickback-dev/cli 0.50.8 → 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.
- package/dist/docs/content.js +7 -7
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/skill/docs/changelog.md +115 -0
- package/dist/skill/docs/compiler/config/auth.md +11 -2
- package/dist/skill/docs/compiler/config/providers.md +4 -4
- package/dist/skill/docs/compiler/definitions/rate-limit.md +11 -9
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +4 -0
- package/dist/skill/docs/stack/realtime/durable-objects.md +12 -7
- package/dist/skill/docs/stack/realtime/index.md +37 -7
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +115 -0
- package/src/skill/docs/compiler/config/auth.md +11 -2
- package/src/skill/docs/compiler/config/providers.md +4 -4
- package/src/skill/docs/compiler/definitions/rate-limit.md +11 -9
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +4 -0
- package/src/skill/docs/stack/realtime/durable-objects.md +12 -7
- package/src/skill/docs/stack/realtime/index.md +37 -7
|
@@ -197,14 +197,14 @@ providers: {
|
|
|
197
197
|
}
|
|
198
198
|
```
|
|
199
199
|
|
|
200
|
-
For
|
|
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
|
-
|
|
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
|
-
- `
|
|
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
|
|
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
|
-
[[
|
|
103
|
+
[[ratelimits]]
|
|
104
104
|
name = "RL_1000_60"
|
|
105
|
-
|
|
106
|
-
namespace_id = "60001000"
|
|
105
|
+
namespace_id = "60002000"
|
|
107
106
|
simple = { limit = 1000, period = 60 }
|
|
108
107
|
|
|
109
|
-
[[
|
|
108
|
+
[[ratelimits]]
|
|
110
109
|
name = "RL_200_60"
|
|
111
|
-
|
|
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` |
|
|
196
|
+
| non-Cloudflare (`bun`, `node`) | Degrades safely — the check no-ops when the binding is absent from `c.env` |
|
|
195
197
|
|
|
196
|
-
|
|
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
|
-
**
|
|
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
|
|
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,
|
|
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
|
|
102
|
-
> (literal-only) firewall with no org/owner/team isolation.
|
|
103
|
-
>
|
|
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 |
|
|
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
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|