@quickback-dev/cli 0.72.6 → 0.72.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/migrations-baseline.d.ts +2 -0
- package/dist/commands/migrations-baseline.d.ts.map +1 -0
- package/dist/commands/migrations-baseline.js +29 -0
- package/dist/commands/migrations-baseline.js.map +1 -0
- package/dist/commands/migrations.d.ts.map +1 -1
- package/dist/commands/migrations.js +16 -9
- package/dist/commands/migrations.js.map +1 -1
- package/dist/index.js +2 -2
- package/dist/lib/migrations/baseline.d.ts +26 -0
- package/dist/lib/migrations/baseline.d.ts.map +1 -0
- package/dist/lib/migrations/baseline.js +258 -0
- package/dist/lib/migrations/baseline.js.map +1 -0
- package/dist/lib/migrations/sqlite-baseline-worker.d.ts +3 -0
- package/dist/lib/migrations/sqlite-baseline-worker.d.ts.map +1 -0
- package/dist/lib/migrations/sqlite-baseline-worker.js +86 -0
- package/dist/lib/migrations/sqlite-baseline-worker.js.map +1 -0
- package/dist/skill/docs/api/actions.md +37 -1
- package/dist/skill/docs/api/openapi.md +2 -0
- package/dist/skill/docs/api/views.md +5 -1
- package/dist/skill/docs/changelog/index.md +29 -0
- package/dist/skill/docs/configure/agents.md +16 -0
- package/dist/skill/docs/define/access.md +2 -0
- package/dist/skill/docs/define/encryption.md +1 -1
- package/dist/skill/docs/define/scopes.md +1 -1
- package/dist/skill/docs/define/views.md +8 -0
- package/dist/skill/docs/platform/auth/index.md +10 -1
- package/dist/skill/docs/platform/auth/security.md +16 -0
- package/dist/skill/docs/platform/database/schema-baselines.md +86 -0
- package/dist/skill/docs/tooling/cli.md +13 -0
- package/dist/skill/docs/tooling/cloud-compiler/authentication.md +2 -0
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +19 -1
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +37 -1
- package/src/skill/docs/api/openapi.md +2 -0
- package/src/skill/docs/api/views.md +5 -1
- package/src/skill/docs/changelog/index.md +29 -0
- package/src/skill/docs/configure/agents.md +16 -0
- package/src/skill/docs/define/access.md +2 -0
- package/src/skill/docs/define/encryption.md +1 -1
- package/src/skill/docs/define/scopes.md +1 -1
- package/src/skill/docs/define/views.md +8 -0
- package/src/skill/docs/platform/auth/index.md +10 -1
- package/src/skill/docs/platform/auth/security.md +16 -0
- package/src/skill/docs/platform/database/schema-baselines.md +86 -0
- package/src/skill/docs/tooling/cli.md +13 -0
- package/src/skill/docs/tooling/cloud-compiler/authentication.md +2 -0
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +19 -1
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
/** Isolated Node process: the CLI stays compatible with Node 18; this opt-in command needs Node 22.13+. */
|
|
2
|
+
export const SQLITE_BASELINE_WORKER = String.raw `
|
|
3
|
+
import { DatabaseSync } from 'node:sqlite';
|
|
4
|
+
import { readFileSync } from 'node:fs';
|
|
5
|
+
import { createRequire } from 'node:module';
|
|
6
|
+
const input = JSON.parse(readFileSync(0, 'utf8'));
|
|
7
|
+
const ident = value => '"' + value.replaceAll('"', '""') + '"';
|
|
8
|
+
const literal = value => value === null ? 'NULL' : typeof value === 'string' ? (value.includes("\0") || value.includes("--> statement-breakpoint") ? "CAST(X'" + Buffer.from(value).toString('hex') + "' AS TEXT)" : "'" + value.replaceAll("'", "''") + "'") : value instanceof Uint8Array ? "X'" + Buffer.from(value).toString('hex') + "'" : String(value);
|
|
9
|
+
const catalog = db => db.prepare("SELECT type, name, tbl_name, sql FROM sqlite_schema WHERE sql IS NOT NULL AND substr(name, 1, 7) <> 'sqlite_' ORDER BY type, name").all();
|
|
10
|
+
const rows = (db, table) => {
|
|
11
|
+
const columns = db.prepare('PRAGMA table_xinfo(' + ident(table) + ')').all().filter(c => c.hidden === 0).map(c => c.name);
|
|
12
|
+
// Read text/blob bytes through hex(): node:sqlite's native text conversion can
|
|
13
|
+
// truncate embedded NULs. SQL quote() preserves exact 64-bit numeric values.
|
|
14
|
+
const fields = columns.flatMap((c,i)=>['typeof('+ident(c)+') AS t'+i, 'CASE WHEN typeof('+ident(c)+") IN ('text','blob') THEN hex("+ident(c)+') ELSE quote('+ident(c)+') END AS v'+i]);
|
|
15
|
+
const query = db.prepare('SELECT ' + fields.join(', ') + ' FROM ' + ident(table));
|
|
16
|
+
return {columns, values: query.all().map(row => columns.map((c,i) => row['t'+i] === 'text' ? "CAST(X'"+row['v'+i]+"' AS TEXT)" : row['t'+i] === 'blob' ? "X'"+row['v'+i]+"'" : row['v'+i])).sort((a,b) => JSON.stringify(a).localeCompare(JSON.stringify(b)))};
|
|
17
|
+
};
|
|
18
|
+
const state = db => ({catalog: catalog(db), rows: Object.fromEntries(catalog(db).filter(o => o.type === 'table').map(t => [t.name, rows(db,t.name)])), sequence: db.prepare("SELECT name FROM sqlite_schema WHERE name = 'sqlite_sequence'").get() ? db.prepare('SELECT name, CAST(seq AS TEXT) AS seq, typeof(seq) AS storageType FROM sqlite_sequence ORDER BY name').all() : []});
|
|
19
|
+
const db = new DatabaseSync(':memory:', {enableForeignKeyConstraints:false});
|
|
20
|
+
for (const migration of input.migrations) {
|
|
21
|
+
// Migration SQL is trusted project code, but must not attach or export files during an offline replay.
|
|
22
|
+
const tokens = migration.replace(/--[^\n]*|\/\*[\s\S]*?\*\/|'(?:''|[^'])*'|"(?:""|[^"])*"|\x60[^\x60]*\x60|\[[^\]]*\]/g, ' ');
|
|
23
|
+
if (/\b(?:ATTACH|DETACH|VACUUM|load_extension)\b/i.test(tokens)) throw new Error('Baseline replay refuses external-database or extension operations');
|
|
24
|
+
db.exec('BEGIN;');
|
|
25
|
+
db.exec(migration);
|
|
26
|
+
db.exec('COMMIT;');
|
|
27
|
+
}
|
|
28
|
+
const original = state(db);
|
|
29
|
+
if (original.catalog.some(o => /^CREATE\s+VIRTUAL\s+TABLE/i.test(o.sql))) throw new Error('Virtual tables require a provider-specific baseline; refusing');
|
|
30
|
+
if (original.catalog.some(o => ['d1_migrations','_cf_METADATA','__drizzle_migrations'].includes(o.name))) throw new Error('Migration SQL must not own platform migration metadata');
|
|
31
|
+
if (db.prepare('PRAGMA foreign_key_check').all().length) throw new Error('Original migration history has foreign-key violations');
|
|
32
|
+
// Let the project's pinned Drizzle validate its snapshot and lower it to SQL.
|
|
33
|
+
// Compare its physical contract to the replay, including defaults, keys and indexes.
|
|
34
|
+
const {generateSQLiteMigration} = createRequire(import.meta.url)(input.drizzleApiPath);
|
|
35
|
+
const snapshotDb = new DatabaseSync(':memory:');
|
|
36
|
+
const empty = {...input.snapshot, tables:{}, views:{}, enums:{}, _meta:{schemas:{},tables:{},columns:{}}};
|
|
37
|
+
for (const sql of await generateSQLiteMigration(empty, input.snapshot)) snapshotDb.exec(sql);
|
|
38
|
+
const tableNames = db => catalog(db).filter(o=>o.type==='table').map(o=>o.name).sort();
|
|
39
|
+
if (!original.catalog.length) throw new Error('An empty schema does not need a baseline');
|
|
40
|
+
if (JSON.stringify(tableNames(db)) !== JSON.stringify(tableNames(snapshotDb))) throw new Error('Latest Drizzle snapshot tables do not match the replayed schema');
|
|
41
|
+
const sorted = rows => rows.sort((a,b)=>JSON.stringify(a).localeCompare(JSON.stringify(b)));
|
|
42
|
+
const sqlTokens = sql => (sql.match(/--[^\n]*|\/\*[\s\S]*?\*\/|'(?:''|[^'])*'|"(?:""|[^"])*"|\x60[^\x60]*\x60|\[[^\]]*\]|[a-zA-Z_][a-zA-Z_0-9]*|[^\s]/g) ?? []).filter(t=>!t.startsWith('--')&&!t.startsWith('/*')).map(t=>t.startsWith("'")?t:/^[a-zA-Z_"]|^\x60|^\[/.test(t)?'i:'+t.replace(/^["\x60\[]|["\x60\]]$/g,'').toLowerCase():t);
|
|
43
|
+
const checks = sql => {const tokens=sqlTokens(sql),result=[];for(let i=0;i<tokens.length;i++){if(tokens[i]!=='i:check'||tokens[i+1]!=='(')continue;let depth=0,j=i+1;for(;j<tokens.length;j++){if(tokens[j]==='(')depth++;if(tokens[j]===')'&&--depth===0)break;}result.push(JSON.stringify(tokens.slice(i+1,j+1)));}return result;};
|
|
44
|
+
const columns = (db,name) => db.prepare('PRAGMA table_xinfo('+ident(name)+')').all().map(c=>[c.name,c.type.toLowerCase(),c.notnull,c.pk,c.hidden,c.dflt_value]);
|
|
45
|
+
const fks = (db,name) => sorted(db.prepare('PRAGMA foreign_key_list('+ident(name)+')').all().map(({id,...rest})=>rest));
|
|
46
|
+
for (const name of tableNames(snapshotDb)) {
|
|
47
|
+
const actualTable=db.prepare("SELECT sql FROM sqlite_schema WHERE type='table' AND name=?").get(name).sql;
|
|
48
|
+
const expectedTable=snapshotDb.prepare("SELECT sql FROM sqlite_schema WHERE type='table' AND name=?").get(name).sql;
|
|
49
|
+
if(checks(expectedTable).some(c=>!checks(actualTable).includes(c))) throw new Error('Latest Drizzle snapshot CHECK constraint differs: '+name);
|
|
50
|
+
if (JSON.stringify(columns(db,name))!==JSON.stringify(columns(snapshotDb,name)) || JSON.stringify(fks(db,name))!==JSON.stringify(fks(snapshotDb,name))) throw new Error('Latest Drizzle snapshot column or foreign-key contract differs: '+name);
|
|
51
|
+
for (const index of snapshotDb.prepare('PRAGMA index_list('+ident(name)+')').all()) {
|
|
52
|
+
const actual = db.prepare('PRAGMA index_list('+ident(name)+')').all().find(i=>i.name===index.name);
|
|
53
|
+
const expectedSql=snapshotDb.prepare("SELECT sql FROM sqlite_schema WHERE type='index' AND name=?").get(index.name)?.sql;
|
|
54
|
+
const actualSql=db.prepare("SELECT sql FROM sqlite_schema WHERE type='index' AND name=?").get(index.name)?.sql;
|
|
55
|
+
if (expectedSql && (!actualSql || JSON.stringify(sqlTokens(expectedSql))!==JSON.stringify(sqlTokens(actualSql)))) throw new Error('Latest Drizzle snapshot index expression differs: '+index.name);
|
|
56
|
+
if (!actual || actual.unique!==index.unique || actual.partial!==index.partial || JSON.stringify(db.prepare('PRAGMA index_xinfo('+ident(index.name)+')').all())!==JSON.stringify(snapshotDb.prepare('PRAGMA index_xinfo('+ident(index.name)+')').all())) throw new Error('Latest Drizzle snapshot index differs: '+index.name);
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
// Keep the latest compiler-owned trigger document as a second migration. Its
|
|
60
|
+
// content hash and recognizable filename preserve trigger dedupe/removal on the next build.
|
|
61
|
+
const objects = original.catalog.filter(o => !(input.triggerSql && o.type === 'trigger' && o.name.startsWith('qb_trg_')));
|
|
62
|
+
const order = {table:0,index:1,view:2,trigger:3};
|
|
63
|
+
objects.sort((a,b) => order[a.type]-order[b.type] || a.name.localeCompare(b.name));
|
|
64
|
+
if (objects.some(o=>o.sql.includes('--> statement-breakpoint'))) throw new Error('Schema SQL contains a reserved Drizzle statement separator');
|
|
65
|
+
const statements = ['PRAGMA defer_foreign_keys = ON;', ...objects.filter(o=>o.type!=='trigger').map(o=>o.sql+';')];
|
|
66
|
+
let seedRows = 0;
|
|
67
|
+
for (const [name, data] of Object.entries(original.rows)) for (const values of data.values) {
|
|
68
|
+
statements.push('INSERT INTO ' + ident(name) + ' (' + data.columns.map(ident).join(', ') + ') VALUES (' + values.join(', ') + ');'); seedRows++;
|
|
69
|
+
}
|
|
70
|
+
if (original.sequence.length) {
|
|
71
|
+
for(const seq of original.sequence) if(seq.storageType !== 'integer' || !/^-?\d+$/.test(seq.seq) || !Object.hasOwn(original.rows,seq.name)) throw new Error('Unsupported sqlite_sequence state; refusing unsafe baseline');
|
|
72
|
+
statements.push('DELETE FROM sqlite_sequence WHERE name IN (' + original.sequence.map(seq=>literal(seq.name)).join(', ') + ');');
|
|
73
|
+
for (const seq of original.sequence) statements.push('INSERT INTO sqlite_sequence (name, seq) VALUES (' + literal(seq.name) + ', ' + seq.seq + ');');
|
|
74
|
+
}
|
|
75
|
+
statements.push(...objects.filter(o=>o.type==='trigger').map(o=>o.sql+';'));
|
|
76
|
+
const sql = '-- Quickback D1 baseline: generated by replaying the complete local migration history.\n' + statements.join('\n--> statement-breakpoint\n') + '\n';
|
|
77
|
+
const fresh = new DatabaseSync(':memory:');
|
|
78
|
+
fresh.exec('PRAGMA foreign_keys = ON; BEGIN;');
|
|
79
|
+
fresh.exec(sql);
|
|
80
|
+
if (input.triggerSql) fresh.exec(input.triggerSql);
|
|
81
|
+
fresh.exec('COMMIT;');
|
|
82
|
+
if (JSON.stringify(state(fresh)) !== JSON.stringify(original)) throw new Error('Baseline replay differs from original schema, triggers, seed data or sequences');
|
|
83
|
+
if (fresh.prepare('PRAGMA foreign_key_check').all().length) throw new Error('Baseline has foreign-key violations');
|
|
84
|
+
process.stdout.write(JSON.stringify({sql, catalog:original.catalog, seedRows}));
|
|
85
|
+
`;
|
|
86
|
+
//# sourceMappingURL=sqlite-baseline-worker.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sqlite-baseline-worker.js","sourceRoot":"","sources":["../../../src/lib/migrations/sqlite-baseline-worker.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAC3G,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmF/C,CAAC"}
|
|
@@ -272,7 +272,43 @@ Why this is safer than hand-rolling `organizationId` on every query:
|
|
|
272
272
|
- Soft-delete and team-isolation filters continue to apply unchanged.
|
|
273
273
|
- No chance of forgetting a `WHERE organizationId = ?` clause on a single query.
|
|
274
274
|
|
|
275
|
-
`x-unsafe: true` is emitted on each unsafe operation in `openapi.json`, and MCP
|
|
275
|
+
`x-unsafe: true` is emitted on each unsafe operation in `openapi.json`, and MCP tools carry an internal `_unsafe` flag (the public description never says why the action is privileged). `unsafe` does not change the tool's behaviour hints — declare those with `mcp` (see [MCP tool title and hints](#mcp-tool-title-and-hints)).
|
|
276
|
+
|
|
277
|
+
## MCP tool title and hints
|
|
278
|
+
|
|
279
|
+
Every action becomes an MCP tool. Agent hosts (Claude, ChatGPT) show the tool's
|
|
280
|
+
`title` and use three hints to decide when to ask the user before calling it.
|
|
281
|
+
Declare them next to the description:
|
|
282
|
+
|
|
283
|
+
```typescript title="quickback/features/applications/actions/listMyApplications.ts"
|
|
284
|
+
import { z } from "zod";
|
|
285
|
+
import { defineAction } from "../.quickback/define-action";
|
|
286
|
+
|
|
287
|
+
export default defineAction({
|
|
288
|
+
description: "List the caller's applications with their current pipeline stage.",
|
|
289
|
+
path: "/applications/mine",
|
|
290
|
+
input: z.object({}),
|
|
291
|
+
access: { roles: ["member"] },
|
|
292
|
+
mcp: { title: "List my applications", readOnly: true },
|
|
293
|
+
execute: async () => {
|
|
294
|
+
return { applications: [] };
|
|
295
|
+
},
|
|
296
|
+
});
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
| Key | Meaning | Default |
|
|
300
|
+
|-----|---------|---------|
|
|
301
|
+
| `title` | Short label the host shows (≤ 60 chars). The long text stays in `description`. | From the action name: `listMyAgenda` → "List my agenda" |
|
|
302
|
+
| `readOnly` | Only reads or computes; changes nothing. GET or POST actions only. | `true` for GET, otherwise `false` |
|
|
303
|
+
| `destructive` | May delete or overwrite data — hosts confirm before calling. | `false` when read-only; otherwise `true` (the compiler can't see what `execute` does) |
|
|
304
|
+
| `openWorld` | Reaches beyond this app's own data (public web, caller-supplied URLs). | `false` |
|
|
305
|
+
|
|
306
|
+
Every generated tool states `readOnlyHint`, `destructiveHint` and `openWorldHint`
|
|
307
|
+
explicitly. Generated CRUD tools derive them from the method: list/get are
|
|
308
|
+
read-only, create is a non-destructive write, update/upsert/delete are
|
|
309
|
+
destructive. A `bulkVariant` keeps the action's hints and gets its own title.
|
|
310
|
+
`unsafe` describes database scoping, not the tool's effect, and does not change
|
|
311
|
+
the hints.
|
|
276
312
|
|
|
277
313
|
## Input Validation
|
|
278
314
|
|
|
@@ -35,6 +35,8 @@ and the generated client SDK skip legacy operations: new code targets the succes
|
|
|
35
35
|
|
|
36
36
|
Each endpoint includes request/response schemas derived from your Drizzle column types, access control metadata, and error responses.
|
|
37
37
|
|
|
38
|
+
A [`PUBLIC`](/define/access) operation on an org-scoped table (`security: []`) also declares the optional `organizationId` query parameter an anonymous caller uses to name the organization.
|
|
39
|
+
|
|
38
40
|
### Schema fidelity
|
|
39
41
|
|
|
40
42
|
The generated component schemas carry enough type information that strict validators (zod, openapi-typescript, openapi-fetch) produce non-optional, narrowed types out of the box:
|
|
@@ -102,6 +102,7 @@ Views support the same query parameters as the list endpoint:
|
|
|
102
102
|
| `{field}.ne` | Not equal | — |
|
|
103
103
|
| `{field}.like` | Pattern match (SQL LIKE) | — |
|
|
104
104
|
| `{field}.in` | Match any value in comma-separated list | — |
|
|
105
|
+
| `organizationId` | [`PUBLIC`](/define/access) views on org-scoped tables only: the organization an anonymous caller is addressing. Omitting it is `403 ORG_REQUIRED`. Signed-in callers act in their active organization and can leave it out. | — |
|
|
105
106
|
|
|
106
107
|
### Examples
|
|
107
108
|
|
|
@@ -114,13 +115,16 @@ GET /api/v1/candidates/views/pipeline?source=referral&name.like=%25Johnson%25
|
|
|
114
115
|
|
|
115
116
|
# Combined
|
|
116
117
|
GET /api/v1/candidates/views/pipeline?source.in=LinkedIn,referral&sort=name&order=asc&limit=25
|
|
118
|
+
|
|
119
|
+
# Anonymous read of a PUBLIC view on an org-scoped table
|
|
120
|
+
GET /api/v1/jobs/views/careers?organizationId=org_abc123
|
|
117
121
|
```
|
|
118
122
|
|
|
119
123
|
## Security
|
|
120
124
|
|
|
121
125
|
All security pillars apply to view endpoints:
|
|
122
126
|
|
|
123
|
-
1. **Authentication** — Required (401 if missing)
|
|
127
|
+
1. **Authentication** — Required (401 if missing), unless the view's access admits `PUBLIC`
|
|
124
128
|
2. **Firewall** — Organization/user isolation applied to all results. Only records the user owns or has access to are returned.
|
|
125
129
|
3. **Access** — Per-view role check. Each view can require different roles.
|
|
126
130
|
4. **Masking** — Applied to all returned fields. If a masked field is in the view's field list, the masking rules still apply based on the user's role.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Product highlights from changes merged into Quickback. Upcoming releases are
|
|
4
|
+
listed separately; detailed setup instructions live in the product guides.
|
|
5
|
+
|
|
6
|
+
## Coming next
|
|
7
|
+
|
|
8
|
+
- **A lighter migration history.** Consolidate D1 migrations into a clean starting point, with checks that protect existing databases. [Learn more](/platform/database/schema-baselines).
|
|
9
|
+
|
|
10
|
+
## November 2026
|
|
11
|
+
|
|
12
|
+
- **More capable AI integrations.** Give assistants clearer tools and live updates as your application changes.
|
|
13
|
+
- **Sharing on your terms.** Share individual records through links with permissions built in.
|
|
14
|
+
- **Stronger workspace privacy.** Keep each customer's credentials encrypted and access tied to the right workspace.
|
|
15
|
+
- **Smoother daily workflows.** Faster admin screens and easier handling of large result sets.
|
|
16
|
+
|
|
17
|
+
## October 2026
|
|
18
|
+
|
|
19
|
+
- **Workspaces that stand apart.** Run customer data in isolated databases, with tools to manage their lifecycle.
|
|
20
|
+
- **More control over sensitive data.** Unlock encrypted data with passkeys and bring it into native apps.
|
|
21
|
+
- **Richer experiences for AI assistants.** Build interactive MCP apps and organize tools across multiple servers.
|
|
22
|
+
- **More responsive applications.** Faster reads, quicker sign-in and more reliable live updates.
|
|
23
|
+
|
|
24
|
+
## September 2026
|
|
25
|
+
|
|
26
|
+
- **Start with what you have.** Turn an existing OpenAPI specification into a Quickback project.
|
|
27
|
+
- **Confidence from editor to production.** Stronger type checks connect backend definitions to application code.
|
|
28
|
+
- **More database choice.** Expanded support for Neon and PlanetScale Postgres.
|
|
29
|
+
- **Stronger foundations.** Tighter permissions, safer database changes and more dependable builds.
|
|
@@ -84,8 +84,12 @@ Opting in exposes auth tools only to callers that authenticated to `/mcp` with a
|
|
|
84
84
|
|
|
85
85
|
Every operation in your generated OpenAPI spec becomes one MCP tool. The tool name is the operation's `operationId` (e.g. `listCustomers`, `createInvoice`, `sendInvoice`). Each tool's `inputSchema` is a JSON Schema combining the request body with every parameter in the operation's **mounted** path — including the `:params` contributed by a namespace prefix (e.g. `/scope/:scopeId/...`), so a standalone or namespace action is always callable, not just record-based ones. Nested `z.object` inputs are preserved as nested objects rather than flattened, so the model sees each field's real type.
|
|
86
86
|
|
|
87
|
+
List and view tools take the same query arguments as the REST endpoint: `limit`, `offset`, `sort`, `order`, and on the collection read also `starting_after`, `ending_before`, `total`, `fields`, `search` and the column filters. See [Query parameters](/api/query-params).
|
|
88
|
+
|
|
87
89
|
`tools/call` re-enters the same Hono app via `app.request(...)` — so **every existing middleware runs exactly as it would for a direct REST call**: authentication, firewall, access control, guards, masking. No bypass.
|
|
88
90
|
|
|
91
|
+
A [`PUBLIC`](/define/access) read on an org-scoped table takes an `organizationId` argument: an anonymous agent passes it to name the organization whose public rows it wants, and gets `ORG_REQUIRED` without it. It is forwarded as `?organizationId=`, the same as a REST call. Tools for authenticated-only operations don't have it; those act in the caller's active organization.
|
|
92
|
+
|
|
89
93
|
Path and query arguments go into the URL; the rest become the JSON body. A `POST`, `PUT` or `PATCH` tool always sends a JSON body, even when the operation has no body fields (an action with `input: z.object({})` and only path params is sent `{}`), so it passes the same body validation as a REST call. A `DELETE` tool sends a JSON body only when the operation declares body fields (batch delete sends `{ ids, options }`); single-record `DELETE` and `GET` tools send no body.
|
|
90
94
|
|
|
91
95
|
### Access-filtered `tools/list`
|
|
@@ -154,6 +158,18 @@ The access tokens it issues carry the OAuth issuer (`BETTER_AUTH_URL` + `/auth/v
|
|
|
154
158
|
|
|
155
159
|
The middleware accepts these tokens only while their Better Auth session (`sid`) is live, and builds the user's context from it — but **not the session's organization**. A token whose audience is a scope kind's resource is the other lane: confined to one instance, no session — see [Instance-bound OAuth tokens](/define/scopes#instance-bound-oauth-tokens).
|
|
156
160
|
|
|
161
|
+
#### Grant lifetime
|
|
162
|
+
|
|
163
|
+
An ordinary grant lives and dies with the sign-in session it was issued under. The token endpoint and the middleware apply the same check — the session row exists, belongs to the user and has not expired — so they cannot disagree:
|
|
164
|
+
|
|
165
|
+
- **Use.** The middleware refuses an access token whose session has ended.
|
|
166
|
+
- **Refresh.** `POST /oauth2/token` with `grant_type=refresh_token` fails with `400 invalid_grant` once the session has ended, and deletes the refresh tokens issued under it. The connector gets a clean signal to sign in again instead of a token that every request rejects. (Better Auth makes this check at the code exchange but not at refresh; the generated `oauthProvider` extension adds it.)
|
|
167
|
+
- **A connector in use keeps its session live.** Each successful refresh slides the session the way Better Auth's own `/get-session` does: by `session.expiresIn`, at most once per `session.updateAge`. A grant therefore does not end `session.expiresIn` after consent just because the user never reopened the browser. A session that has already lapsed or been deleted is never revived, `session.disableSessionRefresh` turns the slide off, and an impersonation session is never extended.
|
|
168
|
+
|
|
169
|
+
Everything that ends the session ends the grant at both endpoints: sign-out, sign-out-everywhere, a password change or reset that revokes sessions, an admin revoking the user's sessions, a ban, and deleting the user. Revoking the refresh token (`POST /oauth2/revoke`) and removing the user's membership in the consented workspace end it too. An unused grant ends when its refresh token expires (`refreshTokenExpiresIn`, 30 days by default) or its session lapses, whichever comes first.
|
|
170
|
+
|
|
171
|
+
`plugins.oauthProvider.extensions` is generated for this check; setting it is an error. Add your own extension from a custom plugin with `extendOAuthProvider()`.
|
|
172
|
+
|
|
157
173
|
#### Workspace-bound tokens
|
|
158
174
|
|
|
159
175
|
With the organization plugin on, an ordinary OAuth token is bound to the workspace the user **consented in**, following Better Auth's own `postLogin.consentReferenceId` pattern:
|
|
@@ -284,6 +284,8 @@ GET /api/v1/listings?organizationId=org_abc123
|
|
|
284
284
|
|
|
285
285
|
The firewall WHERE clause is always enforced. If no `organizationId` is provided, the API returns a `403` with code `ORG_REQUIRED`.
|
|
286
286
|
|
|
287
|
+
The parameter is part of the published contract. Every `PUBLIC` route on an org-scoped table that reads it — the collection, `GET /:id`, named views, and a `PUBLIC` `update` / `delete` / `PUT /:id` — declares an optional `organizationId` query parameter in the [OpenAPI spec](/api/openapi), so the generated types, the client SDK and the matching [MCP tool](/configure/agents#tools) can all send it. Authenticated-only routes don't declare it, and neither do `PUBLIC` routes on owner-scoped or unscoped tables: there is no tenant to name. A signed-in caller acts in their active organization; passing a different `organizationId` is a `403 CROSS_TENANT_FORBIDDEN`.
|
|
288
|
+
|
|
287
289
|
`?organizationId=` is an account/public addressing surface. A request using a
|
|
288
290
|
configured delegated principal cannot use it to acquire account organization
|
|
289
291
|
authority: the generated route returns `403 CROSS_TENANT_FORBIDDEN` and never
|
|
@@ -143,7 +143,7 @@ The keys never move into the object:
|
|
|
143
143
|
- Values at rest look the same (`qbenc:2:<keyVersion>:…`, bound to organization + table + column), but a tenant ciphertext does not open with the edge DEK, and an edge ciphertext does not open in the object.
|
|
144
144
|
- Rotation is the envelope tier's. [`rotateOrgDataKey`](#rotating-an-organizations-dek) starts a new tenant key version and retired versions keep reading; [`rewrapOrgDataKeys`](#rotating-encryption_kek) changes nothing the object sees; deleting the organization's `org_data_keys` row shreds its tenant values too. Warm edge isolates hand out the previous key set for up to five minutes after a rotation; a value sealed under the new version in that window reads as `ENCRYPTION_UNREADABLE` from such an isolate until its cache refreshes.
|
|
145
145
|
- **Fail closed.** Tenant schedules, tenant jobs and alarms run without a forwarded request and carry no key: a write to an encrypted column there throws before any row is written, and nothing opens a value. Write and open encrypted tenant columns from actions and routes.
|
|
146
|
-
- Tenant feature files that import `lib/encryption` or `lib/secrets` are re-pointed at the tenant runtime. A shared `quickback/lib` helper that still reaches either from tenant code fails the build (`TENANCY_EDGE_IMPORT_IN_TENANT`), like `lib/realtime`.
|
|
146
|
+
- Tenant feature files that import `lib/encryption` or `lib/secrets` are re-pointed at the tenant runtime. A shared `quickback/lib` helper that still reaches either from tenant code fails the build (`TENANCY_EDGE_IMPORT_IN_TENANT`), like `lib/realtime`. Platform tables with encrypted columns are unaffected: the edge keeps sealing and opening them with the organization DEK, and the tenant Worker never runs their files.
|
|
147
147
|
|
|
148
148
|
### Moving an existing plaintext column to `q.secret()`
|
|
149
149
|
|
|
@@ -945,7 +945,7 @@ The namespace gate re-proves the relationship on every request, as it does for a
|
|
|
945
945
|
> A claimed table's [legacy forward](/define/areas#keeping-the-old-url-legacy) does not widen this: it refuses an instance-bound token and every caller without an active organization (`403 LEGACY_ORG_REQUIRED`), and it only forwards into an instance of the caller's own organization.
|
|
946
946
|
|
|
947
947
|
|
|
948
|
-
Ordinary OAuth tokens (MCP clients, audience = origin or `/mcp`) are unchanged: they still need a live session and get the user's full context.
|
|
948
|
+
Ordinary OAuth tokens (MCP clients, audience = origin or `/mcp`) are unchanged: they still need a live session — at use and at every refresh, see [Grant lifetime](/configure/agents#grant-lifetime) — and get the user's full context.
|
|
949
949
|
|
|
950
950
|
### Revoke one instance
|
|
951
951
|
|
|
@@ -208,6 +208,14 @@ read: {
|
|
|
208
208
|
}
|
|
209
209
|
```
|
|
210
210
|
|
|
211
|
+
A view can be `PUBLIC` while the rest of the resource stays members-only. On an org-scoped table an anonymous caller names the organization with `?organizationId=`; without it the view returns `403 ORG_REQUIRED`:
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
GET /api/v1/jobs/views/careers?organizationId=org_abc123
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
The view's OpenAPI operation and MCP tool declare `organizationId` for this case. See [`PUBLIC`](/define/access).
|
|
218
|
+
|
|
211
219
|
### Masking
|
|
212
220
|
|
|
213
221
|
Masking rules are applied to the returned fields. If a view includes a masked field like `email`, the masking rules still apply:
|
|
@@ -70,7 +70,7 @@ role. Better Auth's own API is the gate for its tables.
|
|
|
70
70
|
## Compiler-managed auth versions and upgrades
|
|
71
71
|
|
|
72
72
|
The compiler pins Better Auth, its schema CLI, and the generated companion
|
|
73
|
-
packages to **1.7.
|
|
73
|
+
packages to **1.7.17**. Recompile and install the emitted dependencies together;
|
|
74
74
|
remove older Better Auth overrides from `build.dependencies`. An incompatible
|
|
75
75
|
override is rejected because it would run a different auth version from the
|
|
76
76
|
one that generated your schema.
|
|
@@ -81,6 +81,15 @@ migration history stays on your machine. Apply the newly generated auth
|
|
|
81
81
|
migration before starting the updated Worker. Existing migration SQL is
|
|
82
82
|
preserved.
|
|
83
83
|
|
|
84
|
+
This release includes the upstream fixes for Magic Link/OAuth account takeover,
|
|
85
|
+
OAuth Proxy account takeover, and concurrent PostgreSQL rate-limit bypasses.
|
|
86
|
+
Upgrade every deployment sharing verification storage or OAuth Proxy flows
|
|
87
|
+
together, including preview and development deployments. Request fresh Magic
|
|
88
|
+
Links and restart pending OAuth/SAML sign-in and account-linking flows after
|
|
89
|
+
the upgrade: state issued by older versions may no longer complete. These
|
|
90
|
+
security fixes do not themselves require a database schema migration; projects
|
|
91
|
+
upgrading from older auth schemas should still apply any emitted migrations.
|
|
92
|
+
|
|
84
93
|
### Upgrading from 1.6
|
|
85
94
|
|
|
86
95
|
The upgrade adds the current JWT/OAuth schema, including JWKS `alg`/`crv` and
|
|
@@ -346,6 +346,22 @@ auth: defineAuth("better-auth", {
|
|
|
346
346
|
- Cannot selectively allow only specific subdomains
|
|
347
347
|
- All-or-nothing: either exact domain only, or all subdomains
|
|
348
348
|
|
|
349
|
+
#### Cookie prefix
|
|
350
|
+
|
|
351
|
+
Better Auth names its cookies `<prefix>.session_token`, and the prefix is `better-auth` unless you change it:
|
|
352
|
+
|
|
353
|
+
```ts
|
|
354
|
+
auth: defineAuth("better-auth", {
|
|
355
|
+
advanced: {
|
|
356
|
+
cookiePrefix: 'kindling' // cookies become kindling.session_token, …
|
|
357
|
+
}
|
|
358
|
+
})
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
Set it when two separate Better Auth deployments live under one domain and either of them shares its cookie across subdomains. Say `auth.example.com` shares a cookie on `example.com` and a second, unrelated deployment runs at `id.team.example.com`. A browser sends both cookies to the second host, the names are the same, and which session the server reads depends on cookie order. A different prefix on one of them keeps the two apart.
|
|
362
|
+
|
|
363
|
+
Apps that share one session must use the same prefix: an identity service and every app that reads its session cookie. The prefix may contain letters, digits, `-` and `_`. Changing it on a live app signs everyone out, because the old cookie is no longer read.
|
|
364
|
+
|
|
349
365
|
#### 2. Trusted Origins (Application-Level)
|
|
350
366
|
|
|
351
367
|
```ts
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Schema Baselines
|
|
2
|
+
|
|
3
|
+
`quickback migrations baseline` replaces a long **D1/SQLite schema history**
|
|
4
|
+
with a compact baseline. It uses the project's pinned `drizzle-kit@0.31.10`
|
|
5
|
+
and requires Node.js 22.13 or newer for the isolated SQLite replay. The rest
|
|
6
|
+
of the CLI retains its existing Node requirement.
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
quickback migrations baseline --database features # preview; migration files unchanged
|
|
10
|
+
quickback migrations baseline --database features --write # explicit local cutover
|
|
11
|
+
quickback migrations baseline --database auth --write # separate history/database
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
This first version supports `auth` and `features` histories with SQLite v6
|
|
15
|
+
Drizzle snapshots and Wrangler's default `d1_migrations` ledger. It does not
|
|
16
|
+
support PostgreSQL, tenant Durable Objects, custom/broker-managed migration ledgers, virtual
|
|
17
|
+
tables, or histories that attach databases/load extensions. It refuses unknown
|
|
18
|
+
arguments, broken journals, missing SQL, broken snapshot chains and symlinks.
|
|
19
|
+
No command here connects to a database or invokes Wrangler. Use the standard
|
|
20
|
+
Wrangler D1 migration runner for adoption; broker-managed deployment ledgers
|
|
21
|
+
require a separate adoption protocol and are not supported.
|
|
22
|
+
|
|
23
|
+
## What is compacted
|
|
24
|
+
|
|
25
|
+
The command replays the SQL history in an isolated in-memory SQLite process,
|
|
26
|
+
validates the final snapshot through Drizzle, and checks its table, column,
|
|
27
|
+
foreign-key and index contracts. It exports the final tables, indexes, views,
|
|
28
|
+
triggers, migration seed rows (including blobs and large integers), and
|
|
29
|
+
AUTOINCREMENT sequences. Seed expressions such as random ids or timestamps are
|
|
30
|
+
materialized at preparation time; the SQL filename addresses those actual bytes. Replaying the proposed baseline must reproduce that
|
|
31
|
+
state exactly and pass foreign-key checks.
|
|
32
|
+
|
|
33
|
+
The result is one `0000_quickback_baseline_<digest>.sql` and a rooted snapshot
|
|
34
|
+
and journal. A compiler-owned trigger document, when present, remains as a
|
|
35
|
+
second SQL migration under its content hash. This preserves trigger deduplication
|
|
36
|
+
and later trigger removal; concatenating old SQL would not do that. Custom
|
|
37
|
+
triggers remain in the schema baseline, after the seed inserts.
|
|
38
|
+
|
|
39
|
+
`--write` uses the same project migration lock as builds, rechecks the source
|
|
40
|
+
inventory, stages the complete tree, and keeps the original tree byte-for-byte
|
|
41
|
+
under `quickback/.archives/migration-baselines/<database>/<digest>/`. It writes
|
|
42
|
+
reviewable `manifest.json` and `adopt.sql` under
|
|
43
|
+
`quickback/baselines/<database>/<digest>/`. Commit the baseline and review
|
|
44
|
+
artifacts. Keep the archive until every deployed database has crossed over;
|
|
45
|
+
standard Quickback ignores `.archives/`. An ordinary write failure restores
|
|
46
|
+
the original tree. If the process or machine dies during the rename cutover,
|
|
47
|
+
recover the original tree from that archive before another build or deploy.
|
|
48
|
+
|
|
49
|
+
This is an explicit replacement path. Normal `quickback build` remains additive
|
|
50
|
+
and never rewrites applied migrations. `meta/_baseline.json` retains retired
|
|
51
|
+
ledger names so a later rebaseline can recognize previously adopted databases.
|
|
52
|
+
|
|
53
|
+
## Fresh versus existing databases
|
|
54
|
+
|
|
55
|
+
**Fresh databases:** apply the compact SQL files normally with Wrangler. Each
|
|
56
|
+
migration is applied in a transaction; the schema baseline defers foreign keys
|
|
57
|
+
while inserting its seed rows. A baseline is a schema bootstrap, not an export
|
|
58
|
+
of production rows or encrypted integration secrets.
|
|
59
|
+
|
|
60
|
+
**Existing databases:** do not run the baseline's CREATE statements against them.
|
|
61
|
+
|
|
62
|
+
1. Back up each target and stop deployment jobs that could apply migrations.
|
|
63
|
+
2. Using the original history, apply every pending migration up to the cutoff.
|
|
64
|
+
3. Prepare and review the baseline locally. Rebuild the project and inspect the
|
|
65
|
+
next Drizzle migration; an unchanged schema should produce none.
|
|
66
|
+
4. Test `adopt.sql` against a populated local copy or disposable staging target.
|
|
67
|
+
5. Execute the reviewed `adopt.sql` on each matching existing D1 database **before**
|
|
68
|
+
running normal migration application with the compacted files.
|
|
69
|
+
6. Apply subsequent migrations and test the application. Repeat independently
|
|
70
|
+
for auth/features and every environment.
|
|
71
|
+
|
|
72
|
+
The adoption SQL performs a single atomic INSERT into `d1_migrations`. It
|
|
73
|
+
requires every source migration name, permits only known retired/baseline names,
|
|
74
|
+
and checks the exact schema catalog, including triggers and indexes. A mismatch
|
|
75
|
+
raises a malformed-JSON error and records **no** baseline names. Equivalent
|
|
76
|
+
schemas with different SQL text are deliberately refused; investigate instead
|
|
77
|
+
of bypassing the guard. A repeat adoption inserts no duplicate names. Old ledger
|
|
78
|
+
rows are retained, and application tables/rows are never changed by adoption.
|
|
79
|
+
The generated statement is limited to a conservative 64 KiB; larger statements
|
|
80
|
+
refuse preparation rather than produce an unchecked cutover.
|
|
81
|
+
|
|
82
|
+
Do not edit the manifest or adoption guard to silence a mismatch. Missing history
|
|
83
|
+
must be recovered from a trusted archive or deployment artifact, not invented.
|
|
84
|
+
A new baseline changes which migration filenames are pending on an existing
|
|
85
|
+
DB, so deploying compacted files without the adoption step will attempt to
|
|
86
|
+
recreate tables.
|
|
@@ -355,6 +355,19 @@ also writes `.dev.vars.example` with every declared secret, for local
|
|
|
355
355
|
`wrangler dev`. Neon and PlanetScale keep their own template, and any declared
|
|
356
356
|
secret it lacks is appended to it.
|
|
357
357
|
|
|
358
|
+
### Compact D1 Schema Migrations
|
|
359
|
+
|
|
360
|
+
```bash
|
|
361
|
+
quickback migrations baseline --database features
|
|
362
|
+
quickback migrations baseline --database features --write
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
Preview by default. `--write` stages a compact Drizzle baseline, preserves the
|
|
366
|
+
original history, and writes guarded adoption SQL for existing databases.
|
|
367
|
+
Supports D1 auth/features histories; requires Node 22.13+ and the pinned
|
|
368
|
+
Drizzle version. Read [Schema Baselines](/platform/database/schema-baselines)
|
|
369
|
+
before deploying compacted files to an existing database.
|
|
370
|
+
|
|
358
371
|
### Run Data Migrations
|
|
359
372
|
|
|
360
373
|
```bash
|
|
@@ -30,6 +30,8 @@ The API key takes precedence over stored credentials from `quickback login`.
|
|
|
30
30
|
|
|
31
31
|
The compiler-cloud worker validates authentication by forwarding your credentials to the Quickback API's Better Auth `GET /auth/v1/get-session` endpoint via a [Cloudflare service binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/). This resolves both session tokens (from `quickback login`) and API keys (from `QUICKBACK_API_KEY`, sent as `x-api-key` — `get-session` is the only Better Auth endpoint that accepts a key in place of a session).
|
|
32
32
|
|
|
33
|
+
A valid session is enough for a validation compile. A complete compile also needs the account behind it — the session's user, or the API key's owner — to be non-anonymous with a verified email, and it counts toward a daily per-account limit. See [Who can run which compile](/tooling/cloud-compiler/endpoints#who-can-run-which-compile).
|
|
34
|
+
|
|
33
35
|
## Credential Storage
|
|
34
36
|
|
|
35
37
|
Credentials are stored at `~/.quickback/credentials.json`:
|
|
@@ -19,6 +19,24 @@ The cloud compiler API is hosted at `https://compiler.quickback.dev`
|
|
|
19
19
|
|
|
20
20
|
The `/compile` endpoint requires either a session token (from `quickback login`) or an API key (via `QUICKBACK_API_KEY` header). See [Authentication](/tooling/cloud-compiler/authentication) for details.
|
|
21
21
|
|
|
22
|
+
### Who can run which compile
|
|
23
|
+
|
|
24
|
+
| Compile | Who |
|
|
25
|
+
|---------|-----|
|
|
26
|
+
| Validation (`?complete=false`) | Any session, including an anonymous one. [Start](https://start.quickback.dev) runs them for signed-out visitors through its own server-side token. |
|
|
27
|
+
| Complete (`?complete=true`, the default) | A Quickback account that is **not anonymous** and has a **verified email**, within a per-account daily limit. |
|
|
28
|
+
|
|
29
|
+
A complete compile that is refused answers with a JSON body carrying `error`, `code` and `hint`:
|
|
30
|
+
|
|
31
|
+
| Status | `code` | Meaning |
|
|
32
|
+
|--------|--------|---------|
|
|
33
|
+
| 403 | `ANONYMOUS_SESSION` | Anonymous sessions run validation compiles only. Create an account and run `quickback login`. |
|
|
34
|
+
| 403 | `EMAIL_NOT_VERIFIED` | Verify your email address first. |
|
|
35
|
+
| 403 | `BUILDER_ACCESS_REQUIRED` | Complete compiles are limited to approved accounts while access is in private beta. |
|
|
36
|
+
| 429 | `COMPILE_QUOTA_EXCEEDED` | The account used its complete compiles for the day. `Retry-After` gives the seconds until the limit resets at 00:00 UTC. |
|
|
37
|
+
|
|
38
|
+
Every admitted complete compile that counts toward the limit carries `X-Quickback-Compile-Quota-Limit` and `X-Quickback-Compile-Quota-Remaining`. A compile that never ran (all compiler instances busy, `503 COMPILER_BUSY`) does not count. Validation compiles are never limited this way.
|
|
39
|
+
|
|
22
40
|
## Raw-files mode (`POST /compile`)
|
|
23
41
|
|
|
24
42
|
`/compile` normally expects the parsed `CompilerInput` the CLI assembles client-side. Thin clients (agents, web builders, CI without the CLI) can instead send the project sources verbatim and let the compiler organize them server-side:
|
|
@@ -61,7 +79,7 @@ without producing a runtime writes exactly the tagged files from a
|
|
|
61
79
|
|
|
62
80
|
## Edge validation backend
|
|
63
81
|
|
|
64
|
-
Validation compiles (`POST /compile?complete=false`)
|
|
82
|
+
Validation compiles (`POST /compile?complete=false`) are served by an edge Worker instead of the compiler container. The edge Worker has no public URL of its own; `compiler.quickback.dev` checks auth and then forwards to it. This is **transparent to clients**: same endpoint, same auth, same request and response shapes (plain or gzipped JSON, raw-files or parsed input, identical payload limits, error shapes, and generated-file envelopes) — just no container cold start.
|
|
65
83
|
|
|
66
84
|
The response header `X-Quickback-Compile-Backend` says which backend answered:
|
|
67
85
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.72.
|
|
3
|
+
"version": "0.72.8",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
|
@@ -272,7 +272,43 @@ Why this is safer than hand-rolling `organizationId` on every query:
|
|
|
272
272
|
- Soft-delete and team-isolation filters continue to apply unchanged.
|
|
273
273
|
- No chance of forgetting a `WHERE organizationId = ?` clause on a single query.
|
|
274
274
|
|
|
275
|
-
`x-unsafe: true` is emitted on each unsafe operation in `openapi.json`, and MCP
|
|
275
|
+
`x-unsafe: true` is emitted on each unsafe operation in `openapi.json`, and MCP tools carry an internal `_unsafe` flag (the public description never says why the action is privileged). `unsafe` does not change the tool's behaviour hints — declare those with `mcp` (see [MCP tool title and hints](#mcp-tool-title-and-hints)).
|
|
276
|
+
|
|
277
|
+
## MCP tool title and hints
|
|
278
|
+
|
|
279
|
+
Every action becomes an MCP tool. Agent hosts (Claude, ChatGPT) show the tool's
|
|
280
|
+
`title` and use three hints to decide when to ask the user before calling it.
|
|
281
|
+
Declare them next to the description:
|
|
282
|
+
|
|
283
|
+
```typescript title="quickback/features/applications/actions/listMyApplications.ts"
|
|
284
|
+
import { z } from "zod";
|
|
285
|
+
import { defineAction } from "../.quickback/define-action";
|
|
286
|
+
|
|
287
|
+
export default defineAction({
|
|
288
|
+
description: "List the caller's applications with their current pipeline stage.",
|
|
289
|
+
path: "/applications/mine",
|
|
290
|
+
input: z.object({}),
|
|
291
|
+
access: { roles: ["member"] },
|
|
292
|
+
mcp: { title: "List my applications", readOnly: true },
|
|
293
|
+
execute: async () => {
|
|
294
|
+
return { applications: [] };
|
|
295
|
+
},
|
|
296
|
+
});
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
| Key | Meaning | Default |
|
|
300
|
+
|-----|---------|---------|
|
|
301
|
+
| `title` | Short label the host shows (≤ 60 chars). The long text stays in `description`. | From the action name: `listMyAgenda` → "List my agenda" |
|
|
302
|
+
| `readOnly` | Only reads or computes; changes nothing. GET or POST actions only. | `true` for GET, otherwise `false` |
|
|
303
|
+
| `destructive` | May delete or overwrite data — hosts confirm before calling. | `false` when read-only; otherwise `true` (the compiler can't see what `execute` does) |
|
|
304
|
+
| `openWorld` | Reaches beyond this app's own data (public web, caller-supplied URLs). | `false` |
|
|
305
|
+
|
|
306
|
+
Every generated tool states `readOnlyHint`, `destructiveHint` and `openWorldHint`
|
|
307
|
+
explicitly. Generated CRUD tools derive them from the method: list/get are
|
|
308
|
+
read-only, create is a non-destructive write, update/upsert/delete are
|
|
309
|
+
destructive. A `bulkVariant` keeps the action's hints and gets its own title.
|
|
310
|
+
`unsafe` describes database scoping, not the tool's effect, and does not change
|
|
311
|
+
the hints.
|
|
276
312
|
|
|
277
313
|
## Input Validation
|
|
278
314
|
|
|
@@ -35,6 +35,8 @@ and the generated client SDK skip legacy operations: new code targets the succes
|
|
|
35
35
|
|
|
36
36
|
Each endpoint includes request/response schemas derived from your Drizzle column types, access control metadata, and error responses.
|
|
37
37
|
|
|
38
|
+
A [`PUBLIC`](/define/access) operation on an org-scoped table (`security: []`) also declares the optional `organizationId` query parameter an anonymous caller uses to name the organization.
|
|
39
|
+
|
|
38
40
|
### Schema fidelity
|
|
39
41
|
|
|
40
42
|
The generated component schemas carry enough type information that strict validators (zod, openapi-typescript, openapi-fetch) produce non-optional, narrowed types out of the box:
|
|
@@ -102,6 +102,7 @@ Views support the same query parameters as the list endpoint:
|
|
|
102
102
|
| `{field}.ne` | Not equal | — |
|
|
103
103
|
| `{field}.like` | Pattern match (SQL LIKE) | — |
|
|
104
104
|
| `{field}.in` | Match any value in comma-separated list | — |
|
|
105
|
+
| `organizationId` | [`PUBLIC`](/define/access) views on org-scoped tables only: the organization an anonymous caller is addressing. Omitting it is `403 ORG_REQUIRED`. Signed-in callers act in their active organization and can leave it out. | — |
|
|
105
106
|
|
|
106
107
|
### Examples
|
|
107
108
|
|
|
@@ -114,13 +115,16 @@ GET /api/v1/candidates/views/pipeline?source=referral&name.like=%25Johnson%25
|
|
|
114
115
|
|
|
115
116
|
# Combined
|
|
116
117
|
GET /api/v1/candidates/views/pipeline?source.in=LinkedIn,referral&sort=name&order=asc&limit=25
|
|
118
|
+
|
|
119
|
+
# Anonymous read of a PUBLIC view on an org-scoped table
|
|
120
|
+
GET /api/v1/jobs/views/careers?organizationId=org_abc123
|
|
117
121
|
```
|
|
118
122
|
|
|
119
123
|
## Security
|
|
120
124
|
|
|
121
125
|
All security pillars apply to view endpoints:
|
|
122
126
|
|
|
123
|
-
1. **Authentication** — Required (401 if missing)
|
|
127
|
+
1. **Authentication** — Required (401 if missing), unless the view's access admits `PUBLIC`
|
|
124
128
|
2. **Firewall** — Organization/user isolation applied to all results. Only records the user owns or has access to are returned.
|
|
125
129
|
3. **Access** — Per-view role check. Each view can require different roles.
|
|
126
130
|
4. **Masking** — Applied to all returned fields. If a masked field is in the view's field list, the masking rules still apply based on the user's role.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Product highlights from changes merged into Quickback. Upcoming releases are
|
|
4
|
+
listed separately; detailed setup instructions live in the product guides.
|
|
5
|
+
|
|
6
|
+
## Coming next
|
|
7
|
+
|
|
8
|
+
- **A lighter migration history.** Consolidate D1 migrations into a clean starting point, with checks that protect existing databases. [Learn more](/platform/database/schema-baselines).
|
|
9
|
+
|
|
10
|
+
## November 2026
|
|
11
|
+
|
|
12
|
+
- **More capable AI integrations.** Give assistants clearer tools and live updates as your application changes.
|
|
13
|
+
- **Sharing on your terms.** Share individual records through links with permissions built in.
|
|
14
|
+
- **Stronger workspace privacy.** Keep each customer's credentials encrypted and access tied to the right workspace.
|
|
15
|
+
- **Smoother daily workflows.** Faster admin screens and easier handling of large result sets.
|
|
16
|
+
|
|
17
|
+
## October 2026
|
|
18
|
+
|
|
19
|
+
- **Workspaces that stand apart.** Run customer data in isolated databases, with tools to manage their lifecycle.
|
|
20
|
+
- **More control over sensitive data.** Unlock encrypted data with passkeys and bring it into native apps.
|
|
21
|
+
- **Richer experiences for AI assistants.** Build interactive MCP apps and organize tools across multiple servers.
|
|
22
|
+
- **More responsive applications.** Faster reads, quicker sign-in and more reliable live updates.
|
|
23
|
+
|
|
24
|
+
## September 2026
|
|
25
|
+
|
|
26
|
+
- **Start with what you have.** Turn an existing OpenAPI specification into a Quickback project.
|
|
27
|
+
- **Confidence from editor to production.** Stronger type checks connect backend definitions to application code.
|
|
28
|
+
- **More database choice.** Expanded support for Neon and PlanetScale Postgres.
|
|
29
|
+
- **Stronger foundations.** Tighter permissions, safer database changes and more dependable builds.
|