@quickback-dev/cli 0.47.11 → 0.47.13
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/create.js +25 -0
- package/dist/commands/create.js.map +1 -1
- package/dist/docs/content.js +5 -5
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +110 -46
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/action-harvest.test.js +97 -0
- package/dist/lib/action-harvest.test.js.map +1 -1
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +18 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/skill/SKILL.md +46 -0
- package/dist/skill/docs/changelog.md +78 -0
- package/dist/skill/docs/compiler/config/agents.md +42 -1
- package/dist/skill/docs/compiler/definitions/scopes.md +140 -2
- package/dist/skill/docs/stack/auth/plugins/index.md +9 -1
- package/dist/skill/docs/stack/schedules/index.md +17 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +46 -0
- package/src/skill/docs/changelog.md +78 -0
- package/src/skill/docs/compiler/config/agents.md +42 -1
- package/src/skill/docs/compiler/definitions/scopes.md +140 -2
- package/src/skill/docs/stack/auth/plugins/index.md +9 -1
- package/src/skill/docs/stack/schedules/index.md +17 -0
- package/dist/codex/AGENTS.md +0 -290
- package/dist/commands/codex.d.ts +0 -16
- package/dist/commands/codex.d.ts.map +0 -1
- package/dist/commands/codex.js +0 -159
- package/dist/commands/codex.js.map +0 -1
- package/dist/commands/init.d.ts +0 -6
- package/dist/commands/init.d.ts.map +0 -1
- package/dist/commands/init.js +0 -405
- package/dist/commands/init.js.map +0 -1
- package/dist/lib/sweep-stale.d.ts +0 -25
- package/dist/lib/sweep-stale.d.ts.map +0 -1
- package/dist/lib/sweep-stale.js +0 -179
- package/dist/lib/sweep-stale.js.map +0 -1
- package/dist/lib/sweep-stale.test.d.ts +0 -2
- package/dist/lib/sweep-stale.test.d.ts.map +0 -1
- package/dist/lib/sweep-stale.test.js +0 -130
- package/dist/lib/sweep-stale.test.js.map +0 -1
|
@@ -15,6 +15,8 @@ Reach for a scope when a principal must touch a bounded slice of an instance **w
|
|
|
15
15
|
|
|
16
16
|
Each is *event-scoped* but a **distinct least-privilege role**. Org members are unaffected — they keep their normal tenant access.
|
|
17
17
|
|
|
18
|
+
Most scope principals are signed-in users who prove a relationship at [`/scope/v1/enter`](#2-enter-the-scope). But some have **no account at all** — an attendee who arrives by email + invite code, a kiosk/handout code, a partner token. For those, an action proves the principal its own way and [`ctx.mintScope`](#sessionless-scope-mint--ctxmintscope) mints the same scope, no Better Auth user required.
|
|
19
|
+
|
|
18
20
|
## The model
|
|
19
21
|
|
|
20
22
|
### 1. Declare relationships + scopes
|
|
@@ -315,6 +317,131 @@ forge a scope role — the guard, not the flag, is the gate.
|
|
|
315
317
|
- **The mint is gated by the same proven-relationship guard as the in-memory stamp.** It runs *after* the gate has granted access, reading the instance id from the proven path param (`:eventId`) — never from request input — so the minted `scope:<kind>:<role>` is backed by exactly the proof `/scope/v1/enter` requires. The token is **byte-identical** to one `/scope/v1/enter` would produce: same shared mint helper, same carry-forward of any *other* verified scope kinds already on the incoming token (the freshly-proven kind takes precedence; siblings survive the re-mint).
|
|
316
318
|
- **The mint is best-effort.** A mint failure (e.g. a missing signing secret) **never fails the request** — the in-memory stamp already authorized it; the caller simply doesn't receive a refreshed token on that response and can fall back to `/scope/v1/enter`.
|
|
317
319
|
|
|
320
|
+
## Sessionless scope mint — `ctx.mintScope`
|
|
321
|
+
|
|
322
|
+
`POST /scope/v1/enter` and the namespace resolver both prove the relationship by
|
|
323
|
+
**`ctx.userId`** — so they require a Better Auth account. But a legitimate
|
|
324
|
+
principal often has none: an **event attendee who arrives by email + invite
|
|
325
|
+
code**, holding an opaque session token you validate yourself, who must never
|
|
326
|
+
get a global account. The shape is general — magic links, kiosk/handout codes,
|
|
327
|
+
partner-issued API keys, expiring share links that need row-level scope.
|
|
328
|
+
|
|
329
|
+
For these, prove the relationship **your own way** inside an action, then ask
|
|
330
|
+
Quickback to mint a disciplined scope token from the row you proved.
|
|
331
|
+
|
|
332
|
+
### 1. Opt the role into supplied-subject proof
|
|
333
|
+
|
|
334
|
+
Add `subject` to the scope role (default `'user'`):
|
|
335
|
+
|
|
336
|
+
```typescript
|
|
337
|
+
authz: {
|
|
338
|
+
scopes: {
|
|
339
|
+
event: {
|
|
340
|
+
requestField: 'eventId',
|
|
341
|
+
roles: {
|
|
342
|
+
// 'both' → the SAME scope:event:attendee for a logged-in user
|
|
343
|
+
// (via /enter) AND a sessionless invite-holder (via ctx.mintScope).
|
|
344
|
+
attendee: { via: 'attendeeOf', subKeys: ['guestId'], subject: 'both' },
|
|
345
|
+
},
|
|
346
|
+
},
|
|
347
|
+
},
|
|
348
|
+
}
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
- **`'user'`** (default) — `/scope/v1/enter` only, proven by `subject.column = ctx.userId`. Unchanged.
|
|
352
|
+
- **`'supplied'`** — sessionless only. `ctx.mintScope` mints it; `/enter` won't (there's no user to probe).
|
|
353
|
+
- **`'both'`** — either path. A user-attendee and a sessionless invite-attendee converge on **one** `scope:event:attendee` — one firewall arm, one masking rule, both principals.
|
|
354
|
+
|
|
355
|
+
This opt-in is the single fail-closed switch: without `'supplied'` or `'both'`, no relationship is mintable by a supplied id.
|
|
356
|
+
|
|
357
|
+
### 2. Mint from the proven row
|
|
358
|
+
|
|
359
|
+
`ctx.mintScope` is hydrated on `ctx` in **any action** when a `subject:
|
|
360
|
+
'supplied' | 'both'` role is declared (including **PUBLIC** actions — the
|
|
361
|
+
canonical caller has no token yet). The action proves the principal however it
|
|
362
|
+
likes, then hands Quickback **only the conferring row's primary key**:
|
|
363
|
+
|
|
364
|
+
```typescript
|
|
365
|
+
// features/events/actions/enterEvent.ts
|
|
366
|
+
export default defineAction({
|
|
367
|
+
path: '/enter-event',
|
|
368
|
+
method: 'POST',
|
|
369
|
+
input: z.object({ code: z.string() }),
|
|
370
|
+
access: { roles: ['PUBLIC'] }, // unauthenticated entry
|
|
371
|
+
async execute({ ctx, input }) {
|
|
372
|
+
const guestRowId = await validateInviteCode(ctx, input.code); // YOUR proof, YOUR table
|
|
373
|
+
const { token } = await ctx.mintScope({ via: 'attendeeOf', subject: guestRowId });
|
|
374
|
+
return { token }; // client sends it as `Authorization: Bearer …` thereafter
|
|
375
|
+
},
|
|
376
|
+
});
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
You assert **nothing** about the scope. Quickback re-reads the `attendeeOf` row
|
|
380
|
+
by primary key and takes the role, the resource id (`eventId`), the sub-keys,
|
|
381
|
+
and the subject id **off that row** — so a buggy or hostile action can't forge
|
|
382
|
+
`organizer`, can't pick a different event, and can't widen the slice. The only
|
|
383
|
+
thing delegated to you is *which row* — exactly the opaque-credential check that
|
|
384
|
+
has to be custom code.
|
|
385
|
+
|
|
386
|
+
| What you supply | What Quickback reads off the row |
|
|
387
|
+
|---|---|
|
|
388
|
+
| `via` (a declared `supplied`/`both` relationship) + `subject` (the `from`-row PK you proved) | the role, `id` (resource), sub-keys, and `subjectId` — none caller-asserted |
|
|
389
|
+
|
|
390
|
+
The `where:` filter runs on the mint probe exactly as at `/enter` — a cancelled
|
|
391
|
+
or pending row confers nothing, so flipping a guest's `status` revokes them
|
|
392
|
+
within one mint cycle (**≤180s**). Re-prove by calling `ctx.mintScope` again
|
|
393
|
+
(your own refresh endpoint does exactly that). The by-PK probe does **not** apply
|
|
394
|
+
the relationship's tenant firewall (a sessionless principal has no
|
|
395
|
+
`activeOrgId` yet — the proven row *is* what establishes scope), but matching by
|
|
396
|
+
primary key + the `where:` filter keeps it bounded and fail-closed.
|
|
397
|
+
|
|
398
|
+
### 3. The scope-only token
|
|
399
|
+
|
|
400
|
+
`ctx.mintScope` signs a **scope-only** JWT — it carries the `scope` claim and
|
|
401
|
+
nothing else. There is **no user identity**: the auth middleware builds a context
|
|
402
|
+
with **`ctx.userId` undefined**, so every user-, org-, and owner-gated path
|
|
403
|
+
**fails closed automatically** (an owner firewall compares against `undefined`
|
|
404
|
+
→ matches nothing; org-role gates see empty `ctx.roles`). The `AUTHENTICATED`
|
|
405
|
+
and `USER` pseudo-roles **exclude** a scope principal by design — it is
|
|
406
|
+
authenticated *as a scope*, not as "any signed-in user". Only
|
|
407
|
+
`scope:<kind>:<role>` gates and `ctx.scope.<kind>` firewall arms admit it.
|
|
408
|
+
|
|
409
|
+
Everything downstream — REST firewall, masking, scoped-role access, the realtime
|
|
410
|
+
ws-ticket — then treats the sessionless attendee **identically** to a
|
|
411
|
+
user-proven one. There is no new enforcement surface; the principal is just
|
|
412
|
+
`scope:event:attendee`.
|
|
413
|
+
|
|
414
|
+
### `subjectId` — scoping to the person, not just the instance
|
|
415
|
+
|
|
416
|
+
A user-proven scope scopes self-data (an attendee's travel, dietary, todos) by
|
|
417
|
+
`ctx.userId`. A sessionless attendee has no `ctx.userId`, so the **proven
|
|
418
|
+
subject's identity rides in the claim** as a reserved **`subjectId`** — the
|
|
419
|
+
conferring row's primary key:
|
|
420
|
+
|
|
421
|
+
```jsonc
|
|
422
|
+
"scope": { "event": { "id": "evt_123", "roles": ["attendee"], "subjectId": "gst_42" } }
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
Scope self-data on it with one firewall arm:
|
|
426
|
+
|
|
427
|
+
```typescript
|
|
428
|
+
{ field: 'guestId', equals: 'ctx.scope.event.subjectId' }
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
`subjectId` is populated on **both** proof paths — `/scope/v1/enter` projects
|
|
432
|
+
the matched row's PK too — so the arm above is **one arm that serves both** a
|
|
433
|
+
logged-in attendee and a sessionless one. (It is distinct from
|
|
434
|
+
`ctx.scope.event.id`, which is the *instance* — the event.)
|
|
435
|
+
|
|
436
|
+
### Realtime
|
|
437
|
+
|
|
438
|
+
A scope-only token authorizes the realtime
|
|
439
|
+
[ws-ticket](/stack/realtime/durable-objects) directly off its proven
|
|
440
|
+
`ctx.scope` claim — no `ctx.userId` re-probe. The sessionless attendee joins the
|
|
441
|
+
same per-event rooms (and per-attendee rooms keyed on `subjectId`) as a
|
|
442
|
+
user-attendee, carrying the same scope role on the ticket. So the REST gate and
|
|
443
|
+
the socket gate stay identical for accountless principals too.
|
|
444
|
+
|
|
318
445
|
## Revocation & TTL
|
|
319
446
|
|
|
320
447
|
The scope claim is trusted between proofs — it is never re-checked against the database while it rides. Two bounds keep that window finite:
|
|
@@ -331,17 +458,28 @@ So removing a guest/staff row takes effect within **cap + one TTL** for a client
|
|
|
331
458
|
|
|
332
459
|
```typescript
|
|
333
460
|
// AppContext (generated lib/types.ts)
|
|
334
|
-
ctx.scope?: Record<string, { id: string; roles?: string[]; [subKey: string]: string | string[] | undefined }>;
|
|
461
|
+
ctx.scope?: Record<string, { id: string; roles?: string[]; subjectId?: string; [subKey: string]: string | string[] | undefined }>;
|
|
335
462
|
|
|
336
463
|
// authz.scopes.<kind>
|
|
337
464
|
{
|
|
338
465
|
requestField: string; // body field carrying the instance id
|
|
339
|
-
roles: Record<string, {
|
|
466
|
+
roles: Record<string, {
|
|
467
|
+
via: string;
|
|
468
|
+
subKeys?: string[]; // 'col' → eq, 'col[]' → inArray
|
|
469
|
+
subject?: 'user' | 'supplied' | 'both'; // who selects the conferring row (default 'user')
|
|
470
|
+
}>;
|
|
340
471
|
}
|
|
472
|
+
|
|
473
|
+
// ctx.mintScope — present in actions when a `subject: 'supplied' | 'both'` role is declared
|
|
474
|
+
ctx.mintScope(opts: { via: string; subject: string; setAuthToken?: boolean }):
|
|
475
|
+
Promise<{ token: string; scope: { id: string; roles: string[]; subjectId?: string } }>;
|
|
341
476
|
```
|
|
342
477
|
|
|
343
478
|
- `requestField` must equal every role-relationship's `resource.column`.
|
|
344
479
|
- Each relationship's `from` table must exist and ship a generated firewall (it can't be `exception`).
|
|
345
480
|
- A `subKeys` entry ending in `[]` is **set-valued** (lowers to `inArray`, minted as `string[]`); without the marker it's scalar (`eq`, minted as `string`).
|
|
481
|
+
- `subject` defaults to `'user'`. `'supplied'`/`'both'` enable [`ctx.mintScope`](#sessionless-scope-mint--ctxmintscope) (sessionless mint); `'supplied'` is **not** mintable via `/scope/v1/enter`.
|
|
482
|
+
- `ctx.mintScope({ via, subject })` mints a **scope-only** token (no user identity, `ctx.userId` undefined) from the `from`-row whose PK is `subject` — reading the role, resource id, sub-keys, and `subjectId` off that row.
|
|
483
|
+
- `subjectId` is the conferring row's primary key, populated on **both** proof paths — scope self-data on `ctx.scope.<kind>.subjectId`.
|
|
346
484
|
- `q.scope('<kind>')` auto-stamps the column from `ctx.scope.<kind>.id` on insert.
|
|
347
485
|
- Generated route: `POST /scope/v1/enter` (mounted only when `authz.scopes` is declared).
|
|
@@ -342,6 +342,14 @@ plugins, protects `POST /mcp`, emits RFC 8414 and RFC 9728 discovery, and
|
|
|
342
342
|
accepts the provider's JWKS-signed access tokens in the standard Quickback
|
|
343
343
|
auth middleware.
|
|
344
344
|
|
|
345
|
+
`audiences` (RFC 8707 resource indicators) is **unioned** with this worker's own
|
|
346
|
+
origin + `/mcp` — you list only the *other* resource servers you mint tokens for,
|
|
347
|
+
never losing your own. To run a **split authorization-server / resource-server**
|
|
348
|
+
topology (one SSO AS, many `/mcp` resource servers sharing one auth DB), a resource
|
|
349
|
+
server sets `oauth.issuerUrl` to the AS and `agents.mcp.requireAuth: true` — it then
|
|
350
|
+
verifies AS-issued bearers against the shared JWKS. See
|
|
351
|
+
[Agents → Split authorization server](/compiler/config/agents#split-authorization-server--resource-server-multi-app-sso).
|
|
352
|
+
|
|
345
353
|
The legacy plugin object remains available for provider-specific options:
|
|
346
354
|
|
|
347
355
|
```ts
|
|
@@ -352,7 +360,7 @@ auth: defineAuth("better-auth", {
|
|
|
352
360
|
loginPage: "/login", // path on ACCOUNT_URL — default
|
|
353
361
|
allowDynamicClientRegistration: true, // default
|
|
354
362
|
allowUnauthenticatedClientRegistration: true, // default — MCP needs this
|
|
355
|
-
validAudiences: ["https://
|
|
363
|
+
validAudiences: ["https://crm.example.com/mcp"], // optional — unioned with this AS's own origin + /mcp
|
|
356
364
|
scopes: ["openid", "profile", "email", "offline_access"],
|
|
357
365
|
},
|
|
358
366
|
},
|
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
```typescript
|
|
8
8
|
// services/schedules/sweepDigests.ts
|
|
9
9
|
import { defineSchedule } from "quickback";
|
|
10
|
+
import { runDigestSweep } from "../../features/comms/lib/digest-sweep";
|
|
10
11
|
|
|
11
12
|
export default defineSchedule({
|
|
12
13
|
name: "sweepDigests", // identifier + audit actor (system:cron-<name>)
|
|
@@ -20,6 +21,22 @@ export default defineSchedule({
|
|
|
20
21
|
|
|
21
22
|
One file per schedule under `services/schedules/*.ts`. Files prefixed with `_` are ignored. `name` must be a valid camelCase identifier (it's used as a generated symbol and the audit actor).
|
|
22
23
|
|
|
24
|
+
## Importing feature code
|
|
25
|
+
|
|
26
|
+
Schedule files live at `quickback/services/schedules/<name>.ts`, so imports are relative to **that** location. To reach a feature table, a feature `lib/` helper, or `db/`, climb up to the `quickback/` root first (`../../`):
|
|
27
|
+
|
|
28
|
+
```typescript
|
|
29
|
+
// quickback/services/schedules/bookingReminders.ts
|
|
30
|
+
import { bookings } from "../../features/crm/bookings"; // a feature table
|
|
31
|
+
import { generateIcsInvite } from "../../features/crm/lib/ics-generate"; // a feature lib/ helper
|
|
32
|
+
import { runDigestSweep } from "../../lib/digest-sweep"; // a shared lib/ helper
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Two `../` — up from `services/schedules/` to `quickback/`, then down into `features/` (or `lib/`, `db/`). The compiler relocates the handler into the generated `src/lib/schedules.ts` and **rewrites these paths to resolve from there automatically** — you always write them relative to your own source file, exactly as your editor resolves them.
|
|
36
|
+
|
|
37
|
+
> A single `../features/…` is the common mistake — from `services/schedules/` that resolves to `services/features/…`, which doesn't exist (the compiler consumes `services/`; there is no `src/services/`). Use `../../features/…`.
|
|
38
|
+
|
|
39
|
+
|
|
23
40
|
## What the compiler emits
|
|
24
41
|
|
|
25
42
|
1. **`scheduled(event, env, ctx)`** in the Worker's default export, dispatching to every schedule whose cron matches `event.cron`. Multiple schedules can share a cron; a failure in one is isolated from the others.
|
package/dist/codex/AGENTS.md
DELETED
|
@@ -1,290 +0,0 @@
|
|
|
1
|
-
# Quickback
|
|
2
|
-
|
|
3
|
-
Quickback is two things:
|
|
4
|
-
|
|
5
|
-
1. **Compiler** — Transforms declarative TypeScript definitions into secure, production-ready APIs
|
|
6
|
-
2. **Stack** — A Supabase alternative running entirely on Cloudflare (D1, R2, KV, Durable Objects, Queues, Workers AI)
|
|
7
|
-
|
|
8
|
-
The output is standard TypeScript (Hono, Drizzle, Better Auth) running on your own infrastructure.
|
|
9
|
-
|
|
10
|
-
## Project Structure
|
|
11
|
-
|
|
12
|
-
```
|
|
13
|
-
my-app/
|
|
14
|
-
├── quickback/
|
|
15
|
-
│ ├── quickback.config.ts
|
|
16
|
-
│ └── features/
|
|
17
|
-
│ └── {feature-name}/
|
|
18
|
-
│ ├── {table}.ts # Schema + security (defineTable)
|
|
19
|
-
│ ├── actions/ # One file per action — defineAction({...}) (optional)
|
|
20
|
-
│ │ ├── {action}.ts # Binds to primary table (or standalone if path: is set)
|
|
21
|
-
│ │ └── {table}/{action}.ts # Binds to sibling <table>.ts (multi-table features)
|
|
22
|
-
│ └── lib/ # Feature-local helpers, copied verbatim (optional)
|
|
23
|
-
└── ...
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
## quickback.config.ts
|
|
27
|
-
|
|
28
|
-
```typescript
|
|
29
|
-
import { defineConfig, defineRuntime, defineDatabase, defineAuth } from '@quickback/compiler';
|
|
30
|
-
|
|
31
|
-
export default defineConfig({
|
|
32
|
-
name: "my-saas-app",
|
|
33
|
-
providers: {
|
|
34
|
-
runtime: defineRuntime("cloudflare"),
|
|
35
|
-
database: defineDatabase("cloudflare-d1"),
|
|
36
|
-
auth: defineAuth("better-auth"),
|
|
37
|
-
},
|
|
38
|
-
});
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
## Automatic Audit Fields
|
|
42
|
-
|
|
43
|
-
Quickback auto-injects: `createdAt`, `modifiedAt`, `deletedAt`, `createdBy`, `modifiedBy`, `deletedBy`. Do NOT define these in schemas.
|
|
44
|
-
|
|
45
|
-
## defineTable() — Schema + Security
|
|
46
|
-
|
|
47
|
-
Each feature file exports a Drizzle table and a `defineTable()` default export with security config:
|
|
48
|
-
|
|
49
|
-
```typescript
|
|
50
|
-
import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
|
|
51
|
-
import { defineTable } from "@quickback/compiler";
|
|
52
|
-
|
|
53
|
-
export const todos = sqliteTable("todos", {
|
|
54
|
-
id: integer("id").primaryKey(),
|
|
55
|
-
title: text("title").notNull(),
|
|
56
|
-
description: text("description"),
|
|
57
|
-
completed: integer("completed", { mode: "boolean" }).default(false),
|
|
58
|
-
userId: text("user_id").notNull(),
|
|
59
|
-
organizationId: text("organization_id").notNull(),
|
|
60
|
-
});
|
|
61
|
-
|
|
62
|
-
export default defineTable(todos, {
|
|
63
|
-
firewall: [
|
|
64
|
-
{ field: "organizationId", equals: "ctx.activeOrgId" },
|
|
65
|
-
{ field: "userId", equals: "ctx.userId" },
|
|
66
|
-
{ field: "deletedAt", isNull: true },
|
|
67
|
-
],
|
|
68
|
-
read: { access: { roles: ["member", "admin"] } },
|
|
69
|
-
create: { access: { roles: ["member", "admin"] } },
|
|
70
|
-
update: { access: { roles: ["admin"] } },
|
|
71
|
-
delete: { access: { roles: ["admin"] }, mode: "soft" },
|
|
72
|
-
guards: {
|
|
73
|
-
createable: ["title", "description", "completed"],
|
|
74
|
-
updatable: ["title", "description", "completed"],
|
|
75
|
-
},
|
|
76
|
-
masking: {
|
|
77
|
-
userId: { type: "redact", show: { roles: ["admin"] } },
|
|
78
|
-
},
|
|
79
|
-
});
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
## Four Security Layers
|
|
83
|
-
|
|
84
|
-
Every request passes through: `Request → Firewall → Access → Guards → Database → Masking → Response`
|
|
85
|
-
|
|
86
|
-
### 1. Firewall — Data Isolation
|
|
87
|
-
|
|
88
|
-
Auto WHERE clauses for tenant isolation. Predicates are AND'd:
|
|
89
|
-
|
|
90
|
-
```typescript
|
|
91
|
-
firewall: [
|
|
92
|
-
{ field: 'organizationId', equals: 'ctx.activeOrgId' }, // WHERE organizationId = ctx.activeOrgId
|
|
93
|
-
{ field: 'ownerId', equals: 'ctx.userId' }, // AND ownerId = ctx.userId
|
|
94
|
-
{ field: 'teamId', equals: 'ctx.activeTeamId' }, // AND teamId = ctx.activeTeamId
|
|
95
|
-
{ field: 'deletedAt', isNull: true }, // AND deletedAt IS NULL
|
|
96
|
-
]
|
|
97
|
-
|
|
98
|
-
// Public/system resources opt out of tenant scoping (soft-delete still applied):
|
|
99
|
-
firewall: [{ exception: true }]
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
Auto-derived when omitted: scans the schema for `organizationId` / `ownerId` / `teamId` and emits matching predicates. Two or more isolation columns → declare explicitly.
|
|
103
|
-
|
|
104
|
-
### 2. Access — Permission Checks
|
|
105
|
-
|
|
106
|
-
Role-based and record-based (deny by default). Reads (`GET /` and `GET /:id`) gate via `read.access`; mutations gate via `create.access`, `update.access`, `delete.access`, and `upsert.access`.
|
|
107
|
-
|
|
108
|
-
```typescript
|
|
109
|
-
read: { access: { roles: ['member'] } }, // gates GET / and GET /:id
|
|
110
|
-
create: { access: { roles: ['admin'] } },
|
|
111
|
-
update: {
|
|
112
|
-
access: {
|
|
113
|
-
or: [
|
|
114
|
-
{ roles: ['admin'] },
|
|
115
|
-
{ record: { createdBy: { equals: '$ctx.userId' } } },
|
|
116
|
-
],
|
|
117
|
-
},
|
|
118
|
-
},
|
|
119
|
-
delete: { access: { roles: ['admin'] } },
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
> **DSL v2:** `crud.list` and `crud.get` are rejected at compile time. Move them to `read.access`.
|
|
123
|
-
|
|
124
|
-
Operators: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
|
|
125
|
-
Context: `$ctx.userId`, `$ctx.activeOrgId`, `$ctx.roles`
|
|
126
|
-
|
|
127
|
-
### 3. Guards — Field Protection
|
|
128
|
-
|
|
129
|
-
```typescript
|
|
130
|
-
guards: {
|
|
131
|
-
createable: ['name', 'description'],
|
|
132
|
-
updatable: ['description'],
|
|
133
|
-
immutable: ['invoiceNumber'],
|
|
134
|
-
protected: { status: ['approve'] }, // Only via named actions
|
|
135
|
-
}
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
### 4. Masking — PII Redaction
|
|
139
|
-
|
|
140
|
-
```typescript
|
|
141
|
-
masking: {
|
|
142
|
-
ssn: { type: 'ssn', show: { roles: ['admin'] } },
|
|
143
|
-
email: { type: 'email', show: { roles: ['admin'], or: 'owner' } },
|
|
144
|
-
}
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
Types: `email`, `phone`, `ssn`, `creditCard`, `name`, `redact`, `custom`
|
|
148
|
-
|
|
149
|
-
## Views — Column Projections
|
|
150
|
-
|
|
151
|
-
```typescript
|
|
152
|
-
views: {
|
|
153
|
-
summary: { fields: ['id', 'name'], access: { roles: ['member'] } },
|
|
154
|
-
full: { fields: ['id', 'name', 'phone', 'ssn'], access: { roles: ['admin'] } },
|
|
155
|
-
}
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
## Validation
|
|
159
|
-
|
|
160
|
-
```typescript
|
|
161
|
-
validation: {
|
|
162
|
-
name: { minLength: 1, maxLength: 100 },
|
|
163
|
-
capacity: { min: 1, max: 1000 },
|
|
164
|
-
roomType: { enum: ['meeting', 'conference'] },
|
|
165
|
-
email: { email: true },
|
|
166
|
-
}
|
|
167
|
-
```
|
|
168
|
-
|
|
169
|
-
## Actions — Custom Business Logic
|
|
170
|
-
|
|
171
|
-
One file per action under `actions/<name>.ts`. The filename is the action name AND URL segment. `actions/<name>.ts` binds to the feature's primary table; `actions/<table>/<name>.ts` binds to a sibling table. Setting `path:` makes the action standalone.
|
|
172
|
-
|
|
173
|
-
```typescript
|
|
174
|
-
// features/todos/actions/complete.ts
|
|
175
|
-
import { z } from "zod";
|
|
176
|
-
import { eq } from "drizzle-orm";
|
|
177
|
-
import { defineAction } from "../.quickback/define-action";
|
|
178
|
-
import { todos } from "../todos";
|
|
179
|
-
|
|
180
|
-
export default defineAction({
|
|
181
|
-
description: "Mark todo as complete",
|
|
182
|
-
input: z.object({ completedAt: z.string().datetime().optional() }),
|
|
183
|
-
access: { roles: ["member", "admin"], record: { completed: { equals: false } } },
|
|
184
|
-
async execute({ db, record, auditFields }) {
|
|
185
|
-
await db.update(todos)
|
|
186
|
-
.set({ completed: true, modifiedAt: auditFields!.modifiedAt })
|
|
187
|
-
.where(eq(todos.id, record.id));
|
|
188
|
-
return { success: true };
|
|
189
|
-
},
|
|
190
|
-
});
|
|
191
|
-
```
|
|
192
|
-
|
|
193
|
-
Record-based (no `path:`): `POST /api/v1/{resource}/:id/{action}`
|
|
194
|
-
Standalone (`path:` set): custom `path` and `method`
|
|
195
|
-
|
|
196
|
-
`execute:` must be an `async (ctx) => { … }` arrow function. Retired (rejected at load time): bundled `actions.ts`, `_feature.ts`, `handlers/` directory, `defineActions()`.
|
|
197
|
-
|
|
198
|
-
### Actions-Only Features (no tables)
|
|
199
|
-
|
|
200
|
-
A feature with no top-level `*.ts` files is "tableless" — every action must be standalone (have `path:`).
|
|
201
|
-
|
|
202
|
-
```typescript
|
|
203
|
-
// quickback/features/utilities/actions/health-check.ts
|
|
204
|
-
import { z } from "zod";
|
|
205
|
-
import { defineAction } from "../.quickback/define-action";
|
|
206
|
-
|
|
207
|
-
export default defineAction({
|
|
208
|
-
description: "Health check",
|
|
209
|
-
path: "/health",
|
|
210
|
-
method: "GET",
|
|
211
|
-
input: z.object({}),
|
|
212
|
-
access: { roles: ["member", "admin"] },
|
|
213
|
-
async execute() { return { ok: true }; },
|
|
214
|
-
});
|
|
215
|
-
```
|
|
216
|
-
|
|
217
|
-
### Public Actions
|
|
218
|
-
|
|
219
|
-
Use `roles: ["PUBLIC"]` for unauthenticated endpoints. Mandatory audit logged. The wildcard `"*"` is not supported.
|
|
220
|
-
|
|
221
|
-
```typescript
|
|
222
|
-
access: { roles: ["PUBLIC"] } // No auth, audit logged
|
|
223
|
-
access: { roles: ["member"] } // Requires auth + role
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
## Custom Dependencies
|
|
227
|
-
|
|
228
|
-
```typescript
|
|
229
|
-
export default defineConfig({
|
|
230
|
-
build: {
|
|
231
|
-
dependencies: {
|
|
232
|
-
"fast-xml-parser": "^4.5.0",
|
|
233
|
-
},
|
|
234
|
-
},
|
|
235
|
-
});
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
## CMS Layouts
|
|
239
|
-
|
|
240
|
-
```typescript
|
|
241
|
-
layouts: {
|
|
242
|
-
default: {
|
|
243
|
-
sections: [
|
|
244
|
-
{ label: "Details", columns: 2, fields: ["name", "email"] },
|
|
245
|
-
{ label: "Notes", collapsed: true, fields: ["notes"] },
|
|
246
|
-
],
|
|
247
|
-
},
|
|
248
|
-
}
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
## API Reference
|
|
252
|
-
|
|
253
|
-
| Method | Endpoint | Description |
|
|
254
|
-
|--------|----------|-------------|
|
|
255
|
-
| `GET` | `/api/v1/{resource}` | List |
|
|
256
|
-
| `GET` | `/api/v1/{resource}/:id` | Get |
|
|
257
|
-
| `POST` | `/api/v1/{resource}` | Create |
|
|
258
|
-
| `PATCH` | `/api/v1/{resource}/:id` | Update |
|
|
259
|
-
| `DELETE` | `/api/v1/{resource}/:id` | Delete |
|
|
260
|
-
|
|
261
|
-
Query params: `?limit=50&offset=0`, `?status=active`, `?sort=-createdAt`, `?fields=id,name`, `?search=text`
|
|
262
|
-
Filter operators: `.gt`, `.gte`, `.lt`, `.lte`, `.ne`, `.like`, `.in`
|
|
263
|
-
|
|
264
|
-
## Database Dialects
|
|
265
|
-
|
|
266
|
-
| Stack | Import | Table Function |
|
|
267
|
-
|-------|--------|----------------|
|
|
268
|
-
| Cloudflare D1 / SQLite | `drizzle-orm/sqlite-core` | `sqliteTable` |
|
|
269
|
-
| Supabase / PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
|
|
270
|
-
|
|
271
|
-
## Migrations are generated — never hand-merge them
|
|
272
|
-
|
|
273
|
-
The files under `quickback/drizzle/` (`*.sql`, `meta/_journal.json`, `meta/*_snapshot.json`) are **generated artifacts**, not source. Never hand-edit them, and never resolve a merge or rebase conflict inside them.
|
|
274
|
-
|
|
275
|
-
When integrating a branch: get the feature/schema `.ts` files in first, then run `quickback compile`. The compiler regenerates the migrations from the merged schema and journals them in the correct (append-only) order. Hand-merging migration SQL or snapshots produces schema drift and broken ordering that only surfaces at deploy time. If a migration file conflicts during a merge, take either side to unblock, then recompile and let the compiler restate the migrations.
|
|
276
|
-
|
|
277
|
-
## CLI Commands
|
|
278
|
-
|
|
279
|
-
```bash
|
|
280
|
-
quickback create <template> <name> # Create project
|
|
281
|
-
quickback compile # Compile definitions
|
|
282
|
-
quickback docs [topic] # Show documentation
|
|
283
|
-
quickback claude install # Install Claude Code skill
|
|
284
|
-
quickback cursor install # Install Cursor rules
|
|
285
|
-
quickback codex install # Install Codex AGENTS.md rules
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
## Full Documentation
|
|
289
|
-
|
|
290
|
-
https://docs.quickback.dev
|
package/dist/commands/codex.d.ts
DELETED
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Codex command - manage ChatGPT Codex AGENTS.md rules.
|
|
3
|
-
*
|
|
4
|
-
* Codex reads `AGENTS.md` from the project root (merging up the tree), so unlike
|
|
5
|
-
* Cursor's dedicated .mdc file the rules live in a file the user may also own.
|
|
6
|
-
* We therefore manage only a delimited block, leaving the rest of AGENTS.md
|
|
7
|
-
* untouched.
|
|
8
|
-
*
|
|
9
|
-
* Usage:
|
|
10
|
-
* quickback codex install # Add/update the Quickback block in ./AGENTS.md
|
|
11
|
-
* quickback codex update # Alias for install (refresh the block)
|
|
12
|
-
* quickback codex remove # Strip the Quickback block
|
|
13
|
-
* quickback codex status # Check installation status
|
|
14
|
-
*/
|
|
15
|
-
export declare function codex(args: string[]): Promise<void>;
|
|
16
|
-
//# sourceMappingURL=codex.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/commands/codex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAwIH,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBzD"}
|