@quickback-dev/cli 0.70.27 → 0.70.38
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/codex/AGENTS.md +290 -0
- package/dist/commands/build.d.ts +12 -0
- package/dist/commands/build.d.ts.map +1 -1
- package/dist/commands/build.js +69 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/build.test.d.ts.map +1 -0
- package/dist/commands/codex.d.ts +16 -0
- package/dist/commands/codex.d.ts.map +1 -0
- package/dist/commands/codex.js +159 -0
- package/dist/commands/codex.js.map +1 -0
- package/dist/commands/compile.d.ts +62 -0
- package/dist/commands/compile.d.ts.map +1 -0
- package/dist/commands/compile.js +830 -0
- package/dist/commands/compile.js.map +1 -0
- package/dist/commands/compile.test.d.ts.map +1 -0
- package/dist/commands/deploy.d.ts +9 -0
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +20 -2
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/init.d.ts +6 -0
- package/dist/commands/init.d.ts.map +1 -0
- package/dist/commands/init.js +405 -0
- package/dist/commands/init.js.map +1 -0
- package/dist/commands/migrate-data.d.ts +12 -0
- package/dist/commands/migrate-data.d.ts.map +1 -0
- package/dist/commands/migrate-data.js +134 -0
- package/dist/commands/migrate-data.js.map +1 -0
- package/dist/commands/migrate.d.ts.map +1 -1
- package/dist/commands/migrate.js +11 -0
- package/dist/commands/migrate.js.map +1 -1
- package/dist/commands/migrate.test.d.ts.map +1 -0
- package/dist/commands/migrations.test.d.ts.map +1 -0
- package/dist/commands/push.test.d.ts.map +1 -0
- package/dist/commands/schema.test.d.ts.map +1 -0
- package/dist/commands/secrets.d.ts +27 -0
- package/dist/commands/secrets.d.ts.map +1 -0
- package/dist/commands/secrets.js +186 -0
- package/dist/commands/secrets.js.map +1 -0
- package/dist/docs/content.d.ts +7 -0
- package/dist/docs/content.d.ts.map +1 -0
- package/dist/docs/content.js +672 -0
- package/dist/docs/content.js.map +1 -0
- package/dist/docs/index.test.d.ts.map +1 -0
- package/dist/index.js +23 -3
- package/dist/index.js.map +1 -1
- package/dist/lib/access-manifest-diff.d.ts +87 -0
- package/dist/lib/access-manifest-diff.d.ts.map +1 -0
- package/dist/lib/access-manifest-diff.js +331 -0
- package/dist/lib/access-manifest-diff.js.map +1 -0
- package/dist/lib/action-harvest.test.d.ts.map +1 -0
- package/dist/lib/api-client.test.d.ts.map +1 -0
- package/dist/lib/artifact-routing.d.ts.map +1 -1
- package/dist/lib/artifact-routing.js +3 -0
- package/dist/lib/artifact-routing.js.map +1 -1
- package/dist/lib/artifact-routing.test.d.ts.map +1 -0
- package/dist/lib/auth.test.d.ts.map +1 -0
- package/dist/lib/compile-next-steps.test.d.ts.map +1 -0
- package/dist/lib/compiler-floor.test.d.ts.map +1 -0
- package/dist/lib/compiler-stubs.d.ts +2 -0
- package/dist/lib/compiler-stubs.d.ts.map +1 -1
- package/dist/lib/compiler-stubs.js +2 -0
- package/dist/lib/compiler-stubs.js.map +1 -1
- package/dist/lib/config-id-splice.test.d.ts.map +1 -0
- package/dist/lib/config-sync.test.d.ts.map +1 -0
- package/dist/lib/copy-public-assets.test.d.ts.map +1 -0
- package/dist/lib/copy-source-apps.test.d.ts.map +1 -0
- package/dist/lib/drizzle-meta-routing.test.d.ts.map +1 -0
- package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +1 -0
- package/dist/lib/file-loader.d.ts +6 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +17 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.d.ts.map +1 -0
- package/dist/lib/file-writer.test.d.ts.map +1 -0
- package/dist/lib/helpers.d.ts +39 -0
- package/dist/lib/helpers.d.ts.map +1 -0
- package/dist/lib/helpers.js +299 -0
- package/dist/lib/helpers.js.map +1 -0
- package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +1 -0
- package/dist/lib/migrations/drizzle.test.d.ts.map +1 -0
- package/dist/lib/migrations/executor.test.d.ts.map +1 -0
- package/dist/lib/migrations/inventory.test.d.ts.map +1 -0
- package/dist/lib/migrations/lock.test.d.ts.map +1 -0
- package/dist/lib/migrations/paths.test.d.ts.map +1 -0
- package/dist/lib/migrations/plan.test.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/index.test.d.ts.map +1 -0
- package/dist/lib/migrations/prompt-runner.test.d.ts.map +1 -0
- package/dist/lib/migrations/staging.test.d.ts.map +1 -0
- package/dist/lib/neon-canary.test.d.ts.map +1 -0
- package/dist/lib/neon-target.test.d.ts.map +1 -0
- package/dist/lib/neon.test.d.ts.map +1 -0
- package/dist/lib/ops-manifest.d.ts +76 -0
- package/dist/lib/ops-manifest.d.ts.map +1 -0
- package/dist/lib/ops-manifest.js +94 -0
- package/dist/lib/ops-manifest.js.map +1 -0
- package/dist/lib/prepare-output.test.d.ts.map +1 -0
- package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
- package/dist/lib/release-and-pin.d.ts +34 -0
- package/dist/lib/release-and-pin.d.ts.map +1 -0
- package/dist/lib/release-and-pin.js +71 -0
- package/dist/lib/release-and-pin.js.map +1 -0
- package/dist/lib/schema-sync/index.test.d.ts.map +1 -0
- package/dist/lib/shell.d.ts +4 -1
- package/dist/lib/shell.d.ts.map +1 -1
- package/dist/lib/shell.js +8 -3
- package/dist/lib/shell.js.map +1 -1
- package/dist/lib/shell.test.d.ts.map +1 -0
- package/dist/lib/sweep-stale.d.ts +25 -0
- package/dist/lib/sweep-stale.d.ts.map +1 -0
- package/dist/lib/sweep-stale.js +179 -0
- package/dist/lib/sweep-stale.js.map +1 -0
- package/dist/lib/sweep-stale.test.d.ts.map +1 -0
- package/dist/lib/wrangler-resources.test.d.ts.map +1 -0
- package/dist/skill/docs/api/actions.md +2 -0
- package/dist/skill/docs/api/batch-operations.md +18 -4
- package/dist/skill/docs/api/crud.md +62 -0
- package/dist/skill/docs/api/errors.md +17 -2
- package/dist/skill/docs/configure/auth.md +49 -2
- package/dist/skill/docs/configure/bindings.md +15 -0
- package/dist/skill/docs/configure/domains.md +4 -0
- package/dist/skill/docs/configure/index.md +29 -11
- package/dist/skill/docs/configure/providers.md +1 -0
- package/dist/skill/docs/configure/tenancy.md +117 -0
- package/dist/skill/docs/define/access.md +19 -0
- package/dist/skill/docs/define/actions/access.md +76 -0
- package/dist/skill/docs/define/actions/defining.md +156 -1
- package/dist/skill/docs/define/actions/scoped-db.md +236 -9
- package/dist/skill/docs/define/areas.md +46 -0
- package/dist/skill/docs/define/authz-roles.md +10 -0
- package/dist/skill/docs/define/diagnostics.md +263 -0
- package/dist/skill/docs/define/encryption.md +34 -2
- package/dist/skill/docs/define/guards.md +13 -0
- package/dist/skill/docs/define/masking.md +77 -3
- package/dist/skill/docs/define/rate-limit.md +3 -3
- package/dist/skill/docs/define/schema.md +148 -7
- package/dist/skill/docs/define/scopes.md +79 -0
- package/dist/skill/docs/define/sealed-protocol.md +111 -9
- package/dist/skill/docs/define/transitions.md +39 -0
- package/dist/skill/docs/define/views.md +77 -3
- package/dist/skill/docs/platform/api-contract/index.md +4 -0
- package/dist/skill/docs/platform/auth/jwt-optimization.md +2 -0
- package/dist/skill/docs/platform/auth/plugins/aws-ses.md +4 -3
- package/dist/skill/docs/platform/auth/using-auth.md +6 -0
- package/dist/skill/docs/platform/database/d1.md +47 -0
- package/dist/skill/docs/platform/database/data-migrations.md +109 -0
- package/dist/skill/docs/platform/database/index.md +1 -0
- package/dist/skill/docs/platform/database/read-replication.md +257 -0
- package/dist/skill/docs/platform/database/using-d1.md +2 -1
- package/dist/skill/docs/platform/payments/one-off-checkout.md +6 -1
- package/dist/skill/docs/platform/push/index.md +2 -0
- package/dist/skill/docs/platform/realtime/partyserver-rooms.md +95 -9
- package/dist/skill/docs/platform/storage/using-r2.md +135 -19
- package/dist/skill/docs/start/deploy.md +38 -0
- package/dist/skill/docs/tooling/cli.md +120 -0
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +13 -13
- package/dist/skill/docs/tooling/output.md +70 -2
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +2 -0
- package/src/skill/docs/api/batch-operations.md +18 -4
- package/src/skill/docs/api/crud.md +62 -0
- package/src/skill/docs/api/errors.md +17 -2
- package/src/skill/docs/configure/auth.md +49 -2
- package/src/skill/docs/configure/bindings.md +15 -0
- package/src/skill/docs/configure/domains.md +4 -0
- package/src/skill/docs/configure/index.md +29 -11
- package/src/skill/docs/configure/providers.md +1 -0
- package/src/skill/docs/configure/tenancy.md +117 -0
- package/src/skill/docs/define/access.md +19 -0
- package/src/skill/docs/define/actions/access.md +76 -0
- package/src/skill/docs/define/actions/defining.md +156 -1
- package/src/skill/docs/define/actions/scoped-db.md +236 -9
- package/src/skill/docs/define/areas.md +46 -0
- package/src/skill/docs/define/authz-roles.md +10 -0
- package/src/skill/docs/define/diagnostics.md +263 -0
- package/src/skill/docs/define/encryption.md +34 -2
- package/src/skill/docs/define/guards.md +13 -0
- package/src/skill/docs/define/masking.md +77 -3
- package/src/skill/docs/define/rate-limit.md +3 -3
- package/src/skill/docs/define/schema.md +148 -7
- package/src/skill/docs/define/scopes.md +79 -0
- package/src/skill/docs/define/sealed-protocol.md +111 -9
- package/src/skill/docs/define/transitions.md +39 -0
- package/src/skill/docs/define/views.md +77 -3
- package/src/skill/docs/platform/api-contract/index.md +4 -0
- package/src/skill/docs/platform/auth/jwt-optimization.md +2 -0
- package/src/skill/docs/platform/auth/plugins/aws-ses.md +4 -3
- package/src/skill/docs/platform/auth/using-auth.md +6 -0
- package/src/skill/docs/platform/database/d1.md +47 -0
- package/src/skill/docs/platform/database/data-migrations.md +109 -0
- package/src/skill/docs/platform/database/index.md +1 -0
- package/src/skill/docs/platform/database/read-replication.md +257 -0
- package/src/skill/docs/platform/database/using-d1.md +2 -1
- package/src/skill/docs/platform/payments/one-off-checkout.md +6 -1
- package/src/skill/docs/platform/push/index.md +2 -0
- package/src/skill/docs/platform/realtime/partyserver-rooms.md +95 -9
- package/src/skill/docs/platform/storage/using-r2.md +135 -19
- package/src/skill/docs/start/deploy.md +38 -0
- package/src/skill/docs/tooling/cli.md +120 -0
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +13 -13
- package/src/skill/docs/tooling/output.md +70 -2
|
@@ -60,6 +60,7 @@ compile.
|
|
|
60
60
|
| `AUTHZ_NOT_OVER_RESOURCE` | warn | A `not` whose operand resolves to a **resource (SQL) site** — `NOT EXISTS` over a nullable join can silently pass (the null-trap). The site resolution is conservative, so this stays advisory. |
|
|
61
61
|
| `AUTHZ_RECORD_PREDICATE_NOT_ON_LIST` | warn | A **constant** `read.access.record` predicate (`status: { equals: "published" }`, `id: { equals: "never" }`). `access.record` runs against a loaded row on `GET /:id` only — `GET /`, `POST /batch`, and the MCP list tool stop at the role gate, so the rows still list. Omit `read` to hide a resource; use the firewall to filter. `$ctx`-relative predicates are the per-record shape and stay silent. |
|
|
62
62
|
| `AUTHZ_PUSHDOWN_COST` | info | Per-permission report: how many SQL subqueries the permission lowers to, plus the max recursive-CTE depth. Advisory, never fails a build. |
|
|
63
|
+
| `AUTHZ_ROOM_ACCESS_INHERITED` | warn | A resource-backed [realtime room](/platform/realtime/partyserver-rooms#room-roles) with no `access.roles` (connections gated on the table's CRUD `read.access`, so narrowing the room means narrowing CRUD reads) or no `access.writeRoles` (every admitted caller may write). Declare both on the binding. Printed while the config is checked, before the analyzer runs, so `QUICKBACK_AUTHZ_STRICT` does not promote it and there is nothing to override. |
|
|
63
64
|
|
|
64
65
|
A few codes are reserved in the diagnostic enum for the milestones that emit
|
|
65
66
|
them and don't fire on a shipped config today: `AUTHZ_UNBOUNDED_RECURSION`
|
|
@@ -102,6 +103,65 @@ surface is separately guarded today by the IR's unbound-route invariant — a
|
|
|
102
103
|
hard error that predates this promotion and owns that surface; one subject,
|
|
103
104
|
one error.)
|
|
104
105
|
|
|
106
|
+
## Schema and config codes
|
|
107
|
+
|
|
108
|
+
These read the lowered project — each table's resolved create/update field
|
|
109
|
+
sets, its firewall arms, `authz.relationships`, and each action's access —
|
|
110
|
+
and flag the shapes that silently skip a security mechanism Quickback
|
|
111
|
+
already has. They run on every compile.
|
|
112
|
+
|
|
113
|
+
| Code | Default | What it catches | Opt-out |
|
|
114
|
+
|---|---|---|---|
|
|
115
|
+
| `SCHEMA_UNDECLARED_FK` | **error** | A `*Id` / `*_id` column that names a feature table in the same database (`eventId` → `events` or `event`), is client-writable (in the effective `createable` / `updatable` set) **or** sits in a firewall or `authz.relationships` arm, and declares no [`.references()`](/define/schema#references). Without it no [firewalled FK check](/define/firewall#foreign-key-referential-checks) runs, so a caller can point the row at another tenant's parent. Never fires for auth-owned ids (`userId`, `ownerId`, `organizationId`, `teamId`, `memberId`, audit ids) or when no matching feature table exists. | `references: { eventId: { references: false, reason: '…' } }` in `defineTable` |
|
|
116
|
+
| `SCHEMA_FK_MATCH_REQUIRED` | warn | A declared FK where the child **and** its target both carry an org column, with no [`match`](/define/schema#match-a-referenced-rows-parent) on the org column. A `match` on another parent column counts when that column is itself org-matched. | `references: { eventId: { match: false, reason: '…' } }` in `defineTable` |
|
|
117
|
+
| `SCHEMA_JSON_UNGUARDED` | warn | A JSON column (`q.json`, `json` / `jsonb`) clients can write with no `keys` policy — anyone who may update the row may set every key of the document. | `// quickback-allow SCHEMA_JSON_UNGUARDED: <reason>` in the table file |
|
|
118
|
+
| `ACTION_PUBLIC_WITHOUT_RATELIMIT` | warn | An action whose access admits `PUBLIC` with no explicit [`rateLimit`](/define/rate-limit#actions) (it shares the project-default write bucket, keyed by client IP), or with `rateLimit: false`. | `// quickback-allow ACTION_PUBLIC_WITHOUT_RATELIMIT: <reason>` in the action file |
|
|
119
|
+
|
|
120
|
+
Why two defaults:
|
|
121
|
+
|
|
122
|
+
- `SCHEMA_UNDECLARED_FK` is an **error** because the fix is always
|
|
123
|
+
available (`.references()` works on q-DSL and raw Drizzle columns alike)
|
|
124
|
+
and the gap is a cross-tenant write.
|
|
125
|
+
- `SCHEMA_FK_MATCH_REQUIRED` is a **warning** because `match` can only be
|
|
126
|
+
written on a q-DSL column — on a raw Drizzle table the only way to clear an
|
|
127
|
+
error would be an opt-out that misstates intent — and generated CRUD writes
|
|
128
|
+
already run the firewalled FK check. The remaining gap is action-side
|
|
129
|
+
writes, which the `match` trigger backstops. Under
|
|
130
|
+
`QUICKBACK_AUTHZ_STRICT=true` it, and the other two warnings, fail the
|
|
131
|
+
build.
|
|
132
|
+
|
|
133
|
+
Every opt-out needs a non-empty `reason`. The compiler rejects an opt-out
|
|
134
|
+
without one, a `references` entry it does not recognise, or one naming a
|
|
135
|
+
column the table does not have.
|
|
136
|
+
|
|
137
|
+
{/* doc-compile: skip — excerpt of a defineTable config; `guests` and its columns are elided */}
|
|
138
|
+
```ts
|
|
139
|
+
export default defineTable(guests, {
|
|
140
|
+
references: {
|
|
141
|
+
cventEventId: { references: false, reason: 'Cvent-side id; no row in this database' },
|
|
142
|
+
partnerEventId: { match: false, reason: 'guests may be invited to a partner org event' },
|
|
143
|
+
},
|
|
144
|
+
// ...
|
|
145
|
+
});
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### Migration window
|
|
149
|
+
|
|
150
|
+
The error honours `compiler.securityContracts.failMode`. While you add the
|
|
151
|
+
missing declarations, set it to `'warn'` and every finding prints, marked as
|
|
152
|
+
downgraded, without failing the build:
|
|
153
|
+
|
|
154
|
+
```ts
|
|
155
|
+
export default defineConfig({
|
|
156
|
+
compiler: { securityContracts: { failMode: 'warn' } },
|
|
157
|
+
// ...
|
|
158
|
+
});
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
`failMode: 'warn'` also downgrades the
|
|
162
|
+
[security contract](/tooling/output#security-contract-report-and-signature)
|
|
163
|
+
checks, so treat it as temporary.
|
|
164
|
+
|
|
105
165
|
## The override surface
|
|
106
166
|
|
|
107
167
|
Every promoted finding can be explicitly accepted — per finding, with a
|
|
@@ -156,6 +216,209 @@ A high subquery count or a deep recursive CTE (from a recursive
|
|
|
156
216
|
[arrow](/define/arrows)) is a signal to reconsider the rule —
|
|
157
217
|
not an error, but worth a look.
|
|
158
218
|
|
|
219
|
+
## Source codes
|
|
220
|
+
|
|
221
|
+
The checks above read the policy graph. These read your **authored source**:
|
|
222
|
+
action files, the feature `lib/` files, and the project's `lib/`, `hooks/`,
|
|
223
|
+
`plugins/`, `email-templates/`, and `middlewares/` files. They catch code that
|
|
224
|
+
goes around a pillar instead of through it. The analysis is syntactic (no
|
|
225
|
+
type checker), it runs on every compile, and it renders on the
|
|
226
|
+
`[quickback:source]` channel:
|
|
227
|
+
|
|
228
|
+
```
|
|
229
|
+
[quickback:source] ACTION_RAW_DB_WITHOUT_UNSAFE: action "listMyEvents" reaches a raw database handle (drizzle(env.DB)) without declaring `unsafe` — the firewall does not apply to it and no audit row is written.
|
|
230
|
+
at site=action listMyEvents features/user-profiles/actions/listMyEvents.ts:61:20
|
|
231
|
+
hint: Use the scoped `db`, or declare `unsafe: { reason: "…" }` on the action and use `unsafeDb` (audited).
|
|
232
|
+
opt-out: // quickback-allow ACTION_RAW_DB_WITHOUT_UNSAFE: <reason>
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
| Code | Tier | Scope | What it catches |
|
|
236
|
+
|---|---|---|---|
|
|
237
|
+
| `ACTION_RAW_DB_WITHOUT_UNSAFE` | **error** | action files, and every project file they import | A raw database handle reached by an action with no `unsafe:` declaration. |
|
|
238
|
+
| `ACTION_AUTH_DB_WRITE` | **error** | action files, and every project file they import | An insert, update, or delete against a Better Auth table that does not go through Better Auth. |
|
|
239
|
+
| `ACTION_ROLE_CHECK_IN_BODY` | warn | the `execute` function of action files | A role check written in the handler body instead of in the declared `access`. |
|
|
240
|
+
| `ENV_UNDECLARED` | **error** | every authored file (Cloudflare runtime) | An `env.X` read where nothing declares `X`. |
|
|
241
|
+
| `TEMPLATE_UNESCAPED` | **error** | every authored file | A `${}` value in an HTML template literal that is not escaped. |
|
|
242
|
+
| `SOURCE_ALLOW_INVALID` | **error** | — | A `quickback-allow` directive with no reason, an unknown code, or nothing left to suppress. |
|
|
243
|
+
|
|
244
|
+
"Every project file they import" is transitive. It follows relative imports
|
|
245
|
+
and the `~/` alias through the feature `lib/` and the project `lib/`,
|
|
246
|
+
`hooks/`, and `plugins/` files. A finding in a shared file names the action
|
|
247
|
+
that reached it. Packages from `node_modules` are not followed.
|
|
248
|
+
|
|
249
|
+
### `ACTION_RAW_DB_WITHOUT_UNSAFE`
|
|
250
|
+
|
|
251
|
+
It fires on these, in an action that has no `unsafe:`:
|
|
252
|
+
|
|
253
|
+
- `c.get('db')`
|
|
254
|
+
- a database binding read off the environment: `env.DB`, `c.env.AUTH_DB`,
|
|
255
|
+
`env.HYPERDRIVE`, and so on. That includes `env.DB.prepare(…)`.
|
|
256
|
+
- a drizzle driver import (`drizzle-orm/d1`, `drizzle-orm/postgres-js`, …)
|
|
257
|
+
- a call to `drizzle(…)`, `createDb()`, or `createAuthDb()`
|
|
258
|
+
- `auth.$context` (Better Auth's adapter)
|
|
259
|
+
- the action's own `unsafeDb`. This only fires in the action file. An imported
|
|
260
|
+
helper may receive `unsafeDb` from an `unsafe` caller.
|
|
261
|
+
|
|
262
|
+
**Opt-out:** declare `unsafe: { reason: "…" }` on the action (or `unsafe: true`,
|
|
263
|
+
or `firewall: { exception: true }` on a deliberately unscoped action), so the
|
|
264
|
+
call is audited. See [Unsafe mode](/define/actions/scoped-db#unsafe-mode). A
|
|
265
|
+
`quickback-allow` directive also works when a raw handle is in a shared file
|
|
266
|
+
the action imports but does not call.
|
|
267
|
+
|
|
268
|
+
### `ACTION_AUTH_DB_WRITE`
|
|
269
|
+
|
|
270
|
+
It fires on `.insert(T)`, `.update(T)`, and `.delete(T)` when `T` is:
|
|
271
|
+
|
|
272
|
+
- a table imported from the generated auth schema (`…/auth/schema`,
|
|
273
|
+
`…/auth-schema`), by name or through a namespace (`authSchema.user`,
|
|
274
|
+
`const { member } = authSchema`), or
|
|
275
|
+
- anything, when the receiver is the auth database handle (`authDb`,
|
|
276
|
+
`c.get("authDb")`, `AUTH_DB`).
|
|
277
|
+
|
|
278
|
+
It also fires on raw SQL strings that write a Better Auth table:
|
|
279
|
+
`INSERT INTO <t> (…|VALUES|SELECT)`, `UPDATE <t> SET`, `DELETE FROM <t>
|
|
280
|
+
WHERE`. The table names are `user`, `session`, `account`, `verification`,
|
|
281
|
+
`organization`, `member`, `invitation`, `team`, `teamMember`, `apikey`,
|
|
282
|
+
`passkey`, `twoFactor`, `jwks`, and the subscriptions and OAuth plugin tables,
|
|
283
|
+
under both the singular (D1) and plural (Postgres) spellings. A project table
|
|
284
|
+
with the same name is excluded. Reads are never flagged.
|
|
285
|
+
|
|
286
|
+
The check runs whether or not the action is `unsafe`. `unsafe` lets an action
|
|
287
|
+
read across tenants. It does not let it bypass Better Auth's hooks, session
|
|
288
|
+
revocation, or `qbrev` stamping. Use Better Auth for writes: `auth.api.*` on
|
|
289
|
+
the action's `auth` parameter.
|
|
290
|
+
|
|
291
|
+
**Opt-out:** `// quickback-allow ACTION_AUTH_DB_WRITE: <reason>`.
|
|
292
|
+
|
|
293
|
+
### `ACTION_ROLE_CHECK_IN_BODY`
|
|
294
|
+
|
|
295
|
+
Inside `execute` only, it fires on:
|
|
296
|
+
|
|
297
|
+
- a membership test on a roles array: `ctx.roles.includes(…)`,
|
|
298
|
+
`(ctx.roles ?? []).some(…)`, and `every`, `indexOf`, `find`, `findIndex`,
|
|
299
|
+
`has` on anything named `roles`, `userRoles`, or `memberRoles`.
|
|
300
|
+
- an equality comparison (`===`, `!==`, `==`, `!=`) between a role literal and
|
|
301
|
+
the caller's role. A caller's role is an expression rooted at `ctx` whose
|
|
302
|
+
last name contains `role` (`ctx.userRole`, `ctx.member?.role`), or a bare
|
|
303
|
+
local with such a name (`role`). `input.role` and `row.role` are data and are
|
|
304
|
+
not flagged.
|
|
305
|
+
- `['admin', 'owner'].includes(<caller role>)` and `switch (<caller role>)`
|
|
306
|
+
with role-literal cases.
|
|
307
|
+
|
|
308
|
+
A role literal is `owner`, `admin`, `member`, any name in `auth.roleHierarchy`
|
|
309
|
+
or `authz.roles`, or any role named in any action's `access`.
|
|
310
|
+
|
|
311
|
+
It is a warning: role checks in the body still run. The problem is that the
|
|
312
|
+
declared `access` and the route manifest stop describing who can call the
|
|
313
|
+
action. Move the gate into `access` (an `anyOf` arm per caller class), or name
|
|
314
|
+
the role set once in `authz.roles`.
|
|
315
|
+
|
|
316
|
+
**Opt-out:** `// quickback-allow ACTION_ROLE_CHECK_IN_BODY: <reason>`. Use it
|
|
317
|
+
for response shaping that is not a gate.
|
|
318
|
+
|
|
319
|
+
### `ENV_UNDECLARED`
|
|
320
|
+
|
|
321
|
+
It fires on `env.X`, `(env as any).X`, `env["X"]`, and `const { X } = env`,
|
|
322
|
+
where the environment is `env`, `c.env`, `ctx.env`, or `this.env`.
|
|
323
|
+
`process.env` and `import.meta.env` are not checked. `X` is declared if it is:
|
|
324
|
+
|
|
325
|
+
- a member of the generated `CloudflareBindings` interface (`src/env.d.ts`):
|
|
326
|
+
the compiler's own bindings plus everything under `bindings`, including
|
|
327
|
+
`bindings.vars` and `bindings.secrets`, or
|
|
328
|
+
- provided by the generated `wrangler.toml`: `[vars]` and per-environment
|
|
329
|
+
`[env.<target>.vars]`, every `binding = "…"`, and the
|
|
330
|
+
`[*.secrets] required` lists.
|
|
331
|
+
|
|
332
|
+
This is the same set wrangler deploys with, so an `ENV_UNDECLARED` read is
|
|
333
|
+
`undefined` at runtime unless something outside the config sets it.
|
|
334
|
+
|
|
335
|
+
**Fix:** declare it: `bindings: { secrets: [{ name: "X" }] }` or
|
|
336
|
+
`bindings: { vars: { X: "…" } }`. **Opt-out**, for a value set outside the
|
|
337
|
+
config (for example `wrangler deploy --var`):
|
|
338
|
+
`// quickback-allow ENV_UNDECLARED: <reason>`. On a non-Cloudflare runtime
|
|
339
|
+
the check does not run.
|
|
340
|
+
|
|
341
|
+
### `TEMPLATE_UNESCAPED`
|
|
342
|
+
|
|
343
|
+
A template literal counts as HTML when any of these is true:
|
|
344
|
+
|
|
345
|
+
1. its literal text contains a tag: `<p`, `</div`, `<!DOCTYPE`.
|
|
346
|
+
2. it is passed directly to a function whose name contains `html`
|
|
347
|
+
(`c.html(…)`, `sendHtml(…)`), or bound to a variable, property, or
|
|
348
|
+
assignment target whose name ends in `html` (`html`, `bodyHtml`,
|
|
349
|
+
`innerHTML`; not `htmlR2Key`).
|
|
350
|
+
3. the file is under an `email-templates/` or `templates/` directory, and the
|
|
351
|
+
template is not bound to a name containing `subject`, `text`, or `plain`.
|
|
352
|
+
|
|
353
|
+
Each `${}` value in an HTML template must be one of these:
|
|
354
|
+
|
|
355
|
+
- a call to an escaping function: `esc(…)`, or any name containing `escape`
|
|
356
|
+
or `sanitize` (`escapeHtml`, `escapeAttr`, `sanitizeUrl`)
|
|
357
|
+
- a `.replace` / `.replaceAll` chain whose patterns together cover `&` and `<`
|
|
358
|
+
(`s.replace(/[&<>"']/g, …)`)
|
|
359
|
+
- a template tagged with a tag whose name contains `html`, `escape`, or
|
|
360
|
+
`sanitize` (`` html`…` ``). An escaping tag also exempts the template itself.
|
|
361
|
+
- a literal; arithmetic, comparison, or a unary expression; `x.length`;
|
|
362
|
+
`Number(…)`, `parseInt(…)`, `parseFloat(…)`, `Math.*(…)`, `.toFixed(…)`;
|
|
363
|
+
`encodeURIComponent(…)`, `encodeURI(…)`
|
|
364
|
+
- a nested template, a `cond ? a : b`, `a && b`, `a || b`, `a ?? b`, or
|
|
365
|
+
`a + b` whose parts are all allowed
|
|
366
|
+
- `xs.map(cb).join(…)`, or `[…].join(…)`, where every value `cb` returns
|
|
367
|
+
(or every element) is allowed. `cb` can be an escaping function
|
|
368
|
+
(`.map(escapeHtml)`).
|
|
369
|
+
- a same-file binding whose every value is allowed: a `const`, or a
|
|
370
|
+
`let`/`var` when its initializer and every `=` / `+=` to it in the
|
|
371
|
+
declaring block are allowed
|
|
372
|
+
- a call to a same-file function whose every `return` is allowed. Recursive
|
|
373
|
+
renderers are fine.
|
|
374
|
+
|
|
375
|
+
Anything else is unescaped: function parameters, values imported from another
|
|
376
|
+
module, and property reads such as `input.name`. One finding is reported per
|
|
377
|
+
template and lists the offending values. A helper whose own template is
|
|
378
|
+
reported is not reported again where it is used.
|
|
379
|
+
|
|
380
|
+
**Fix:** escape the value at the interpolation, or build the markup with an
|
|
381
|
+
escaping `html` tag. **Opt-out**, for a value that is already markup (a
|
|
382
|
+
fragment from another module's renderer, a server-built constant):
|
|
383
|
+
`// quickback-allow TEMPLATE_UNESCAPED: <reason>` on the line where the
|
|
384
|
+
template starts, or above it.
|
|
385
|
+
|
|
386
|
+
### Opting out: `quickback-allow`
|
|
387
|
+
|
|
388
|
+
Every source code has the same opt-out: a comment that names the code and
|
|
389
|
+
gives a reason.
|
|
390
|
+
|
|
391
|
+
```ts
|
|
392
|
+
// quickback-allow TEMPLATE_UNESCAPED: badgeSvg is rendered server-side from a fixed icon set
|
|
393
|
+
const badge = `<div class="badge">${input.badgeSvg}</div>`;
|
|
394
|
+
|
|
395
|
+
const showBilling = ctx.roles?.includes("owner"); // quickback-allow ACTION_ROLE_CHECK_IN_BODY: response shaping, not a gate
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
- `// quickback-allow <CODE>: <reason>` covers findings of `<CODE>` on the
|
|
399
|
+
same line or the line below it.
|
|
400
|
+
- `// quickback-allow-file <CODE>: <reason>`, anywhere in a file, covers every
|
|
401
|
+
`<CODE>` finding in that file.
|
|
402
|
+
- `/* … */` comments work too.
|
|
403
|
+
|
|
404
|
+
An allowed finding does not print; the directive in the source is the record.
|
|
405
|
+
`SOURCE_ALLOW_INVALID` (an error) fires when a directive:
|
|
406
|
+
|
|
407
|
+
- has no reason,
|
|
408
|
+
- names an unknown code, or
|
|
409
|
+
- suppresses nothing, because the finding was fixed or the file is outside
|
|
410
|
+
the code's scope. Remove the directive.
|
|
411
|
+
|
|
412
|
+
### Migration window: `failMode: "warn"`
|
|
413
|
+
|
|
414
|
+
Source-code errors fail the compile by default. To adopt them on an existing
|
|
415
|
+
project, set
|
|
416
|
+
[`compiler.securityContracts.failMode`](/configure#security-contract-reports-and-signing) to
|
|
417
|
+
`"warn"`. Every source error, including `SOURCE_ALLOW_INVALID`, then prints as
|
|
418
|
+
a warning marked `downgraded by compiler.securityContracts.failMode = "warn"`,
|
|
419
|
+
and the compile continues. The same switch governs the generated-output
|
|
420
|
+
security contracts. `ACTION_ROLE_CHECK_IN_BODY` is a warning in both modes.
|
|
421
|
+
|
|
159
422
|
## See also
|
|
160
423
|
|
|
161
424
|
- [Permissions](/define/permissions) — the `anyOf` / `allOf` /
|
|
@@ -100,6 +100,38 @@ Two practical notes:
|
|
|
100
100
|
- **Action responses**: rows returned from `db.insert(...).returning()` inside your own actions contain ciphertext — decrypt explicitly with `ctx.crypto.decrypt(value, { table, column })` if your action returns the field. Generated CRUD routes handle this automatically.
|
|
101
101
|
- **No server-side equality lookups** on encrypted values (blind indexes are a roadmap item). If you need to filter by it, it probably shouldn't be encrypted — or it needs a separate non-sensitive derived column.
|
|
102
102
|
|
|
103
|
+
## Secret columns — `q.secret()`
|
|
104
|
+
|
|
105
|
+
Some values are written once and only ever *used* by the server: a third-party client secret, a webhook URL that carries its own token. Nobody — not an admin, not the row's owner — needs to read them back. `q.secret()` is that column kind:
|
|
106
|
+
|
|
107
|
+
```typescript
|
|
108
|
+
export default feature('integrations', {
|
|
109
|
+
columns: {
|
|
110
|
+
id: q.id(),
|
|
111
|
+
organizationId: q.scope('organization'), // required — keys are per-org
|
|
112
|
+
name: q.text().required(),
|
|
113
|
+
clientSecret: q.secret({ maxLength: 500 }),
|
|
114
|
+
...q.audit(),
|
|
115
|
+
...q.softDelete(),
|
|
116
|
+
},
|
|
117
|
+
read: { access: { roles: ['member+'] } },
|
|
118
|
+
create: { access: { roles: ['admin+'] } },
|
|
119
|
+
update: { access: { roles: ['admin+'] } },
|
|
120
|
+
});
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
- **Encrypted at rest** with this envelope tier — same keys, chokepoint, `qbenc:` format, rules, and boot guard as `.encrypted()`.
|
|
124
|
+
- **Never returned.** The compiler gives the column a `masking` rule of `show: 'never'`, so CRUD, views, realtime, and changesets redact it (`[REDACTED]`; `null` stays `null`, so a client can tell whether one is set) for every role, the owner included. The read path does not even decrypt it. A `masking` entry of your own that would reveal it — `false`, or any `show` other than `'never'` — is a compile error.
|
|
125
|
+
- **Writable** through create, update, batch, and actions like any column. Clients send plaintext.
|
|
126
|
+
- **Readable server-side only through [`ctx.unmask(row, column)`](/define/actions/scoped-db#ctxunmask--reading-a-qsecret-column)** inside an action, which opens it with the row's organization key and records a best-effort audit entry. `ctx.crypto.decrypt` refuses secret columns.
|
|
127
|
+
- `.sealed()` and `.array()` on a secret are compile errors.
|
|
128
|
+
|
|
129
|
+
| | Stored as | Who reads plaintext |
|
|
130
|
+
|---|---|---|
|
|
131
|
+
| `.encrypted()` | envelope ciphertext | allowed roles, through every read path (masking composes on top) |
|
|
132
|
+
| `q.secret()` | envelope ciphertext | nobody through a read path; action code through `ctx.unmask` |
|
|
133
|
+
| `.sealed()` | client-sealed ciphertext | only a client holding a granted key — the server never can |
|
|
134
|
+
|
|
103
135
|
---
|
|
104
136
|
|
|
105
137
|
# Sealed tier — end-to-end encryption
|
|
@@ -200,7 +232,7 @@ Behind that one call:
|
|
|
200
232
|
5. **`/seal/v1/key`** (bearer that capability) passes three fail-closed gates — tenant, capability, live-grant — and returns the still-wrapped content key.
|
|
201
233
|
6. The client unwraps the scope key, unwraps the content key, and decrypts. **None of this touches the server with a readable key.**
|
|
202
234
|
|
|
203
|
-
Passkey reveal is the same call as `revealWithPasskey({ ..., getAssertion })`, where `getAssertion(nonce)` runs the WebAuthn ceremony.
|
|
235
|
+
Passkey reveal is the same call as `revealWithPasskey({ ..., getAssertion })`, where `getAssertion(nonce)` runs the WebAuthn ceremony. A PRF-capable passkey can also **replace the passphrase prompt**: the client wraps the passphrase-derived user master under the passkey's PRF output once (`wrapMasterWithPrf`), and from then on a single ceremony both proves the step-up and unlocks the keys (`revealWithPasskey({ ..., prfUnwrap })`). Sign-in passkeys are emitted PRF-capable at creation; native-app origins go in `encryption.seal.extraOrigins`. The derivation and envelope are specified in [Multi-factor unlock (passkey PRF)](/define/sealed-protocol#multi-factor-unlock-passkey-prf).
|
|
204
236
|
|
|
205
237
|
## Rules the compiler enforces
|
|
206
238
|
|
|
@@ -218,7 +250,7 @@ Sealed values are opaque references at rest, so they're fenced off from every su
|
|
|
218
250
|
The sealed tier protects against **full Worker compromise** — leaked secrets, malicious or buggy server code, a coerced operator. All of them get ciphertext; the keys to read it never exist server-side. Its operating model is explicit:
|
|
219
251
|
|
|
220
252
|
- **A reveal needs a real second factor.** The vault passphrase (or passkey) is separate from login and never leaves the client.
|
|
221
|
-
- **Recovery is opt-in and zero-knowledge.** A key admin can enroll a scope key wrapped under a client-held recovery
|
|
253
|
+
- **Recovery is opt-in and zero-knowledge.** A key admin can enroll a scope key wrapped under a client-held recovery factor through `/seal/v1/recovery/enroll` — a recovery code, or (`wrapMethod: 'prf-aesgcm'`) a hardware security key or shared vault passkey, one live row per method; `/recovery/use` returns only those opaque wrapped blobs. If no recovery is enrolled and every reader loses their factor, the data is unrecoverable by design.
|
|
222
254
|
- **Rotation includes re-granting.** `/rotate` versions the scope key and returns the live-reader worklist and public keys so the key-admin client can wrap and grant the new private key without exposing it to the server.
|
|
223
255
|
- **No server-side processing.** Your actions can't read, mask, search, or index a sealed value — it's plaintext only in a client that just revealed it. If the server needs to process the field, you want the envelope tier instead.
|
|
224
256
|
- **Passkey rollout check.** The server verification path and nonce-bound
|
|
@@ -116,6 +116,19 @@ guards: {
|
|
|
116
116
|
|
|
117
117
|
**If a field is not listed anywhere, it cannot be set by the client.**
|
|
118
118
|
|
|
119
|
+
### Keys inside a JSON column
|
|
120
|
+
|
|
121
|
+
Guards work per column. A typed `q.json` column can also give its keys their own write tiers with [`q.json(schema, { keys })`](/define/schema#per-key-write-authority-keys). An `organizer` key follows the column's `createable` / `updatable` entry. A `platform` key is refused by every generic write with **422 `JSON_KEY_RESTRICTED`** (field and key named in `details.fields`), and a PATCH of the column keeps its stored value. Only an action whose caller matched its `access.userRole` lane, or one that lists the key in [`writes:`](/define/actions/defining#json-key-writes-and-requires), may change it. A `derivedFrom` key is never writable.
|
|
122
|
+
|
|
123
|
+
```typescript
|
|
124
|
+
guards: {
|
|
125
|
+
createable: ["name", "settings"], // settings.theme (organizer) is writable here
|
|
126
|
+
updatable: ["name", "settings"], // settings.beta (platform) is not, on either route
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Leaving a JSON column in `updatable` with no `keys` makes every key of it client-writable, so declare `keys` whenever any part of the value is managed by the platform.
|
|
131
|
+
|
|
119
132
|
## System-Managed Fields (Always Protected)
|
|
120
133
|
|
|
121
134
|
`GUARDS_CONFIG.systemManaged` rejects any field in this set from client input — even with `guards: false`. The set always includes the audit fields:
|
|
@@ -58,6 +58,7 @@ It also removes a bug class outright. When detection can never quietly supply a
|
|
|
58
58
|
| :--- | :--- | :--- |
|
|
59
59
|
| `GET /:id`, list, named views, `POST`, `PATCH`, `PUT`, batch | Masked per role | Returned in full |
|
|
60
60
|
| Realtime frames + live-view deltas | Masked per-subscriber-role | Sent in full |
|
|
61
|
+
| Action results declaring [`outputMask`](/define/actions/defining#masking-action-output-outputmask) | Masked per role | Returned in full |
|
|
61
62
|
| `?filter=` / `?sort=` | Only roles in the [query gate](#query-gate-filter--sort--search) | Unrestricted |
|
|
62
63
|
| `?search=` | Dropped from the default searchable set | Searchable |
|
|
63
64
|
| FK display label / `embeddings` / action egress scan | Blocked — see [Egress protection](#egress-protection) | Allowed |
|
|
@@ -214,13 +215,82 @@ masking: {
|
|
|
214
215
|
|
|
215
216
|
```typescript
|
|
216
217
|
show: 'never' | {
|
|
217
|
-
roles?: string[];
|
|
218
|
-
or?: 'owner'
|
|
218
|
+
roles?: string[]; // Unmasked if user has any of these roles
|
|
219
|
+
or?: 'owner' // …OR the user is the record owner
|
|
220
|
+
| { record: { /* … */ } }; // …OR the row's own state matches
|
|
219
221
|
}
|
|
220
222
|
```
|
|
221
223
|
|
|
222
224
|
The `'owner'` condition compares against the owner column declared via `q.scope('owner')` (or auto-detected from a `userId` / `ownerId` column). If no owner scope is present, it falls back to `createdBy`.
|
|
223
225
|
|
|
226
|
+
### Record-state masking
|
|
227
|
+
|
|
228
|
+
Some fields are secret only while the row is in a certain state: a poll's
|
|
229
|
+
voters until the poll closes, a roster entry until the attendee opts into the
|
|
230
|
+
directory. `or: { record: { … } }` reveals the field to every caller who can
|
|
231
|
+
read the row once the row's own columns match — OR'd with `roles`:
|
|
232
|
+
|
|
233
|
+
```typescript
|
|
234
|
+
import { feature, q } from '@quickback/compiler';
|
|
235
|
+
|
|
236
|
+
export default feature('votes', {
|
|
237
|
+
columns: {
|
|
238
|
+
id: q.id(),
|
|
239
|
+
pollId: q.text().required(),
|
|
240
|
+
optionId: q.text().required(),
|
|
241
|
+
voterId: q.text().required(),
|
|
242
|
+
closedAt: q.timestamp().optional(),
|
|
243
|
+
organizationId: q.scope('organization'),
|
|
244
|
+
...q.audit(),
|
|
245
|
+
...q.softDelete(),
|
|
246
|
+
},
|
|
247
|
+
guards: { createable: ['pollId', 'optionId', 'voterId'], updatable: ['closedAt'] },
|
|
248
|
+
masking: {
|
|
249
|
+
// Admins always see the voter; everyone else once the ballot is closed.
|
|
250
|
+
voterId: {
|
|
251
|
+
type: 'redact',
|
|
252
|
+
show: { roles: ['admin'], or: { record: { closedAt: { notNull: true } } } },
|
|
253
|
+
},
|
|
254
|
+
},
|
|
255
|
+
read: { access: { roles: ['member', 'admin'] } },
|
|
256
|
+
create: { access: { roles: ['member', 'admin'] } },
|
|
257
|
+
update: { access: { roles: ['admin'] } },
|
|
258
|
+
delete: { access: { roles: ['admin'] }, mode: 'soft' },
|
|
259
|
+
});
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Conditions are on columns of the **same row**, and several conditions AND
|
|
263
|
+
together:
|
|
264
|
+
|
|
265
|
+
| Condition | Holds when |
|
|
266
|
+
|---|---|
|
|
267
|
+
| `{ notNull: true }` / `{ null: true }` | the column is set / empty |
|
|
268
|
+
| `{ equals: v }` / `{ notEquals: v }` | the column equals / differs from a literal (string, number, boolean) |
|
|
269
|
+
| `{ in: [...] }` / `{ notIn: [...] }` | the column is / is not one of the literals |
|
|
270
|
+
| `{ before: 'now' }` / `{ after: 'now' }` | a timestamp or date column is earlier / later than the request time |
|
|
271
|
+
|
|
272
|
+
It applies everywhere the field is masked, through one evaluator: `GET /:id`,
|
|
273
|
+
lists and named views, write responses, batch, [action
|
|
274
|
+
output](/define/actions/defining#masking-action-output-outputmask), realtime
|
|
275
|
+
frames and live-view deltas. The rule is about the row, not the caller, so
|
|
276
|
+
operands are literals — `$ctx.*` is a compile error (the caller axis is
|
|
277
|
+
`roles` and `or: 'owner'`).
|
|
278
|
+
|
|
279
|
+
It fails closed:
|
|
280
|
+
|
|
281
|
+
- A row whose projection **omits** a condition column never matches, so the
|
|
282
|
+
field stays masked. A named view that projects the field without its
|
|
283
|
+
condition columns is a compile error; a `?fields=` request that drops them
|
|
284
|
+
just gets the masked value.
|
|
285
|
+
- An unknown column or operator, `equals: null`, `before`/`after` on a column
|
|
286
|
+
that is not a timestamp or date, or a value other than `'now'` there is a
|
|
287
|
+
compile error. (`eq` is suggested as `equals`.)
|
|
288
|
+
- A condition on a column that is **itself masked** is a compile error:
|
|
289
|
+
revealing one field whenever another matches would disclose the other.
|
|
290
|
+
- The query gate does not change: `?filter=` / `?sort=` / `?search=` on the
|
|
291
|
+
column still follow `query.roles` (default `show.roles`), whatever state the
|
|
292
|
+
rows are in.
|
|
293
|
+
|
|
224
294
|
### `show: 'never'` — masked for everyone, deliberately
|
|
225
295
|
|
|
226
296
|
```typescript
|
|
@@ -236,6 +306,10 @@ Write `'never'` when nobody is the intent. Any other string is a compile error r
|
|
|
236
306
|
> This does **not** add a `userRole` axis to masking. Gating a mask on Better Auth user roles (`sysadmin`, `appmanager`) is still refused at compile time. `'never'` only lets the deliberate case say so out loud; a mask that wants the same audience as a `userRole`-gated table still has to go through a gated view.
|
|
237
307
|
|
|
238
308
|
|
|
309
|
+
### Masks derived from a realtime room
|
|
310
|
+
|
|
311
|
+
A [realtime room](/platform/realtime/partyserver-rooms#room-roles) whose binding declares `writeRoles` and is keyed by a non-PK column (`access.resource.key`, e.g. `yjsRoomId`) masks that column for you: `{ type: 'redact', show: { roles: <writeRoles> } }`, on every read path above. The binding owns that column's audience, so declaring `masking.<key>` on the table as well is a compile error.
|
|
312
|
+
|
|
239
313
|
### Relationship-aware field projection
|
|
240
314
|
|
|
241
315
|
For relationship-specific field visibility, use a named view gated by the
|
|
@@ -252,7 +326,7 @@ compile-time refusal, never a silently ignored condition or a broader grant.
|
|
|
252
326
|
[Named gates](/define/authz-roles#named-gates-authzrules) (`authz.rules`) follow the same discipline in `show:`:
|
|
253
327
|
|
|
254
328
|
- A **who-only** gate expands like a named role (its flat role list; the owner-gated flat-role constraint above applies).
|
|
255
|
-
- A gate carrying a **`record:`** predicate is a **compile error
|
|
329
|
+
- A gate carrying a **`record:`** predicate is a **compile error**. A gate's record predicate is ANDed with its roles; masking's record dimension is the OR arm [`or: { record }`](#record-state-masking) — the row's state reveals the field on its own — so state the condition there and reference a who-only rule in `show:`.
|
|
256
330
|
- A gate carrying **firewall lanes** is a **compile error** — masking has no firewall array to satisfy, so the gate's row lanes would silently not apply. Reference a who-only rule (or inline the roles) in `show:`, and stamp the firewall gate on the resource's `firewall:` instead.
|
|
257
331
|
|
|
258
332
|
**Supported patterns**, depending on intent:
|
|
@@ -108,7 +108,7 @@ Default-using resources collapse onto two shared bindings (`RL_1000_60`, `RL_200
|
|
|
108
108
|
|
|
109
109
|
## How requests are keyed
|
|
110
110
|
|
|
111
|
-
Each handler composes a key as `<resource>:<op>:<
|
|
111
|
+
Each handler composes a key as `<resource>:<op>:<identity>`. The identity is the caller's `userId`. A sessionless scope-only principal (for example an event pass, which has no `userId`) is keyed on its verified JWT subject, `scope:<kind>:<subjectId>`, so every pass holder gets their own bucket even when many of them share one network. Only callers with neither — routes that opt into PUBLIC access — fall back to the client's `cf-connecting-ip` header, then to the literal `'anon'` if that header is absent too.
|
|
112
112
|
|
|
113
113
|
This means:
|
|
114
114
|
|
|
@@ -193,8 +193,8 @@ Set `rateLimit: false` to opt the action out of enforcement entirely.
|
|
|
193
193
|
|
|
194
194
|
| Action kind | Key shape |
|
|
195
195
|
|-------------|-----------|
|
|
196
|
-
| Record-based | `<resource>:action:<actionName>:<userId\|cf-connecting-ip\|anon>` |
|
|
197
|
-
| Standalone | `standalone:<path>:<userId\|cf-connecting-ip\|anon>` |
|
|
196
|
+
| Record-based | `<resource>:action:<actionName>:<userId\|scopeSubject\|cf-connecting-ip\|anon>` |
|
|
197
|
+
| Standalone | `standalone:<path>:<userId\|scopeSubject\|cf-connecting-ip\|anon>` |
|
|
198
198
|
|
|
199
199
|
The `:action:` infix is what keeps `update` (resource bucket) and `approve` (action bucket) from sharing counters when they happen to land on the same binding name.
|
|
200
200
|
|