@quickback-dev/cli 0.70.45 → 0.72.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/build.d.ts.map +1 -1
- package/dist/commands/build.js +10 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +7 -1
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/mcp.d.ts.map +1 -1
- package/dist/commands/mcp.js +6 -5
- package/dist/commands/mcp.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/access-manifest-diff.d.ts +6 -0
- package/dist/lib/access-manifest-diff.d.ts.map +1 -1
- package/dist/lib/access-manifest-diff.js +10 -0
- package/dist/lib/access-manifest-diff.js.map +1 -1
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +36 -0
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/api-client.d.ts +8 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/deployment-target.d.ts +13 -0
- package/dist/lib/deployment-target.d.ts.map +1 -1
- package/dist/lib/deployment-target.js +4 -0
- package/dist/lib/deployment-target.js.map +1 -1
- package/dist/lib/file-loader.d.ts +22 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +80 -18
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.js +9 -0
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/harness.d.ts +10 -0
- package/dist/lib/harness.d.ts.map +1 -1
- package/dist/lib/harness.js +31 -0
- package/dist/lib/harness.js.map +1 -1
- package/dist/lib/migrations/executor.js +5 -1
- package/dist/lib/migrations/executor.js.map +1 -1
- package/dist/lib/migrations/plan.js +3 -0
- package/dist/lib/migrations/plan.js.map +1 -1
- package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/index.js +23 -2
- package/dist/lib/migrations/postprocessors/index.js.map +1 -1
- package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts +30 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.js +109 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.js.map +1 -0
- package/dist/lib/migrations/prior-state.d.ts +13 -1
- package/dist/lib/migrations/prior-state.d.ts.map +1 -1
- package/dist/lib/migrations/prior-state.js +33 -2
- package/dist/lib/migrations/prior-state.js.map +1 -1
- package/dist/lib/migrations/types.d.ts +2 -2
- package/dist/lib/migrations/types.d.ts.map +1 -1
- package/dist/lib/migrations/types.js +3 -0
- package/dist/lib/migrations/types.js.map +1 -1
- package/dist/lib/wrangler-resources.d.ts +14 -1
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +29 -7
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/skill/docs/api/actions.md +73 -2
- package/dist/skill/docs/api/batch-operations.md +2 -0
- package/dist/skill/docs/api/caching.md +2 -2
- package/dist/skill/docs/api/crud.md +13 -0
- package/dist/skill/docs/api/errors.md +111 -10
- package/dist/skill/docs/api/index.md +24 -0
- package/dist/skill/docs/api/openapi.md +8 -0
- package/dist/skill/docs/api/query-params.md +6 -0
- package/dist/skill/docs/configure/agents.md +73 -1
- package/dist/skill/docs/configure/auth.md +7 -1
- package/dist/skill/docs/configure/bindings.md +55 -0
- package/dist/skill/docs/configure/cloudflare-access.md +191 -0
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +4 -2
- package/dist/skill/docs/configure/providers.md +2 -1
- package/dist/skill/docs/configure/tenancy.md +3 -0
- package/dist/skill/docs/configure/tenant-databases.md +2407 -0
- package/dist/skill/docs/define/access.md +33 -1
- package/dist/skill/docs/define/actions/defining.md +118 -1
- package/dist/skill/docs/define/actions/scoped-db.md +32 -8
- package/dist/skill/docs/define/areas.md +145 -2
- package/dist/skill/docs/define/diagnostics.md +160 -21
- package/dist/skill/docs/define/encryption.md +13 -2
- package/dist/skill/docs/define/fga.md +320 -42
- package/dist/skill/docs/define/firewall.md +4 -0
- package/dist/skill/docs/define/index.md +1 -0
- package/dist/skill/docs/define/read.md +39 -0
- package/dist/skill/docs/define/relationships.md +30 -12
- package/dist/skill/docs/define/schema.md +2 -0
- package/dist/skill/docs/define/scopes.md +393 -9
- package/dist/skill/docs/define/sealed-protocol.md +67 -12
- package/dist/skill/docs/define/transitions.md +4 -1
- package/dist/skill/docs/define/triggers.md +55 -1
- package/dist/skill/docs/platform/api-contract/index.md +4 -2
- package/dist/skill/docs/platform/auth/jwt-optimization.md +13 -1
- package/dist/skill/docs/platform/auth/using-auth.md +1 -1
- package/dist/skill/docs/platform/database/d1.md +112 -3
- package/dist/skill/docs/platform/database/data-migrations.md +3 -1
- package/dist/skill/docs/platform/database/neon.md +10 -2
- package/dist/skill/docs/platform/queues/handlers.md +48 -16
- package/dist/skill/docs/platform/queues/using-queues.md +16 -0
- package/dist/skill/docs/platform/realtime/durable-objects.md +285 -17
- package/dist/skill/docs/platform/realtime/index.md +9 -6
- package/dist/skill/docs/platform/realtime/named-invalidations.md +3 -1
- package/dist/skill/docs/platform/realtime/using-realtime.md +28 -3
- package/dist/skill/docs/platform/schedules/index.md +1 -1
- package/dist/skill/docs/platform/storage/r2.md +10 -1
- package/dist/skill/docs/platform/storage/using-r2.md +42 -1
- package/dist/skill/docs/tooling/output.md +9 -2
- package/dist/skill/docs/ui/account/features/admin.md +5 -3
- package/dist/skill/docs/ui/account/hooks.md +9 -2
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +73 -2
- package/src/skill/docs/api/batch-operations.md +2 -0
- package/src/skill/docs/api/caching.md +2 -2
- package/src/skill/docs/api/crud.md +13 -0
- package/src/skill/docs/api/errors.md +111 -10
- package/src/skill/docs/api/index.md +24 -0
- package/src/skill/docs/api/openapi.md +8 -0
- package/src/skill/docs/api/query-params.md +6 -0
- package/src/skill/docs/configure/agents.md +73 -1
- package/src/skill/docs/configure/auth.md +7 -1
- package/src/skill/docs/configure/bindings.md +55 -0
- package/src/skill/docs/configure/cloudflare-access.md +191 -0
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +4 -2
- package/src/skill/docs/configure/providers.md +2 -1
- package/src/skill/docs/configure/tenancy.md +3 -0
- package/src/skill/docs/configure/tenant-databases.md +2407 -0
- package/src/skill/docs/define/access.md +33 -1
- package/src/skill/docs/define/actions/defining.md +118 -1
- package/src/skill/docs/define/actions/scoped-db.md +32 -8
- package/src/skill/docs/define/areas.md +145 -2
- package/src/skill/docs/define/diagnostics.md +160 -21
- package/src/skill/docs/define/encryption.md +13 -2
- package/src/skill/docs/define/fga.md +320 -42
- package/src/skill/docs/define/firewall.md +4 -0
- package/src/skill/docs/define/index.md +1 -0
- package/src/skill/docs/define/read.md +39 -0
- package/src/skill/docs/define/relationships.md +30 -12
- package/src/skill/docs/define/schema.md +2 -0
- package/src/skill/docs/define/scopes.md +393 -9
- package/src/skill/docs/define/sealed-protocol.md +67 -12
- package/src/skill/docs/define/transitions.md +4 -1
- package/src/skill/docs/define/triggers.md +55 -1
- package/src/skill/docs/platform/api-contract/index.md +4 -2
- package/src/skill/docs/platform/auth/jwt-optimization.md +13 -1
- package/src/skill/docs/platform/auth/using-auth.md +1 -1
- package/src/skill/docs/platform/database/d1.md +112 -3
- package/src/skill/docs/platform/database/data-migrations.md +3 -1
- package/src/skill/docs/platform/database/neon.md +10 -2
- package/src/skill/docs/platform/queues/handlers.md +48 -16
- package/src/skill/docs/platform/queues/using-queues.md +16 -0
- package/src/skill/docs/platform/realtime/durable-objects.md +285 -17
- package/src/skill/docs/platform/realtime/index.md +9 -6
- package/src/skill/docs/platform/realtime/named-invalidations.md +3 -1
- package/src/skill/docs/platform/realtime/using-realtime.md +28 -3
- package/src/skill/docs/platform/schedules/index.md +1 -1
- package/src/skill/docs/platform/storage/r2.md +10 -1
- package/src/skill/docs/platform/storage/using-r2.md +42 -1
- package/src/skill/docs/tooling/output.md +9 -2
- package/src/skill/docs/ui/account/features/admin.md +5 -3
- package/src/skill/docs/ui/account/hooks.md +9 -2
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/dist/codex/AGENTS.md +0 -290
- package/dist/commands/build.test.d.ts.map +0 -1
- package/dist/commands/codex.d.ts +0 -16
- package/dist/commands/codex.d.ts.map +0 -1
- package/dist/commands/codex.js +0 -159
- package/dist/commands/codex.js.map +0 -1
- package/dist/commands/compile.d.ts +0 -62
- package/dist/commands/compile.d.ts.map +0 -1
- package/dist/commands/compile.js +0 -830
- package/dist/commands/compile.js.map +0 -1
- package/dist/commands/compile.test.d.ts.map +0 -1
- package/dist/commands/init.d.ts +0 -6
- package/dist/commands/init.d.ts.map +0 -1
- package/dist/commands/init.js +0 -405
- package/dist/commands/init.js.map +0 -1
- package/dist/commands/migrate.test.d.ts.map +0 -1
- package/dist/commands/migrations.test.d.ts.map +0 -1
- package/dist/commands/push.test.d.ts.map +0 -1
- package/dist/commands/schema.test.d.ts.map +0 -1
- package/dist/docs/content.d.ts +0 -7
- package/dist/docs/content.d.ts.map +0 -1
- package/dist/docs/content.js +0 -672
- package/dist/docs/content.js.map +0 -1
- package/dist/docs/index.test.d.ts.map +0 -1
- package/dist/lib/action-harvest.test.d.ts.map +0 -1
- package/dist/lib/api-client.test.d.ts.map +0 -1
- package/dist/lib/artifact-routing.test.d.ts.map +0 -1
- package/dist/lib/auth.test.d.ts.map +0 -1
- package/dist/lib/compile-next-steps.test.d.ts.map +0 -1
- package/dist/lib/compiler-floor.test.d.ts.map +0 -1
- package/dist/lib/config-id-splice.test.d.ts.map +0 -1
- package/dist/lib/config-sync.test.d.ts.map +0 -1
- package/dist/lib/copy-public-assets.test.d.ts.map +0 -1
- package/dist/lib/copy-source-apps.test.d.ts.map +0 -1
- package/dist/lib/drizzle-meta-routing.test.d.ts.map +0 -1
- package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +0 -1
- package/dist/lib/file-loader.test.d.ts.map +0 -1
- package/dist/lib/file-writer.test.d.ts.map +0 -1
- package/dist/lib/helpers.d.ts +0 -39
- package/dist/lib/helpers.d.ts.map +0 -1
- package/dist/lib/helpers.js +0 -299
- package/dist/lib/helpers.js.map +0 -1
- package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +0 -1
- package/dist/lib/migrations/drizzle.test.d.ts.map +0 -1
- package/dist/lib/migrations/executor.test.d.ts.map +0 -1
- package/dist/lib/migrations/inventory.test.d.ts.map +0 -1
- package/dist/lib/migrations/lock.test.d.ts.map +0 -1
- package/dist/lib/migrations/paths.test.d.ts.map +0 -1
- package/dist/lib/migrations/plan.test.d.ts.map +0 -1
- package/dist/lib/migrations/postprocessors/index.test.d.ts.map +0 -1
- package/dist/lib/migrations/prompt-runner.test.d.ts.map +0 -1
- package/dist/lib/migrations/staging.test.d.ts.map +0 -1
- package/dist/lib/neon-canary.test.d.ts.map +0 -1
- package/dist/lib/neon-target.test.d.ts.map +0 -1
- package/dist/lib/neon.test.d.ts.map +0 -1
- package/dist/lib/prepare-output.test.d.ts.map +0 -1
- package/dist/lib/prepare-state-output.test.d.ts.map +0 -1
- package/dist/lib/schema-sync/index.test.d.ts.map +0 -1
- package/dist/lib/shell.test.d.ts.map +0 -1
- package/dist/lib/sweep-stale.d.ts +0 -25
- package/dist/lib/sweep-stale.d.ts.map +0 -1
- package/dist/lib/sweep-stale.js +0 -179
- package/dist/lib/sweep-stale.js.map +0 -1
- package/dist/lib/sweep-stale.test.d.ts.map +0 -1
- package/dist/lib/wrangler-resources.test.d.ts.map +0 -1
|
@@ -24,7 +24,7 @@ Roles and one-hop relationship joins can't express:
|
|
|
24
24
|
- **Hierarchical** permissions — a document inherits viewers from its folder.
|
|
25
25
|
- **Group** permissions — every member of `team:eng` is a viewer.
|
|
26
26
|
- **Per-record grants** — assign one person to one record without a global role.
|
|
27
|
-
- **
|
|
27
|
+
- **Share links** — one object, one role, per-link expiry and revocation, no account.
|
|
28
28
|
|
|
29
29
|
These are exactly what Zanzibar's *userset rewrites* and *tuple-to-userset*
|
|
30
30
|
relations solve, and what the FGA pillar gives you.
|
|
@@ -79,6 +79,7 @@ relation, and `from` reference must resolve, or the compile fails loud.
|
|
|
79
79
|
| --- | --- |
|
|
80
80
|
| `define viewer: [user]` | Direct assignment — a stored tuple grants `viewer`. |
|
|
81
81
|
| `define viewer: [user, user:*]` | `user:*` = **type-bound public access** (everyone). |
|
|
82
|
+
| `define viewer: [user, link]` | `link` = a **share link** subject (`link:<id>`). Requires `type link`. |
|
|
82
83
|
| `define viewer: [team#member]` | A **userset** — every `member` of a `team` is a `viewer`. |
|
|
83
84
|
| `define viewer: [user] or editor` | **Union** — `editor`s are also `viewer`s (derived). |
|
|
84
85
|
| `define viewer: editor and member` | **Intersection** — must be both. |
|
|
@@ -104,14 +105,16 @@ await ctx.fga.write([
|
|
|
104
105
|
// POST /api/v1/fga/v1/write
|
|
105
106
|
// { "writes": [{ "user": "user:anne", "relation": "recruiter", "object": "job:123" }] }
|
|
106
107
|
|
|
107
|
-
// 3. A
|
|
108
|
+
// 3. A share link (see Share links below)
|
|
108
109
|
```
|
|
109
110
|
|
|
110
111
|
## Checking access
|
|
111
112
|
|
|
112
113
|
### `ctx.fga` in handlers and actions
|
|
113
114
|
|
|
114
|
-
Every authenticated request
|
|
115
|
+
Every authenticated request with an active organization — and every
|
|
116
|
+
[share-link principal](#the-link-principal) — gets an org-scoped `ctx.fga`
|
|
117
|
+
client. An anonymous request has no tenant, so it has no `ctx.fga`:
|
|
115
118
|
|
|
116
119
|
```typescript
|
|
117
120
|
const allowed = await ctx.fga.check('user:' + ctx.userId, 'can_manage', 'job:' + jobId);
|
|
@@ -202,25 +205,232 @@ request fails with a hard **422 `FGA_LIST_TOO_LARGE`** whose hint points to
|
|
|
202
205
|
page. Raise the cap or paginate via the API for collections that legitimately
|
|
203
206
|
authorize more than `maxIds` rows per caller.
|
|
204
207
|
|
|
205
|
-
##
|
|
208
|
+
## Share links
|
|
206
209
|
|
|
207
|
-
|
|
208
|
-
|
|
210
|
+
A share link is a capability, not an account: one object, one role, its own
|
|
211
|
+
expiry and revocation, no Better Auth user. Quickback has two kinds, chosen per
|
|
212
|
+
relation by the model:
|
|
209
213
|
|
|
210
|
-
|
|
214
|
+
| Relation declares | Minting writes | Each link has its own | Use for |
|
|
215
|
+
| --- | --- | --- | --- |
|
|
216
|
+
| `[user, link]` | `(link:<id>, relation, object)` | role, expiry, revocation, scope instance, restriction | Kitchen sheets, guest lists, anything with personal data |
|
|
217
|
+
| `[user, user:*]` | `(user:*, relation, object)` | expiry (signed token) | "Make this object public" |
|
|
218
|
+
|
|
219
|
+
### Link subjects (`link:<id>`)
|
|
211
220
|
|
|
212
|
-
|
|
213
|
-
can be granted to *everyone* by writing one tuple:
|
|
221
|
+
Declare `type link` and list it on the relations a link may be granted:
|
|
214
222
|
|
|
215
223
|
```typescript
|
|
216
|
-
|
|
224
|
+
authz: {
|
|
225
|
+
fga: {
|
|
226
|
+
model: `
|
|
227
|
+
model
|
|
228
|
+
schema 1.1
|
|
229
|
+
type user
|
|
230
|
+
type link
|
|
231
|
+
type doc
|
|
232
|
+
relations
|
|
233
|
+
define editor: [user, link]
|
|
234
|
+
define viewer: [user, link] or editor
|
|
235
|
+
`,
|
|
236
|
+
sharing: {
|
|
237
|
+
enabled: true,
|
|
238
|
+
// Default link lifetime in seconds. Required (> 0) when the table masks a column.
|
|
239
|
+
ttlSeconds: 86400,
|
|
240
|
+
// Every type a link can point at names its table. `fields` is the landing projection.
|
|
241
|
+
resources: { doc: { table: 'docs', fields: ['id', 'title'] } },
|
|
242
|
+
links: { cookieTtlSeconds: 900, rateLimitPerMinute: 60 },
|
|
243
|
+
},
|
|
244
|
+
},
|
|
245
|
+
}
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
Mint, list and revoke on the FGA API:
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
POST /fga/v1/share { "object": "doc:d1", "relation": "viewer", "ttlSeconds": 3600 }
|
|
252
|
+
→ 201 { id: "lnk_…", token, url, expiresAt }
|
|
253
|
+
url = https://api.acme.dev/share/v1/open#share=<token>
|
|
254
|
+
GET /fga/v1/share/links?object=doc:d1 → { links: [{ id, relation, scope, expiresAt, active }] }
|
|
255
|
+
POST /fga/v1/share/revoke { "id": "lnk_…" }
|
|
217
256
|
```
|
|
218
257
|
|
|
219
|
-
|
|
258
|
+
The token is returned **once**. Only `HMAC-SHA256(BETTER_AUTH_SECRET, token)`
|
|
259
|
+
is stored, in the compiler-owned `fga_share_links` table. Revoking sets
|
|
260
|
+
`revoked_at` and deletes the link's tuple; either one alone stops the link.
|
|
261
|
+
|
|
262
|
+
**Who may mint and revoke** is a Better Auth access statement, not a parallel
|
|
263
|
+
permission system. The compiler registers the organization plugin's access
|
|
264
|
+
control with `share: ['create', 'revoke']` (from
|
|
265
|
+
`src/lib/fga/share-access.ts`): `owner` and every `writeRoles` role hold both,
|
|
266
|
+
`member` holds neither. `auth.api.hasPermission` and the client's
|
|
267
|
+
`organization.hasPermission({ permissions: { share: ['create'] } })` answer from
|
|
268
|
+
the same statements the share routes check. A caller without `share:create`
|
|
269
|
+
gets 403. Minting needs that permission through a real membership role — a
|
|
270
|
+
sysadmin without one can revoke links but not mint them.
|
|
271
|
+
|
|
272
|
+
**The creator is an edge.** A link is honoured only while the user who minted
|
|
273
|
+
it is still a member of the link's organization whose **current** role holds
|
|
274
|
+
`share:create`. Every resolution reads that role from Better Auth; nothing is
|
|
275
|
+
stored. Remove the creator from the organization, or move them to a role
|
|
276
|
+
without `share:create`, and every link they minted stops working — and with it
|
|
277
|
+
every request that was admitted only through those links. Restore the role and
|
|
278
|
+
the links work again (revoke them to end them for good).
|
|
279
|
+
|
|
280
|
+
#### Opening a link
|
|
281
|
+
|
|
282
|
+
1. The share URL is `/share/v1/open#share=<token>`. The token is in the
|
|
283
|
+
**fragment**, which browsers never send — not in the request line, not in
|
|
284
|
+
`Referer` — so it never reaches access logs. `GET /share/v1/open` serves a
|
|
285
|
+
page with no token in it; its script (`/share/v1/open.js`, CSP
|
|
286
|
+
`script-src 'self'` compatible) reads the fragment, clears it from the
|
|
287
|
+
address bar, and `POST`s `{ "token": "…" }` as `application/json` to
|
|
288
|
+
`/share/v1/exchange` (any other content type is 415, so a cross-site form
|
|
289
|
+
cannot plant a cookie). The exchange sets a short-lived `HttpOnly` cookie
|
|
290
|
+
`qb_share` holding a signed link id — never the token — and the page moves
|
|
291
|
+
to the clean URL `/share/v1/link`.
|
|
292
|
+
An IP that has spent its failed-lookup budget is refused (429) before any
|
|
293
|
+
hash or database query; valid lookups never spend budget.
|
|
294
|
+
2. `GET /share/v1/link` re-checks the link's tuple and returns `{ link, record }`:
|
|
295
|
+
what the link grants and the `resources.<type>.fields` projection of its
|
|
296
|
+
object (never a soft-deleted row). A signed-in visitor sees it too.
|
|
297
|
+
3. Every later request carries the cookie. API clients send the token in the
|
|
298
|
+
`x-share-token` header instead.
|
|
299
|
+
|
|
300
|
+
Every link and share-router response sets `Referrer-Policy: no-referrer` and
|
|
301
|
+
`Cache-Control: no-store`. A revoked or expired link returns 404 at open and 401
|
|
302
|
+
on the API.
|
|
303
|
+
|
|
304
|
+
`GET /share/v1/<token>` (the token in the path, 303 to the landing URL) still
|
|
305
|
+
works for links minted before the fragment URL and will be removed in the next
|
|
306
|
+
minor. Its token does appear in request logs — revoke any link whose URL may
|
|
307
|
+
have been logged.
|
|
308
|
+
|
|
309
|
+
#### The link principal
|
|
310
|
+
|
|
311
|
+
A request with a valid link credential runs as `link:<id>` through the
|
|
312
|
+
**normal generated routes**:
|
|
313
|
+
|
|
314
|
+
- `ctx.authMethod === 'link'`, `ctx.link = { id, organizationId, relation, object, expiresAt, scope, viaUserId }`.
|
|
315
|
+
- No `userId`, no org role (`ctx.roles = []`), no `/me/*`. `AUTHENTICATED`,
|
|
316
|
+
`SESSION` and `USER` do not admit it.
|
|
317
|
+
- It exists **only on routes whose access has an `fga` arm for the link's
|
|
318
|
+
object type** (the compiler marks them in each resource router). On every
|
|
319
|
+
other route — a `PUBLIC` create, a standalone action, an action or resource
|
|
320
|
+
of another type — the link credential is ignored and the request runs as the
|
|
321
|
+
caller it otherwise is (anonymous, or their own session). A link never lends
|
|
322
|
+
an organization to a `PUBLIC` route.
|
|
323
|
+
- Each operation and concrete named view uses its own effective access and
|
|
324
|
+
object types. A PUBLIC view cannot borrow authority from an FGA sibling
|
|
325
|
+
view, and batch access is independent of single-record access.
|
|
326
|
+
- On a link-capable route, only `fga` arms (checked against `link:<id>`'s own
|
|
327
|
+
tuples) admit it. A `PUBLIC` sibling does not bypass that check. A roles-less arm (`record:` only) and function-form access
|
|
328
|
+
deny it, so `and: [{ fga }, { record }]` and `{ fga, record }` **never**
|
|
329
|
+
admit a link — put the
|
|
330
|
+
record condition in the model (or a separate `fga` relation) instead.
|
|
331
|
+
- `ctx.fga` is hydrated for the link's organization, so `access: { fga }`
|
|
332
|
+
gates, collection filtering, and `ctx.fga.check(...)` in actions work.
|
|
333
|
+
- Masking evaluates its (empty) role set: masked columns stay masked.
|
|
334
|
+
- Writes are audited as `created_by` / `modified_by` = `link:<id>`.
|
|
335
|
+
- The link middleware runs on `/api/*` and `/share/v1/link` only. The FGA API,
|
|
336
|
+
`/auth`, storage and realtime never see a link principal.
|
|
337
|
+
|
|
338
|
+
```typescript
|
|
339
|
+
// docs.ts — members read everything in the org; a link reads only what its tuples grant.
|
|
340
|
+
read: {
|
|
341
|
+
access: {
|
|
342
|
+
or: [
|
|
343
|
+
{ roles: ['owner', 'admin', 'member'] },
|
|
344
|
+
{ fga: { relation: 'viewer', object: 'doc:{id}' } },
|
|
345
|
+
],
|
|
346
|
+
},
|
|
347
|
+
},
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
A signed-in caller keeps their own identity over an ambient `qb_share` cookie
|
|
351
|
+
on API routes; the `x-share-token` header always applies.
|
|
352
|
+
|
|
353
|
+
> **Custom code must check `ctx.link`.** A link principal has
|
|
354
|
+
> `ctx.authenticated === true`, and an org-level link also has `ctx.activeOrgId`
|
|
355
|
+
> set. Code that gates on those alone — a function-form access rule, a
|
|
356
|
+
> project middleware, an action that reads `ctx.activeOrgId` — treats a link
|
|
357
|
+
> holder as an org caller. Branch on `ctx.link` (or `ctx.authMethod === 'link'`)
|
|
358
|
+
> first. Generated code already does: function-form access denies a link, and an
|
|
359
|
+
> action without an `fga` arm (a `PUBLIC` action) runs a link holder as an
|
|
360
|
+
> anonymous caller, never with the link's org-scoped `db`.
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
#### Placement: two locks
|
|
364
|
+
|
|
365
|
+
Links and their tuples live with the object they protect. At mint, the object
|
|
366
|
+
row must exist in the minter's organization (404 otherwise), and its
|
|
367
|
+
non-tenant scope column (`q.scope('event')`, …) binds the link to that scope
|
|
368
|
+
instance:
|
|
369
|
+
|
|
370
|
+
- **Scoped object** (an `event_id` row): the principal gets
|
|
371
|
+
`ctx.scope = { event: { id } }` and no org claim, exactly like an event-bound
|
|
372
|
+
token. The table's `ctx.scope.event` firewall arm runs first; a link for
|
|
373
|
+
`evt_A`'s doc returns `FIREWALL_NOT_FOUND` on `evt_B`'s rows before FGA is
|
|
374
|
+
consulted. The FGA Check is the second lock.
|
|
375
|
+
- **Org-level object**: the principal gets `activeOrgId` = the link's
|
|
376
|
+
organization, so the object's own routes resolve; FGA alone decides per
|
|
377
|
+
object. A link holder is not an org member, so the action `db` never sees
|
|
378
|
+
that claim: inside a link-capable action, an org-scoped table answers
|
|
379
|
+
`403 FIREWALL_CLAIM_MISSING` (the action already has its object as
|
|
380
|
+
`record`). Without this, any org arm reached through the action's `db`
|
|
381
|
+
admitted the link holder to the whole organization's rows. Rows loaded by
|
|
382
|
+
`?include=` on the object's own routes still see the link's organization:
|
|
383
|
+
they are joined to the shared row by foreign key.
|
|
384
|
+
|
|
385
|
+
Compile errors:
|
|
386
|
+
|
|
387
|
+
- A type with `link` relations and no `sharing.resources.<type>` entry.
|
|
388
|
+
- A `resources.<type>.table` without a `q.scope('organization')` column.
|
|
389
|
+
- A table that declares `masking` while `sharing.ttlSeconds` is unset or 0 —
|
|
390
|
+
every link to personal data must expire. At mint, `ttlSeconds: 0` or a value
|
|
391
|
+
above `sharing.ttlSeconds` is a 400 for those types.
|
|
392
|
+
- `link` relations without `sharing.enabled`, or without the Better Auth
|
|
393
|
+
organization plugin.
|
|
394
|
+
|
|
395
|
+
#### Restricted links
|
|
396
|
+
|
|
397
|
+
Add `restrict` at mint to also require a signed-in user:
|
|
398
|
+
|
|
399
|
+
```bash
|
|
400
|
+
POST /fga/v1/share { "object": "doc:d1", "relation": "viewer",
|
|
401
|
+
"restrict": { "orgMembers": true, "emailDomains": ["acme.dev"] } }
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
- `orgMembers` — the user's active organization must be the link's.
|
|
405
|
+
- `emailDomains` — the user's email must be **verified** (`user.emailVerified`)
|
|
406
|
+
and its domain listed. JWT-lane callers carry no verification flag, so they
|
|
407
|
+
never satisfy it.
|
|
408
|
+
|
|
409
|
+
Anonymous or non-matching callers get 403 at open and on the API. A matching
|
|
410
|
+
user runs as `link:<id>` (with `ctx.link.viaUserId` set) — the link grants, not
|
|
411
|
+
their own roles. The cookie a restricted link sets is bound to the user who
|
|
412
|
+
opened it and applies only on `/share/v1/link` and paths naming the link's
|
|
413
|
+
object; anywhere else (or for anyone else) it is ignored and the caller's own
|
|
414
|
+
session applies. It never replaces a session that already holds a role in the
|
|
415
|
+
link's organization — an admin who opens a restricted viewer link keeps admin.
|
|
416
|
+
|
|
417
|
+
### Type-bound public access (`user:*`)
|
|
418
|
+
|
|
419
|
+
A relation that lists `user:*` (`define viewer: [user, user:*]`) can be granted
|
|
420
|
+
to everyone with one tuple:
|
|
220
421
|
|
|
221
|
-
|
|
422
|
+
```typescript
|
|
423
|
+
await ctx.fga.write([{ user: 'user:*', relation: 'viewer', object: 'job:' + id }]);
|
|
424
|
+
```
|
|
222
425
|
|
|
223
|
-
|
|
426
|
+
`POST /fga/v1/share` on such a relation (write-role gated) writes that tuple and
|
|
427
|
+
returns an HMAC-signed `{ token, url }`. `GET /share/v1/:token` needs no
|
|
428
|
+
session: it verifies the signature and expiry (`ttlSeconds`, default never),
|
|
429
|
+
re-checks the stored `user:*` grant, and returns the public projection.
|
|
430
|
+
Revoke by deleting the `user:*` tuple — that revokes **every** link to the
|
|
431
|
+
object at once, and every holder sees the same thing. Use `link` subjects when
|
|
432
|
+
links need their own role or revocation. If the relation has neither `link` nor
|
|
433
|
+
`user:*`, minting returns 400.
|
|
224
434
|
|
|
225
435
|
```typescript
|
|
226
436
|
authz: {
|
|
@@ -228,13 +438,9 @@ authz: {
|
|
|
228
438
|
model: `...`,
|
|
229
439
|
sharing: {
|
|
230
440
|
enabled: true,
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
//
|
|
234
|
-
baseUrl: 'https://share.acme.dev',
|
|
235
|
-
// Tokens never expire by default; set a TTL in seconds to expire them.
|
|
236
|
-
ttlSeconds: 0,
|
|
237
|
-
// Public projection: what a `job:<id>` share link may reveal, no login.
|
|
441
|
+
route: '/share', // GET /share/v1/:token (always mounted)
|
|
442
|
+
baseUrl: 'https://share.acme.dev', // optional vanity base URL
|
|
443
|
+
ttlSeconds: 0, // 0 = never expires
|
|
238
444
|
resources: {
|
|
239
445
|
job: { table: 'jobs', fields: ['id', 'title', 'department', 'status'] },
|
|
240
446
|
},
|
|
@@ -243,20 +449,7 @@ authz: {
|
|
|
243
449
|
}
|
|
244
450
|
```
|
|
245
451
|
|
|
246
|
-
|
|
247
|
-
(write-role gated) → `{ token, url }`. Minting **writes the `(user:*, relation,
|
|
248
|
-
object)` tuple** (making the object publicly viewable per the model) and then
|
|
249
|
-
signs the link. If the relation has no `user:*` arm in the model, minting
|
|
250
|
-
fails with a 400 rather than handing back a dead link.
|
|
251
|
-
- **Resolve** a link: `GET /share/v1/:token` — **no authentication**. The route
|
|
252
|
-
verifies the HMAC, then **checks the stored grant** (no contextual shortcut):
|
|
253
|
-
the object must still have the granted `user:*` relation right now. Only then
|
|
254
|
-
does it return the configured public projection. Nothing else leaks — the
|
|
255
|
-
token is scoped to exactly that object and relation.
|
|
256
|
-
- **Revoke** a link: delete the `(user:*, relation, object)` tuple (via
|
|
257
|
-
`POST /fga/v1/write` `deletes`, or your own action). The next `GET` Check
|
|
258
|
-
fails and the link stops returning content — revocation is real, not just
|
|
259
|
-
token expiry.
|
|
452
|
+
A public projection may not list a masked column (compile error).
|
|
260
453
|
|
|
261
454
|
### The share URL: route, base URL, or both
|
|
262
455
|
|
|
@@ -278,8 +471,32 @@ You get **both** by default:
|
|
|
278
471
|
},
|
|
279
472
|
```
|
|
280
473
|
|
|
281
|
-
Minted links then use `https://share.acme.dev/v1/:token
|
|
282
|
-
|
|
474
|
+
Minted links then use `https://share.acme.dev/share/v1/:token`.
|
|
475
|
+
|
|
476
|
+
## Membership tuples from Better Auth
|
|
477
|
+
|
|
478
|
+
Don't write tuples that mirror organization membership. Declare the mapping and
|
|
479
|
+
the compiler derives them:
|
|
480
|
+
|
|
481
|
+
```typescript
|
|
482
|
+
authz: {
|
|
483
|
+
fga: {
|
|
484
|
+
model: `...`, // type organization relations define member: [user] ...
|
|
485
|
+
membership: {
|
|
486
|
+
type: 'organization',
|
|
487
|
+
relations: { member: ['member', 'admin', 'owner'], admin: ['admin', 'owner'] },
|
|
488
|
+
},
|
|
489
|
+
},
|
|
490
|
+
}
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
The organization plugin's hooks (`afterAddMember`, `afterAcceptInvitation`,
|
|
494
|
+
`afterUpdateMemberRole`, `afterRemoveMember`, `afterDeleteOrganization`) call
|
|
495
|
+
`src/lib/fga/membership.ts`, which recomputes `(user:<id>, <relation>,
|
|
496
|
+
organization:<orgId>)` from the member's current role. Each sync replaces the
|
|
497
|
+
user's full mirrored set, so the next membership event repairs a failed one.
|
|
498
|
+
Each relation must allow `[user]` directly (compile error otherwise). Cloudflare
|
|
499
|
+
runtime only.
|
|
283
500
|
|
|
284
501
|
## REST API
|
|
285
502
|
|
|
@@ -293,10 +510,14 @@ When `authz.fga` is set, the compiler mounts an OpenFGA-compatible surface at
|
|
|
293
510
|
| `POST /expand` | `{ relation, object }` | `{ tree }` |
|
|
294
511
|
| `POST /read` | `{ object?, relation?, user? }` | `{ tuples }` |
|
|
295
512
|
| `POST /write` | `{ writes?, deletes? }` | `{ ok }` (write-role) |
|
|
296
|
-
| `POST /share` | `{ object, relation, ttlSeconds? }` | `{ token, url }` (write-role) |
|
|
513
|
+
| `POST /share` | `{ object, relation, ttlSeconds?, restrict? }` | `link` relation: `{ id, token, url, expiresAt }` (`share:create`); `user:*` relation: `{ token, url }` (write-role) |
|
|
514
|
+
| `GET /share/links` | `?object=type:id` | `{ links }` (`share:create`) |
|
|
515
|
+
| `POST /share/revoke` | `{ id }` | `{ ok }` (`share:revoke`) |
|
|
297
516
|
|
|
298
|
-
`writeRoles` (default `['admin']`) controls who can write tuples and mint
|
|
299
|
-
links
|
|
517
|
+
`writeRoles` (default `['admin']`) controls who can write tuples and mint
|
|
518
|
+
`user:*` share links, and which roles get `share: ['create', 'revoke']`
|
|
519
|
+
(plus `owner`). Pseudo-roles and `+` hierarchy suffixes are honored. A
|
|
520
|
+
share-link principal gets 403 on every `/fga/v1` route.
|
|
300
521
|
|
|
301
522
|
## How it resolves
|
|
302
523
|
|
|
@@ -310,10 +531,68 @@ default 25).
|
|
|
310
531
|
The engine **enforces the model's direct type restrictions at check time**: a
|
|
311
532
|
stored tuple whose subject shape isn't allowed for the relation is inert. So a
|
|
312
533
|
`user:*` tuple on a relation declared `[user]` (no wildcard) can never grant
|
|
313
|
-
access, even if it was written out-of-band — the model is the ceiling.
|
|
534
|
+
access, even if it was written out-of-band — the model is the ceiling. The
|
|
535
|
+
same holds for tuple-to-userset edges: a stored `parent` tuple pointing at a
|
|
536
|
+
type the relation no longer lists is ignored.
|
|
537
|
+
|
|
538
|
+
A cycle never grants. On the `but not` side of an exclusion a cycle denies
|
|
539
|
+
rather than reading as "not excluded".
|
|
540
|
+
|
|
541
|
+
### OpenFGA conformance
|
|
542
|
+
|
|
543
|
+
The engine runs OpenFGA's own published suites
|
|
544
|
+
(`assets/tests/consolidated_1_1_tests.yaml` and `abac_tests.yaml` from
|
|
545
|
+
openfga/openfga, vendored under Apache-2.0) in the compiler test suite
|
|
546
|
+
(`fga-openfga-conformance.test.ts`):
|
|
547
|
+
|
|
548
|
+
| Suite | Executed | Pass | Skipped (unsupported) |
|
|
549
|
+
| --- | --- | --- | --- |
|
|
550
|
+
| `consolidated_1_1_tests.yaml` | 606 Check + ListObjects assertions | 606 (100%) | 297 ListUsers, 30 request-validation error codes |
|
|
551
|
+
| `abac_tests.yaml` | 0 | — | 234 conditions, 97 ListUsers |
|
|
552
|
+
|
|
553
|
+
Not implemented: CEL conditions (the parser rejects `condition` blocks and
|
|
554
|
+
`with` restrictions; conditional tuples fail closed), the ListUsers API, and
|
|
555
|
+
OpenFGA's request-validation error codes (an invalid request denies instead of
|
|
556
|
+
erroring). The DSL accepts `#` comments.
|
|
314
557
|
|
|
315
558
|
## Limitations
|
|
316
559
|
|
|
560
|
+
- With [database per tenant](/configure/tenant-databases#fga)
|
|
561
|
+
(`tenancy.isolation: 'durable-object'`), tuples live in each organization's
|
|
562
|
+
object. `ctx.fga` works in tenant actions and `/fga/v1` is forwarded there.
|
|
563
|
+
`sharing`, `membership` and `access: { fga }` arms are not supported yet.
|
|
564
|
+
|
|
565
|
+
- Link sharing requires compiler-managed table metadata. Scoped link sharing
|
|
566
|
+
also requires a managed organization-scoped parent, resolved through
|
|
567
|
+
`authz.scopes.<kind>.instance` or the existing unambiguous scope-instance
|
|
568
|
+
FK/firewall mapping. An unresolved or ambiguous parent fails compilation
|
|
569
|
+
with an actionable mapping error. This requirement applies to link sharing,
|
|
570
|
+
not unrelated `q.scope()` columns. Multiple placement scopes on one shared
|
|
571
|
+
table are currently rejected.
|
|
572
|
+
- Apply the generated trigger migration before serving link routes. Object
|
|
573
|
+
deletion (soft or hard), identity/organization/scope reassignment, and parent
|
|
574
|
+
deletion remove the affected links and tuples. Restoring a soft-deleted row
|
|
575
|
+
or inserting a replacement with the same ID does not revive old tokens or
|
|
576
|
+
cookies. Cleanup also removes incoming object/userset references, plus
|
|
577
|
+
generic tuples for a parent's mapped child objects even when those tuples
|
|
578
|
+
have no scope placement metadata.
|
|
579
|
+
- Cleanup runs in compiler-owned D1 SQL triggers in the same statement as the
|
|
580
|
+
write. It covers generated CRUD, batch, scoped custom writes, imports and raw
|
|
581
|
+
SQL, including writes without `.returning()` and with audit fields disabled.
|
|
582
|
+
A cleanup failure aborts the originating statement; earlier successful
|
|
583
|
+
statements in a nontransactional batch retain the usual partial-success
|
|
584
|
+
semantics. Minting validates the live object and parent and creates its
|
|
585
|
+
primary tuple in one insert statement, so concurrent deletion cannot leave
|
|
586
|
+
a usable late grant. A racing missing target returns 404; other integrity
|
|
587
|
+
failures abort minting without returning a token.
|
|
588
|
+
- Directly disabling/dropping the compiler-owned triggers or restoring old
|
|
589
|
+
link/tuple data bypasses this lifecycle contract. Existing stale grants from
|
|
590
|
+
before this migration cannot be distinguished from intentional grants;
|
|
591
|
+
revoke them before upgrading if their object IDs may already have been reused.
|
|
592
|
+
- `link` subjects compile on **Cloudflare D1 only**. On Postgres the compile
|
|
593
|
+
fails: a link principal carries no RLS claims yet, so its queries would run
|
|
594
|
+
without the row-level backstop. `user:*` share links work on every database.
|
|
595
|
+
|
|
317
596
|
- `access: { fga }` covers **per-record** operations (`GET /:id`, `update`,
|
|
318
597
|
`delete`, record-based actions) and **collection filtering** on
|
|
319
598
|
`read.access` / views (see
|
|
@@ -323,8 +602,7 @@ access, even if it was written out-of-band — the model is the ceiling.
|
|
|
323
602
|
- **Collection filtering is bounded** by `authz.fga.listObjects.maxIds`
|
|
324
603
|
(default 1000). A caller authorized for more rows than the cap gets a hard
|
|
325
604
|
**422 `FGA_LIST_TOO_LARGE`**, not a partial page — paginate via
|
|
326
|
-
`POST /fga/v1/list-objects` for those cases.
|
|
327
|
-
shapes are filtered; deeper nesting is a compile error.
|
|
605
|
+
`POST /fga/v1/list-objects` for those cases.
|
|
328
606
|
- **Conditional tuples** (CEL conditions / ABAC) are **not supported, and fail
|
|
329
607
|
closed**. The tuple table reserves `condition_name` / `condition_context`, but
|
|
330
608
|
there is no CEL evaluator — so a tuple carrying a condition is treated as
|
|
@@ -380,6 +380,10 @@ When `equals` references the request context, use these standard sources:
|
|
|
380
380
|
| `ctx.scope.<kind>` / `ctx.scope.<kind>.<subKey>` | A verified scope-principal claim (see [Scopes](/define/scopes)) |
|
|
381
381
|
| `ctx.<claim>.<subKey>` | A [feature-area](/define/areas) context anchor — a row the area/relationship middleware loaded from a proven route param and exposed on `ctx` (e.g. `ctx.event.id`, `ctx.event.organizationId`). Present only on the area-claimed route; renders null-safe (deny-when-absent) inside `all`/`any` groups |
|
|
382
382
|
|
|
383
|
+
`ctx.activeOrgId` is an **org membership** claim: it comes from the caller's session or token, never from a row. A relationship lane or namespace gate that matches an attendee's guest row does not set it, so an `organizationId = ctx.activeOrgId` arm never admits a non-member to the organization's rows. Reach those callers with an arm that names them (`ctx.scope.<kind>`, `via:`, `ctx.<claim>.<subKey>`). See [Relationships](/define/relationships#standalone-actions-surface-keys-and-loads--exposeas).
|
|
384
|
+
|
|
385
|
+
With [`tenancy.isolation: 'durable-object'`](/configure/tenant-databases#tenant-ownership), every tenant table's firewall also gets a compiler-owned pin, `organizationId = ctx.tenantId`, ANDed in front of yours. `ctx.tenantId` is the organization the tenant object serves, set from the object's own name. A firewall that names `ctx.tenantId` itself is a compile error.
|
|
386
|
+
|
|
383
387
|
These values are populated by the auth middleware (or, for scope/area anchors, the area middleware) from the request. Any predicate where `equals` starts with `ctx.` is treated as server-derived: the column lands in `GUARDS_CONFIG.systemManaged` (clients cannot submit it) and is **auto-populated on create / changeset-root insert / upsert** from that context source — a raw-Drizzle selected-event fence like `{ field: 'eventId', equals: 'ctx.event.id' }` stamps `eventId` from `ctx.event.id` the same way `q.scope('organization')` stamps `organizationId`.
|
|
384
388
|
|
|
385
389
|
**Only conjunctive arms auto-populate.** A `ctx.*`-bound column is auto-populated only when its arm is **conjunctive** — reachable through the top-level array or a nested `all:` group, so it holds for every admitted row. A column bound *only* through an `any:` branch is disjunctive and lane-dependent (e.g. an attendee's own `eventPersonId`, which must come from a **proven** scope claim, not the org lane), so the compiler does **not** guess a create value for it. Give such a column its own population source — declare it with [`q.scope()` / `q.stamp()`](/define/schema#qstamp--proven-principal-identity-columns) (a proven-identity column force-stamps from the scope claim), let it inherit through a changeset `inherit`/`fk`, or write it in an authored action. A `NOT NULL` disjunctive-only column with none of these has no create path and will hit the database `NOT NULL` constraint on insert.
|
|
@@ -284,6 +284,7 @@ Beyond the five security layers, `defineTable` accepts a handful of declarative
|
|
|
284
284
|
| `embeddings` | Auto-generate vector embeddings for specified fields on insert/update. | [Stack → Embeddings](/platform/vector/using-embeddings) |
|
|
285
285
|
| `realtime` | Per-table broadcast config (`enabled`, `onInsert`, `onUpdate`, `onDelete`, `requiredRoles`, `fields`). | [Stack → Realtime](/platform/realtime/using-realtime) |
|
|
286
286
|
| `path` | Override the route base path (defaults to feature name). | — |
|
|
287
|
+
| `legacy` | `{ deprecated, sunset, path? }` on a table a namespace claims: keeps its pre-claim URL serving as a deprecated forward to the namespace route, for org members only. | [Keeping the old URL](/define/areas#keeping-the-old-url-legacy) |
|
|
287
288
|
|
|
288
289
|
All options are optional — omit them and Quickback uses sensible defaults (auto-detected display column, auto-grouped layout, no embeddings, no realtime).
|
|
289
290
|
|
|
@@ -105,6 +105,10 @@ interface ReadConfig {
|
|
|
105
105
|
views?: {
|
|
106
106
|
[viewName: string]: ViewConfig;
|
|
107
107
|
};
|
|
108
|
+
|
|
109
|
+
// Mount the generated read routes (GET /, GET /:id, GET /views/*).
|
|
110
|
+
// Default true. See "Tables only your actions read" below.
|
|
111
|
+
routes?: boolean;
|
|
108
112
|
}
|
|
109
113
|
|
|
110
114
|
interface ViewConfig {
|
|
@@ -115,6 +119,41 @@ interface ViewConfig {
|
|
|
115
119
|
}
|
|
116
120
|
```
|
|
117
121
|
|
|
122
|
+
## Tables only your actions read (`routes: false`)
|
|
123
|
+
|
|
124
|
+
`read: { routes: false }` keeps `read.access` declared but mounts **no**
|
|
125
|
+
generated read route: no `GET /`, `GET /:id` or `GET /views/*`, and none in
|
|
126
|
+
OpenAPI or MCP. The schema registry lists `read` in the table's
|
|
127
|
+
`routesDisabled` (the bundled CMS still lists the table; its rows then fail to
|
|
128
|
+
load). Another table cannot `?include=` it either: that fails the build. It is
|
|
129
|
+
the read twin of `create` / `update` / `delete` `routes: false`. Realtime
|
|
130
|
+
broadcasts of the table, if it has `realtime` on, still go to whoever
|
|
131
|
+
`read.access` admits, so leave realtime off on such tables.
|
|
132
|
+
|
|
133
|
+
Use it for tables your own actions read and filter: operator ledgers, job
|
|
134
|
+
state, export and restore records. Access rules do not keep a sysadmin out: a
|
|
135
|
+
`sysadmin` session passes every rule, `roles: ['INTERNAL']` included, so a
|
|
136
|
+
mounted read route on such a table is readable by any sysadmin, outside any
|
|
137
|
+
Cloudflare Access gate on your operator paths.
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
import { feature, q } from "@quickback/compiler";
|
|
141
|
+
|
|
142
|
+
export default feature("data_exports", {
|
|
143
|
+
columns: {
|
|
144
|
+
id: q.id(),
|
|
145
|
+
organizationId: q.scope("organization"),
|
|
146
|
+
...q.audit(),
|
|
147
|
+
...q.softDelete(),
|
|
148
|
+
},
|
|
149
|
+
firewall: { organization: {} },
|
|
150
|
+
read: { access: { roles: ["INTERNAL"] }, routes: false },
|
|
151
|
+
create: { access: { roles: ["INTERNAL"] }, routes: false },
|
|
152
|
+
update: { access: { roles: ["INTERNAL"] }, routes: false },
|
|
153
|
+
delete: { access: { roles: ["INTERNAL"] }, routes: false },
|
|
154
|
+
});
|
|
155
|
+
```
|
|
156
|
+
|
|
118
157
|
## Access Ordering on `/:id`
|
|
119
158
|
|
|
120
159
|
Single-record `GET /:id` evaluates checks in this order to close the
|
|
@@ -158,11 +158,13 @@ The resolver:
|
|
|
158
158
|
|
|
159
159
|
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.
|
|
160
160
|
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 soft-delete predicates AND-applied — **not** its tenant scope (a cross-tenant attendee has no `activeOrgId` to match; see [Firewall — relationships](/define/firewall#relationship-based-scoping-via) for the two invariants that make the row trustworthy instead: FK integrity on `resource.column`, and write-gating on the relationship table). If neither role nor relationship qualifies → 403.
|
|
161
|
-
3. **
|
|
162
|
-
4. **Firewall-gated load of the loaded resource** — `SELECT * FROM events WHERE id = :eventId AND buildEventsFirewallConditions(
|
|
161
|
+
3. **No tenant stamping from the matched row.** `ctx.activeOrgId` and `ctx.activeTeamId` are never set from a relationship row. An `organizationId = ctx.activeOrgId` (or `teamId = ctx.activeTeamId`) firewall arm means *membership*: stamping the attendee's row org or team would make every such arm admit the whole organization's — or team's — rows (every other event's guests, staff and notes) to a caller who is not a member.
|
|
162
|
+
4. **Firewall-gated load of the loaded resource** — `SELECT * FROM events WHERE id = :eventId AND buildEventsFirewallConditions(…, db)`. The events firewall is applied as normal. For a caller with no active organization (or team), this one load evaluates the firewall with the matched row's `organizationId` (or `teamId`) — pinned to the one instance by its id, and never kept on `ctx`.
|
|
163
163
|
5. Assigns the loaded row to `ctx.event` for the action body.
|
|
164
164
|
|
|
165
|
-
**What each query enforces.** The relationship match applies the `from` table's soft-delete only; the loaded resource runs under its full firewall, bound to the
|
|
165
|
+
**What each query enforces.** The relationship match applies the `from` table's soft-delete only; the loaded resource runs under its full firewall, bound to the matched row's tenant — so a relationship row can only open an instance in its own tenant. The relationship row's existence is the proof that the caller is authorized; its tenant column binds the one instance it opens. That makes the row's integrity load-bearing: declare `resource.column` as a foreign key and guard it against update (`guards: { immutable: ['eventId'] }`), and gate who may write the relationship table as tightly as the access it confers.
|
|
166
|
+
|
|
167
|
+
**After the gate, rows come from the arms that name the caller.** Inside `execute()`, the scoped `db` and every CRUD route see an attendee as what it is: no active organization, a hydrated `ctx.event`, and (after the [scope refresh](/define/scopes)) `ctx.scope.event`. A table whose firewall is org-only returns nothing to it (`403 FIREWALL_CLAIM_MISSING` from the scoped `db`, and the [`db` type gate](/define/actions/scoped-db#caught-at-compile-time) refuses the statement at compile time in a namespace with relationship lanes). Give the tables an attendee should read an arm that names it — `firewall: { any: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }, { field: 'eventId', equals: 'ctx.scope.event' }] }` — or read the instance's org from `ctx.event.organizationId` and pin by it explicitly.
|
|
166
168
|
|
|
167
169
|
### Conditional tenant preconditions
|
|
168
170
|
|
|
@@ -173,28 +175,28 @@ if (!ctx.activeOrgId) return c.json(AccessErrors.noOrg(), 403);
|
|
|
173
175
|
if (!ctx.activeTeamId) return c.json(AccessErrors.noTeam(), 403);
|
|
174
176
|
```
|
|
175
177
|
|
|
176
|
-
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
|
|
178
|
+
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 binds the loaded instance to that row's tenant. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / SYSADMIN) and `firewall: { exception: true }` also bypass the preconditions. `ADMIN` is rejected at compile time.
|
|
177
179
|
|
|
178
|
-
Typical event-attendee setup (`guests` table carries `organizationId`): the org precondition is dropped on every action whose access references `attendee` or `eventStaff`. Org admins
|
|
180
|
+
Typical event-attendee setup (`guests` table carries `organizationId`): the org precondition is dropped on every action whose access references `attendee` or `eventStaff`. Org admins get `ctx.activeOrgId` from their session. Attendees get no `ctx.activeOrgId` — they reach rows through `ctx.event` and the scope arms that name them.
|
|
179
181
|
|
|
180
182
|
### Requirement on the relationship's `from` table
|
|
181
183
|
|
|
182
|
-
For tenant
|
|
184
|
+
For the tenant binding to work, the relationship's `from` table must carry tenant columns:
|
|
183
185
|
|
|
184
|
-
- For org
|
|
185
|
-
- For team
|
|
186
|
+
- For the org binding (skipping the org precondition, binding the loaded instance): an `organizationId` column (or whatever spelling the project's auth-provider defaults pick).
|
|
187
|
+
- For the team binding: a `teamId` column.
|
|
186
188
|
|
|
187
189
|
When the `from` table has **neither**, the compiler emits a `[quickback:authz]` warning at compile time:
|
|
188
190
|
|
|
189
191
|
```
|
|
190
192
|
Relationship "X" at authz.relationships.X has no organization or team columns
|
|
191
193
|
on its `from` table ("guests"). Action "Y" will compile, but downstream
|
|
192
|
-
scoped-db queries inside execute() may 403 because
|
|
193
|
-
|
|
194
|
-
|
|
194
|
+
scoped-db queries inside execute() may 403 because the match row supplies
|
|
195
|
+
no organization or team. Either add the tenant column to "guests", or set
|
|
196
|
+
firewall: { exception: true } on the action.
|
|
195
197
|
```
|
|
196
198
|
|
|
197
|
-
The relationship match still works (existence check), but no tenant
|
|
199
|
+
The relationship match still works (existence check), but no tenant can be read from it — so the conventional precondition still fires and the action still 403s for callers without a session-resident tenant claim. Add the tenant column (or denormalize it onto the relationship table during writes) to enable the binding.
|
|
198
200
|
|
|
199
201
|
The body can then trust `ctx.event` and drop the hand-rolled `SELECT … FROM guests WHERE …` boilerplate:
|
|
200
202
|
|
|
@@ -355,6 +357,22 @@ The validator and resolver reject:
|
|
|
355
357
|
- `+` hierarchy suffix on a relationship-role name (terminal, like pseudo-roles).
|
|
356
358
|
- Relationship-backed rules in `masking.show` (use a relationship-gated view
|
|
357
359
|
for field projection; action access is fully supported).
|
|
360
|
+
- With [`tenancy.isolation: 'durable-object'`](/configure/tenant-databases#admission-tables-stay-on-the-platform),
|
|
361
|
+
a relationship whose tables live in tenant objects, when anything but a
|
|
362
|
+
[tenant-backed scope kind](/configure/tenant-databases#tenant-backed-scope-kinds), its
|
|
363
|
+
[tenant namespace](/configure/tenant-databases#tenant-namespaces) or its ticket reads it
|
|
364
|
+
from the edge (`TENANCY_ADMISSION_DEPENDENCY`). A scope kind's relationships are
|
|
365
|
+
tenant-backed together with its instance table, in one unpartitioned tenant
|
|
366
|
+
object, each `from` table with an organization column, no `hops` and no SQL
|
|
367
|
+
helper ([full list](/configure/tenant-databases#which-kinds-can-be-tenant-backed)).
|
|
368
|
+
A namespace's lanes, `loads` tables and claimed routes run where its tables
|
|
369
|
+
live: all in the organization object (the gate then runs in the tenant
|
|
370
|
+
Worker) or all on the platform (`TENANCY_NAMESPACE_SPLIT`,
|
|
371
|
+
`TENANCY_NAMESPACE_PARTITIONED`, `TENANCY_NAMESPACE_UNROUTED`).
|
|
372
|
+
- An OAuth scope kind with two or more user-provable relationship roles and no
|
|
373
|
+
[`precedence`](/define/scopes#subject-precedence)
|
|
374
|
+
(`SCOPE_OAUTH_PRECEDENCE_REQUIRED`), or whose namespace `via` lanes are in
|
|
375
|
+
another order (`SCOPE_PRECEDENCE_LANE_CONFLICT`).
|
|
358
376
|
|
|
359
377
|
|
|
360
378
|
## Outgrown this?
|
|
@@ -462,6 +462,8 @@ export default {
|
|
|
462
462
|
};
|
|
463
463
|
```
|
|
464
464
|
|
|
465
|
+
On Postgres with Better Auth, `namingConvention: 'camelCase'` fails the compile. Better Auth then camel-cases its own tables and columns (`userId`, `organizationId`), and the generated RLS policies on those tables name them in snake_case. Keep `snake_case`, or set `compiler.securityContracts.skipManagedTables: true` and ship your own RLS for the Better Auth tables.
|
|
466
|
+
|
|
465
467
|
For one-off overrides on a specific column, pass an explicit name as the positional argument:
|
|
466
468
|
|
|
467
469
|
```ts
|