@quickback-dev/cli 0.70.26 → 0.70.31
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.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/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.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/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 +1 -1
- 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.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/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.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/prepare-output.test.d.ts.map +1 -0
- package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
- package/dist/lib/schema-sync/index.test.d.ts.map +1 -0
- 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/configure/providers.md +3 -0
- package/dist/skill/docs/define/encryption.md +2 -2
- package/dist/skill/docs/define/read.md +6 -0
- package/dist/skill/docs/define/sealed-protocol.md +115 -10
- package/dist/skill/docs/platform/database/index.md +1 -0
- package/dist/skill/docs/platform/database/neon.md +86 -0
- package/dist/skill/docs/platform/database/planetscale-postgres.md +7 -0
- package/dist/skill/docs/platform/database/read-replication.md +122 -0
- package/dist/skill/docs/platform/database/using-d1.md +2 -1
- package/package.json +1 -1
- package/src/skill/docs/configure/providers.md +3 -0
- package/src/skill/docs/define/encryption.md +2 -2
- package/src/skill/docs/define/read.md +6 -0
- package/src/skill/docs/define/sealed-protocol.md +115 -10
- package/src/skill/docs/platform/database/index.md +1 -0
- package/src/skill/docs/platform/database/neon.md +86 -0
- package/src/skill/docs/platform/database/planetscale-postgres.md +7 -0
- package/src/skill/docs/platform/database/read-replication.md +122 -0
- package/src/skill/docs/platform/database/using-d1.md +2 -1
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Stale-file sweep for generated output trees.
|
|
3
|
+
*
|
|
4
|
+
* `src/` is hermetic — every file there is emitted by the compiler and
|
|
5
|
+
* carries the "Generated by quickback.dev" header. When a feature is
|
|
6
|
+
* removed/renamed or a generator stops emitting a file, the orphaned file
|
|
7
|
+
* lingers under merge-only writes and can mask bugs (dead routes, ghost
|
|
8
|
+
* imports, mismatched types, stale schemas the user assumes are current).
|
|
9
|
+
*
|
|
10
|
+
* This helper walks a target dir, deletes any file whose path isn't in the
|
|
11
|
+
* compiler's manifest *and* carries the generated-header marker, then
|
|
12
|
+
* collapses the empty directories left behind. Files without the marker are
|
|
13
|
+
* preserved (defence against accidentally nuking hand-authored content that
|
|
14
|
+
* snuck into a generated tree).
|
|
15
|
+
*
|
|
16
|
+
* Before any deletes, it copies the target dir into a timestamped archive
|
|
17
|
+
* under `archiveDir` (when provided). The archive is uncompressed (just a
|
|
18
|
+
* recursive copy via Node's built-in fs.cp) so it's trivially inspectable
|
|
19
|
+
* and recoverable with `cp -r`. Old archives beyond `archiveKeep` are
|
|
20
|
+
* pruned. The archive is skipped entirely on no-op compiles where no
|
|
21
|
+
* orphans were found.
|
|
22
|
+
*/
|
|
23
|
+
import { promises as fs } from 'fs';
|
|
24
|
+
import { join, relative, sep } from 'path';
|
|
25
|
+
const GENERATED_MARKER = 'Generated by quickback.dev';
|
|
26
|
+
const HEADER_PROBE_BYTES = 512;
|
|
27
|
+
const DEFAULT_ARCHIVE_KEEP = 3;
|
|
28
|
+
/**
|
|
29
|
+
* OS / editor noise that every contributor accidentally drops into checked-out
|
|
30
|
+
* trees. These files are *never* compiler output and *never* user-authored
|
|
31
|
+
* content the user cares about — silently skip them rather than warning the
|
|
32
|
+
* user every compile that ".DS_Store has no Quickback header".
|
|
33
|
+
*/
|
|
34
|
+
const SILENT_IGNORE_BASENAMES = new Set([
|
|
35
|
+
'.DS_Store',
|
|
36
|
+
'Thumbs.db',
|
|
37
|
+
'.localized',
|
|
38
|
+
]);
|
|
39
|
+
/**
|
|
40
|
+
* Sweep stale generated files under `targetDir`. Paths in `manifest` are
|
|
41
|
+
* relative to `outputDir` (matching the wire shape the compiler returns).
|
|
42
|
+
*/
|
|
43
|
+
export async function sweepStaleGeneratedFiles(outputDir, targetDir, manifest, options = {}) {
|
|
44
|
+
const result = { deleted: [], preserved: [] };
|
|
45
|
+
const fullTarget = join(outputDir, targetDir);
|
|
46
|
+
if (!(await pathExists(fullTarget)))
|
|
47
|
+
return result;
|
|
48
|
+
const manifestSet = new Set();
|
|
49
|
+
for (const p of manifest)
|
|
50
|
+
manifestSet.add(normalizePath(p));
|
|
51
|
+
const skipNormalized = [...(options.skipPrefixes ?? [])].map(normalizePath);
|
|
52
|
+
const isSkipped = (relPath) => skipNormalized.some((sp) => relPath === sp || relPath.startsWith(sp + '/'));
|
|
53
|
+
const onDisk = [];
|
|
54
|
+
await collectFiles(fullTarget, outputDir, onDisk);
|
|
55
|
+
// First pass: identify deletions without acting, so the archive captures
|
|
56
|
+
// the pre-delete state and runs only when there's something to lose.
|
|
57
|
+
const toDelete = [];
|
|
58
|
+
for (const relPath of onDisk) {
|
|
59
|
+
if (manifestSet.has(relPath))
|
|
60
|
+
continue;
|
|
61
|
+
if (isSkipped(relPath))
|
|
62
|
+
continue;
|
|
63
|
+
const base = relPath.slice(relPath.lastIndexOf('/') + 1);
|
|
64
|
+
if (SILENT_IGNORE_BASENAMES.has(base))
|
|
65
|
+
continue;
|
|
66
|
+
const fullPath = join(outputDir, relPath);
|
|
67
|
+
if (await fileHasMarker(fullPath, GENERATED_MARKER)) {
|
|
68
|
+
toDelete.push(relPath);
|
|
69
|
+
}
|
|
70
|
+
else {
|
|
71
|
+
result.preserved.push(relPath);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
if (toDelete.length === 0)
|
|
75
|
+
return result;
|
|
76
|
+
if (options.archiveDir) {
|
|
77
|
+
result.archivePath = await archiveDirectory(fullTarget, options.archiveDir, basename(targetDir));
|
|
78
|
+
await pruneArchives(options.archiveDir, basename(targetDir), options.archiveKeep ?? DEFAULT_ARCHIVE_KEEP);
|
|
79
|
+
}
|
|
80
|
+
for (const relPath of toDelete) {
|
|
81
|
+
await fs.unlink(join(outputDir, relPath));
|
|
82
|
+
result.deleted.push(relPath);
|
|
83
|
+
}
|
|
84
|
+
await removeEmptyDirs(fullTarget);
|
|
85
|
+
return result;
|
|
86
|
+
}
|
|
87
|
+
async function archiveDirectory(srcDir, archiveBase, prefix) {
|
|
88
|
+
const stamp = new Date().toISOString().replace(/[:.]/g, '-').replace(/Z$/, '');
|
|
89
|
+
const dest = join(archiveBase, `${prefix}-${stamp}`);
|
|
90
|
+
await fs.mkdir(archiveBase, { recursive: true });
|
|
91
|
+
// fs.cp with recursive copies the tree, preserves dir structure, no deps.
|
|
92
|
+
await fs.cp(srcDir, dest, { recursive: true, force: true });
|
|
93
|
+
return dest;
|
|
94
|
+
}
|
|
95
|
+
async function pruneArchives(archiveBase, prefix, keep) {
|
|
96
|
+
if (!(await pathExists(archiveBase)))
|
|
97
|
+
return;
|
|
98
|
+
const entries = await fs.readdir(archiveBase);
|
|
99
|
+
const stamped = entries.filter((e) => e.startsWith(`${prefix}-`)).sort().reverse();
|
|
100
|
+
const stale = stamped.slice(keep);
|
|
101
|
+
for (const old of stale) {
|
|
102
|
+
await fs.rm(join(archiveBase, old), { recursive: true, force: true }).catch(() => { });
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
async function pathExists(p) {
|
|
106
|
+
try {
|
|
107
|
+
await fs.access(p);
|
|
108
|
+
return true;
|
|
109
|
+
}
|
|
110
|
+
catch {
|
|
111
|
+
return false;
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
async function collectFiles(dir, outputDir, into) {
|
|
115
|
+
let entries;
|
|
116
|
+
try {
|
|
117
|
+
entries = await fs.readdir(dir, { withFileTypes: true });
|
|
118
|
+
}
|
|
119
|
+
catch {
|
|
120
|
+
return;
|
|
121
|
+
}
|
|
122
|
+
for (const entry of entries) {
|
|
123
|
+
const full = join(dir, entry.name);
|
|
124
|
+
if (entry.isDirectory()) {
|
|
125
|
+
await collectFiles(full, outputDir, into);
|
|
126
|
+
}
|
|
127
|
+
else if (entry.isFile()) {
|
|
128
|
+
into.push(normalizePath(relative(outputDir, full)));
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
async function fileHasMarker(path, marker) {
|
|
133
|
+
let handle = null;
|
|
134
|
+
try {
|
|
135
|
+
handle = await fs.open(path, 'r');
|
|
136
|
+
const buf = Buffer.alloc(HEADER_PROBE_BYTES);
|
|
137
|
+
const { bytesRead } = await handle.read(buf, 0, HEADER_PROBE_BYTES, 0);
|
|
138
|
+
return buf.subarray(0, bytesRead).toString('utf8').includes(marker);
|
|
139
|
+
}
|
|
140
|
+
catch {
|
|
141
|
+
return false;
|
|
142
|
+
}
|
|
143
|
+
finally {
|
|
144
|
+
if (handle)
|
|
145
|
+
await handle.close();
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
async function removeEmptyDirs(dir) {
|
|
149
|
+
let entries;
|
|
150
|
+
try {
|
|
151
|
+
entries = await fs.readdir(dir, { withFileTypes: true });
|
|
152
|
+
}
|
|
153
|
+
catch {
|
|
154
|
+
return;
|
|
155
|
+
}
|
|
156
|
+
for (const entry of entries) {
|
|
157
|
+
if (entry.isDirectory()) {
|
|
158
|
+
await removeEmptyDirs(join(dir, entry.name));
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
try {
|
|
162
|
+
const after = await fs.readdir(dir);
|
|
163
|
+
if (after.length === 0) {
|
|
164
|
+
await fs.rmdir(dir).catch(() => { });
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
catch {
|
|
168
|
+
/* ignore */
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
function normalizePath(p) {
|
|
172
|
+
return sep === '/' ? p : p.split(sep).join('/');
|
|
173
|
+
}
|
|
174
|
+
function basename(p) {
|
|
175
|
+
const norm = normalizePath(p).replace(/\/+$/, '');
|
|
176
|
+
const idx = norm.lastIndexOf('/');
|
|
177
|
+
return idx >= 0 ? norm.slice(idx + 1) : norm;
|
|
178
|
+
}
|
|
179
|
+
//# sourceMappingURL=sweep-stale.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sweep-stale.js","sourceRoot":"","sources":["../../src/lib/sweep-stale.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sweep-stale.test.d.ts","sourceRoot":"","sources":["../../src/lib/sweep-stale.test.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"wrangler-resources.test.d.ts","sourceRoot":"","sources":["../../src/lib/wrangler-resources.test.ts"],"names":[],"mappings":""}
|
|
@@ -110,6 +110,7 @@ single Postgres database with no bindings or split mode (see
|
|
|
110
110
|
| `usePlurals` | `boolean` | `false` (`true` on Neon / PlanetScale Postgres) | Pluralize auth table names (e.g. `user` vs `users`). The default differs by provider — porting a D1 project to Postgres, set `usePlurals: false` explicitly to keep its table names |
|
|
111
111
|
| `splitDatabases` | `boolean` | `true` | Separate auth and features databases (D1 only) |
|
|
112
112
|
| `queryTimeoutMs` | `number` | — | Per-statement deadline for every D1 query the generated code runs (CRUD, actions, the auth adapter, cron/queue/email runners, files, audit). Unset = no deadline. D1 only — the Postgres drivers have their own timeout options. Past the deadline a read answers `503 DB_TIMEOUT` and a write `500 DB_WRITE_OUTCOME_UNKNOWN`; see [Backend stalls](/platform/database/using-d1#backend-stalls) and [Database errors](/api/errors#database-constraint-errors). The statement is **not** cancelled on the backend |
|
|
113
|
+
| `readReplication` | `boolean \| { header?: string }` | — | Run each request's feature `db` on a D1 session so regional read replicas can serve it. `GET`/`HEAD` continue the client's session from the bookmark header (default `x-d1-bookmark`) or start `first-unconstrained`; other methods start `first-primary`. The response echoes the bookmark. D1 only; auth/audit/webhooks and cron/queue/email runners stay on the primary. Enable replication on the database itself in the Cloudflare dashboard — see [Read replication](/platform/database/read-replication) |
|
|
113
114
|
| `authBinding` | `string` | `"AUTH_DB"` | Binding name for auth database |
|
|
114
115
|
| `featuresBinding` | `string` | `"DB"` | Binding name for features database |
|
|
115
116
|
| `databaseId` | `string` | — | D1 database ID for the features database (used in generated wrangler.toml) |
|
|
@@ -132,6 +133,8 @@ single Postgres database with no bindings or split mode (see
|
|
|
132
133
|
| `connectionMode` | `"auto" \| "http" \| "websocket" \| "hyperdrive"` | `"auto"` | How the generated runtime connects (`hyperdrive` enables interactive Postgres transactions on Workers) |
|
|
133
134
|
| `hyperdrive.id` | `string` | — | Required Cloudflare Hyperdrive configuration ID when `connectionMode: "hyperdrive"` |
|
|
134
135
|
| `hyperdrive.localConnectionString` | `string` | — | Optional local-only Postgres connection used by Wrangler dev |
|
|
136
|
+
| `hyperdrive.cached.id` | `string` | — | Second Hyperdrive config with query caching **on**, bound as `HYPERDRIVE_CACHED` and connecting as the read-only `quickback_reader` role. Required when any resource declares `read: { cache: "hyperdrive" }` — see [Cached public reads](/platform/database/neon#cached-public-reads-a-second-hyperdrive-binding) |
|
|
137
|
+
| `hyperdrive.cached.localConnectionString` | `string` | — | The reader role's local URL for Wrangler dev; required whenever `hyperdrive.localConnectionString` is set |
|
|
135
138
|
| `pooled` | `boolean` | `true` | Use the pooled Neon connection string (recommended for Workers) |
|
|
136
139
|
| `usePlurals` | `boolean` | `true` | Auth table names (`users`, `members`, …). **The D1 default is `false`** — a project moving from D1 must set `usePlurals: false` to keep `user`, `member`, … |
|
|
137
140
|
|
|
@@ -200,7 +200,7 @@ Behind that one call:
|
|
|
200
200
|
5. **`/seal/v1/key`** (bearer that capability) passes three fail-closed gates — tenant, capability, live-grant — and returns the still-wrapped content key.
|
|
201
201
|
6. The client unwraps the scope key, unwraps the content key, and decrypts. **None of this touches the server with a readable key.**
|
|
202
202
|
|
|
203
|
-
Passkey reveal is the same call as `revealWithPasskey({ ..., getAssertion })`, where `getAssertion(nonce)` runs the WebAuthn ceremony.
|
|
203
|
+
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
204
|
|
|
205
205
|
## Rules the compiler enforces
|
|
206
206
|
|
|
@@ -218,7 +218,7 @@ Sealed values are opaque references at rest, so they're fenced off from every su
|
|
|
218
218
|
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
219
|
|
|
220
220
|
- **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
|
|
221
|
+
- **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
222
|
- **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
223
|
- **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
224
|
- **Passkey rollout check.** The server verification path and nonce-bound
|
|
@@ -91,6 +91,12 @@ interface ReadConfig {
|
|
|
91
91
|
// `firewall` block is used (the common case).
|
|
92
92
|
firewall?: FirewallConfig;
|
|
93
93
|
|
|
94
|
+
// Serve reads through Cloudflare Hyperdrive's query cache (Postgres over
|
|
95
|
+
// Hyperdrive only). Public, tenant-free data: requires
|
|
96
|
+
// `firewall: { exception: true }`, a roles-only access admitting PUBLIC,
|
|
97
|
+
// and the HYPERDRIVE_CACHED binding. See Neon → Cached public reads.
|
|
98
|
+
cache?: "hyperdrive";
|
|
99
|
+
|
|
94
100
|
// Pagination defaults for collection reads.
|
|
95
101
|
pageSize?: number; // Default page size (default: 50)
|
|
96
102
|
maxPageSize?: number; // Hard cap (default: 100)
|
|
@@ -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
|
|
|
@@ -103,7 +104,10 @@ and on `.returning()` alike. That's the type-level face of "the server is
|
|
|
103
104
|
structurally unable to read it": at rest the column only ever holds a
|
|
104
105
|
`{ __vaultRef }` marker, and the brand keeps action code from string-processing
|
|
105
106
|
or hand-forwarding that marker. Sealed values leave the system exclusively
|
|
106
|
-
through the `/seal/v1` reveal rails below.
|
|
107
|
+
through the `/seal/v1` reveal rails below. On D1 the column is emitted as
|
|
108
|
+
Drizzle JSON-mode text (`text(name, { mode: 'json' })`), so the marker is
|
|
109
|
+
stored as JSON and reads back as the `{ __vaultRef, vaultItemId }` object; the
|
|
110
|
+
SQL type stays `TEXT`. (Envelope `.encrypted()` columns are
|
|
107
111
|
deliberately *not* branded — they type as `string` because the server can
|
|
108
112
|
decrypt that tier; an action reading one gets `qbenc:` ciphertext.)
|
|
109
113
|
|
|
@@ -240,22 +244,32 @@ A reader who has a role for a scope but no grant publishes their X25519 USER pub
|
|
|
240
244
|
```
|
|
241
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.
|
|
242
246
|
|
|
243
|
-
### 12. `/recovery/enroll` — escrow the scope key under a recovery
|
|
247
|
+
### 12. `/recovery/enroll` — escrow the scope key under a recovery factor (key-admin)
|
|
244
248
|
|
|
245
|
-
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 |
|
|
246
257
|
|
|
247
258
|
```jsonc
|
|
248
|
-
// → { scopeRef, wrappedPrivateKey: "<qbseal envelope,
|
|
249
|
-
// ← { 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" }
|
|
250
261
|
```
|
|
251
262
|
|
|
252
|
-
### 13. `/recovery/use` — retrieve the recovery blob (key-admin)
|
|
263
|
+
### 13. `/recovery/use` — retrieve the recovery blob(s) (key-admin)
|
|
253
264
|
|
|
254
|
-
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.
|
|
255
268
|
|
|
256
269
|
```jsonc
|
|
257
|
-
// → { scopeRef }
|
|
258
|
-
// ← { 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
|
|
259
273
|
```
|
|
260
274
|
|
|
261
275
|
#### role→grant: readers request, key-admins fulfil
|
|
@@ -271,10 +285,99 @@ When the passkey plugin is enabled, `/reveal` verifies a WebAuthn assertion whos
|
|
|
271
285
|
| `challenge` | the `/challenge` `nonce` **as the base64url string** (the client signs the b64url text, the server passes `expectedChallenge = nonce`) |
|
|
272
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) |
|
|
273
287
|
| `userVerification` | **required** (`requireUserVerification: true` — a reveal is a deliberate re-auth) |
|
|
274
|
-
| 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>`) |
|
|
275
289
|
|
|
276
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.
|
|
277
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
|
+
|
|
278
381
|
## Conformance vectors
|
|
279
382
|
|
|
280
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.
|
|
@@ -288,6 +391,8 @@ Canonical vectors live at **`packages/seal-client/vectors/qbseal-v1.json`**, gen
|
|
|
288
391
|
| `sealedBoxOpen` | recipient secret + box → plaintext | open-direction (canonical) |
|
|
289
392
|
| `reveal` | passphrase → keys; owner + scope unwrap paths → plaintext | open-direction (canonical) |
|
|
290
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) |
|
|
291
396
|
|
|
292
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.
|
|
293
398
|
|
|
@@ -29,5 +29,6 @@ security definitions compile to either provider.
|
|
|
29
29
|
|
|
30
30
|
- **[D1 Setup](/platform/database/d1)** — Bindings, wrangler config, migrations
|
|
31
31
|
- **[Using D1](/platform/database/using-d1)** — Drizzle queries, dual-DB mode, schema patterns
|
|
32
|
+
- **[Read replication](/platform/database/read-replication)** — Serve reads from D1's regional replicas with the Sessions API
|
|
32
33
|
- **[Neon](/platform/database/neon)** — Serverless Postgres setup and usage
|
|
33
34
|
- **[PlanetScale Postgres](/platform/database/planetscale-postgres)** — Roles, connection usernames, the cache-disabled Hyperdrive binding
|
|
@@ -348,6 +348,92 @@ to your concurrency, not your statement count. Raise it later with
|
|
|
348
348
|
suspend pays the compute start. Lengthen or disable autosuspend on the
|
|
349
349
|
production branch.
|
|
350
350
|
|
|
351
|
+
### Cached public reads: a second Hyperdrive binding
|
|
352
|
+
|
|
353
|
+
Hyperdrive's query cache keys on query text and parameters alone and never
|
|
354
|
+
invalidates on write, so it cannot sit under the claims-scoped `HYPERDRIVE`
|
|
355
|
+
binding. It can serve **public, tenant-free** data through a second binding
|
|
356
|
+
whose database role can see nothing else. Opt a resource in with
|
|
357
|
+
`read.cache`:
|
|
358
|
+
|
|
359
|
+
{/* doc-compile: skip — read.cache fails closed without hyperdrive.cached on the project config, which the doc harness's default project does not declare. */}
|
|
360
|
+
```ts
|
|
361
|
+
// features/venues/venues.ts
|
|
362
|
+
import { q, defineTable } from "@quickback/compiler";
|
|
363
|
+
|
|
364
|
+
export const venues = q.table("venues", {
|
|
365
|
+
id: q.id(),
|
|
366
|
+
name: q.text().required(),
|
|
367
|
+
city: q.text().required(),
|
|
368
|
+
...q.audit(),
|
|
369
|
+
...q.softDelete(),
|
|
370
|
+
});
|
|
371
|
+
|
|
372
|
+
export default defineTable(venues, {
|
|
373
|
+
firewall: { exception: true },
|
|
374
|
+
read: {
|
|
375
|
+
access: { roles: ["PUBLIC"] },
|
|
376
|
+
cache: "hyperdrive",
|
|
377
|
+
},
|
|
378
|
+
});
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
`GET /api/v1/venues`, `GET /api/v1/venues/:id` and its named views then read
|
|
382
|
+
through `HYPERDRIVE_CACHED` as `quickback_reader`, a role the security
|
|
383
|
+
migration creates with one privilege: `SELECT` on the tables that declared
|
|
384
|
+
`read.cache`, each with a `USING (true)` SELECT policy for that role. The
|
|
385
|
+
cache can only ever hold rows that role can read, so cache safety is
|
|
386
|
+
structural, not a property of any query. Everything else (writes, actions,
|
|
387
|
+
every other table) stays on `HYPERDRIVE`.
|
|
388
|
+
|
|
389
|
+
The compiler refuses `read.cache` unless all of these hold:
|
|
390
|
+
|
|
391
|
+
- Postgres over Hyperdrive on the Cloudflare runtime.
|
|
392
|
+
- `hyperdrive.cached: { id }` on the provider config, or
|
|
393
|
+
`bindings.hyperdrive.cached` on every named environment.
|
|
394
|
+
- `firewall: { exception: true }` — no tenant or owner row filter.
|
|
395
|
+
- `read.access` is a roles-only tree that admits `PUBLIC`. Record predicates,
|
|
396
|
+
relationship / permission arms, principals and function-form access are
|
|
397
|
+
rejected.
|
|
398
|
+
- No FK display columns and no `include` on the resource — the reader role
|
|
399
|
+
holds no grant on other tables.
|
|
400
|
+
|
|
401
|
+
Masking still applies per caller after the query. Reads can be stale for up
|
|
402
|
+
to the cached config's `max_age` (default 60 s, `--max-age` to change it;
|
|
403
|
+
`--swr` extends serving-while-revalidating). `Server-Timing` counts these
|
|
404
|
+
statements and the cached connection's open under `stmts` / `cold`.
|
|
405
|
+
|
|
406
|
+
Set it up once per database:
|
|
407
|
+
|
|
408
|
+
```bash
|
|
409
|
+
# 1. The security migration created quickback_reader NOLOGIN; give it a login.
|
|
410
|
+
psql "$DATABASE_SETUP_URL" -c "ALTER ROLE quickback_reader LOGIN PASSWORD '<reader-password>';"
|
|
411
|
+
|
|
412
|
+
# 2. A second Hyperdrive config, caching ON, as that role.
|
|
413
|
+
npx wrangler hyperdrive create my-app-db-cached \
|
|
414
|
+
--max-age 60 \
|
|
415
|
+
--connection-string="postgresql://quickback_reader:<reader-password>@<endpoint>.<region>.aws.neon.tech/neondb?sslmode=require"
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
```ts
|
|
419
|
+
database: defineDatabase("neon", {
|
|
420
|
+
connectionMode: "hyperdrive",
|
|
421
|
+
hyperdrive: {
|
|
422
|
+
id: "<hyperdrive-config-id>",
|
|
423
|
+
cached: { id: "<cached-config-id>" },
|
|
424
|
+
},
|
|
425
|
+
}),
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
With named environments, declare `bindings.hyperdrive.cached: { id }` on
|
|
429
|
+
every target; the `dev` target also needs
|
|
430
|
+
`cached.localConnectionString` (the reader role's local URL), as does the
|
|
431
|
+
provider-level `hyperdrive.cached` whenever `hyperdrive.localConnectionString`
|
|
432
|
+
is set — `wrangler dev` connects the cached binding as `quickback_reader`,
|
|
433
|
+
and the `quickback` role's URL reads nothing through it. The emitted
|
|
434
|
+
`createCachedDb(env)` is read-only by construction: a write or a
|
|
435
|
+
`db.transaction()` on it throws before reaching the database.
|
|
436
|
+
|
|
351
437
|
For local `wrangler dev` without named environments, set
|
|
352
438
|
`providers.database.config.hyperdrive.localConnectionString` to a local or
|
|
353
439
|
development-only Postgres URL. With named environments, put it on the target
|
|
@@ -206,6 +206,13 @@ project sets neither. The rest of the tuning notes — the session cookie cache
|
|
|
206
206
|
and connection limits — are on
|
|
207
207
|
[Neon → Tuning the Worker for Hyperdrive](/platform/database/neon#tuning-the-worker-for-hyperdrive).
|
|
208
208
|
|
|
209
|
+
Public, tenant-free resources can opt into Hyperdrive's query cache with
|
|
210
|
+
`read: { cache: "hyperdrive" }` through a second binding and the read-only
|
|
211
|
+
`quickback_reader` role — see
|
|
212
|
+
[Cached public reads](/platform/database/neon#cached-public-reads-a-second-hyperdrive-binding).
|
|
213
|
+
On PlanetScale the reader's connection username is the role name plus the
|
|
214
|
+
branch id, `quickback_reader.<branch_id>`, like the other roles.
|
|
215
|
+
|
|
209
216
|
## What is shared with Neon, and what is not
|
|
210
217
|
|
|
211
218
|
Shared — read the Neon page for the detail, it is the same generated output:
|