@quickback-dev/cli 0.66.5 → 0.66.7
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/README.md +0 -1
- package/dist/index.js +1 -1
- package/dist/lib/api-client.d.ts +1 -1
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +13 -8
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/api-client.test.js +47 -0
- package/dist/lib/api-client.test.js.map +1 -1
- package/dist/lib/migrations/drizzle.d.ts.map +1 -1
- package/dist/lib/migrations/drizzle.js +6 -1
- package/dist/lib/migrations/drizzle.js.map +1 -1
- package/dist/lib/migrations/drizzle.test.js +7 -0
- package/dist/lib/migrations/drizzle.test.js.map +1 -1
- package/dist/lib/migrations/executor.d.ts.map +1 -1
- package/dist/lib/migrations/executor.js +4 -0
- package/dist/lib/migrations/executor.js.map +1 -1
- package/dist/lib/migrations/postprocessors/better-auth-upgrade.d.ts +7 -0
- package/dist/lib/migrations/postprocessors/better-auth-upgrade.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/better-auth-upgrade.js +149 -0
- package/dist/lib/migrations/postprocessors/better-auth-upgrade.js.map +1 -0
- package/dist/skill/SKILL.md +0 -2
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/configure/auth.md +4 -5
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +4 -4
- package/dist/skill/docs/configure/security.md +3 -3
- package/dist/skill/docs/define/access.md +23 -3
- package/dist/skill/docs/define/actions/defining.md +2 -2
- package/dist/skill/docs/define/actions/index.md +6 -0
- package/dist/skill/docs/define/actions/record-and-standalone.md +1 -2
- package/dist/skill/docs/define/areas.md +14 -15
- package/dist/skill/docs/define/changesets.md +5 -0
- package/dist/skill/docs/define/diagnostics.md +2 -2
- package/dist/skill/docs/define/fga.md +1 -1
- package/dist/skill/docs/define/firewall.md +5 -5
- package/dist/skill/docs/define/guards.md +2 -1
- package/dist/skill/docs/define/masking.md +2 -2
- package/dist/skill/docs/define/relationships.md +8 -10
- package/dist/skill/docs/define/scopes.md +1 -1
- package/dist/skill/docs/define/transitions.md +11 -0
- package/dist/skill/docs/define/triggers.md +4 -0
- package/dist/skill/docs/index.md +0 -6
- package/dist/skill/docs/platform/auth/index.md +37 -0
- package/dist/skill/docs/platform/auth/jwt-optimization.md +2 -2
- package/dist/skill/docs/platform/queues/handlers.md +12 -0
- package/dist/skill/docs/platform/realtime/durable-objects.md +1 -1
- package/dist/skill/docs/platform/realtime/partyserver-rooms.md +4 -4
- package/dist/skill/docs/platform/schedules/index.md +3 -1
- package/dist/skill/docs/platform/webhooks/inbound.md +1 -1
- package/dist/skill/docs/tooling/claude-skill.md +0 -7
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +11 -1
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +16 -0
- package/dist/skill/docs/tooling/output.md +7 -6
- package/dist/skill/docs/ui/account/features/admin.md +1 -1
- package/dist/skill/docs/ui/account/features/organizations.md +1 -1
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/dist/skill/docs/ui/admin/owned-records.md +81 -0
- package/dist/skill/docs/ui/admin/schema-format.md +16 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +0 -2
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/configure/auth.md +4 -5
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +4 -4
- package/src/skill/docs/configure/security.md +3 -3
- package/src/skill/docs/define/access.md +23 -3
- package/src/skill/docs/define/actions/defining.md +2 -2
- package/src/skill/docs/define/actions/index.md +6 -0
- package/src/skill/docs/define/actions/record-and-standalone.md +1 -2
- package/src/skill/docs/define/areas.md +14 -15
- package/src/skill/docs/define/changesets.md +5 -0
- package/src/skill/docs/define/diagnostics.md +2 -2
- package/src/skill/docs/define/fga.md +1 -1
- package/src/skill/docs/define/firewall.md +5 -5
- package/src/skill/docs/define/guards.md +2 -1
- package/src/skill/docs/define/masking.md +2 -2
- package/src/skill/docs/define/relationships.md +8 -10
- package/src/skill/docs/define/scopes.md +1 -1
- package/src/skill/docs/define/transitions.md +11 -0
- package/src/skill/docs/define/triggers.md +4 -0
- package/src/skill/docs/index.md +0 -6
- package/src/skill/docs/platform/auth/index.md +37 -0
- package/src/skill/docs/platform/auth/jwt-optimization.md +2 -2
- package/src/skill/docs/platform/queues/handlers.md +12 -0
- package/src/skill/docs/platform/realtime/durable-objects.md +1 -1
- package/src/skill/docs/platform/realtime/partyserver-rooms.md +4 -4
- package/src/skill/docs/platform/schedules/index.md +3 -1
- package/src/skill/docs/platform/webhooks/inbound.md +1 -1
- package/src/skill/docs/tooling/claude-skill.md +0 -7
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +11 -1
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +16 -0
- package/src/skill/docs/tooling/output.md +7 -6
- package/src/skill/docs/ui/account/features/admin.md +1 -1
- package/src/skill/docs/ui/account/features/organizations.md +1 -1
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/src/skill/docs/ui/admin/owned-records.md +81 -0
- package/src/skill/docs/ui/admin/schema-format.md +16 -0
- package/dist/skill/docs/changelog/index.md +0 -945
- package/dist/skill/docs/changelog/v0.1x.md +0 -1202
- package/dist/skill/docs/changelog/v0.2x.md +0 -589
- package/dist/skill/docs/changelog/v0.3x.md +0 -1152
- package/dist/skill/docs/changelog/v0.4x.md +0 -1108
- package/dist/skill/docs/changelog/v0.5x.md +0 -885
- package/src/skill/docs/changelog/index.md +0 -945
- package/src/skill/docs/changelog/v0.1x.md +0 -1202
- package/src/skill/docs/changelog/v0.2x.md +0 -589
- package/src/skill/docs/changelog/v0.3x.md +0 -1152
- package/src/skill/docs/changelog/v0.4x.md +0 -1108
- package/src/skill/docs/changelog/v0.5x.md +0 -885
|
@@ -232,7 +232,7 @@ Or enable the in-project browser via the [`docs` config option](#interactive-api
|
|
|
232
232
|
|
|
233
233
|
Alongside the spec, every compile writes `reports/operations.manifest.json` — a
|
|
234
234
|
stable, machine-readable index of the full route surface (resource, action,
|
|
235
|
-
view,
|
|
235
|
+
view, auth, realtime, storage, and FGA routes, plus
|
|
236
236
|
surfaces):
|
|
237
237
|
|
|
238
238
|
```json
|
|
@@ -55,7 +55,7 @@ The short version, before the knob-by-knob detail:
|
|
|
55
55
|
- **Default: 180-second TTL, auto-refreshed.** Every authenticated call returns a fresh token via the `set-auth-token` header, so the low TTL is invisible to logged-in users. The worst-case window for a stolen or pre-revocation token is 3 minutes — and you can shrink it to 30 seconds with one config line.
|
|
56
56
|
- **Need revocation faster than the TTL?** Set [`revocationCheck: 'kv'`](#revocationcheck-none--kv--token-revocation-strategy). Revoked tokens are rejected within seconds; revocation stamps are written automatically on sign-out and session revocation (per session), on password change with `revokeOtherSessions`, account deletion, user ban, org-member removal, role change, and changes to scope-conferring relationship rows. Long-lived tokens are therefore safe to pair with it: a remote "sign out everywhere" kills a lost device's bearer.
|
|
57
57
|
|
|
58
|
-
Those two knobs — `expiresIn` and `revocationCheck` — cover the vast majority of deployments. The honest residual for the strictest threat models: the KV check revokes per-principal (not per-session) and propagates cross-PoP in ~60s. It **fails closed** — if KV can't be read, the bearer isn't trusted and a bearer-only caller gets a retryable `503`, so enabling it ties bearer availability to KV. If you need per-session kill semantics, set `expiresIn: 30` for a hard 30-second ceiling
|
|
58
|
+
Those two knobs — `expiresIn` and `revocationCheck` — cover the vast majority of deployments. The honest residual for the strictest threat models: the KV check revokes per-principal (not per-session) and propagates cross-PoP in ~60s. It **fails closed** — if KV can't be read, the bearer isn't trusted and a bearer-only caller gets a retryable `503`, so enabling it ties bearer availability to KV. If you need per-session kill semantics, set `expiresIn: 30` for a hard 30-second ceiling.
|
|
59
59
|
|
|
60
60
|
### Behavior recap
|
|
61
61
|
|
|
@@ -130,7 +130,7 @@ Default `'none'`.
|
|
|
130
130
|
| `'none'` | No revocation check. Stolen / pre-revocation tokens valid until TTL expires (scope claims: until the carry-forward cap). Use a low `expiresIn` to bound the replay window. | 0 |
|
|
131
131
|
| `'kv'` | Fast-path checks per-principal revocation timestamps in the project's existing `KV` binding before trusting a verified token. Fails closed: an unreadable store means the bearer is not trusted. | 2+ KV reads (~5-15ms, edge-cached) |
|
|
132
132
|
|
|
133
|
-
`'kv'` (
|
|
133
|
+
`'kv'` (**Cloudflare runtime only**) keeps the fast-path stateless against the auth DB (still 0 D1 queries). There is nothing extra to provision — entries ride the `KV` binding every project already has, prefixed `qbrev:` and self-expiring after the maximum token lifetime, so the store never accumulates.
|
|
134
134
|
|
|
135
135
|
A token is rejected when its mint timestamp (`iat`/`iatMs`, or the scope claim's proof time) is **at or before** the stored timestamp for any principal key it rides on:
|
|
136
136
|
|
|
@@ -147,8 +147,7 @@ Semantics worth knowing:
|
|
|
147
147
|
|
|
148
148
|
- **Revoke-on-touch for scopes:** any update or delete of a conferring row stamps the revocation, without evaluating whether the change actually ended the relationship. A false positive just forces a cheap re-prove (`/scope/v1/enter` or a minting namespace route).
|
|
149
149
|
- **Scope proof time is per kind:** a token can carry several scope kinds proven at different instants, so each entry carries its own proof stamp (`sctMs`, `m<ms>`) and is compared against its own marker. Proving one kind never restamps the others — re-entering `event` cannot bring a revoked `location` claim back to life. Entries minted before the release that added the stamp carry none, and fall back to the token-level `sct`/`sctMs` until they expire (bounded by the carry-forward cap plus one TTL).
|
|
150
|
-
- **No same-second gap:** markers are stored in epoch milliseconds (written `m<ms>` — an explicit format
|
|
151
|
-
- **Do not straddle the v0.61.0 upgrade.** A worker from **before** v0.61.0 reads `m<ms>` markers as `NaN` and treats them as *no revocation at all* — not as a corrupt entry. So rolling back across this release, or pointing two differently-versioned deploy targets at one shared KV namespace, means every revocation written by the new version is **silently unenforced** by the old one until the entry expires (`ENTRY_TTL_SECONDS`, ~19 minutes at default settings). Upgrade all targets sharing a namespace together; if you must roll back, treat outstanding bearer tokens as unrevoked for that window — lower `expiresIn`, or purge the `qbrev:` keys and re-stamp from the old version.
|
|
150
|
+
- **No same-second gap:** markers are stored in epoch milliseconds (written `m<ms>` — an explicit format marker, not a magnitude the reader guesses at) and tokens carry millisecond companions (`iatMs` / `sctMs`) alongside the standards-compatible seconds claims, so a token minted a few milliseconds before the revocation is rejected — while one legitimately re-minted *after* it in that same second is still accepted.
|
|
152
151
|
- **Fails closed:** a missing binding, a failed read, or a corrupt entry means the token's revocation state is *unknown* — and an unknown bearer is not authenticated. The caller gets `503 AUTH_REVOCATION_UNAVAILABLE` (RFC 9457, retryable). Recovery is a **separate cookie-only request**: a request carrying `Authorization` has its cookie stripped before session auth, so within that one request there is nothing left to fall back to. Reads are never silently skipped, because the outage that hides a revocation is exactly the moment this check exists for.
|
|
153
152
|
- **Availability coupling:** the flip side of the above. Bearer-token auth now depends on KV being readable. Alert on `AUTH_REVOCATION_UNAVAILABLE`; a sustained rate means the binding is missing on some deployment target, or KV is degraded. Every named environment must declare `bindings.kv` — the compiler rejects a target that doesn't.
|
|
154
153
|
- **Eventual consistency:** KV propagates cross-PoP in ~60s. "Immediate" means seconds at the writing location, bounded-seconds globally — still far inside the 15-minute carry-forward cap that bounds revocation without this check.
|
|
@@ -195,7 +194,7 @@ The `?redirect=…` query param is preserved unchanged so the central sign-in su
|
|
|
195
194
|
|
|
196
195
|
Signing in is the *only* thing the CMS gate redirects for. A signed-in caller who isn't admitted is served the CMS shell and shown a screen naming what they'd need — see [CMS access](/ui/admin#access-gate). There is no wrong-role redirect, and no `auth.profileUrl`.
|
|
197
196
|
|
|
198
|
-
>
|
|
197
|
+
> `auth.profileUrl` is not supported. The config schema is strict, so a `profileUrl` key fails the compile — delete it.
|
|
199
198
|
|
|
200
199
|
|
|
201
200
|
### Resolution precedence
|
|
@@ -280,7 +280,7 @@ EXTRA_APP_HOSTS = "app-preview.example.com,pr-42.example.com"
|
|
|
280
280
|
wrangler secret put EXTRA_APP_HOSTS --env preview
|
|
281
281
|
```
|
|
282
282
|
|
|
283
|
-
Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed worker auto-trusts its own configured base origin without needing an explicit `trustedOrigins` entry. With `EXTRA_APP_HOSTS`, one env var extends all three allowlists — apps, CORS, and Better Auth's `trustedOrigins`.
|
|
283
|
+
Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed worker auto-trusts its own configured base origin without needing an explicit `trustedOrigins` entry. With `EXTRA_APP_HOSTS`, one env var extends all three allowlists — apps, CORS, and Better Auth's `trustedOrigins`.
|
|
284
284
|
|
|
285
285
|
> **Multi-app deploys**
|
|
286
286
|
>
|
|
@@ -145,7 +145,7 @@ a compile error; delete that line and keep `routes`. See
|
|
|
145
145
|
[API Contract](/platform/api-contract#contractversion-is-retired) for what
|
|
146
146
|
changes if you were pinned to `version: "v1"`.
|
|
147
147
|
|
|
148
|
-
Action input-schema fidelity is a compile gate
|
|
148
|
+
Action input-schema fidelity is a compile gate. The CLI must
|
|
149
149
|
successfully harvest `z.toJSONSchema(action.input)` for every authored action;
|
|
150
150
|
partial or missing harvests fail with the exact action file keys, bundle or
|
|
151
151
|
evaluation phase, and underlying local error. Dependencies are resolved from
|
|
@@ -433,7 +433,7 @@ action layer.
|
|
|
433
433
|
|
|
434
434
|
Quickback manages four **audit columns** (`createdAt`, `modifiedAt`, `createdBy`, `modifiedBy`) on every feature table, plus two **soft-delete columns** (`deletedAt`, `deletedBy`) on tables whose resource uses soft delete (the default delete mode). The audit columns drive record-provenance queries and the CMS audit panel; the soft-delete pair drives soft-delete filtering.
|
|
435
435
|
|
|
436
|
-
You declare them in the table's `columns` object with `...q.audit()` and `...q.softDelete()`. The compiler validates every managed column against its canonical shape and fails the compile when one is missing, diverges, or is present on a hard-delete table — run `quickback migrate visible-columns` to adopt the declarations on an existing project. Set `compiler.features.visibleAuditColumns: false` to downgrade those checks to warnings and
|
|
436
|
+
You declare them in the table's `columns` object with `...q.audit()` and `...q.softDelete()`. The compiler validates every managed column against its canonical shape and fails the compile when one is missing, diverges, or is present on a hard-delete table — run `quickback migrate visible-columns` to adopt the declarations on an existing project. Set `compiler.features.visibleAuditColumns: false` to downgrade those checks to warnings and silently inject the columns.
|
|
437
437
|
|
|
438
438
|
To opt out of the managed columns entirely, project-wide:
|
|
439
439
|
|
|
@@ -485,7 +485,7 @@ export default defineConfig({
|
|
|
485
485
|
|
|
486
486
|
If `signature.required: true` and no key is available, compilation fails with a clear error message (or warning in `failMode: "warn"`).
|
|
487
487
|
|
|
488
|
-
## Hostname architecture
|
|
488
|
+
## Hostname architecture
|
|
489
489
|
|
|
490
490
|
A modern Quickback project runs on **one Cloudflare Worker** that serves multiple URL surfaces. By default, everything lives under a single unified backend hostname (auto-inferred as `quickback.{baseDomain}` from your other configured subdomains, or overridable via `config.domain`). For larger deployments, you can opt-in to **dedicated hostnames** for specific surfaces — they're additive aliases, never replacements.
|
|
491
491
|
|
|
@@ -515,7 +515,7 @@ For branding or operational separation, you can opt specific surfaces onto their
|
|
|
515
515
|
cms: { domain: 'cms.example.com' },
|
|
516
516
|
account: { domain: 'account.example.com' },
|
|
517
517
|
|
|
518
|
-
//
|
|
518
|
+
// Backend surfaces on their own hosts:
|
|
519
519
|
auth: { domain: 'auth.example.com' },
|
|
520
520
|
api: { domain: 'api.example.com' },
|
|
521
521
|
|
|
@@ -118,7 +118,7 @@ The compiler applies these so config stays minimal:
|
|
|
118
118
|
- **`X-Frame-Options` derives from `csp.frameAncestors`** (`['@none']` → `DENY`, contains `@self` → `SAMEORIGIN`, otherwise omitted — XFO can't represent arbitrary origins so CSP becomes the truth there). Override with `security.frameOptions`.
|
|
119
119
|
- **`corp: 'same-origin'` is auto-emitted when `coep` is set.** `require-corp` without CORP breaks the ASSETS binding fetches on Cloudflare; the compiler couples them so users don't have to remember.
|
|
120
120
|
|
|
121
|
-
### CSP auto-config
|
|
121
|
+
### CSP auto-config
|
|
122
122
|
|
|
123
123
|
When you opt into a `csp` object, the compiler additively widens directives based on which Quickback features your project has enabled. **Additive** means anything you already wrote stays; we only push values that aren't already present.
|
|
124
124
|
|
|
@@ -140,7 +140,7 @@ font-src 'self' https://fonts.gstatic.com
|
|
|
140
140
|
connect-src 'self' @trustedOrigins https://api.your-app.com
|
|
141
141
|
```
|
|
142
142
|
|
|
143
|
-
Each directive is scoped to exactly what it needs. `defaultSrc` is *not* widened with style-only or connect-only hosts — that would let those hosts also reach `script-src` / `img-src` / `media-src` via fall-back, which is wider than the bundled SPA actually needs.
|
|
143
|
+
Each directive is scoped to exactly what it needs. `defaultSrc` is *not* widened with style-only or connect-only hosts — that would let those hosts also reach `script-src` / `img-src` / `media-src` via fall-back, which is wider than the bundled SPA actually needs.
|
|
144
144
|
|
|
145
145
|
**Visibility:** every applied addition prints to stderr at compile time — one line per addition with the directive, value, and reason. No silent magic. Loop's compile output now looks like:
|
|
146
146
|
|
|
@@ -155,7 +155,7 @@ Each directive is scoped to exactly what it needs. `defaultSrc` is *not* widened
|
|
|
155
155
|
|
|
156
156
|
#### Why the SPA-baked origin shows up capitalised in CSP
|
|
157
157
|
|
|
158
|
-
Projects with `domain: "..."` + bundled CMS / Account SPAs will see `connect-src 'self' https://Api.example.com …` in their served CSP — note the capital `A`. That's deliberate
|
|
158
|
+
Projects with `domain: "..."` + bundled CMS / Account SPAs will see `connect-src 'self' https://Api.example.com …` in their served CSP — note the capital `A`. That's deliberate and works around a `wrangler dev` quirk, not a typo on our end.
|
|
159
159
|
|
|
160
160
|
`wrangler dev` rewrites the configured `custom_domain` host string in **every** response header value (Location, Content-Security-Policy, X-…) to the local hostname, with a case-sensitive substring matcher. Without the case-shift, the served CSP becomes `connect-src 'self' https://localhost:8787 …` and the bundled SPA's hardcoded `VITE_QUICKBACK_API_URL` fetches get blocked because the prod URL no longer appears in the allowlist.
|
|
161
161
|
|
|
@@ -100,7 +100,7 @@ any lowercase role name you reference in an access tree (`"recruiter"`,
|
|
|
100
100
|
`"hiring-manager"`, `"support"`, …) is a custom org-membership role, matched
|
|
101
101
|
against `ctx.roles` like the built-ins.
|
|
102
102
|
|
|
103
|
-
|
|
103
|
+
Custom roles declared in access trees are **auto-registered
|
|
104
104
|
with the Better Auth organization plugin**, so members can actually be
|
|
105
105
|
provisioned into them: `invite-member` and `update-member-role` accept them
|
|
106
106
|
(previously they rejected custom roles with `400 ROLE_NOT_FOUND`).
|
|
@@ -132,6 +132,26 @@ interface Access {
|
|
|
132
132
|
}
|
|
133
133
|
```
|
|
134
134
|
|
|
135
|
+
### An empty list is a compile error
|
|
136
|
+
|
|
137
|
+
`roles: []`, `userRole: []`, and `principals: []` are refused at compile
|
|
138
|
+
time, on every access node — CRUD operations, `read`, views, actions, and
|
|
139
|
+
the arms of `or` / `and`. The runtime evaluator treats an empty list as
|
|
140
|
+
"no gate on this axis", so an arm that names nobody would admit **every
|
|
141
|
+
authenticated caller**. Masking uses the same literal the other way round
|
|
142
|
+
(`show: { roles: [] }` shows nobody), which is exactly why the compiler will
|
|
143
|
+
not guess here. Say what you mean:
|
|
144
|
+
|
|
145
|
+
{/* doc-compile: skip — config fragments, not a compilable project */}
|
|
146
|
+
```typescript
|
|
147
|
+
create: { access: { userRole: ['sysadmin'] } } // closed to everyone but platform admins
|
|
148
|
+
// or omit `create` entirely — the route is not emitted
|
|
149
|
+
read: { access: { roles: ['AUTHENTICATED'] } } // every signed-in caller really is the audience
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Every empty arm in the project is listed in one compile error, so a project
|
|
153
|
+
fixes them all in one pass.
|
|
154
|
+
|
|
135
155
|
## `userRole` vs `roles`
|
|
136
156
|
|
|
137
157
|
`roles` and `userRole` check **two different fields** and are often confused — get this wrong and you'll grant access too broadly.
|
|
@@ -200,7 +220,7 @@ access: { roles: ["PUBLIC"] }
|
|
|
200
220
|
- `PUBLIC` skips authentication and role checks — anyone can call the endpoint
|
|
201
221
|
- **`PUBLIC` is the explicit, uppercase opt-in for unauthenticated access.** It works on every access node — reads, top-level writes (`create`/`update`/`delete`/`upsert`), views, and actions. The compiler trusts the marker; row-level safety comes from the firewall, masking, and (for token-gated endpoints like RSVP confirm, magic-link redemption, List-Unsubscribe-Post, webhook ingest) your handler's own validation. Anonymous write endpoints typically pair `roles: ["PUBLIC"]` with `firewall: { exception: true }` on the resource so the row predicate doesn't reject every unauthenticated caller.
|
|
202
222
|
- **Firewall still applies** — data is scoped by the firewall (organization, owner, team)
|
|
203
|
-
- **Tree semantics:** `PUBLIC` admits anonymous callers from anywhere in the access tree, not just a flat `roles` list. An `or:` arm containing `PUBLIC` admits anonymous callers past the authentication gate; an `and:` group admits them only when *every* arm does. The access, org, and firewall layers still evaluate the full tree afterwards.
|
|
223
|
+
- **Tree semantics:** `PUBLIC` admits anonymous callers from anywhere in the access tree, not just a flat `roles` list. An `or:` arm containing `PUBLIC` admits anonymous callers past the authentication gate; an `and:` group admits them only when *every* arm does. The access, org, and firewall layers still evaluate the full tree afterwards.
|
|
204
224
|
- Every `PUBLIC` action invocation is **mandatory audit logged** to the security audit table (IP address, input, result, timing)
|
|
205
225
|
- The wildcard `"*"` is **not supported** — using it throws a compile-time error
|
|
206
226
|
- Tables with no isolation columns and any `PUBLIC` route do not require `firewall: [{ exception: true }]`
|
|
@@ -330,7 +350,7 @@ Use one of these instead:
|
|
|
330
350
|
|
|
331
351
|
#### `SYSADMIN` — cross-tenant DB-admin tier
|
|
332
352
|
|
|
333
|
-
Use `roles: ["SYSADMIN"]` for endpoints that should only be reachable by platform sysadmins — the cross-tenant DB-admin tier
|
|
353
|
+
Use `roles: ["SYSADMIN"]` for endpoints that should only be reachable by platform sysadmins — the cross-tenant DB-admin tier. Compiles to `ctx.userRole === "sysadmin"`. **Requires `cms: { sysadmin: true }` on the project config**; without that flag, using `SYSADMIN` fails the compile so the role can't sit as dead code.
|
|
334
354
|
|
|
335
355
|
```typescript
|
|
336
356
|
// Cross-tenant audit dashboard, sysadmin-only
|
|
@@ -115,8 +115,8 @@ Zod 4's `z.toJSONSchema`. It does not call `execute`; the hosted compiler never
|
|
|
115
115
|
evaluates project code. The output contract feeds OpenAPI and
|
|
116
116
|
`Api.<feature>.actions.<action>.Output` in `quickback.gen.ts`.
|
|
117
117
|
|
|
118
|
-
**Every action input must produce a schema.**
|
|
119
|
-
|
|
118
|
+
**Every action input must produce a schema.** A failed harvest fails the
|
|
119
|
+
compile, naming the exact action, whether
|
|
120
120
|
bundling or evaluation failed, and the underlying local error. Output remains
|
|
121
121
|
optional.
|
|
122
122
|
|
|
@@ -19,6 +19,12 @@ most common needless action is one of these hand-rolled.
|
|
|
19
19
|
Write the action for the remainder: third-party calls, multi-step orchestration,
|
|
20
20
|
AI/streaming responses, anything genuinely imperative.
|
|
21
21
|
|
|
22
|
+
The compiler backstops this check: an action named `<crudVerb><Table>`
|
|
23
|
+
(`createIssue`, `listIssues`) or `<statusVerb><Table>` (`closeIssue`,
|
|
24
|
+
`cancelReservation`) with no `transition:` config compiles with a **warning**
|
|
25
|
+
pointing at the primitive it shadows. Heed it — the duplicate route never
|
|
26
|
+
inherits the table's guards, masking, or ETags.
|
|
27
|
+
|
|
22
28
|
## Overview
|
|
23
29
|
|
|
24
30
|
Quickback supports two types of actions:
|
|
@@ -17,7 +17,7 @@ POST /applications/:id/schedule-interview
|
|
|
17
17
|
1. **Authentication** - User token is validated
|
|
18
18
|
2. **Input Validation** - Request body validated against Zod schema
|
|
19
19
|
3. **Role Gate** - The access roles are checked *before* the record is
|
|
20
|
-
fetched
|
|
20
|
+
fetched, so a wrong-role caller gets a uniform
|
|
21
21
|
`403 ACCESS_ROLE_REQUIRED` whether or not the record exists — the
|
|
22
22
|
response can't be used to probe for record ids
|
|
23
23
|
4. **Record Loading** - The record is fetched by ID **through the firewall**
|
|
@@ -420,4 +420,3 @@ imply "this writes data" — it's the right method whenever the request body is
|
|
|
420
420
|
load-bearing. Use the response shape (`responseType: "json"`, or just the data
|
|
421
421
|
your handler returns) to convey read semantics; HTTP method choice is about
|
|
422
422
|
input transport, not action intent.
|
|
423
|
-
|
|
@@ -305,7 +305,7 @@ doubt: if only one folder's features reference it, it belongs in that folder's a
|
|
|
305
305
|
|
|
306
306
|
When several standalone actions share a path prefix and the same relationship gate — `/event/:eventId/announce`, `/event/:eventId/cancel`, `/event/:eventId/respond` — declaring the gate per-action means writing the same `roles: ['attendee']` over and over AND paying the relationship-resolver cost N times per request (one subquery + one row-load, multiplied by the number of actions).
|
|
307
307
|
|
|
308
|
-
Namespace mounts hoist the resolver into one Hono middleware that runs once per request. Every action under the prefix skips the inline gate; `ctx.<exposeAs>` is hydrated by the middleware before the action's `execute()` runs. With the per-namespace helper
|
|
308
|
+
Namespace mounts hoist the resolver into one Hono middleware that runs once per request. Every action under the prefix skips the inline gate; `ctx.<exposeAs>` is hydrated by the middleware before the action's `execute()` runs. With the [per-namespace helper](#narrow-ctxexposeas-typing), that field is also statically typed as the loaded row.
|
|
309
309
|
|
|
310
310
|
### When to use roles vs. relationships
|
|
311
311
|
|
|
@@ -317,13 +317,13 @@ A user is authorized for a row when **any** of the following is true:
|
|
|
317
317
|
|
|
318
318
|
Use **relationships** when membership is specific to *this row* — external collaborators who aren't in your org, attendees, anyone connected to the resource by virtue of data rather than payroll. Use **roles / team** when staff at your org/team should see everything in their scope by default.
|
|
319
319
|
|
|
320
|
-
The two compose at the action level (`access.or` accepts both relationship-roles and tenant roles) and
|
|
320
|
+
The two compose at the action level (`access.or` accepts both relationship-roles and tenant roles) and at the namespace level: `namespace.via` accepts an array of lanes, first match wins.
|
|
321
321
|
|
|
322
322
|
> **Rule of thumb.** If the answer is *"yes if you work here,"* reach for org/team roles. If the answer is *"yes if you have something to do with **this** row,"* reach for a per-row relationship. Reach for both together — at the namespace or via `access.or` — when an action should let either side in.
|
|
323
323
|
|
|
324
324
|
Two declaration sites depending on whether the participating actions live in one feature or many:
|
|
325
325
|
|
|
326
|
-
### Single feature: `defineTable({ namespace })`
|
|
326
|
+
### Single feature: `defineTable({ namespace })`
|
|
327
327
|
|
|
328
328
|
Use when every action under the prefix lives in the same feature directory. The namespace travels with the table that owns it — no addition to `quickback.config.ts` needed.
|
|
329
329
|
|
|
@@ -366,9 +366,9 @@ export default defineAction({
|
|
|
366
366
|
|
|
367
367
|
The compiler emits one `app.use(...)` on the events feature's Hono app. Every standalone action in `features/events/actions/` whose path starts with `/event/:eventId/` joins the namespace automatically.
|
|
368
368
|
|
|
369
|
-
Multi-lane
|
|
369
|
+
Multi-lane and bulk-grant lanes work identically on the table-level declaration — `via:` accepts the same shapes documented below for the project-level form.
|
|
370
370
|
|
|
371
|
-
### Cross-feature: `authz.namespaces`
|
|
371
|
+
### Cross-feature: `authz.namespaces`
|
|
372
372
|
|
|
373
373
|
Use when the namespace spans multiple features. The declaration sits next to your other authz config in `quickback.config.ts`.
|
|
374
374
|
|
|
@@ -422,7 +422,7 @@ export default defineAction({
|
|
|
422
422
|
|
|
423
423
|
The compiler emits one synthetic `src/routes/__namespace-event-scope.routes.ts` that imports each contributing feature's `actions` map under a distinct alias, mounts the resolver middleware once, and dispatches to the matching action. Worker-root mount order ensures the middleware fires before any per-feature route handler under the prefix.
|
|
424
424
|
|
|
425
|
-
### Multi-lane via
|
|
425
|
+
### Multi-lane via — first match wins
|
|
426
426
|
|
|
427
427
|
When more than one relationship can authorize a caller for the namespaced resource, pass `via:` as an array. The middleware tries each lane in declaration order and stops at the first match — `ctx.<exposeAs>` is hydrated from whichever lane fired.
|
|
428
428
|
|
|
@@ -458,9 +458,9 @@ authz: {
|
|
|
458
458
|
}
|
|
459
459
|
```
|
|
460
460
|
|
|
461
|
-
Hydration is **per matched lane
|
|
461
|
+
Hydration is **per matched lane**: each lane fills `ctx.<its own exposeAs>` from its own `loads:` table, so lanes may load different tables into different keys. Both lanes above name `events` / `event`, so `ctx.event` is populated whichever fires. A lane declaring neither `loads:` nor `exposeAs:` is authorization-only — it opens the gate and hydrates nothing.
|
|
462
462
|
|
|
463
|
-
### Bulk-grant lanes
|
|
463
|
+
### Bulk-grant lanes
|
|
464
464
|
|
|
465
465
|
Relationship lanes cover "specifically connected to this row." Bulk-grant lanes cover "anyone with this role / team membership in the row's tenant" — the case where an org admin or a team member should see every event in their scope without writing per-event relationship rows.
|
|
466
466
|
|
|
@@ -483,7 +483,7 @@ Each bulk-grant lane:
|
|
|
483
483
|
- **`{ roles: [...] }`** — passes when the caller's BA org-role for the loaded resource's tenant includes any listed role. Short-circuits the relationship loop entirely; the role check is in-memory and cheap. Use for the "company admin sees everything" case.
|
|
484
484
|
- **`{ team: true }`** — passes when `ctx.activeTeamId` is set. The loads-table firewall does the actual `events.teamId === ctx.activeTeamId` check during hydration. Use when the resource is team-scoped and you want active-team membership to grant access.
|
|
485
485
|
|
|
486
|
-
Both bulk-grant lanes piggyback on the namespace's relationship lane(s) for hydration — they don't fetch a separate per-row subject; they just gate access and let the loads-table firewall handle the tenant scoping.
|
|
486
|
+
Both bulk-grant lanes piggyback on the namespace's relationship lane(s) for hydration — they don't fetch a separate per-row subject; they just gate access and let the loads-table firewall handle the tenant scoping. When a relationship lane anchors hydration, declare `loads:` + `exposeAs:` on that lane.
|
|
487
487
|
|
|
488
488
|
When a request misses every lane, the 403 deny payload lists every authorization path the caller could have taken — relationship names, role names, and `"team-membership"` for `{ team: true }` lanes — so a developer debugging an unexpected 403 sees the full surface they need to satisfy.
|
|
489
489
|
|
|
@@ -497,7 +497,7 @@ Actions opt in by matching `path:` against a declared namespace prefix. There's
|
|
|
497
497
|
|
|
498
498
|
Both forms share the same shape checks:
|
|
499
499
|
|
|
500
|
-
- **`via:` accepts one of three shapes.** A single relationship name
|
|
500
|
+
- **`via:` accepts one of three shapes.** A single relationship name, an array of relationship names (first match wins), or an array mixing relationship names with bulk-grant guards (`{ roles: [...] }`, `{ team: true }`). **A bare string is always a relationship name.** There is no string form for a role: `{ roles: [...] }` is a bulk-grant lane against Better Auth org roles, even when the name you put in it is a composed role defined `via` a relationship.
|
|
501
501
|
- **Each relationship lane declares `loads` + `exposeAs`, or neither.** Both → the lane hydrates `ctx.<exposeAs>` from `loads` when it matches. Neither → an authorization-only lane. Exactly one is a compile error.
|
|
502
502
|
- **Bulk-grant lanes inherit `loads:` + `exposeAs:` from sibling relationship lanes.** Pure bulk-grant namespaces (no relationship lane at all) are also accepted — set `loads:` + `exposeAs:` directly on the namespace declaration so hydration has somewhere to anchor.
|
|
503
503
|
- **`prefix:` must contain at least one `:param` segment** (e.g. `/event/:eventId`). The middleware reads the relationship key from `c.req.param()` because no request body has been parsed at middleware time.
|
|
@@ -516,11 +516,11 @@ Inside a namespace action's `execute()`:
|
|
|
516
516
|
- Tenant context (`ctx.activeOrgId` / `ctx.activeTeamId`) is stamped from the matched relationship row when its `from` table carries those columns. Downstream scoped queries work without further setup.
|
|
517
517
|
- The action's own `access:` block (additional roles, userRole, record predicates, OTHER relationship arms) still runs after the namespace gate — namespace handles entry, per-action gates further.
|
|
518
518
|
|
|
519
|
-
### Narrow `ctx.<exposeAs>` typing
|
|
519
|
+
### Narrow `ctx.<exposeAs>` typing
|
|
520
520
|
|
|
521
|
-
The namespace middleware hydrates `ctx.<exposeAs>` at runtime
|
|
521
|
+
The namespace middleware hydrates `ctx.<exposeAs>` at runtime. The static type of that field is `any` via the `AppContext` index signature: useful for not blocking access, but a missed opportunity for autocomplete and typo-catching.
|
|
522
522
|
|
|
523
|
-
|
|
523
|
+
The compiler emits one **per-namespace `defineAction` helper** alongside the standard `<feature>/.quickback/define-action.ts`. Importing from the narrowed helper retypes `ctx.<exposeAs>` inside `execute({ ctx })` to the loaded row's `$inferSelect` shape. Nothing else changes — runtime behavior, action discovery, and the `path:` namespace match are identical.
|
|
524
524
|
|
|
525
525
|
```ts title="features/feeds/actions/feedMoments.ts"
|
|
526
526
|
// One-line flip per namespace-scoped action:
|
|
@@ -549,7 +549,7 @@ The compiler emits one helper per `(feature, namespace)` pair where the feature
|
|
|
549
549
|
|
|
550
550
|
#### Opt-in, not breaking
|
|
551
551
|
|
|
552
|
-
Actions that
|
|
552
|
+
Actions that import `defineAction` from `../.quickback/define-action` compile with `ctx.<exposeAs>` as `any` via the `AppContext` index signature. Use the per-namespace helper for the narrowed type.
|
|
553
553
|
|
|
554
554
|
#### Compile-time advisory
|
|
555
555
|
|
|
@@ -578,4 +578,3 @@ src/features/interviews/.quickback/
|
|
|
578
578
|
#### Why per-namespace and not per-action
|
|
579
579
|
|
|
580
580
|
A `defineAction` helper that's narrow to *one* exposed key (the namespace's `exposeAs`) is enough — every action under a namespace sees the same hydrated key. The alternative (per-action emit) duplicates the same prelude N times for the same shape; per-namespace keeps emission proportional to the number of distinct hydration shapes in the project.
|
|
581
|
-
|
|
@@ -64,6 +64,11 @@ the operations manifest.
|
|
|
64
64
|
update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
|
|
65
65
|
```
|
|
66
66
|
|
|
67
|
+
The registry records these ops in `routesDisabled`, so the
|
|
68
|
+
[CMS](/ui/admin/owned-records) suppresses raw-CRUD buttons for them while
|
|
69
|
+
still rendering the relation inline on the root's record page — its writes
|
|
70
|
+
are changeset ops, which `routes: false` deliberately leaves open.
|
|
71
|
+
|
|
67
72
|
## The wire contract
|
|
68
73
|
|
|
69
74
|
One blessed path — **RFC 5789 media-type dispatch** on the routes you already
|
|
@@ -26,7 +26,7 @@ The first line stays greppable (`[quickback:<channel>] CODE: message`); the
|
|
|
26
26
|
source location, fix hint, and — for promoted errors — the exact override
|
|
27
27
|
recipe render on continuation lines.
|
|
28
28
|
|
|
29
|
-
## Errors vs warnings
|
|
29
|
+
## Errors vs warnings
|
|
30
30
|
|
|
31
31
|
The checks split into two tiers:
|
|
32
32
|
|
|
@@ -114,7 +114,7 @@ authz: {
|
|
|
114
114
|
{
|
|
115
115
|
check: 'AUTHZ_CAPABILITY_CEILING',
|
|
116
116
|
target: 'sessions/scope:event:organizer',
|
|
117
|
-
reason: '
|
|
117
|
+
reason: 'temporary exception while the organizer grant profile is implemented',
|
|
118
118
|
},
|
|
119
119
|
],
|
|
120
120
|
},
|
|
@@ -307,7 +307,7 @@ stored tuple whose subject shape isn't allowed for the relation is inert. So a
|
|
|
307
307
|
`user:*` tuple on a relation declared `[user]` (no wildcard) can never grant
|
|
308
308
|
access, even if it was written out-of-band — the model is the ceiling.
|
|
309
309
|
|
|
310
|
-
## Limitations
|
|
310
|
+
## Limitations
|
|
311
311
|
|
|
312
312
|
- `access: { fga }` covers **per-record** operations (`GET /:id`, `update`,
|
|
313
313
|
`delete`, record-based actions) and **collection filtering** on
|
|
@@ -100,9 +100,9 @@ type FirewallPredicate =
|
|
|
100
100
|
| { field: string; isNull: true } // column IS NULL
|
|
101
101
|
| { field: string; in: string[] | string; optional?: boolean } // column IN (...)
|
|
102
102
|
| { field: string; via: string } // column IN (relationship subquery)
|
|
103
|
-
| { field?: string; permission: string } // named authz.permissions reference
|
|
104
|
-
| { all: FirewallPredicate[] } // AND group
|
|
105
|
-
| { any: FirewallPredicate[] }
|
|
103
|
+
| { field?: string; permission: string } // named authz.permissions reference
|
|
104
|
+
| { all: FirewallPredicate[] } // AND group
|
|
105
|
+
| { any: FirewallPredicate[] } // OR group
|
|
106
106
|
| { exception: true }; // opt out of tenant scoping
|
|
107
107
|
|
|
108
108
|
type FirewallConfig = ReadonlyArray<FirewallPredicate>;
|
|
@@ -113,7 +113,7 @@ firewallErrorMode?: 'reveal' | 'hide';
|
|
|
113
113
|
|
|
114
114
|
The top-level array is AND'd together. `firewallErrorMode` lives at the resource top level — it's a presentation-layer choice (403 vs 404), not a query-shape one.
|
|
115
115
|
|
|
116
|
-
## Boolean groups: `all` / `any`
|
|
116
|
+
## Boolean groups: `all` / `any`
|
|
117
117
|
|
|
118
118
|
A flat array can only express AND. To grant access through **either** of two independent paths — "an org member **OR** an event attendee" — nest an `any` group. The top-level array stays sugar for `all`, so every existing firewall is byte-identical.
|
|
119
119
|
|
|
@@ -389,7 +389,7 @@ So `firewall: [{ exception: true }]` on the default configuration returns `isNul
|
|
|
389
389
|
|
|
390
390
|
## Sysadmin Escape Hatch
|
|
391
391
|
|
|
392
|
-
When `cms: { sysadmin: true }` is set on the project
|
|
392
|
+
When `cms: { sysadmin: true }` is set on the project, every `buildFirewallConditions()` emits a runtime branch that drops tenant scopes for `ctx.userRole === 'sysadmin'` callers while keeping the soft-delete predicate:
|
|
393
393
|
|
|
394
394
|
```typescript
|
|
395
395
|
// Generated for an org-scoped table when cms.sysadmin: true
|
|
@@ -76,7 +76,8 @@ guards: {
|
|
|
76
76
|
> to the table for `db.update(<table>).set({ … })` / `db.insert(<table>).values({ … })`
|
|
77
77
|
> and refuses an `immutable` column in any update, or a `protected` column
|
|
78
78
|
> written by an action that is not in its list — with an error naming the action,
|
|
79
|
-
> the column, and the fix.
|
|
79
|
+
> the column, and the fix. Every offending action in the project is listed in
|
|
80
|
+
> that one error, so a single compile surfaces all of them. The two tiers are therefore distinct: `immutable` is
|
|
80
81
|
> written once at create and never again; if a column needs an action to change
|
|
81
82
|
> it, it is `protected`, mapped to that action.
|
|
82
83
|
>
|
|
@@ -50,7 +50,7 @@ Whether `customers.email` is PII to hide or the display label of a contact list
|
|
|
50
50
|
|
|
51
51
|
So the compiler asks. A false positive costs you one line (`cc: false`) — which is also a durable, reviewable record that somebody looked.
|
|
52
52
|
|
|
53
|
-
It also removes a bug class outright. When detection can never quietly supply a rule, the set of masked columns is the set you declared, so no two surfaces can disagree about it.
|
|
53
|
+
It also removes a bug class outright. When detection can never quietly supply a rule, the set of masked columns is the set you declared, so no two surfaces can disagree about it.
|
|
54
54
|
|
|
55
55
|
### What a decision controls
|
|
56
56
|
|
|
@@ -215,7 +215,7 @@ masking: {
|
|
|
215
215
|
}
|
|
216
216
|
```
|
|
217
217
|
|
|
218
|
-
`show: { roles: [] }` has the same effect, but it doesn't say the same thing. An empty role list reads as an oversight, and it is also what authors fall back to when the audience they wanted is **inexpressible** — masking gates on org and scoped roles, so a table gated `access: { userRole: ['sysadmin'] }` cannot name its own audience in a mask. Two different intentions, one spelling, and no way for the next reader to tell them apart.
|
|
218
|
+
`show: { roles: [] }` has the same effect, but it doesn't say the same thing. An empty role list reads as an oversight, and it is also what authors fall back to when the audience they wanted is **inexpressible** — masking gates on org and scoped roles, so a table gated `access: { userRole: ['sysadmin'] }` cannot name its own audience in a mask. Two different intentions, one spelling, and no way for the next reader to tell them apart. Note the asymmetry with access, where an empty list would mean *everyone* — which is why [access refuses it at compile time](/define/access#an-empty-list-is-a-compile-error).
|
|
219
219
|
|
|
220
220
|
Write `'never'` when nobody is the intent. Any other string is a compile error rather than a guess — `show: 'admin'` is a plausible typo, and masking-for-everyone is the wrong thing to assume from it.
|
|
221
221
|
|
|
@@ -118,7 +118,7 @@ the compiler rejects a relationship-bearing `masking.show` rule and points to a
|
|
|
118
118
|
relationship-gated view instead. It never drops the relationship arm or turns
|
|
119
119
|
it into a broader role grant.
|
|
120
120
|
|
|
121
|
-
### Standalone actions: surface keys and `loads` / `exposeAs`
|
|
121
|
+
### Standalone actions: surface keys and `loads` / `exposeAs`
|
|
122
122
|
|
|
123
123
|
When a standalone action's `access.roles` references a relationship-role, the compiler emits a runtime gate between input validation and `execute()`. The gate reads the relationship's `resource.column` value from the action surface — either a path parameter (`:eventId`) or an input field (`input.eventId`). If neither is present, the current compiler stops with a clear build error; an action can never ship with a relationship rule it has no key to evaluate.
|
|
124
124
|
|
|
@@ -132,7 +132,7 @@ authz: {
|
|
|
132
132
|
subject: { column: 'userId', equals: 'ctx.userId' },
|
|
133
133
|
resource: { column: 'eventId' },
|
|
134
134
|
where: { status: 'confirmed' },
|
|
135
|
-
loads: 'events', //
|
|
135
|
+
loads: 'events', // load matching event row
|
|
136
136
|
exposeAs: 'event', // ← onto ctx.event for the action body
|
|
137
137
|
},
|
|
138
138
|
},
|
|
@@ -142,7 +142,7 @@ authz: {
|
|
|
142
142
|
}
|
|
143
143
|
```
|
|
144
144
|
|
|
145
|
-
The resolver
|
|
145
|
+
The resolver:
|
|
146
146
|
|
|
147
147
|
1. **Cheap in-memory role check** first — `ctx.roles?.includes('admin')` and friends. If the caller has a qualifying role, this short-circuits and no DB queries fire for the access gate.
|
|
148
148
|
2. **Firewall-gated relationship match** if the role check failed — `SELECT { organizationId, teamId } FROM guests WHERE userId=ctx.userId AND eventId=input.eventId AND status='confirmed'` with the `guests` table's full firewall AND-applied. If neither role nor relationship qualifies → 403.
|
|
@@ -152,24 +152,22 @@ The resolver (v0.20):
|
|
|
152
152
|
|
|
153
153
|
**No firewall bypass anywhere.** Both queries run with their respective tables' full firewalls. The relationship row's existence is the proof that the caller is authorized; its tenant columns are the source of the stamped claim.
|
|
154
154
|
|
|
155
|
-
### Conditional tenant preconditions
|
|
155
|
+
### Conditional tenant preconditions
|
|
156
156
|
|
|
157
|
-
Standalone actions in features with org/team-scoped tables
|
|
157
|
+
Standalone actions in features with org/team-scoped tables emit tenant preconditions only when a relationship cannot supply the tenant:
|
|
158
158
|
|
|
159
159
|
```ts
|
|
160
160
|
if (!ctx.activeOrgId) return c.json(AccessErrors.noOrg(), 403);
|
|
161
161
|
if (!ctx.activeTeamId) return c.json(AccessErrors.noTeam(), 403);
|
|
162
162
|
```
|
|
163
163
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
v0.20 makes these preconditions **conditional on relationship supply**. If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / SYSADMIN) and `firewall: { exception: true }` still bypass the preconditions as before. `ADMIN` is now rejected at compile time.
|
|
164
|
+
If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / SYSADMIN) and `firewall: { exception: true }` also bypass the preconditions. `ADMIN` is rejected at compile time.
|
|
167
165
|
|
|
168
166
|
Typical event-attendee setup (`guests` table carries `organizationId`): the org precondition is dropped on every action whose access references `attendee` or `eventStaff`. Org admins still get `ctx.activeOrgId` from their session as today; attendees get it from the relationship row, mid-request. Both paths converge on a valid tenant claim before `execute()` runs.
|
|
169
167
|
|
|
170
168
|
### Requirement on the relationship's `from` table
|
|
171
169
|
|
|
172
|
-
For
|
|
170
|
+
For tenant-stamping to work, the relationship's `from` table must carry tenant columns:
|
|
173
171
|
|
|
174
172
|
- For org stamping: an `organizationId` column (or whatever spelling the project's auth-provider defaults pick).
|
|
175
173
|
- For team stamping: a `teamId` column.
|
|
@@ -213,7 +211,7 @@ export default defineAction({
|
|
|
213
211
|
|
|
214
212
|
`loads` and `exposeAs` are co-required (set both or neither). `exposeAs` must be a valid JS identifier and must not collide with built-in `ctx` fields (`userId`, `activeOrgId`, `activeTeamId`, `db`, etc.).
|
|
215
213
|
|
|
216
|
-
### Action firewall escape hatch
|
|
214
|
+
### Action firewall escape hatch
|
|
217
215
|
|
|
218
216
|
`defineAction({ firewall: { exception: true } })` opts the action out of the inherited session-key preconditions (`ctx.activeOrgId` / `ctx.activeTeamId` requirements) AND the relationship resolver. The handler receives `unsafeDb` for raw Drizzle access. Use for cross-tenant or admin routes whose surface intentionally doesn't name a session/relationship key:
|
|
219
217
|
|
|
@@ -672,7 +672,7 @@ The scope claim is trusted between proofs — it is never re-checked against the
|
|
|
672
672
|
|
|
673
673
|
So removing a guest/staff row takes effect within **cap + one TTL** for a client that keeps polling, and within one TTL once it goes idle. Two ways to tighten that:
|
|
674
674
|
|
|
675
|
-
- **`auth.jwt.revocationCheck: 'kv'`** (
|
|
675
|
+
- **`auth.jwt.revocationCheck: 'kv'`** (Cloudflare runtime) — sub-TTL revocation: updating or deleting a conferring relationship row stamps a revocation timestamp in KV, and the bearer fast-path rejects a carried scope claim whose proof is at or before it — no same-second gap. Each kind is compared against **its own** proof time (`sctMs` on the entry; tokens without one fall back to the token-level `sct`/`sctMs`), so a mint of one kind can't carry a revoked kind past its marker. Neither the refresh nor a re-mint ever substitutes its own clock for a proof it didn't take. The check fails closed — a scope claim whose revocation state can't be read is not trusted either. See [auth config](/configure/auth).
|
|
676
676
|
- **`via` arms** — for tables where any caching is too wide, gate with a `via` arm instead of a bare `ctx.scope.<kind>` arm: `via` emits a live subquery against the relationship table on every request, immune to a stale claim entirely.
|
|
677
677
|
|
|
678
678
|
## Reference
|
|
@@ -15,6 +15,17 @@ Two declaration sites:
|
|
|
15
15
|
idempotency, and compiler-applied writes, for an action you are writing
|
|
16
16
|
anyway.
|
|
17
17
|
|
|
18
|
+
Both work on **any table in the feature** — the primary and its siblings
|
|
19
|
+
alike. A sibling table's transitions synthesize to
|
|
20
|
+
`actions/<table>/<name>.ts`, bound to that table, importing the generated
|
|
21
|
+
per-table helper (`.quickback/define-action.<table>`), and mount at
|
|
22
|
+
`POST /<table>/:id/<name>` exactly like a primary's. So a status machine on a
|
|
23
|
+
child table (`reservations` inside `features/sessions/`) does not force the
|
|
24
|
+
table into its own feature — group related tables freely. Never replace
|
|
25
|
+
declared transitions with hand-written per-verb actions: you lose the
|
|
26
|
+
generated routes, the `guards.protected` integration, and the CMS
|
|
27
|
+
affordances.
|
|
28
|
+
|
|
18
29
|
## Two lines per state change
|
|
19
30
|
|
|
20
31
|
```typescript
|
|
@@ -78,6 +78,10 @@ the next migrate.
|
|
|
78
78
|
- `OLD.column` / `NEW.column` references use **SQL column names**
|
|
79
79
|
(`deleted_at`, not `deletedAt`) and are validated against the table at
|
|
80
80
|
compile time.
|
|
81
|
+
- Bare `CASE ... END` expressions, including nested cases, are supported.
|
|
82
|
+
For example: `SELECT CASE WHEN NEW.total < 0 THEN RAISE(ABORT, 'invalid total') END;`.
|
|
83
|
+
That `END` closes the expression; authored `BEGIN ... END` trigger frames
|
|
84
|
+
are rejected.
|
|
81
85
|
- Optional `when:` is a SQL expression guard (`WHEN` clause).
|
|
82
86
|
- To reject a write, `SELECT RAISE(ABORT, 'message');` — this is the only
|
|
83
87
|
trigger form that blocks *every* write path, including raw SQL.
|
package/dist/skill/docs/index.md
CHANGED
|
@@ -76,9 +76,3 @@ The runtime services around your compiled code. Everything you need for a comple
|
|
|
76
76
|
- **[Account UI](/ui/account)** — Pre-built auth and profile pages
|
|
77
77
|
|
|
78
78
|
Everything runs on **your own Cloudflare account** — no Quickback infrastructure between you and your data.
|
|
79
|
-
|
|
80
|
-
---
|
|
81
|
-
|
|
82
|
-
### Changelog
|
|
83
|
-
|
|
84
|
-
[**Changelog**](/changelog) — what's new in Quickback. Release notes, new features, and improvements.
|
|
@@ -62,3 +62,40 @@ Roles are used throughout the security layers — in [Access](/define/access) ru
|
|
|
62
62
|
|
|
63
63
|
- [Plugins](/platform/auth/plugins) — Email OTP, passkeys, magic links, and more
|
|
64
64
|
- [Security](/platform/auth/security) — Cookies, rate limiting, cross-domain auth
|
|
65
|
+
|
|
66
|
+
## Compiler-managed auth versions and upgrades
|
|
67
|
+
|
|
68
|
+
The compiler pins Better Auth, its schema CLI, and the generated companion
|
|
69
|
+
packages to **1.7.2**. Recompile and install the emitted dependencies together;
|
|
70
|
+
remove older Better Auth overrides from `build.dependencies`. An incompatible
|
|
71
|
+
override is rejected because it would run a different auth version from the
|
|
72
|
+
one that generated your schema.
|
|
73
|
+
|
|
74
|
+
For an existing project, retain its `quickback/drizzle` migration history and
|
|
75
|
+
use the updated CLI when recompiling. The CLI generates the upgrade locally;
|
|
76
|
+
migration history stays on your machine. Apply the newly generated auth migration before
|
|
77
|
+
starting the updated Worker. Existing migration SQL is preserved. The upgrade
|
|
78
|
+
adds the current JWT/OAuth schema, including JWKS `alg`/`crv` and resource-bound
|
|
79
|
+
grants, and backfills account identities without resetting credentials.
|
|
80
|
+
|
|
81
|
+
Automatic account backfill covers password, SIWE, Google, Apple, Facebook,
|
|
82
|
+
Line, GitHub, and compiler-managed Cloudflare accounts. Unknown/custom provider
|
|
83
|
+
identities and duplicate identities must be resolved with an explicit migration;
|
|
84
|
+
the generated migration fails before replacing existing account rows. Custom
|
|
85
|
+
foreign keys into SQLite's account table also require an explicit migration.
|
|
86
|
+
Rehearse the migration against a database copy, and stop old auth writers during
|
|
87
|
+
the cutover so they cannot write the previous account shape.
|
|
88
|
+
|
|
89
|
+
Existing OAuth grants without a recorded resource set are revoked during the
|
|
90
|
+
upgrade; clients must authorize again. Client registrations and ordinary
|
|
91
|
+
sessions are retained. The compiler maps its audience configuration into the
|
|
92
|
+
1.7 `resources` option and preserves the previous global resource allowlist
|
|
93
|
+
for clients (`enforcePerClientResources: false`). Authorization-code and refresh
|
|
94
|
+
grants still bind resources and reject widening to an unauthorized resource.
|
|
95
|
+
Projects opting into per-client resource restrictions must link their clients
|
|
96
|
+
to resources using the OAuth provider's resource administration APIs.
|
|
97
|
+
|
|
98
|
+
The bundled Account UI uses `signIn.social` and `linkSocial` for generic OAuth
|
|
99
|
+
providers, including Cloudflare. Their callback is now
|
|
100
|
+
`/auth/v1/callback/cloudflare`; update the registered redirect URI when upgrading
|
|
101
|
+
an existing Cloudflare login integration.
|