@quickback-dev/cli 0.66.17 → 0.66.18
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/build.d.ts.map +1 -1
- package/dist/commands/build.js +26 -20
- package/dist/commands/build.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts +3 -2
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +3 -2
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/file-writer.d.ts +9 -0
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js +30 -5
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/skill/docs/api/actions.md +10 -9
- package/dist/skill/docs/api/errors.md +14 -2
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/api/query-params.md +3 -3
- package/dist/skill/docs/configure/auth.md +8 -4
- package/dist/skill/docs/configure/index.md +1 -1
- package/dist/skill/docs/define/access.md +16 -6
- package/dist/skill/docs/define/actions/defining.md +8 -1
- package/dist/skill/docs/define/actions/scoped-db.md +69 -8
- package/dist/skill/docs/define/changesets.md +8 -3
- package/dist/skill/docs/define/encryption.md +6 -3
- package/dist/skill/docs/define/fga.md +9 -4
- package/dist/skill/docs/define/firewall.md +15 -7
- package/dist/skill/docs/define/masking.md +1 -1
- package/dist/skill/docs/define/relationships.md +6 -3
- package/dist/skill/docs/define/schema.md +27 -2
- package/dist/skill/docs/define/scopes.md +15 -1
- package/dist/skill/docs/define/transitions.md +5 -0
- package/dist/skill/docs/define/views.md +9 -0
- package/dist/skill/docs/platform/api-contract/index.md +4 -2
- package/dist/skill/docs/platform/auth/api-keys.md +10 -1
- package/dist/skill/docs/platform/auth/jwt-optimization.md +10 -4
- package/dist/skill/docs/platform/auth/plugins/aws-ses.md +11 -4
- package/dist/skill/docs/platform/auth/plugins/index.md +4 -2
- package/dist/skill/docs/platform/auth/plugins/subscriptions.md +3 -3
- package/dist/skill/docs/platform/push/index.md +31 -23
- package/dist/skill/docs/platform/storage/r2.md +36 -4
- package/dist/skill/docs/platform/vector/embeddings.md +11 -76
- package/dist/skill/docs/platform/vector/index.md +1 -1
- package/dist/skill/docs/platform/vector/using-embeddings.md +10 -73
- package/dist/skill/docs/platform/webhooks/outbound.md +12 -8
- package/dist/skill/docs/tooling/cli.md +2 -2
- package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +2 -1
- package/dist/skill/docs/tooling/cloud-compiler/index.md +18 -3
- package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +7 -4
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +1 -1
- package/dist/skill/docs/tooling/output.md +6 -2
- package/dist/skill/docs/ui/account/hooks.md +2 -2
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +10 -9
- package/src/skill/docs/api/errors.md +14 -2
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/api/query-params.md +3 -3
- package/src/skill/docs/configure/auth.md +8 -4
- package/src/skill/docs/configure/index.md +1 -1
- package/src/skill/docs/define/access.md +16 -6
- package/src/skill/docs/define/actions/defining.md +8 -1
- package/src/skill/docs/define/actions/scoped-db.md +69 -8
- package/src/skill/docs/define/changesets.md +8 -3
- package/src/skill/docs/define/encryption.md +6 -3
- package/src/skill/docs/define/fga.md +9 -4
- package/src/skill/docs/define/firewall.md +15 -7
- package/src/skill/docs/define/masking.md +1 -1
- package/src/skill/docs/define/relationships.md +6 -3
- package/src/skill/docs/define/schema.md +27 -2
- package/src/skill/docs/define/scopes.md +15 -1
- package/src/skill/docs/define/transitions.md +5 -0
- package/src/skill/docs/define/views.md +9 -0
- package/src/skill/docs/platform/api-contract/index.md +4 -2
- package/src/skill/docs/platform/auth/api-keys.md +10 -1
- package/src/skill/docs/platform/auth/jwt-optimization.md +10 -4
- package/src/skill/docs/platform/auth/plugins/aws-ses.md +11 -4
- package/src/skill/docs/platform/auth/plugins/index.md +4 -2
- package/src/skill/docs/platform/auth/plugins/subscriptions.md +3 -3
- package/src/skill/docs/platform/push/index.md +31 -23
- package/src/skill/docs/platform/storage/r2.md +36 -4
- package/src/skill/docs/platform/vector/embeddings.md +11 -76
- package/src/skill/docs/platform/vector/index.md +1 -1
- package/src/skill/docs/platform/vector/using-embeddings.md +10 -73
- package/src/skill/docs/platform/webhooks/outbound.md +12 -8
- package/src/skill/docs/tooling/cli.md +2 -2
- package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +2 -1
- package/src/skill/docs/tooling/cloud-compiler/index.md +18 -3
- package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +7 -4
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +1 -1
- package/src/skill/docs/tooling/output.md +6 -2
- package/src/skill/docs/ui/account/hooks.md +2 -2
|
@@ -22,9 +22,11 @@ The JWT encodes everything needed for auth middleware:
|
|
|
22
22
|
| Claim | Description |
|
|
23
23
|
|-------|-------------|
|
|
24
24
|
| `sub` | User ID |
|
|
25
|
+
| `sid` | Better Auth session the token was minted from — carried by scope mints and the rolling refresh too, so [`qbrev:sid`](/configure/auth#revocationcheck-none--kv--token-revocation-strategy) revokes every token descended from a signed-out session |
|
|
25
26
|
| `orgId` | Active organization ID |
|
|
26
27
|
| `role` | Organization membership role (`owner`, `admin`, `member`) |
|
|
27
28
|
| `userRole` | Global user role (when admin panel is enabled) |
|
|
29
|
+
| `ict` | Identity proof time (unix seconds) — when `orgId` / `role` / `userRole` / `tiers` were last read from the database. Stamped only by the session-path mint and `GET /auth/v1/token`; carried verbatim by `/scope/v1/enter`, namespace mints and the rolling refresh, which drop those claims once `ict` is older than the 15-minute carry-forward cap (or absent). See [Scopes](/define/scopes#revocation--ttl) |
|
|
28
30
|
| `email` | User email |
|
|
29
31
|
| `name` | User display name |
|
|
30
32
|
| `iat` | Issued-at timestamp (unix **seconds**, the standard claim) |
|
|
@@ -68,8 +70,9 @@ Validation steps (in generated `src/middleware/auth.ts`):
|
|
|
68
70
|
2. Call `verifyJwt(token, env)` from `src/lib/jwt.ts`
|
|
69
71
|
3. Verify the EdDSA signature with jose against the keyring's public JWKS — cached per isolate, refetched at most once when a token names an unknown `kid` (key rotation). Only `EdDSA` is accepted, so alg-confusion is rejected by construction, and `iss` / `aud` are pinned to the compile-time constants
|
|
70
72
|
4. Check `exp` against the current time
|
|
71
|
-
5. On success: hydrate `AppContext` from claims (`sub`, `orgId`, `role`, `userRole`, `email`, `name`) — no DB query
|
|
72
|
-
6. On failure (
|
|
73
|
+
5. On success: hydrate `AppContext` from claims (`sub`, `sid`, `orgId`, `role`, `userRole`, `email`, `name`) — no DB query
|
|
74
|
+
6. On failure for a token **this project minted** (rotated key, expired, tampered, revoked — recognised by the pinned `iss`, or the legacy HS256 shape): **`401`** with `AUTH_INVALID_TOKEN` (`AUTH_EXPIRED` when `exp` has passed) and `WWW-Authenticate: Bearer error="invalid_token"`. No fall-through: a presented-and-bad credential is never treated as no credential, so clients can key "drop the cached token and re-mint" on 401 alone. A foreign JWT (an OAuth access token — same keyring, OAuth issuer) falls through to its own verifier — which is why [`auth.jwt.issuer`](/configure/auth#issuer-string--iss-claim) may never equal the OAuth issuer (compile error). A token that *verifies* but is not one this lane admits (a session user's scope token on a project without `auth.jwt`) is a good credential, not a bad one: it falls through to session auth
|
|
75
|
+
7. With no JWT at all: fall back to Better Auth's session cookie auth; if that succeeds, mint a fresh JWT and return it in the `set-auth-token` response header
|
|
73
76
|
|
|
74
77
|
The Files worker (R2 uploads) runs the same verifier (`src/lib/jwt-verify.ts`) over the public keys it reads from the `jwks` table — no shared secret, no network round-trip to the auth API for file operations.
|
|
75
78
|
|
|
@@ -168,11 +171,14 @@ When a JWT expires or is invalid:
|
|
|
168
171
|
|
|
169
172
|
## Token Endpoint
|
|
170
173
|
|
|
171
|
-
`GET /auth/v1/token` — Better Auth's jwt plugin — mints a fresh JWT from the current session. Present only when `auth.jwt` is declared; the claims come from the compiler-emitted `resolveIdentityClaims` (`sid`, `orgId` beside the raw membership `role`, `userRole`, `tiers`, `email`, `name`, pinned `iss` / `aud`), and the TTL is your [`auth.jwt.expiresIn`](/configure/auth#expiresin-number--ttl-in-seconds) — the same value the session-path refresh uses. There is no Quickback-generated `/api/v1/token` any more.
|
|
174
|
+
`GET /auth/v1/token` — Better Auth's jwt plugin — mints a fresh JWT from the current session. Present only when `auth.jwt` is declared; the claims come from the compiler-emitted `resolveIdentityClaims` (`sid`, `ict`, `orgId` beside the raw membership `role`, `userRole`, `tiers`, `email`, `name`, pinned `iss` / `aud`), and the TTL is your [`auth.jwt.expiresIn`](/configure/auth#expiresin-number--ttl-in-seconds) — the same value the session-path refresh uses. There is no Quickback-generated `/api/v1/token` any more.
|
|
172
175
|
|
|
173
176
|
**Session authentication is required — and enforced.** The plugin gates the
|
|
174
177
|
endpoint on a Better Auth session (cookie or session-token bearer); a request
|
|
175
178
|
authenticated by a bearer JWT, an API key, or an OAuth access token gets `401`.
|
|
179
|
+
An `x-api-key` stands in for its owner's session on exactly one Better Auth
|
|
180
|
+
endpoint — `GET /auth/v1/get-session` — and nowhere else under `/auth/v1/*`
|
|
181
|
+
(see [API Keys](/platform/auth/api-keys)).
|
|
176
182
|
This is deliberate: only the session path re-validates against Better Auth's
|
|
177
183
|
session store on every request, so bans, member removals, role demotions, and
|
|
178
184
|
sign-outs take effect immediately. If a JWT could mint its own replacement, a
|
|
@@ -281,7 +287,7 @@ Whenever the project signs any JWT — an `auth.jwt` lane, [`authz.scopes`](/def
|
|
|
281
287
|
|
|
282
288
|
- **The keyring** — the EdDSA key pair in the `jwks` table, private key encrypted at rest with `BETTER_AUTH_SECRET`.
|
|
283
289
|
- **`GET /auth/v1/jwks`** — the public keys. Any external service verifies Quickback tokens from here; nothing needs the secret.
|
|
284
|
-
- **`GET /auth/v1/token`** — mints an identity JWT for the current session (cookie or session-token bearer). Its claims come from the compiler-emitted `resolveIdentityClaims` in `src/lib/auth.ts`: `sid`, `orgId` beside the **raw** membership `role`, `userRole`, `tiers`, `email`, `name`, and the pinned `iss` / `aud` — the same shape the middleware mints on the session path. Present only when `auth.jwt` is declared; otherwise the path is disabled and the keyring exists for scope and agent tokens alone.
|
|
290
|
+
- **`GET /auth/v1/token`** — mints an identity JWT for the current session (cookie or session-token bearer). Its claims come from the compiler-emitted `resolveIdentityClaims` in `src/lib/auth.ts`: `sid`, `ict`, `orgId` beside the **raw** membership `role`, `userRole`, `tiers`, `email`, `name`, and the pinned `iss` / `aud` — the same shape the middleware mints on the session path. Present only when `auth.jwt` is declared; otherwise the path is disabled and the keyring exists for scope and agent tokens alone.
|
|
285
291
|
|
|
286
292
|
### What Quickback still mints
|
|
287
293
|
|
|
@@ -74,21 +74,28 @@ interface Input {
|
|
|
74
74
|
supportEmail?: string;
|
|
75
75
|
}
|
|
76
76
|
|
|
77
|
+
// `name` is whatever the user typed at sign-up — escape every value you put in HTML.
|
|
78
|
+
const esc = (v: string) =>
|
|
79
|
+
v.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>')
|
|
80
|
+
.replace(/"/g, '"').replace(/'/g, ''');
|
|
81
|
+
|
|
77
82
|
export default function welcomeTemplate({ otp, name, appName, appUrl }: Input) {
|
|
78
83
|
const greeting = name ? `Hi ${name},` : 'Hi,';
|
|
79
84
|
return {
|
|
80
85
|
subject: `Welcome to ${appName} — set your password`,
|
|
81
86
|
html: `
|
|
82
|
-
<h1>Welcome to ${appName}</h1>
|
|
83
|
-
<p>${greeting} your account is ready. Use this code to set your password and sign in:</p>
|
|
84
|
-
<p style="font-size:32px;letter-spacing:8px"><b>${otp}</b></p>
|
|
85
|
-
<p>Visit <a href="${appUrl}/set-password">${appUrl}/set-password</a> to finish setup.</p>
|
|
87
|
+
<h1>Welcome to ${esc(appName)}</h1>
|
|
88
|
+
<p>${esc(greeting)} your account is ready. Use this code to set your password and sign in:</p>
|
|
89
|
+
<p style="font-size:32px;letter-spacing:8px"><b>${esc(otp)}</b></p>
|
|
90
|
+
<p>Visit <a href="${esc(appUrl)}/set-password">${esc(appUrl)}/set-password</a> to finish setup.</p>
|
|
86
91
|
`,
|
|
87
92
|
text: `${greeting}\n\nYour ${appName} code: ${otp}\n\nFinish setup at ${appUrl}/set-password`,
|
|
88
93
|
};
|
|
89
94
|
}
|
|
90
95
|
```
|
|
91
96
|
|
|
97
|
+
Template inputs arrive **unescaped** — `name` in particular is user-controlled. The built-in templates HTML-escape every interpolation; an override must do the same, or a sign-up name like `<a href=…>` renders as live markup in the recipient's inbox.
|
|
98
|
+
|
|
92
99
|
Recognized keys:
|
|
93
100
|
|
|
94
101
|
| Key | When it fires |
|
|
@@ -272,7 +272,7 @@ Better Auth's JWT plugin owns the keyring every Quickback token is signed with.
|
|
|
272
272
|
|
|
273
273
|
**Endpoints:**
|
|
274
274
|
- `GET /auth/v1/jwks` — the public keys. External services verify Quickback tokens from here without holding any secret.
|
|
275
|
-
- `GET /auth/v1/token` — mint an identity JWT for the current session (cookie or session-token bearer). Carries the same claims the middleware mints: `sid`, `orgId` beside the raw `role`, `userRole`, `tiers`, `email`, `name`. TTL is `auth.jwt.expiresIn` (default 180 s). Present only when `auth.jwt` is declared.
|
|
275
|
+
- `GET /auth/v1/token` — mint an identity JWT for the current session (cookie or session-token bearer). Carries the same claims the middleware mints: `sid`, `ict`, `orgId` beside the raw `role`, `userRole`, `tiers`, `email`, `name`. TTL is `auth.jwt.expiresIn` (default 180 s). Present only when `auth.jwt` is declared.
|
|
276
276
|
|
|
277
277
|
> The keyring is one system with Quickback's fast-path, not a second token format: identity tokens, the session-path refresh, and scope tokens are all EdDSA-signed with the same key and checked by the same verifier. See [JWT Optimization → Relation to Better Auth's JWT Plugin](/platform/auth/jwt-optimization#relation-to-better-auths-jwt-plugin).
|
|
278
278
|
|
|
@@ -301,6 +301,8 @@ The header takes precedence when both are present. The query-param form lands in
|
|
|
301
301
|
- `GET /auth/v1/api-key/list` — list keys for the current user
|
|
302
302
|
- `POST /auth/v1/api-key/delete` — revoke a key
|
|
303
303
|
|
|
304
|
+
These need a real session (cookie or session-token bearer). Under `/auth/v1/*` a key authenticates only `GET /auth/v1/get-session`; every other Better Auth endpoint ignores `x-api-key`, so a leaked key cannot mint JWTs, manage keys, or act on organizations. See [API Keys](/platform/auth/api-keys).
|
|
305
|
+
|
|
304
306
|
Keys can carry organization context via `metadata.organizationId` — when set, the auth middleware looks up the user's role in that org and populates `ctx.roles` accordingly, so a single key inherits the same firewall + access scope as the user who created it.
|
|
305
307
|
|
|
306
308
|
### OAuth Provider (MCP-ready)
|
|
@@ -502,7 +504,7 @@ export const longSessionPlugin = {
|
|
|
502
504
|
|
|
503
505
|
#### Out of scope
|
|
504
506
|
|
|
505
|
-
- **No schema generation.** If your plugin needs database tables, declare them as a Quickback feature
|
|
507
|
+
- **No schema generation.** If your plugin needs database tables or extra fields, declare them as a Quickback feature. The compiler never loads project-local plugin files while it generates the auth schema, so a plugin's `schema` is not read. A referenced plugin whose source declares a `schema` gets a compile warning. (Bare-specifier plugins are loaded, from the compiler's pinned dependencies — never from anything your project uploads — so a package the compiler bundles, such as `better-auth/plugins`, still contributes its schema.)
|
|
506
508
|
- **No conditional inclusion.** Every entry in `customPlugins` is always emitted. Gate environment-specific plugins inside the plugin file itself.
|
|
507
509
|
- **No name collision check against the named registry.** Duplicate registration is a Better Auth runtime concern, not a compile-time one — don't reach for `customPlugins` to override a named plugin's options; use the object form on `plugins` instead.
|
|
508
510
|
|
|
@@ -287,9 +287,9 @@ Everything under `src/` is generated — change tiers in `quickback.config.ts` a
|
|
|
287
287
|
import { q, defineTable } from "@quickback/compiler";
|
|
288
288
|
|
|
289
289
|
export const projects = q.table("projects", {
|
|
290
|
-
id: q.
|
|
291
|
-
|
|
292
|
-
name: q.text(
|
|
290
|
+
id: q.id(),
|
|
291
|
+
ownerId: q.scope("owner"),
|
|
292
|
+
name: q.text().required(),
|
|
293
293
|
...q.audit(),
|
|
294
294
|
...q.softDelete(),
|
|
295
295
|
});
|
|
@@ -6,7 +6,7 @@ APNs is planned as a second provider. The helper signature is shared, so most co
|
|
|
6
6
|
|
|
7
7
|
## What you get
|
|
8
8
|
|
|
9
|
-
- **`enqueuePushFanout(queue, target, payload, opts?)`** — the primary send surface. Takes a declarative audience (`{
|
|
9
|
+
- **`enqueuePushFanout(queue, target, payload, opts?)`** — the primary send surface. Takes a declarative audience (`{ organizationId, targetRoles? }`, `{ userIds }`, `{ targetTags }`, `{ all: true }`) or an explicit subscription list, and routes between inline delivery and queue fan-out.
|
|
10
10
|
- **`sendPush(subscription, payload, vapid)`** — single-recipient delivery. Returns `{ status: 'sent' | 'gone' | 'failed', statusCode, ... }`.
|
|
11
11
|
- **`sendPushBulk(subscriptions, payload, vapid, opts?)`** — in-request fan-out with a default concurrency cap of 8 (Workers subrequest-budget friendly).
|
|
12
12
|
- **`vapidFromEnv(env)`** — assembles the `VapidConfig` from `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY` / `VAPID_SUBJECT`.
|
|
@@ -56,7 +56,7 @@ With `push.defaultSchema: true`, the compiler injects a hardened, owner-scoped `
|
|
|
56
56
|
- **INTERNAL-only reads** — the crypto fields (`endpoint`, `p256dh`, `auth`) never leave the worker via any HTTP path. A `views.mine` projection exposes only `id`, `userAgent`, `lastSeenAt`, `createdAt` for "Your devices" UIs.
|
|
57
57
|
- **Owner firewall** — `owner_id` is auto-stamped on create; user A can never read or delete user B's subscription.
|
|
58
58
|
- **Create-time validation** — the endpoint must be `https:` (the worker POSTs VAPID-signed requests at that URL, so an arbitrary endpoint is an SSRF primitive), `p256dh` must decode to a 65-byte uncompressed P-256 point, and `auth` to a 16-byte secret. The `https:` check is not the whole SSRF story: at send time the push sender additionally rejects any endpoint whose host resolves to a private, link-local, loopback, `localhost`, or `.internal` address. Together — **https + a non-public-host block** — this narrows the SSRF surface; treat it as defense-in-depth, not a guarantee that SSRF is impossible.
|
|
59
|
-
- **Proven identity tags** — a `tags` column is stamped **server-side** from `ctx
|
|
59
|
+
- **Proven identity tags** — a `tags` column is stamped **server-side** from `ctx`: `user:<id>`, and — only when the request carries a scoped token — `scope:<kind>:<subject>` plus one `scope:<kind>:<instance>#<role>` per scope role the verified claim grants (the same dialect realtime tickets use). Client-supplied tags are ignored: they drive fan-out targeting. **Org roles are never stamped** — a device is user-owned, and org audiences are resolved from live membership at send time; see [Targeting](#targeting).
|
|
60
60
|
- **Rate limit + cap** — creates are limited to 10/minute per caller, and only the newest 10 live subscriptions per user are kept (older rows are soft-deleted, so a user's new device always works).
|
|
61
61
|
|
|
62
62
|
This create-time hardening (endpoint/key validation, server-side tag stamping, the per-user cap) runs in JS before/after-insert hooks that fire **only on audit-wrapped writes** — the REST create path and actions. The normal browser subscribe is REST, so it's fully covered; but raw-SQL writes, queue/cron inserts, or direct INTERNAL-context inserts into `push_subscriptions` bypass all of it. Don't hand-insert subscription rows expecting the guards to apply.
|
|
@@ -181,22 +181,27 @@ export default defineAction({
|
|
|
181
181
|
description: "Publish an event and notify admins.",
|
|
182
182
|
input: z.object({}),
|
|
183
183
|
access: { roles: ["owner", "admin"] },
|
|
184
|
-
async execute({ record, env, effects }) {
|
|
184
|
+
async execute({ record, ctx, env, effects }) {
|
|
185
185
|
// ...your committed write happens here...
|
|
186
186
|
|
|
187
|
-
// After-commit: notify
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
187
|
+
// After-commit: notify this organization's admins (owners too, via
|
|
188
|
+
// auth.roleHierarchy). The scope is on the send — resolved from
|
|
189
|
+
// membership when the queue consumer runs, never from the device.
|
|
190
|
+
const organizationId = ctx.activeOrgId;
|
|
191
|
+
if (organizationId) {
|
|
192
|
+
effects.enqueue("push:eventPublished", () =>
|
|
193
|
+
enqueuePushFanout(
|
|
194
|
+
env.PUSH_FANOUT_QUEUE!,
|
|
195
|
+
{ organizationId, targetRoles: ["admin"] },
|
|
196
|
+
{
|
|
197
|
+
title: record.name,
|
|
198
|
+
body: "Event published — tap to review",
|
|
199
|
+
url: `https://app.example.com/events/${record.id}`,
|
|
200
|
+
tag: `event-${record.id}`,
|
|
201
|
+
},
|
|
202
|
+
),
|
|
203
|
+
);
|
|
204
|
+
}
|
|
200
205
|
|
|
201
206
|
return { published: true };
|
|
202
207
|
},
|
|
@@ -205,24 +210,27 @@ export default defineAction({
|
|
|
205
210
|
|
|
206
211
|
The declarative form enqueues **one small message**; the generated queue consumer resolves the audience against `push_subscriptions` inside the server-internal trust zone and fans out delivery chunks. Subscription crypto never enters your action code.
|
|
207
212
|
|
|
208
|
-
Target
|
|
213
|
+
Target an organization with `{ organizationId, targetRoles? }` or specific people with `{ userIds }` — both work for every subscription, because they resolve against the row's owner rather than a stamped claim.
|
|
209
214
|
|
|
210
215
|
### Targeting
|
|
211
216
|
|
|
212
|
-
|
|
217
|
+
A declarative target names **exactly one** audience:
|
|
213
218
|
|
|
214
219
|
| Target | Selects |
|
|
215
220
|
|---|---|
|
|
216
|
-
| `{
|
|
221
|
+
| `{ organizationId: 'org_1' }` | Devices of every current member of that organization |
|
|
222
|
+
| `{ organizationId: 'org_1', targetRoles: ['admin'] }` | Devices of that org's members holding a listed role — `auth.roleHierarchy`-expanded, so an `owner` satisfies `'admin'` |
|
|
223
|
+
| `{ organizationId: 'org_1', targetRoles: [...], userIds: [...] }` | The same, narrowed to those users |
|
|
217
224
|
| `{ userIds: ['u1', 'u2'] }` | Subscriptions owned by those users |
|
|
225
|
+
| `{ targetTags: ['scope:event:e9#attendee'] }` | Rows whose stamped tags include ANY listed tag — **`scope:*` tags exist only on scoped-token subscribes** (see note below) |
|
|
218
226
|
| `{ all: true }` | Every live subscription — broadcast must be this explicit |
|
|
219
|
-
| `{ targetTags: ['scope:events:e9'] }` | Rows whose stamped tags include ANY listed tag — **but `scope:*` tags exist only on scoped-token subscribes** (see note below); against session-created rows this selects nobody |
|
|
220
|
-
| `{ targetTags: [...], targetRoles: [...] }` | Rows matching BOTH arms (AND across arms, union within) |
|
|
221
227
|
| `{ subscriptions: [...] }` | An explicit list you already hold |
|
|
222
228
|
|
|
223
|
-
|
|
229
|
+
**Org audiences are resolved at send time.** The queue consumer reads the organization's Better Auth membership when it resolves the fan-out (one query; on D1 through the `AUTH_DB` binding), filters by role, and delivers to those members' devices. A member who is demoted or removed stops receiving on the very next send, and one organization's roles never reach another organization's members — a user who is an admin in one org and a member in another is an admin only for the first. `targetRoles` is **only** valid beside `organizationId`: a role without an organization has no tenant, so `{ targetRoles }` alone is a type error and throws at runtime. The `organizationId` arm needs the Better Auth `organization` plugin; without it the target throws.
|
|
224
230
|
|
|
225
|
-
|
|
231
|
+
Selection is **fail-closed**: an empty array selects *nobody* (nothing is enqueued), a target with no arm throws, and arms do not combine (`{ userIds, targetTags }` throws) — accidental broadcast is structurally impossible. Tags are proven at subscribe time from `ctx`; clients cannot forge their way into an audience.
|
|
232
|
+
|
|
233
|
+
> **`scope:*` tags need a scoped token.** `ctx.scope` is populated *only* from a verified scoped-JWT claim — the same relationship-derived scope the [realtime pillar](/platform/realtime/durable-objects) uses. A normal browser subscribe authenticated with a session cookie stamps only `user:<id>`; it **never** stamps a `scope:*` tag. Because targeting is fail-closed, a `{ targetTags: ['scope:event:e9#attendee'] }` fan-out over session-created subscriptions delivers to **nobody**. Scope tags — identity and role alike — are frozen at subscribe (re-subscribing refreshes them), so a scope role revoked afterwards keeps matching until then; org roles have no such window because they are never stamped.
|
|
226
234
|
|
|
227
235
|
|
|
228
236
|
With an explicit `{ subscriptions }` list, passing `opts.vapid` (via `vapidFromEnv(env)`) lets lists at or under `push.fanout.threshold` (default 500) deliver **inline** with per-recipient results; larger lists chunk onto the queue.
|
|
@@ -155,7 +155,7 @@ export default {
|
|
|
155
155
|
|
|
156
156
|
| Method | Endpoint | Description |
|
|
157
157
|
|--------|----------|-------------|
|
|
158
|
-
| POST | `/bucket` | Create a bucket |
|
|
158
|
+
| POST | `/bucket` | Create a bucket (`allowedMimeTypes` must be a subset of `allowedTypes`) |
|
|
159
159
|
| GET | `/bucket` | List buckets |
|
|
160
160
|
| GET | `/bucket/:name` | Get bucket info |
|
|
161
161
|
| DELETE | `/bucket/:name` | Delete bucket (must be empty) |
|
|
@@ -201,6 +201,14 @@ POST /storage/v1/bucket
|
|
|
201
201
|
`readScope: "public"` is the default for listing photos and avatars. Switch to
|
|
202
202
|
`organization` or `user` only when a signed-in session must gate the GET.
|
|
203
203
|
|
|
204
|
+
A bucket can also set `fileSizeLimit` and `allowedMimeTypes`. Both **narrow**
|
|
205
|
+
the project-wide `maxFileSize` / `allowedTypes`; neither can widen them.
|
|
206
|
+
`allowedMimeTypes` entries outside the project's `allowedTypes` are rejected
|
|
207
|
+
with `400` `VALIDATION_INVALID_INPUT`, listing the offenders in
|
|
208
|
+
`details.disallowed`. Bucket rows written before that check existed are
|
|
209
|
+
intersected with `allowedTypes` at upload and presign time, so a widened list
|
|
210
|
+
has no effect.
|
|
211
|
+
|
|
204
212
|
### Scope Options
|
|
205
213
|
|
|
206
214
|
| Scope | Read Behavior | Write Behavior |
|
|
@@ -317,8 +325,9 @@ curl -X POST https://api.example.com/storage/v1/confirm/videos/clip.mp4 \
|
|
|
317
325
|
> The `size` and `contentType` from step 1 are **bound into the signature** as
|
|
318
326
|
> `Content-Length` and `Content-Type` — the client MUST replay the returned
|
|
319
327
|
> `headers` verbatim on the PUT, or R2 rejects it. That is what makes
|
|
320
|
-
> `maxFileSize` and `allowedTypes`
|
|
321
|
-
>
|
|
328
|
+
> `maxFileSize` and `allowedTypes` (and a bucket's narrower `fileSizeLimit` /
|
|
329
|
+
> `allowedMimeTypes`) real limits on the object that lands, not just on the
|
|
330
|
+
> request that asked for a URL.
|
|
322
331
|
|
|
323
332
|
|
|
324
333
|
### Required secrets
|
|
@@ -424,6 +433,25 @@ The files worker:
|
|
|
424
433
|
> trusted as minted.
|
|
425
434
|
|
|
426
435
|
|
|
436
|
+
### Response headers
|
|
437
|
+
|
|
438
|
+
Uploaded bytes are attacker-controlled, and the API origin shares cookies with
|
|
439
|
+
the CMS and Account apps. So every stored object — from `GET`/`HEAD
|
|
440
|
+
/storage/v1/object/...` and from the files worker alike — is served with one
|
|
441
|
+
header policy:
|
|
442
|
+
|
|
443
|
+
| Header | Value |
|
|
444
|
+
|--------|-------|
|
|
445
|
+
| `X-Content-Type-Options` | `nosniff` |
|
|
446
|
+
| `Content-Security-Policy` | `default-src 'none'; sandbox` |
|
|
447
|
+
| `Content-Disposition` | `inline` for `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/avif`; otherwise `attachment; filename="…"; filename*=UTF-8''…` |
|
|
448
|
+
|
|
449
|
+
An SVG, HTML, XML, or PDF upload therefore **downloads** when opened directly
|
|
450
|
+
instead of rendering on your domain. `<img src>` embedding is unaffected —
|
|
451
|
+
subresource loads ignore `Content-Disposition` and the document CSP. The
|
|
452
|
+
filename is the last segment of the object key, RFC 6266-encoded. If you need
|
|
453
|
+
to display PDFs inline, render them from a separate, cookie-less origin.
|
|
454
|
+
|
|
427
455
|
## Generated Files
|
|
428
456
|
|
|
429
457
|
When file storage is configured, the compiler generates:
|
|
@@ -432,6 +460,7 @@ When file storage is configured, the compiler generates:
|
|
|
432
460
|
|------|---------|
|
|
433
461
|
| `src/storage/routes.ts` | Storage API routes (upload, presign, confirm, download) |
|
|
434
462
|
| `src/storage/presign.ts` | R2 presigned-URL signer (`createPresigner`, backs `ctx.storage`) |
|
|
463
|
+
| `src/lib/object-headers.ts` | `objectHeaders()` — the serving-header policy shared by the storage routes and the files worker |
|
|
435
464
|
| `src/files/schema.ts` | Files metadata schema (buckets, objects) — `sqliteTable` on D1, a `files` Postgres schema otherwise |
|
|
436
465
|
| `src/files/index.ts` | `createFilesDb` — the D1 binding handle, or the Postgres service-lane handle |
|
|
437
466
|
| `drizzle.files.config.ts` | Second migration target — **D1 only** |
|
|
@@ -536,7 +565,7 @@ cd cloudflare-workers/files && npx wrangler deploy --env dev
|
|
|
536
565
|
| `binding` | `string` | `R2_BUCKET` | R2 bucket binding name (managed mode) |
|
|
537
566
|
| `filesBinding` | `string` | `FILES_DB` | Files metadata D1 binding (managed mode, `cloudflare-d1` only — Postgres uses the `files` schema of the single database and emits no binding) |
|
|
538
567
|
| `maxFileSize` | `number \| string` | 10MB | Max upload size — bytes or `"100mb"` (managed mode) |
|
|
539
|
-
| `allowedTypes` | `string[]` | Images only | Allowed MIME types (managed mode) |
|
|
568
|
+
| `allowedTypes` | `string[]` | Images only | Allowed MIME types (managed mode). The ceiling for every bucket: a bucket's `allowedMimeTypes` must be a subset. |
|
|
540
569
|
| `publicDomain` | `string` | - | Custom domain for files worker (managed mode) |
|
|
541
570
|
|
|
542
571
|
### How the size limit is enforced
|
|
@@ -564,5 +593,8 @@ Both paths answer `413` with the actual and permitted byte counts.
|
|
|
564
593
|
read scope never implies a public write.
|
|
565
594
|
- **Serve security**: Public prefix = URL is the capability. Session-gated
|
|
566
595
|
paths re-check membership on every GET. Signed GET expires.
|
|
596
|
+
- **Content safety**: Every served object carries `nosniff` and a sandboxing
|
|
597
|
+
CSP; only raster images are `inline`, everything else is an `attachment`
|
|
598
|
+
([Response headers](#response-headers)).
|
|
567
599
|
- **Soft deletes**: Files are marked deleted in metadata but retained in R2
|
|
568
600
|
- **Tenant isolation**: All files are prefixed with organization ID
|
|
@@ -100,82 +100,18 @@ onUpdate: ['description', 'title']
|
|
|
100
100
|
- The queue consumer is an internal process that executes pre-validated jobs
|
|
101
101
|
- If a user can't create a job posting, they can't trigger an embedding job
|
|
102
102
|
|
|
103
|
-
##
|
|
103
|
+
## Re-embedding a Row
|
|
104
104
|
|
|
105
|
-
|
|
105
|
+
There is no separate embeddings endpoint. To re-embed a row, **PATCH it**: the
|
|
106
|
+
generated `PATCH /api/v1/<resource>/:id` (and `PATCH /batch`) enqueues a fresh job
|
|
107
|
+
after the write passes auth, firewall, and guards. With `onUpdate: [...fields]`,
|
|
108
|
+
the PATCH must include one of the watched fields — resending the current value is
|
|
109
|
+
enough; with the default `onUpdate`, any PATCH re-embeds. The job always uses the
|
|
110
|
+
table's configured `model` and `embeddingColumn`; clients never choose either.
|
|
106
111
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
```bash
|
|
112
|
-
curl -X POST https://your-api.workers.dev/api/v1/embeddings \
|
|
113
|
-
-H "Content-Type: application/json" \
|
|
114
|
-
-H "Cookie: better-auth.session_token=..." \
|
|
115
|
-
-d '{
|
|
116
|
-
"content": "Text to embed",
|
|
117
|
-
"model": "@cf/baai/bge-base-en-v1.5",
|
|
118
|
-
"table": "jobs",
|
|
119
|
-
"id": "job_123"
|
|
120
|
-
}'
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
#### Request Body
|
|
124
|
-
|
|
125
|
-
| Field | Type | Required | Description |
|
|
126
|
-
|-------|------|----------|-------------|
|
|
127
|
-
| `content` | `string` | Yes | Text to generate embedding for |
|
|
128
|
-
| `model` | `string` | No | Embedding model (defaults to table config or `@cf/baai/bge-base-en-v1.5`) |
|
|
129
|
-
| `table` | `string` | No | Table to store embedding back to |
|
|
130
|
-
| `id` | `string` | Conditional | Record ID to update (required if `table` is specified) |
|
|
131
|
-
|
|
132
|
-
#### Response
|
|
133
|
-
|
|
134
|
-
```json
|
|
135
|
-
{
|
|
136
|
-
"queued": true,
|
|
137
|
-
"jobId": "550e8400-e29b-41d4-a716-446655440000",
|
|
138
|
-
"table": "jobs",
|
|
139
|
-
"id": "job_123",
|
|
140
|
-
"model": "@cf/baai/bge-base-en-v1.5"
|
|
141
|
-
}
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
### GET /api/v1/embeddings/tables
|
|
145
|
-
|
|
146
|
-
List tables that have embeddings configured:
|
|
147
|
-
|
|
148
|
-
```bash
|
|
149
|
-
curl https://your-api.workers.dev/api/v1/embeddings/tables \
|
|
150
|
-
-H "Cookie: better-auth.session_token=..."
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
Response:
|
|
154
|
-
|
|
155
|
-
```json
|
|
156
|
-
{
|
|
157
|
-
"tables": [
|
|
158
|
-
{
|
|
159
|
-
"name": "jobs",
|
|
160
|
-
"embeddingColumn": "embedding",
|
|
161
|
-
"model": "@cf/baai/bge-base-en-v1.5"
|
|
162
|
-
}
|
|
163
|
-
]
|
|
164
|
-
}
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
### Authentication & Authorization
|
|
168
|
-
|
|
169
|
-
The generic embeddings API requires authentication and uses the `activeOrgId` from the user's context to enforce organization-level isolation. Embedding jobs are scoped to the user's current organization.
|
|
170
|
-
|
|
171
|
-
### Use Cases
|
|
172
|
-
|
|
173
|
-
The generic embeddings API is useful for:
|
|
174
|
-
|
|
175
|
-
- **Batch embedding**: Embed content without going through CRUD routes
|
|
176
|
-
- **Re-embedding**: Force re-generation of embeddings for existing records
|
|
177
|
-
- **Preview embeddings**: Test embedding generation before persisting
|
|
178
|
-
- **External content**: Embed content that doesn't fit your defined schemas
|
|
112
|
+
For content that doesn't live in a table (previews, external text), call the
|
|
113
|
+
search service's [`embed()`](/platform/vector/embeddings#generate-embeddings-directly)
|
|
114
|
+
from an action — it runs under that action's own access rules.
|
|
179
115
|
|
|
180
116
|
## Generated Files
|
|
181
117
|
|
|
@@ -184,10 +120,9 @@ When embeddings are configured, the compiler generates:
|
|
|
184
120
|
| File | Purpose |
|
|
185
121
|
|------|---------|
|
|
186
122
|
| `src/queue-consumer.ts` | Queue consumer handler for processing embedding jobs |
|
|
187
|
-
| `src/routes/embeddings.ts` | Generic embeddings API routes |
|
|
188
123
|
| `wrangler.toml` | Queue producer/consumer bindings, AI binding |
|
|
189
124
|
| `src/env.d.ts` | `EMBEDDINGS_QUEUE`, `AI` types |
|
|
190
|
-
| `src/index.ts` | Exports `queue` handler
|
|
125
|
+
| `src/index.ts` | Exports the `queue` handler |
|
|
191
126
|
|
|
192
127
|
### wrangler.toml additions
|
|
193
128
|
|
|
@@ -41,4 +41,4 @@ The default embedding model is `@cf/baai/bge-base-en-v1.5` (768 dimensions). You
|
|
|
41
41
|
## Pages
|
|
42
42
|
|
|
43
43
|
- **[Automatic Embeddings](/platform/vector/embeddings)** — `defineTable()` embeddings config, queue consumer, Vectorize integration, and `defineEmbedding()` search service
|
|
44
|
-
- **[Using Embeddings](/platform/vector/using-embeddings)** —
|
|
44
|
+
- **[Using Embeddings](/platform/vector/using-embeddings)** — Re-embedding rows, semantic search, and practical usage
|
|
@@ -1,76 +1,14 @@
|
|
|
1
1
|
# Using Embeddings
|
|
2
2
|
|
|
3
|
-
This page covers the runtime API for working with embeddings —
|
|
3
|
+
This page covers the runtime API for working with embeddings — re-embedding rows, the search service, and practical usage patterns.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Re-embedding Rows
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
POST /api/v1/embeddings
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
Enqueue an embedding job for arbitrary content:
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
curl -X POST https://api.example.com/api/v1/embeddings \
|
|
19
|
-
-H "Content-Type: application/json" \
|
|
20
|
-
-H "Cookie: better-auth.session_token=..." \
|
|
21
|
-
-d '{
|
|
22
|
-
"content": "Text to generate an embedding for",
|
|
23
|
-
"model": "@cf/baai/bge-base-en-v1.5",
|
|
24
|
-
"table": "jobs",
|
|
25
|
-
"id": "job_123"
|
|
26
|
-
}'
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
**Request body:**
|
|
30
|
-
|
|
31
|
-
| Field | Type | Required | Description |
|
|
32
|
-
|-------|------|----------|-------------|
|
|
33
|
-
| `content` | string | Yes | Text to embed |
|
|
34
|
-
| `model` | string | No | Embedding model (defaults to table config or `@cf/baai/bge-base-en-v1.5`) |
|
|
35
|
-
| `table` | string | No | Table to store the embedding in |
|
|
36
|
-
| `id` | string | Conditional | Record ID (required when `table` is provided) |
|
|
37
|
-
|
|
38
|
-
**Response:**
|
|
39
|
-
|
|
40
|
-
```json
|
|
41
|
-
{
|
|
42
|
-
"queued": true,
|
|
43
|
-
"jobId": "550e8400-e29b-41d4-a716-446655440000",
|
|
44
|
-
"table": "jobs",
|
|
45
|
-
"id": "job_123",
|
|
46
|
-
"model": "@cf/baai/bge-base-en-v1.5"
|
|
47
|
-
}
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
This endpoint is useful for:
|
|
51
|
-
- Re-embedding existing records
|
|
52
|
-
- Embedding content that doesn't go through CRUD routes
|
|
53
|
-
- Batch embedding via scripts
|
|
54
|
-
|
|
55
|
-
### List Embedding Tables
|
|
56
|
-
|
|
57
|
-
```
|
|
58
|
-
GET /api/v1/embeddings/tables
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
List tables that have embeddings configured:
|
|
62
|
-
|
|
63
|
-
```json
|
|
64
|
-
{
|
|
65
|
-
"tables": [
|
|
66
|
-
{
|
|
67
|
-
"name": "jobs",
|
|
68
|
-
"embeddingColumn": "embedding",
|
|
69
|
-
"model": "@cf/baai/bge-base-en-v1.5"
|
|
70
|
-
}
|
|
71
|
-
]
|
|
72
|
-
}
|
|
73
|
-
```
|
|
7
|
+
Embeddings have no endpoint of their own. Rows are embedded on INSERT and
|
|
8
|
+
re-embedded on UPDATE by the generated CRUD routes, after auth, firewall, and
|
|
9
|
+
guards pass — so **PATCH the row to re-embed** (with `onUpdate: [...fields]`,
|
|
10
|
+
include a watched field; resending its current value is enough). The job uses the
|
|
11
|
+
table's configured `model` and `embeddingColumn`.
|
|
74
12
|
|
|
75
13
|
## Search Service
|
|
76
14
|
|
|
@@ -162,14 +100,13 @@ The `metadata` fields in your `defineTable` embeddings config are automatically
|
|
|
162
100
|
|---------|-----|----------|
|
|
163
101
|
| Auto (INSERT) | Compiler enqueues after successful create | Default behavior |
|
|
164
102
|
| Auto (UPDATE) | Compiler enqueues when watched fields change | Keeps embeddings fresh |
|
|
165
|
-
|
|
|
103
|
+
| Re-embed | `PATCH` the row (or `PATCH /batch`) | Re-embedding existing records |
|
|
166
104
|
| Manual (Queue) | `env.EMBEDDINGS_QUEUE.send(...)` | Custom pipelines |
|
|
167
105
|
|
|
168
106
|
## Security
|
|
169
107
|
|
|
170
|
-
-
|
|
171
|
-
- Jobs are scoped to the
|
|
172
|
-
- Embedding jobs are only enqueued after all security checks pass (auth, firewall, guards)
|
|
108
|
+
- Embedding jobs are only enqueued by the generated write routes, after all security checks pass (auth, firewall, guards) — there is no client-facing embeddings endpoint
|
|
109
|
+
- Jobs are scoped to the writer's `activeOrgId`
|
|
173
110
|
- The queue consumer is an internal process — it trusts pre-validated jobs
|
|
174
111
|
|
|
175
112
|
## Supported Models
|
|
@@ -22,12 +22,16 @@ import { emitWebhookEvent } from '../lib/webhooks/emit';
|
|
|
22
22
|
// After creating a user
|
|
23
23
|
const newUser = await db.insert(users).values(data).returning();
|
|
24
24
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
25
|
+
// ctx.activeOrgId is `string | undefined` — narrow it first. Passing it
|
|
26
|
+
// unguarded is a type error, and an unscoped emit throws at runtime.
|
|
27
|
+
if (ctx.activeOrgId) {
|
|
28
|
+
await emitWebhookEvent(
|
|
29
|
+
"user.created",
|
|
30
|
+
newUser[0],
|
|
31
|
+
{ organizationId: ctx.activeOrgId },
|
|
32
|
+
env
|
|
33
|
+
);
|
|
34
|
+
}
|
|
31
35
|
```
|
|
32
36
|
|
|
33
37
|
**Parameters:**
|
|
@@ -36,7 +40,7 @@ await emitWebhookEvent(
|
|
|
36
40
|
|-----------|------|-------------|
|
|
37
41
|
| `eventType` | `string` | Event name (e.g., `user.created`) |
|
|
38
42
|
| `payload` | `unknown` | Event data (auto-wrapped with metadata) |
|
|
39
|
-
| `options` | `
|
|
43
|
+
| `options` | `{ organizationId: string } \| { userId: string }` | **Required.** Exactly one scope — only endpoints registered to that org or user receive the event. Neither or both throws. |
|
|
40
44
|
| `env` | `CloudflareBindings` | Cloudflare environment bindings |
|
|
41
45
|
|
|
42
46
|
**Note:** The compiler does NOT auto-emit events after CRUD operations. You must call `emitWebhookEvent()` explicitly where you want webhooks triggered.
|
|
@@ -166,7 +170,7 @@ Endpoints subscribe to events using patterns:
|
|
|
166
170
|
|
|
167
171
|
### Access Control
|
|
168
172
|
|
|
169
|
-
Endpoints are scoped by `userId` or `organizationId`. Users can only manage their own endpoints. When emitting events, only endpoints matching the event's scope receive deliveries.
|
|
173
|
+
Endpoints are scoped by `userId` or `organizationId`. Users can only manage their own endpoints. When emitting events, only endpoints matching the event's scope receive deliveries. Every emit must name exactly one scope: an unscoped emit (`{}`, or an `organizationId` that is `undefined` at runtime) throws instead of reaching every tenant's endpoints — there is no global broadcast.
|
|
170
174
|
|
|
171
175
|
### URL Validation (anti-SSRF)
|
|
172
176
|
|
|
@@ -102,7 +102,7 @@ Every file under `src/` carries a `Generated by quickback.dev` header and is own
|
|
|
102
102
|
|
|
103
103
|
1. Snapshots the existing `src/` tree to `quickback/.archives/src-<ISO-timestamp>/` (a plain recursive copy — `cp -R` semantics, no compression).
|
|
104
104
|
2. Wipes `src/` entirely.
|
|
105
|
-
3. Writes the fresh manifest from the compiler.
|
|
105
|
+
3. Writes the fresh manifest from the compiler. Every path is checked first: an absolute path, a `.` / `..` segment, or anything resolving outside the output directory fails the build before a single file is written — the CLI never trusts the compiler's response to stay inside your project.
|
|
106
106
|
|
|
107
107
|
This prevents stale output: removed features stop leaving orphan folders, deleted SPA assets with old content hashes get cleared, and `.DS_Store` files don't keep retired directories alive.
|
|
108
108
|
|
|
@@ -376,7 +376,7 @@ The CLI parses your feature files with the TypeScript compiler API, and falls ba
|
|
|
376
376
|
|
|
377
377
|
`typescript` is an optional peer dependency, supported at **`>=5.0.0 <7`** — both 5.x and 6.x expose the classic compiler API. TypeScript 7 (the native port) resolves its main entry to a module exporting only `version` — parsing moved to the explicitly-unstable `typescript/unstable/*` subpaths — so it cannot drive the AST parser, and the CLI says so by name rather than degrading quietly.
|
|
378
378
|
|
|
379
|
-
Compiled projects pin
|
|
379
|
+
Compiled projects pin `typescript` to 6.x for exactly this reason: `quickback build` runs schema sync before every compile, and a project on TypeScript 7 cannot build. Don't bump it to 7 by hand.
|
|
380
380
|
|
|
381
381
|
Set `QUICKBACK_STRICT_PARSE=1` in CI so a regex-parsed build fails the pipeline instead of shipping:
|
|
382
382
|
|
|
@@ -28,7 +28,7 @@ The API key takes precedence over stored credentials from `quickback login`.
|
|
|
28
28
|
|
|
29
29
|
## How Tokens Are Validated
|
|
30
30
|
|
|
31
|
-
The compiler-cloud worker validates authentication by forwarding your
|
|
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
33
|
## Credential Storage
|
|
34
34
|
|
|
@@ -35,9 +35,10 @@ The `/compile` endpoint requires either a session token (from `quickback login`)
|
|
|
35
35
|
|
|
36
36
|
The map uses project-root-relative paths and follows the same layout `quickback build` reads from disk: `quickback/quickback.config.ts`, `quickback/features/**`, `quickback/services/**`, `quickback/{lib,hooks,plugins,middlewares,email-templates}/**`, plus `quickback/drizzle/**/meta/**` and `wrangler.toml` for incremental builds.
|
|
37
37
|
|
|
38
|
-
|
|
38
|
+
Three constraints, all fail-closed:
|
|
39
39
|
|
|
40
40
|
- **The config must be fully static.** The compiler parses `quickback.config.ts` with a literals-only evaluator — it never executes user code. Object/array/string/number/boolean literals, substitution-free template literals, and the `define*` helper calls all work; variables, computed values, and imports-as-values are rejected with a 400 that names the offending construct and line.
|
|
41
|
+
- **Table files must be declarative.** Everything above `export default defineTable(...)` is checked before it reaches the generated schema that migration tooling loads — only `drizzle-orm` / `@quickback/compiler` / table-file imports and inert expressions pass ([rules](/define/schema#table-files-are-declarative)); anything else fails the compile naming the file and line.
|
|
41
42
|
- **Action input schemas are contract-sensitive.** For v1, raw-files requests may omit `actionInputSchemas` and use the compiler's lower-fidelity static parser. V2 requires one usable client-harvested `z.toJSONSchema(action.input)` entry for every authored action. The CLI reports each missing action with its local bundle or evaluation error; the API independently reports missing or invalid action keys.
|
|
42
43
|
|
|
43
44
|
Raw-files requests work with both `?complete=true` and `?complete=false`
|