@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
|
@@ -135,6 +135,7 @@ place for generated CRUD writes.
|
|
|
135
135
|
|
|
136
136
|
|
|
137
137
|
- **Indexes and constraints:** column-level `.index()` / `.unique()` / `.check(expr)`, or table-level `indexes` / `unique` / `check` as a third arg to `q.table(name, cols, { indexes, unique, check })`. With `feature()`, pass `indexes`, `unique` and `check` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts. In the two-export form they go on `q.table`; on `defineTable(...)` they are a compile error, because they describe the table, not the resource. See [Constraints](#constraints--check-and-unique).
|
|
138
|
+
- **Race-safe write kinds (on `defineTable`):** `ledger: { grants, reserve }` makes the table the debits side of a balance served as `db.ledger.<name>` ([Ledgers](/define/actions/scoped-db#ledgers-dbledgername)); `idempotency: { rowToken, clientId? }` makes `POST /` and `POST /batch` replay a create whose row token is already stored ([Row-token idempotency](/api/crud#row-token-idempotency)).
|
|
138
139
|
|
|
139
140
|
### Column Types
|
|
140
141
|
|
|
@@ -142,6 +143,7 @@ place for generated CRUD writes.
|
|
|
142
143
|
|---------|---------------------|----------|
|
|
143
144
|
| `q.text()` | `text(...)` | `z.string()` |
|
|
144
145
|
| `q.url()` | `text(...)` | `z.string().url({ protocol: /^https?$/ })` |
|
|
146
|
+
| `q.secret()` | `text(...)` (envelope-encrypted, never returned) | `z.string()` — see [Secret columns](/define/encryption#secret-columns--qsecret) |
|
|
145
147
|
| `q.int()` | `integer(...)` | `z.number().int()` |
|
|
146
148
|
| `q.bigint()` | `bigint(..., { mode: 'number' })` | `z.number().int()` within ±(2^53 − 1) |
|
|
147
149
|
| `q.smallint()` | `smallint(...)` | `z.number().int()` within −32768..32767 |
|
|
@@ -155,6 +157,7 @@ place for generated CRUD writes.
|
|
|
155
157
|
| `q.id()` | `text('id').primaryKey()` | `z.string()` |
|
|
156
158
|
| `q.scope(kind)` | `text(...).notNull()` | `z.string()` |
|
|
157
159
|
| `q.stamp({ fromScope, claim })` | `text(...).notNull()` (nullable with `optional: true`) | `z.string().optional()` |
|
|
160
|
+
| `q.storageKey({ bucket, key, mime, maxBytes })` | `text(...)` | never in a request body — written by `db.allocateUpload` only |
|
|
158
161
|
| `.array()` on `q.text()` / `q.enum()` / `q.int()` / `q.uuid()` | `text(...).array()` etc. | `z.array(<element>)` |
|
|
159
162
|
|
|
160
163
|
The Drizzle column is the Postgres form; on SQLite/D1 the compiler lowers it. The next section has the per-dialect storage for the exact-numeric, date, and array types.
|
|
@@ -172,6 +175,8 @@ In request bodies a column that is not `.required()` is `.optional().nullable()`
|
|
|
172
175
|
|
|
173
176
|
Every rule is enforced on the generated create, update, and batch routes, described in OpenAPI, and read by the CMS form from the [schema registry](/ui/admin/schema-format). A misspelled option (`maxlength`) is a compile error, not a silent no-op. `q.url()` takes `sqlName` and `maxLength` only.
|
|
174
177
|
|
|
178
|
+
`q.secret()` is a write-only credential column — an API client secret, a webhook URL with an embedded token. It takes `sqlName`, `minLength`, `maxLength`, and `pattern`; it is encrypted at rest like `.encrypted()`, redacted on every read path for every role (owner included), and read server-side only through `ctx.unmask(row, column)`. The table needs a `q.scope('organization')` column. See [Secret columns](/define/encryption#secret-columns--qsecret).
|
|
179
|
+
|
|
175
180
|
`q.url()` is `q.text()` plus an absolute-`http(s)`-URL check at the validation edge, so `javascript:` / `data:` / `ftp:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
|
|
176
181
|
|
|
177
182
|
`q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting (default `"uuid"`). This keeps q's output decoupled from any specific ID library.
|
|
@@ -208,6 +213,80 @@ The schema must be written inline from `z` and literals, because the compiler co
|
|
|
208
213
|
- using `z` anywhere else in the table file
|
|
209
214
|
- importing anything from `zod` other than `{ z }`
|
|
210
215
|
|
|
216
|
+
#### Per-key write authority (`keys`)
|
|
217
|
+
|
|
218
|
+
`createable` and `updatable` decide whether a client may write a column. One JSON column can mix keys a project member may change with keys only a platform operator may change (entitlements, plan features, feature flags). The second argument of `q.json(schema, opts)` can declare a tier for each key:
|
|
219
|
+
|
|
220
|
+
```typescript title="quickback/features/projects/projects.ts"
|
|
221
|
+
import { feature, q } from "@quickback/compiler";
|
|
222
|
+
import { z } from "zod";
|
|
223
|
+
|
|
224
|
+
export default feature("projects", {
|
|
225
|
+
columns: {
|
|
226
|
+
id: q.id(),
|
|
227
|
+
name: q.text().required(),
|
|
228
|
+
settings: q.json(
|
|
229
|
+
z.object({
|
|
230
|
+
theme: z.string().optional(),
|
|
231
|
+
beta: z.boolean().optional(),
|
|
232
|
+
}),
|
|
233
|
+
{
|
|
234
|
+
keys: {
|
|
235
|
+
theme: { tier: "organizer" }, // ordinary: writable wherever `settings` is
|
|
236
|
+
beta: { tier: "platform" }, // generic writes refuse it
|
|
237
|
+
},
|
|
238
|
+
},
|
|
239
|
+
).optional(),
|
|
240
|
+
organizationId: q.scope("organization"),
|
|
241
|
+
...q.audit(),
|
|
242
|
+
...q.softDelete(),
|
|
243
|
+
},
|
|
244
|
+
guards: { createable: ["name", "settings"], updatable: ["name", "settings"] },
|
|
245
|
+
read: { access: { roles: ["member"] } },
|
|
246
|
+
create: { access: { roles: ["member"] } },
|
|
247
|
+
update: { access: { roles: ["member"] } },
|
|
248
|
+
});
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
| Option | Meaning |
|
|
252
|
+
|--------|---------|
|
|
253
|
+
| `sqlName` | SQL column name. The legacy positional form `q.json(schema, "col")` still works. |
|
|
254
|
+
| `keys.<key>.tier` | `"organizer"` (the default): an ordinary key. `"platform"`: see below. |
|
|
255
|
+
| `keys.<key>.derivedFrom` | The key is computed from another table and never stored. Requires `tier: "platform"` and a `z.boolean()` property. |
|
|
256
|
+
|
|
257
|
+
`keys` needs an inline `z.object({ ... })` value schema, and every key it lists must be a property of that schema. A key the schema doesn't declare, an unknown option, or a non-literal options object is a compile error.
|
|
258
|
+
|
|
259
|
+
**Platform keys.** Generic CRUD writes (POST, PATCH, PUT, the batch routes, and changeset ops) refuse a body that carries a platform key with **422 `JSON_KEY_RESTRICTED`**, and `details.fields` names it as `<column>.<key>`. A PATCH that replaces the column keeps the stored platform keys: `PATCH { settings: { theme: "dark" } }` leaves `beta` as it was. Platform keys are `readOnly` in the column's JSON Schema (OpenAPI, `api-types.gen.ts`, MCP).
|
|
260
|
+
|
|
261
|
+
Only an action can change a platform key, and only one of these actions:
|
|
262
|
+
|
|
263
|
+
- an action whose `access` names a `userRole` lane, when the caller's `user.role` matched it (`access: { userRole: ["operator"] }`);
|
|
264
|
+
- an action that names the key in [`writes:`](/define/actions/defining#json-key-writes-and-requires).
|
|
265
|
+
|
|
266
|
+
The [scoped `db`](/define/actions/scoped-db) enforces this rule, and so do handles from `unsafeDb.scopeTo(...)`. Any other action that writes the column gets 422 `JSON_KEY_RESTRICTED` if it changes or drops a platform key. Read-modify-write that carries the key over unchanged, such as `.set({ settings: { ...record.settings, theme } })`, is allowed. An insert may not set a platform key without the grant. An upsert's `onConflictDoUpdate({ set })` that touches the column is refused unless the action holds every grant, because the compiler cannot compare it against the stored row. The raw `unsafeDb` handle bypasses this check, as it bypasses the firewall.
|
|
267
|
+
|
|
268
|
+
**Derived keys.** `derivedFrom: { table, column, in, match? }` turns a key into a projection of another table. The key is `true` when a row of `table` that is linked to this row has `column` in the `in` set, and `false` otherwise. Soft-deleted rows don't count.
|
|
269
|
+
|
|
270
|
+
{/* doc-compile: skip — derivedFrom resolves against a second table (`plans`) the isolated fence does not declare; the tests/output-matrix/fixtures/json-key-tiers project compiles both. */}
|
|
271
|
+
```typescript
|
|
272
|
+
settings: q.json(
|
|
273
|
+
z.object({ premiumExport: z.boolean().optional() }),
|
|
274
|
+
{
|
|
275
|
+
keys: {
|
|
276
|
+
premiumExport: {
|
|
277
|
+
tier: "platform",
|
|
278
|
+
// true while a `plans` row for this project is active or trialing
|
|
279
|
+
derivedFrom: { table: "plans", column: "status", in: ["active", "trialing"] },
|
|
280
|
+
},
|
|
281
|
+
},
|
|
282
|
+
},
|
|
283
|
+
),
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
- `table` is the other table's SQL name or export name, and `column` is a column of it.
|
|
287
|
+
- `match: { source, target }` links the rows: `source` is a column on this table, `target` a column on `table`. Omit it when `table` has exactly one `.references()` to this table. The compiler then infers the link (`plans.projectId → projects.id`). Zero or several references with no `match` is a compile error.
|
|
288
|
+
- A derived key is never stored and never writable. Every write path refuses it, actions with a grant included. CRUD reads (GET, list, views) and CRUD write responses fill it in from the source table. Realtime frames carry the stored value, which never holds a derived key. An action's [`requires:`](/define/actions/defining#json-key-writes-and-requires) also reads the source table, so the purchase or subscription row is the only source of truth.
|
|
289
|
+
|
|
211
290
|
Under `generateId: "cuid"`, `"nanoid"`, or `"short"`, the `q.id()` default
|
|
212
291
|
calls an npm helper (`createId` from `@paralleldrive/cuid2`, or `nanoid` /
|
|
213
292
|
`customAlphabet` from `nanoid`). Don't import it in the table file, which may
|
|
@@ -328,6 +407,41 @@ columns: {
|
|
|
328
407
|
|
|
329
408
|
**Idempotency (at-least-once).** The stamp rides inside the write, so it inherits the endpoint's replay semantics: a **keyed** replay (a repeated `Idempotency-Key` whose handler is skipped) neither re-writes nor re-stamps; a **keyless** retry re-writes and therefore re-stamps from the caller's then-current proven claim.
|
|
330
409
|
|
|
410
|
+
### q.storageKey() — R2 object keys the compiler owns
|
|
411
|
+
|
|
412
|
+
`q.storageKey(...)` declares a column that holds an R2 object key. The compiler,
|
|
413
|
+
not the client, writes the key:
|
|
414
|
+
|
|
415
|
+
```ts no-compile
|
|
416
|
+
r2Key: q.storageKey({
|
|
417
|
+
bucket: "MEDIA", // a bindings.r2Buckets binding
|
|
418
|
+
key: "media/{organizationId}/{eventId}/{uuid}.{ext}",
|
|
419
|
+
mime: ["image/*", "application/pdf"],
|
|
420
|
+
maxBytes: 10_000_000,
|
|
421
|
+
}),
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
- **Never client-writable.** No generated write body (create, update, batch,
|
|
425
|
+
PUT, changeset) carries the column. Listing it in `guards.createable`,
|
|
426
|
+
`updatable`, `immutable` or `protected` is a compile error
|
|
427
|
+
(`STORAGE_KEY_GUARDED`).
|
|
428
|
+
- **Written only by `db.allocateUpload(table, { ...rowValues, ext, mime, size })`**
|
|
429
|
+
inside an action. It renders the key from the template, with `{column}`
|
|
430
|
+
values from the row, a fresh `{uuid}`, and `{ext}` from the call. It then
|
|
431
|
+
returns `{ row, putUrl, headers }`: a PUT signed for exactly the declared
|
|
432
|
+
`mime` and at most `maxBytes`.
|
|
433
|
+
- **Prefix-checked.** The row's prefix is the template up to `{uuid}` with the
|
|
434
|
+
row's own values (`media/org_abc/evt_1/`). Reads (`db.signDownload`), deletes,
|
|
435
|
+
and [tenant purge](/configure/tenancy) refuse a stored key outside it. Each
|
|
436
|
+
firewall tenant column (`organizationId`, `ownerId`, a scope column) must be a
|
|
437
|
+
placeholder before `{uuid}`. Each placeholder fills a whole path segment.
|
|
438
|
+
- **Deleted with the row.** A hard delete through the generated routes or the
|
|
439
|
+
action `db` deletes the object too.
|
|
440
|
+
|
|
441
|
+
The column takes `.required()`, `.optional()`, `.unique()` and `.index()`.
|
|
442
|
+
Other modifiers fail the compile. The template rules, the error codes, and the
|
|
443
|
+
full upload and download flow are in [Using R2 → Signed upload](/platform/storage/using-r2#signed-upload-large-or-confidential-files).
|
|
444
|
+
|
|
331
445
|
### Naming Convention
|
|
332
446
|
|
|
333
447
|
By default, `q` picks the SQL column name from the JS key using the target database's conventional casing. Both `cloudflare-d1` and `neon` default to **`snake_case`** (`organizationId` → `organization_id`).
|
|
@@ -397,15 +511,23 @@ export default feature('line_items', {
|
|
|
397
511
|
| `check: [{ name, sql }]` | `CONSTRAINT "<name>" CHECK (<sql>)` |
|
|
398
512
|
| `unique: [{ columns }]` | `CREATE UNIQUE INDEX …` |
|
|
399
513
|
| `unique: [{ columns, where: '…' }]` | `CREATE UNIQUE INDEX … WHERE …` (a partial unique index) |
|
|
514
|
+
| `unique: [{ columns, where: { deletedAt: null, status: 'active' } }]` | `CREATE UNIQUE INDEX … WHERE "deleted_at" IS NULL AND "status" = 'active'` |
|
|
400
515
|
| `unique: [{ columns, whereNotDeleted: true }]` | `CREATE UNIQUE INDEX … WHERE "deleted_at" IS NULL` |
|
|
401
516
|
| `unique: [{ columns, nullsNotDistinct: true }]` | `CONSTRAINT … UNIQUE NULLS NOT DISTINCT (…)`. Postgres 15+ only. |
|
|
402
517
|
|
|
403
518
|
**How the SQL is written.** Column-level `.check(expr)` is appended to the
|
|
404
519
|
quoted physical column name, as `"<column>" <expr>`. Write only what follows
|
|
405
520
|
the column: `'> 0'`, `"IN ('draft', 'open')"`, `'BETWEEN 1 AND 5'`. The
|
|
406
|
-
table-level `sql` and
|
|
521
|
+
table-level `sql` and a string unique `where` are complete expressions over the
|
|
407
522
|
**physical (snake_case) column names**: `product_id`, not `productId`.
|
|
408
523
|
|
|
524
|
+
The **object form** of `where` takes the JS column names and renders the
|
|
525
|
+
physical ones for you, AND-joined. Each value is a literal: `null`
|
|
526
|
+
(`IS NULL`), `{ notNull: true }` (`IS NOT NULL`), a string, a finite number,
|
|
527
|
+
or a boolean (`= TRUE` / `= FALSE`, valid on Postgres and on the SQLite D1
|
|
528
|
+
ships). A key that is not a column of the table, or any other value, is a
|
|
529
|
+
compile error.
|
|
530
|
+
|
|
409
531
|
**Nothing is translated per dialect.** The SQL must be valid for your
|
|
410
532
|
database. `num_nonnulls(a, b, c) = 1` works on Postgres only. On D1, write
|
|
411
533
|
`(a IS NOT NULL) + (b IS NOT NULL) + (c IS NOT NULL) = 1`. An invalid
|
|
@@ -424,6 +546,7 @@ from source, and it fails the compile on any of the following:
|
|
|
424
546
|
- a value that isn't a literal
|
|
425
547
|
- an unknown key
|
|
426
548
|
- `where` together with `whereNotDeleted`
|
|
549
|
+
- an object `where` naming an unknown column, or a non-literal value
|
|
427
550
|
- `nullsNotDistinct` on a partial unique
|
|
428
551
|
- `whereNotDeleted` on a table without `...q.softDelete()`
|
|
429
552
|
- `nullsNotDistinct` in a SQLite/D1 project, since SQLite always treats NULLs
|
|
@@ -452,8 +575,8 @@ created again. The insert returns `409 DB_UNIQUE_VIOLATION` against a row the
|
|
|
452
575
|
caller can no longer see. Column-level `.unique()` has the same problem.
|
|
453
576
|
|
|
454
577
|
On a soft-delete table, make the unique **partial**. `whereNotDeleted: true`
|
|
455
|
-
adds `WHERE "deleted_at" IS NULL`,
|
|
456
|
-
under your naming convention. Uniqueness then holds among live rows only, and
|
|
578
|
+
(or the object form `where: { deletedAt: null }`) adds `WHERE "deleted_at" IS NULL`,
|
|
579
|
+
using the table's actual soft-delete column under your naming convention. Uniqueness then holds among live rows only, and
|
|
457
580
|
a deleted value can be reused. Restoring a soft-deleted row whose value a live
|
|
458
581
|
row has since taken fails with a unique violation. That is the correct
|
|
459
582
|
outcome, because the two rows would otherwise collide.
|
|
@@ -913,7 +1036,9 @@ The platform provides the pieces for an explicit policy:
|
|
|
913
1036
|
- **Aggregate deletion** — use database foreign keys with
|
|
914
1037
|
`onDelete: 'cascade'` for same-database ownership, and orchestrate
|
|
915
1038
|
cross-database records, R2 objects, and external systems from an explicit
|
|
916
|
-
offboarding action or queued job.
|
|
1039
|
+
offboarding action or queued job. For a whole organization,
|
|
1040
|
+
[`tenancy.purge`](/configure/tenancy) derives the table list from the
|
|
1041
|
+
firewall and deletes the rows' storage-key objects with them.
|
|
917
1042
|
- **Encrypted data** — deleting an organization's wrapped DEK makes its
|
|
918
1043
|
envelope-encrypted fields unreadable, provided no backup or export still
|
|
919
1044
|
holds that row ([crypto-shredding](/define/encryption#per-organization-keys-blast-radius-and-crypto-shredding)
|
|
@@ -1123,9 +1248,25 @@ files sit at `features/<feature>/`. The thunk names a real binding; without
|
|
|
1123
1248
|
the import the generated schema fails migration generation.
|
|
1124
1249
|
|
|
1125
1250
|
Do this even when a column name appears obvious, such as `sessionId` beside a
|
|
1126
|
-
`sessions` table. A matching `*Id` name is
|
|
1127
|
-
|
|
1128
|
-
|
|
1251
|
+
`sessions` table. A matching `*Id` name is not enough evidence to silently
|
|
1252
|
+
invent a relationship, so the compiler refuses the omission instead:
|
|
1253
|
+
[`SCHEMA_UNDECLARED_FK`](/define/diagnostics#schema-and-config-codes) fails the
|
|
1254
|
+
build when a `*Id` column names a feature table in the same database, is
|
|
1255
|
+
client-writable or used in a firewall / relationship arm, and declares no
|
|
1256
|
+
`.references()`. When the column genuinely is not a pointer into that table,
|
|
1257
|
+
say so with a reason:
|
|
1258
|
+
|
|
1259
|
+
{/* doc-compile: skip — one-key excerpt of a defineTable config */}
|
|
1260
|
+
```typescript
|
|
1261
|
+
references: {
|
|
1262
|
+
cventEventId: { references: false, reason: 'Cvent-side id; no row in this database' },
|
|
1263
|
+
},
|
|
1264
|
+
```
|
|
1265
|
+
|
|
1266
|
+
When both tables carry an org column, also declare
|
|
1267
|
+
[`match`](#match-a-referenced-rows-parent) on it —
|
|
1268
|
+
`SCHEMA_FK_MATCH_REQUIRED` warns until you do, or until you opt out with
|
|
1269
|
+
`references: { eventId: { match: false, reason: '…' } }`.
|
|
1129
1270
|
|
|
1130
1271
|
### Self-references
|
|
1131
1272
|
|
|
@@ -681,6 +681,76 @@ the matched row's PK too — so the arm above is **one arm that serves both** a
|
|
|
681
681
|
logged-in attendee and a sessionless one. (It is distinct from
|
|
682
682
|
`ctx.scope.event.id`, which is the *instance* — the event.)
|
|
683
683
|
|
|
684
|
+
### `ctx.self` — the caller's own row
|
|
685
|
+
|
|
686
|
+
`subjectId` gives one firewall arm for both principals, but an action body
|
|
687
|
+
still needs the *row*: a logged-in attendee is found by `linkedUserId =
|
|
688
|
+
ctx.userId`, a pass holder by `id = ctx.scope.event.subjectId`, and every action
|
|
689
|
+
that touches "my" data repeats that branch. Declare it once on the role:
|
|
690
|
+
|
|
691
|
+
```typescript
|
|
692
|
+
// quickback.config.ts
|
|
693
|
+
scopes: {
|
|
694
|
+
event: {
|
|
695
|
+
requestField: 'eventId',
|
|
696
|
+
roles: {
|
|
697
|
+
attendee: {
|
|
698
|
+
via: 'attendeeOf',
|
|
699
|
+
subject: 'both',
|
|
700
|
+
self: {
|
|
701
|
+
table: 'guests',
|
|
702
|
+
exposeAs: 'guest',
|
|
703
|
+
by: { session: 'linkedUserId', subject: 'id' }, // instance: 'eventId' (default: requestField)
|
|
704
|
+
recheck: { status: 'confirmed', deletedAt: null },
|
|
705
|
+
},
|
|
706
|
+
},
|
|
707
|
+
},
|
|
708
|
+
},
|
|
709
|
+
}
|
|
710
|
+
```
|
|
711
|
+
|
|
712
|
+
Every action then sees **`ctx.self.guest`**, typed as the `guests` row or
|
|
713
|
+
`null` — one code path for both principals:
|
|
714
|
+
|
|
715
|
+
```typescript
|
|
716
|
+
async execute({ ctx }) {
|
|
717
|
+
const me = ctx.self.guest; // same row for a session user and a pass holder
|
|
718
|
+
if (!me) throw new ActionError('Not an attendee of this event', 'NOT_ATTENDEE', 403);
|
|
719
|
+
}
|
|
720
|
+
```
|
|
721
|
+
|
|
722
|
+
How it resolves, on **every** action request, before the action's access check:
|
|
723
|
+
|
|
724
|
+
- The caller must hold `scope:<kind>:<role>` for an instance
|
|
725
|
+
(`ctx.scope.<kind>` — from a scope token, or the namespace refresh). Anyone
|
|
726
|
+
else (an org admin admitted by a `{ roles }` lane) gets `null`: the lane
|
|
727
|
+
carries no self.
|
|
728
|
+
- One row of `self.table` is loaded, pinned to the caller —
|
|
729
|
+
`by.session = ctx.userId` for a Better Auth session, otherwise
|
|
730
|
+
`by.subject = ctx.scope.<kind>.subjectId` — to the instance
|
|
731
|
+
(`by.instance = ctx.scope.<kind>.id`), and to every `recheck` condition
|
|
732
|
+
(`null` = IS NULL, an array = one of), through the table's own firewall
|
|
733
|
+
(soft-delete applies; tenant scopes are skipped exactly as for a relationship
|
|
734
|
+
probe — the pins are the boundary).
|
|
735
|
+
- **`recheck` is a per-request re-proof.** A carried scope claim is trusted
|
|
736
|
+
between proofs (see [Revocation & TTL](#revocation--ttl)); when no row passes
|
|
737
|
+
the recheck, `ctx.self.<exposeAs>` is `null` **and the role is withdrawn
|
|
738
|
+
from `ctx.scope.<kind>.roles` for that request**, so every gate that relied
|
|
739
|
+
on it denies. A guest who stopped being `confirmed` loses the attendee role
|
|
740
|
+
at their next action, not at the token's TTL.
|
|
741
|
+
|
|
742
|
+
Defaults and checks (compile time):
|
|
743
|
+
|
|
744
|
+
| Key | Default | Required when |
|
|
745
|
+
|---|---|---|
|
|
746
|
+
| `by.session` | the relationship's `subject.column`, when `table` is its `from` table bound to `ctx.userId` | the role is user-provable (`subject: 'user' \| 'both'`) and `table` is another table. Rejected on `subject: 'supplied'`. |
|
|
747
|
+
| `by.subject` | `'id'` when `table` is the relationship's `from` table (`subjectId` is that row's PK) | the role is supplied-provable (`'supplied' \| 'both'`) and `table` is another table. Rejected on `subject: 'user'`. |
|
|
748
|
+
| `by.instance` | the scope's `requestField` | — |
|
|
749
|
+
|
|
750
|
+
`exposeAs` must be unique across every declared `self`. Refs can name the
|
|
751
|
+
caller's row as their ownership subject —
|
|
752
|
+
[`ownedVia: { …, subject: 'ctx.self.guest' }`](/define/actions/defining#id-arrays-parent-state-and-mine-through-a-junction).
|
|
753
|
+
|
|
684
754
|
### Realtime
|
|
685
755
|
|
|
686
756
|
A scope-only token authorizes the realtime
|
|
@@ -717,9 +787,18 @@ ctx.scope?: Record<string, { id: string; roles?: string[]; subjectId?: string; [
|
|
|
717
787
|
via: string;
|
|
718
788
|
subKeys?: string[]; // 'col' → eq, 'col[]' → inArray
|
|
719
789
|
subject?: 'user' | 'supplied' | 'both'; // who selects the conferring row (default 'user')
|
|
790
|
+
self?: { // ctx.self.<exposeAs> — the caller's own row
|
|
791
|
+
table: string;
|
|
792
|
+
exposeAs: string;
|
|
793
|
+
by?: { session?: string; subject?: string; instance?: string };
|
|
794
|
+
recheck?: Record<string, string | number | boolean | null | Array<string | number>>;
|
|
795
|
+
};
|
|
720
796
|
}>;
|
|
721
797
|
}
|
|
722
798
|
|
|
799
|
+
// ctx.self — present in actions when any scoped role declares `self`
|
|
800
|
+
ctx.self: { [exposeAs]: Row | null };
|
|
801
|
+
|
|
723
802
|
// ctx.mintScope — present in actions when a `subject: 'supplied' | 'both'` role is declared
|
|
724
803
|
ctx.mintScope(opts: { via: string; subject: string; setAuthToken?: boolean }):
|
|
725
804
|
Promise<{ token: string; scope: { id: string; roles: string[]; subjectId?: string } }>;
|
|
@@ -34,6 +34,7 @@ All standard; no hand-rolled constructions. A conforming port maps each to its p
|
|
|
34
34
|
| Step-up proof | **Ed25519** sign/verify | over the [step-up message](#step-up-message) |
|
|
35
35
|
| Sealed box (wrap a key to a pubkey) | **X25519 ECDH → HKDF-SHA256 → AES-256-GCM** | see below |
|
|
36
36
|
| Content / key encryption | **AES-256-GCM** | 12-byte IV, 16-byte tag appended to ciphertext |
|
|
37
|
+
| Passkey PRF unlock (wrap the user master) | **HKDF-SHA256 → AES-256-GCM** | see [Multi-factor unlock](#multi-factor-unlock-passkey-prf) |
|
|
37
38
|
|
|
38
39
|
### Argon2id floor
|
|
39
40
|
|
|
@@ -243,22 +244,32 @@ A reader who has a role for a scope but no grant publishes their X25519 USER pub
|
|
|
243
244
|
```
|
|
244
245
|
The key-admin wraps the scope key to each `userPublicKey` and calls [`/grant`](#7-grant--enroll-a-reader--store-their-wrapped-scope-key-key-admin), which **auto-resolves** the matching pending request.
|
|
245
246
|
|
|
246
|
-
### 12. `/recovery/enroll` — escrow the scope key under a recovery
|
|
247
|
+
### 12. `/recovery/enroll` — escrow the scope key under a recovery factor (key-admin)
|
|
247
248
|
|
|
248
|
-
A key-admin (holding the scope private key) wraps it to a
|
|
249
|
+
A key-admin (holding the scope private key) wraps it to a client-held recovery factor and escrows the blob. The server stores only the opaque recovery-wrapped material — the factor, held by the client, is what makes it usable; the server can never unwrap it.
|
|
250
|
+
|
|
251
|
+
`wrapMethod` names the client-side wrap and defaults to `recovery-code`. One live recovery per **(scope key version, wrapMethod)**, so a passkey-wrapped recovery can sit next to the recovery code; re-enrolling the same method on the same key version is a 409 until it is revoked or the key rotates. `wrapMeta` is an optional JSON object the server stores verbatim and hands back at `/recovery/use` (public wrap material only — a credential id, salts, a label; capped at 4 KiB). The server never reads either field.
|
|
252
|
+
|
|
253
|
+
| `wrapMethod` | The blob is… |
|
|
254
|
+
|---|---|
|
|
255
|
+
| `recovery-code` (default) | the scope key wrapped to a key derived from a recovery code |
|
|
256
|
+
| `prf-aesgcm` | the scope key wrapped under a KEK derived from a WebAuthn PRF output (a hardware security key or a shared vault passkey); `wrapMeta` carries the credential id and salts the client needs to re-derive the KEK |
|
|
249
257
|
|
|
250
258
|
```jsonc
|
|
251
|
-
// → { scopeRef, wrappedPrivateKey: "<qbseal envelope,
|
|
252
|
-
// ← { enrolled: true, scopeRef, keyVersion: 1 }
|
|
259
|
+
// → { scopeRef, wrappedPrivateKey: "<qbseal envelope>", wrapMethod?: "recovery-code" | "prf-aesgcm", wrapMeta?: { … } }
|
|
260
|
+
// ← { enrolled: true, scopeRef, keyVersion: 1, wrapMethod: "recovery-code" }
|
|
253
261
|
```
|
|
254
262
|
|
|
255
|
-
### 13. `/recovery/use` — retrieve the recovery blob (key-admin)
|
|
263
|
+
### 13. `/recovery/use` — retrieve the recovery blob(s) (key-admin)
|
|
256
264
|
|
|
257
|
-
Returns the live recovery-wrapped scope key (and appends a `recovery` entry to the reveal log). The client unwraps it with
|
|
265
|
+
Returns the live recovery-wrapped scope key for the newest key version that has one (and appends a `recovery` entry to the reveal log). The client unwraps it with its recovery factor to recover the scope private key, then re-grants readers. The returned blobs are **useless without the factor** — the server gates *who* may fetch them, the factor gates whether one can be unwrapped.
|
|
266
|
+
|
|
267
|
+
Without `wrapMethod`, every live method for that key version rides along in `recoveries`, so a client can offer "use your security key or enter the recovery code" from one call; the top-level fields are the `recovery-code` row when one exists (wire-compatible with clients that predate `wrapMethod`). Pass `wrapMethod` to narrow to one method; 404 parity when none of that method is live.
|
|
258
268
|
|
|
259
269
|
```jsonc
|
|
260
|
-
// → { scopeRef }
|
|
261
|
-
// ← { scopeRef, keyVersion, wrappedPrivateKey: "<qbseal envelope>"
|
|
270
|
+
// → { scopeRef, wrapMethod?: "recovery-code" | "prf-aesgcm" }
|
|
271
|
+
// ← { scopeRef, keyVersion, wrappedPrivateKey: "<qbseal envelope>", wrapMethod, wrapMeta,
|
|
272
|
+
// recoveries: [{ wrapMethod, wrapMeta, wrappedPrivateKey }, …] } // 404 parity if none
|
|
262
273
|
```
|
|
263
274
|
|
|
264
275
|
#### role→grant: readers request, key-admins fulfil
|
|
@@ -274,10 +285,99 @@ When the passkey plugin is enabled, `/reveal` verifies a WebAuthn assertion whos
|
|
|
274
285
|
| `challenge` | the `/challenge` `nonce` **as the base64url string** (the client signs the b64url text, the server passes `expectedChallenge = nonce`) |
|
|
275
286
|
| `rpID` | the passkey plugin's `rpID` — i.e. `crossSubDomainCookies.domain` (leading dot stripped) when configured, else the registrable host of `env.ACCOUNT_URL`, else the compile-time account origin (both emissions share one resolution, so they cannot skew) |
|
|
276
287
|
| `userVerification` | **required** (`requireUserVerification: true` — a reveal is a deliberate re-auth) |
|
|
277
|
-
| origin | the resolved account origin (mirrors the `passkey({ rpID, origin })` plugin) |
|
|
288
|
+
| origin | any of: the resolved account origin (mirrors the `passkey({ rpID, origin })` plugin), `https://<rpID>` (what an Apple associated-domain app asserts), and every entry of `encryption.seal.extraOrigins` (e.g. `android:apk-key-hash:<sha256>`) |
|
|
278
289
|
|
|
279
290
|
The credential is looked up in the **auth** database (`passkey` table) and the signature counter is clone-checked. Conformance for passkey is **verify-based** at the server; the client's job is to bind `challenge = nonce` exactly.
|
|
280
291
|
|
|
292
|
+
## Multi-factor unlock (passkey PRF)
|
|
293
|
+
|
|
294
|
+
The passphrase is one way to reach the USER keys; a passkey with the WebAuthn **PRF extension** is the other. The two converge on one secret — the 32-byte **user master** (the raw Argon2id output, before the HKDF split) — so either factor yields byte-identical keys:
|
|
295
|
+
|
|
296
|
+
```
|
|
297
|
+
master = Argon2id(passphrase, salt, params) deriveUserMaster
|
|
298
|
+
keys = HKDF-split(master) userKeysFromMaster (ed25519 / x25519, as above)
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
A PRF-capable passkey evaluates a per-credential pseudo-random function inside the authenticator, released only after user verification. The client wraps the master under a key derived from that output and stores the wrapped blob next to the enrollment. At reveal time **one ceremony** both proves the step-up (the assertion) and unlocks the keys (the PRF output) — no passphrase prompt. The server stores the blob as opaque ciphertext: it never sees the PRF output, the KEK, or the master.
|
|
302
|
+
|
|
303
|
+
### Derivation
|
|
304
|
+
|
|
305
|
+
```
|
|
306
|
+
prfSalt = SHA-256( utf8("qbseal-prf-salt-v1") ‖ utf8(orgId) ) ← extensions.prf.eval.first
|
|
307
|
+
prf = PRF(credential, prfSalt) ← 32 bytes, from the authenticator
|
|
308
|
+
|
|
309
|
+
binding = utf8(userId) ‖ 0x00 ‖ utf8(orgId) ‖ 0x00 ‖ utf8(credentialId)
|
|
310
|
+
|
|
311
|
+
KEK = HKDF-SHA256( ikm = prf, salt = kekSalt,
|
|
312
|
+
info = utf8("qbseal-prf-kek-v1") ‖ binding, L = 32 )
|
|
313
|
+
ct = AES-256-GCM( KEK, iv, plaintext = master, AAD = binding )
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
- `prfSalt` is **per org**, so one user's PRF outputs across orgs are unrelated. Pass the same salt at registration and every assertion.
|
|
317
|
+
- `credentialId` is the passkey's **base64url credential id string exactly as WebAuthn returns it** (`PublicKeyCredential.id`); it is never re-encoded. The envelope carries it verbatim so a client can pick the matching passkey before the ceremony.
|
|
318
|
+
- `kekSalt` is 32 fresh random bytes and `iv` 12; both are stored in the envelope. The `(userId, orgId, credentialId)` binding is in **both** the KEK info and the AAD, so a blob lifted from another user, org, or credential fails on the GCM tag. Open fails closed on any mismatch.
|
|
319
|
+
|
|
320
|
+
### Envelope
|
|
321
|
+
|
|
322
|
+
A `qbseal:1` envelope with a new `alg` — the wire version is unchanged and every existing decoder keeps accepting it structurally:
|
|
323
|
+
|
|
324
|
+
```jsonc
|
|
325
|
+
{ "alg": "prf-aesgcm",
|
|
326
|
+
"cred": "<credentialId, verbatim>",
|
|
327
|
+
"salt": "<base64url kekSalt, 32 bytes>",
|
|
328
|
+
"iv": "<base64url, 12 bytes>",
|
|
329
|
+
"ct": "<base64url AES-GCM ciphertext ‖ tag of the 32-byte master>" }
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
### Client usage
|
|
333
|
+
|
|
334
|
+
```typescript
|
|
335
|
+
import { deriveUserMaster, prfSaltFor, wrapMasterWithPrf, SealClient } from './lib/seal-client';
|
|
336
|
+
|
|
337
|
+
// ENROLL the passkey as a second factor (once, with the passphrase in hand).
|
|
338
|
+
const master = deriveUserMaster(passphrase, salt, enrollment.argon2);
|
|
339
|
+
const reg = await startAuthentication({ optionsJSON: {
|
|
340
|
+
...options, extensions: { prf: { eval: { first: prfSaltFor(orgId) } } },
|
|
341
|
+
} });
|
|
342
|
+
const prf = new Uint8Array(reg.clientExtensionResults.prf!.results!.first);
|
|
343
|
+
const wrapped = await wrapMasterWithPrf({ master, prf, userId, orgId, credentialId: reg.id });
|
|
344
|
+
// store `wrapped` (opaque) alongside the user's enrollment
|
|
345
|
+
|
|
346
|
+
// REVEAL with the passkey only — no passphrase prompt.
|
|
347
|
+
const seal = new SealClient(transport);
|
|
348
|
+
const plaintext = await seal.revealWithPasskey({
|
|
349
|
+
scopeRef, vaultItemId,
|
|
350
|
+
getAssertion: async (nonce) => {
|
|
351
|
+
const a = await startAuthentication({ optionsJSON: {
|
|
352
|
+
challenge: nonce, rpId, userVerification: 'required',
|
|
353
|
+
extensions: { prf: { eval: { first: prfSaltFor(orgId) } } },
|
|
354
|
+
} });
|
|
355
|
+
return { assertion: a, prf: new Uint8Array(a.clientExtensionResults.prf!.results!.first) };
|
|
356
|
+
},
|
|
357
|
+
prfUnwrap: { wrapped, userId, orgId, credentialId, argon2: enrollment.argon2 },
|
|
358
|
+
});
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
`getAssertion` may still return the raw `AuthenticationResponseJSON` with a passphrase-derived `session` — the original signature is unchanged. When `prfUnwrap` is given and no `session`, the SDK opens the blob with the assertion's PRF output (`unwrapMasterWithPrf`), builds the session from the master (`sessionFromMaster`), and completes the unwrap; it fails closed if the assertion carried no PRF output. Only the assertion is sent to `/reveal` — the PRF output never leaves the client. The Swift (`KDF.deriveUserMaster`, `KDF.userKeysFromMaster`, `Prf`) and Kotlin (`Kdf.deriveUserMaster`, `Kdf.userKeysFromMaster`, `Prf`) SDKs expose the same primitives, vector-locked to the TS reference.
|
|
362
|
+
|
|
363
|
+
### Compiler support
|
|
364
|
+
|
|
365
|
+
- With **`encryption.seal.passkeyPrf: true`** the emitted `passkey({ rpID, origin })` plugin call adds `registration: { extensions: { prf: {} } }`, so sign-in passkeys are PRF-capable at creation and the same credential serves as the unlock factor — no second enrollment ceremony. It is off by default because it changes the registration ceremony for every passkey the project creates; authenticators without PRF ignore the flag. Creation-time PRF evaluation is optional in WebAuthn, so clients should still run one assertion with `prf.eval` after registration to obtain the output they wrap with.
|
|
366
|
+
- **Reveal-log honesty.** After a PRF unlock, follow-up reveals inside the client's unlock window present the Ed25519 `passphrase`-kind proof (the key came from the unwrapped master, not from a passphrase). The server records the proof kind it verified; it cannot see how the client obtained the key. A client may declare `stepUp.unlockedBy: 'passkey' | 'passphrase'` as an unverifiable hint, which the server records verbatim next to `reauthMethod` — treat it as telemetry, never as evidence.
|
|
367
|
+
- The reveal verify accepts assertions from native apps as well as the browser. `expectedOrigin` is the account origin, `https://<rpID>` (the origin Apple's `ASAuthorization` asserts for an associated-domain app), and anything listed in **`encryption.seal.extraOrigins`** — the home for Android's `android:apk-key-hash:<sha256>`:
|
|
368
|
+
|
|
369
|
+
```typescript
|
|
370
|
+
// quickback.config.ts (fragment)
|
|
371
|
+
encryption: {
|
|
372
|
+
seal: {
|
|
373
|
+
keyAdminRoles: ['owner', 'admin'],
|
|
374
|
+
extraOrigins: ['android:apk-key-hash:pNiP5iKyQ8JwgGOaKA1zGPUB3eTSh-f-5d7HsAwBGFQ'],
|
|
375
|
+
},
|
|
376
|
+
},
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
Entries must be non-empty strings without whitespace; duplicates are dropped. A browser origin other than the account origin cannot be smuggled in — the passkey plugin's own registration check already refuses credentials from it, so listing it here widens nothing.
|
|
380
|
+
|
|
281
381
|
## Conformance vectors
|
|
282
382
|
|
|
283
383
|
Canonical vectors live at **`packages/seal-client/vectors/qbseal-v1.json`**, generated from the reference TS SDK (`bun packages/seal-client/scripts/generate-vectors.ts`) and self-validated against it (`src/vectors.test.ts`). Every input (passphrase, salt, key seeds, IVs, ephemerals) is fixed, so the file is byte-stable and each vector reproduces from its inputs alone.
|
|
@@ -291,6 +391,8 @@ Canonical vectors live at **`packages/seal-client/vectors/qbseal-v1.json`**, gen
|
|
|
291
391
|
| `sealedBoxOpen` | recipient secret + box → plaintext | open-direction (canonical) |
|
|
292
392
|
| `reveal` | passphrase → keys; owner + scope unwrap paths → plaintext | open-direction (canonical) |
|
|
293
393
|
| `envelope` | `qbseal:1:` sealed-cell decodes structurally | full |
|
|
394
|
+
| `masterSplit` | passphrase → the 32-byte master; master → the `kdf` public keys | full |
|
|
395
|
+
| `prfWrap` | `prfSaltFor(orgId)`; pinned prf + kekSalt + iv + ids → the `prf-aesgcm` envelope; a `wrongCredentialId` that must NOT open it | full (wrap is pinned by fixed salt/iv) |
|
|
294
396
|
|
|
295
397
|
A port verifies the open-direction vectors exactly, and proves its *seal* direction by round-tripping through its own open. Vectors are the **cross-language byte-for-byte guarantee** — CI runs every client (TypeScript, Swift, and Kotlin) against this one file and fails on drift.
|
|
296
398
|
|
|
@@ -127,6 +127,45 @@ Semantics:
|
|
|
127
127
|
writes into a `q.timestamp()` column as-is, on every database and every
|
|
128
128
|
`db` handle — see [Column types](/define/schema#decimals-dates-64-bit-integers-and-arrays).
|
|
129
129
|
|
|
130
|
+
### Concurrency: the guard is in the UPDATE
|
|
131
|
+
|
|
132
|
+
D1 has no transaction across statements, so a transition that read the row
|
|
133
|
+
and then wrote it by id would let two concurrent requests both succeed (two
|
|
134
|
+
scanners checking in one guest). The compiler-applied write never does that:
|
|
135
|
+
the UPDATE itself carries the state it checked.
|
|
136
|
+
|
|
137
|
+
```sql
|
|
138
|
+
-- field transition (close: open → closed)
|
|
139
|
+
UPDATE tickets SET status = 'closed', modified_at = ?, …
|
|
140
|
+
WHERE <firewall> AND id = ? AND status = 'open' -- the from-state it read
|
|
141
|
+
RETURNING *;
|
|
142
|
+
|
|
143
|
+
-- stamp-only transition (checkIn, guard: { checkedInAt: { null: true } })
|
|
144
|
+
UPDATE guests SET checked_in_at = ?, checked_in_by_id = ?, …
|
|
145
|
+
WHERE <firewall> AND id = ? AND status = 'confirmed' AND checked_in_at IS NULL
|
|
146
|
+
RETURNING *;
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The WHERE pins the exact value the pre-check saw (a compare-and-set), which is
|
|
150
|
+
stricter than `status IN (<every from-state>)`: if a twin moved the row
|
|
151
|
+
between two legal source states, the stale request loses instead of acting on
|
|
152
|
+
a row it never checked. When two requests race:
|
|
153
|
+
|
|
154
|
+
- one UPDATE matches and wins (`200`);
|
|
155
|
+
- the other sees the new state in its pre-check (`409
|
|
156
|
+
ACCESS_ACTION_NOT_ALLOWED_FOR_STATE` / `onIllegal`), or matches no row at the
|
|
157
|
+
UPDATE (`409 ACCESS_TRANSITION_LOST`);
|
|
158
|
+
- with `idempotent: "noop"`, a request that loses to a twin that already
|
|
159
|
+
reached the target answers `{ success: true, unchanged: true }`, exactly as
|
|
160
|
+
if it had arrived second.
|
|
161
|
+
|
|
162
|
+
This holds for every table-level transition (the compiler always applies the
|
|
163
|
+
write) and every action-level `transition` with `stamp`, `clears`,
|
|
164
|
+
`applyBefore: true` or no `execute`. A hand-written `execute` that does its own
|
|
165
|
+
write must use `whereTransition(table)` in its WHERE and throw
|
|
166
|
+
`TransitionLostError` on an empty `RETURNING` — a write by `whereRecord` alone
|
|
167
|
+
is the race.
|
|
168
|
+
|
|
130
169
|
### On a feature-area route
|
|
131
170
|
|
|
132
171
|
A transition normally lives on a table-bound record action (`POST /:id/{action}`).
|
|
@@ -318,11 +318,12 @@ Response now carries the aggregations alongside `data`:
|
|
|
318
318
|
| `count` | optional | `COUNT(*)` if omitted, `COUNT(field)` (non-null) if given | `{ fn: 'count' }` |
|
|
319
319
|
| `count_distinct` | required | scalar number | `{ fn: 'count_distinct', field: 'sourceId' }` |
|
|
320
320
|
| `groupBy` | required | `{ value: count }` map | `{ fn: 'groupBy', field: 'status' }` |
|
|
321
|
+
| `rollup` | — (`groupBy`, `count`, `sum`) | array of bucket rows | `{ fn: 'rollup', groupBy: 'optionId', count: true, sum: ['weight'] }` |
|
|
321
322
|
|
|
322
323
|
`groupBy` always returns a count map keyed by the distinct values of `field`.
|
|
323
|
-
`NULL` values bucket under the literal string `"(none)"`.
|
|
324
|
-
|
|
325
|
-
|
|
324
|
+
`NULL` values bucket under the literal string `"(none)"`. To sum other
|
|
325
|
+
columns per bucket, use a [declared rollup](#declared-rollups-fn-rollup) on
|
|
326
|
+
an aggregate-only view.
|
|
326
327
|
|
|
327
328
|
### Filter and firewall inheritance
|
|
328
329
|
|
|
@@ -427,6 +428,79 @@ buckets ("1 guest, allergy = shellfish"):
|
|
|
427
428
|
row-returning views, where the aggregations ride alongside the rows and the
|
|
428
429
|
row firewall already governs disclosure.
|
|
429
430
|
|
|
431
|
+
### Declared rollups (`fn: 'rollup'`)
|
|
432
|
+
|
|
433
|
+
A rollup is the grouped aggregate an action would otherwise compute in
|
|
434
|
+
JavaScript — and actions can't run raw aggregates. It emits one firewalled
|
|
435
|
+
`SELECT <groupBy>, COUNT(*), SUM(<col>)… GROUP BY <groupBy>` over the view's
|
|
436
|
+
filtered set, and each returned row carries the bucket and its totals — never
|
|
437
|
+
a row id or a subject. A caller who may not read individual ballots can read
|
|
438
|
+
the tally if the view's `access` admits them:
|
|
439
|
+
|
|
440
|
+
```typescript
|
|
441
|
+
import { feature, q } from '@quickback/compiler';
|
|
442
|
+
|
|
443
|
+
export default feature('votes', {
|
|
444
|
+
columns: {
|
|
445
|
+
id: q.id(),
|
|
446
|
+
pollId: q.text().required(),
|
|
447
|
+
optionId: q.text().required(),
|
|
448
|
+
weight: q.int().default(1).required(),
|
|
449
|
+
organizationId: q.scope('organization'),
|
|
450
|
+
...q.audit(),
|
|
451
|
+
...q.softDelete(),
|
|
452
|
+
},
|
|
453
|
+
guards: { createable: ['pollId', 'optionId', 'weight'], updatable: [] },
|
|
454
|
+
read: {
|
|
455
|
+
access: { roles: ['admin'] }, // individual ballots: admins only
|
|
456
|
+
views: {
|
|
457
|
+
tally: {
|
|
458
|
+
aggregateOnly: true,
|
|
459
|
+
fields: [],
|
|
460
|
+
kMin: 1, // a poll tally may show single votes
|
|
461
|
+
access: { roles: ['member', 'admin'] },
|
|
462
|
+
query: { filterable: ['pollId'] },
|
|
463
|
+
aggregations: {
|
|
464
|
+
tally: { fn: 'rollup', groupBy: 'optionId', count: true, sum: ['weight'] },
|
|
465
|
+
},
|
|
466
|
+
},
|
|
467
|
+
},
|
|
468
|
+
},
|
|
469
|
+
create: { access: { roles: ['member', 'admin'] } },
|
|
470
|
+
update: { access: { roles: ['admin'] } },
|
|
471
|
+
delete: { access: { roles: ['admin'] }, mode: 'soft' },
|
|
472
|
+
});
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
`GET /api/v1/votes/views/tally?pollId=p1` returns:
|
|
476
|
+
|
|
477
|
+
```json
|
|
478
|
+
{
|
|
479
|
+
"view": "tally",
|
|
480
|
+
"aggregations": {
|
|
481
|
+
"tally": [
|
|
482
|
+
{ "optionId": "opt_a", "count": 12, "sum": { "weight": 15 } },
|
|
483
|
+
{ "optionId": "opt_b", "count": 7, "sum": { "weight": 7 } }
|
|
484
|
+
]
|
|
485
|
+
}
|
|
486
|
+
}
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
- `groupBy` names one column; `count: true` adds the bucket size; `sum` lists
|
|
490
|
+
numeric columns, returned under `sum`. At least one of `count` / `sum`.
|
|
491
|
+
- Only on `aggregateOnly: true` views — a rollup is its own surface, gated by
|
|
492
|
+
its own `access`, never a side-channel of a row view. `kMin` applies:
|
|
493
|
+
buckets smaller than k fold into one `"(other)"` row, and a non-empty set
|
|
494
|
+
smaller than k returns `"(suppressed)"`.
|
|
495
|
+
- **The bucket may not identify a subject.** Grouping by the primary key, the
|
|
496
|
+
owner column, a `q.stamp()` identity column, `createdBy` / `modifiedBy` /
|
|
497
|
+
`deletedBy`, a reference to the auth user table, or an encrypted column is
|
|
498
|
+
a compile error — one bucket per subject is a per-subject read.
|
|
499
|
+
- A masked `groupBy` or `sum` column needs every role that can reach the view
|
|
500
|
+
to be in its masking query roles (the `groupBy` / `min` / `max` rule
|
|
501
|
+
above), and at request time a caller who may not query one of them gets
|
|
502
|
+
`"(suppressed)"`.
|
|
503
|
+
|
|
430
504
|
## Response Format
|
|
431
505
|
|
|
432
506
|
View responses include metadata about the view:
|