@quickback-dev/cli 0.66.1 → 0.66.2
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/README.md +7 -4
- package/dist/commands/build.d.ts +51 -0
- package/dist/commands/build.d.ts.map +1 -0
- package/dist/commands/build.js +793 -0
- package/dist/commands/build.js.map +1 -0
- package/dist/commands/build.test.d.ts +2 -0
- package/dist/commands/build.test.d.ts.map +1 -0
- package/dist/commands/build.test.js +150 -0
- package/dist/commands/build.test.js.map +1 -0
- package/dist/commands/check.d.ts +2 -2
- package/dist/commands/check.js +4 -4
- package/dist/commands/check.js.map +1 -1
- package/dist/commands/create.d.ts +1 -1
- package/dist/commands/create.js +7 -7
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/deploy.d.ts +6 -6
- package/dist/commands/deploy.js +23 -23
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/example.js +1 -1
- package/dist/commands/example.js.map +1 -1
- package/dist/commands/mcp.js +1 -1
- package/dist/commands/mcp.js.map +1 -1
- package/dist/commands/migrate.d.ts +1 -1
- package/dist/commands/migrate.js +3 -3
- package/dist/commands/migrate.js.map +1 -1
- package/dist/commands/migrations.js +2 -2
- package/dist/commands/migrations.js.map +1 -1
- package/dist/commands/push.js +1 -1
- package/dist/commands/push.js.map +1 -1
- package/dist/commands/start.js +1 -1
- package/dist/commands/start.js.map +1 -1
- package/dist/cursor/quickback.mdc +1 -1
- package/dist/index.js +18 -15
- package/dist/index.js.map +1 -1
- package/dist/lib/auth.js +1 -1
- package/dist/lib/auth.js.map +1 -1
- package/dist/lib/compiler-floor.d.ts +1 -1
- package/dist/lib/compiler-floor.js +1 -1
- package/dist/lib/file-loader.js +2 -2
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.d.ts +2 -0
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js +16 -0
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/file-writer.test.js +16 -0
- package/dist/lib/file-writer.test.js.map +1 -1
- package/dist/lib/migrations/file-envelopes.js +3 -3
- package/dist/lib/migrations/file-envelopes.js.map +1 -1
- package/dist/lib/prepare-output.test.js +1 -1
- package/dist/lib/prepare-output.test.js.map +1 -1
- package/dist/lib/schema-sync/index.js +1 -1
- package/dist/lib/schema-sync/index.test.js +1 -1
- package/dist/lib/schema-sync/index.test.js.map +1 -1
- package/dist/skill/SKILL.md +6 -6
- package/dist/skill/docs/api/crud.md +7 -0
- package/dist/skill/docs/api/index.md +1 -1
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/changelog/index.md +19 -1
- package/dist/skill/docs/configure/agents.md +1 -1
- package/dist/skill/docs/configure/index.md +8 -3
- package/dist/skill/docs/configure/providers.md +1 -0
- package/dist/skill/docs/configure/variables.md +3 -3
- package/dist/skill/docs/define/access.md +7 -0
- package/dist/skill/docs/define/actions/defining.md +35 -7
- package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/dist/skill/docs/define/actions/scoped-db.md +46 -16
- package/dist/skill/docs/define/areas.md +1 -1
- package/dist/skill/docs/define/diagnostics.md +1 -0
- package/dist/skill/docs/define/encryption.md +1 -1
- package/dist/skill/docs/define/feature.md +14 -7
- package/dist/skill/docs/define/guards.md +27 -3
- package/dist/skill/docs/define/schema.md +24 -14
- package/dist/skill/docs/define/security.md +1 -1
- package/dist/skill/docs/define/transitions.md +35 -4
- package/dist/skill/docs/define/views.md +33 -0
- package/dist/skill/docs/index.md +2 -2
- package/dist/skill/docs/platform/auth/api-keys.md +1 -1
- package/dist/skill/docs/platform/auth/using-auth.md +37 -0
- package/dist/skill/docs/platform/database/d1.md +2 -2
- package/dist/skill/docs/platform/database/neon.md +4 -4
- package/dist/skill/docs/platform/email/index.md +1 -1
- package/dist/skill/docs/platform/queues/handlers.md +1 -1
- package/dist/skill/docs/platform/queues/using-queues.md +1 -1
- package/dist/skill/docs/platform/schedules/index.md +1 -1
- package/dist/skill/docs/platform/storage/index.md +3 -3
- package/dist/skill/docs/platform/storage/r2.md +87 -37
- package/dist/skill/docs/platform/storage/using-r2.md +99 -19
- package/dist/skill/docs/platform/webhooks/inbound.md +40 -0
- package/dist/skill/docs/start/deploy-browser.md +39 -44
- package/dist/skill/docs/start/deploy-owner-access.md +28 -19
- package/dist/skill/docs/start/deploy.md +2 -2
- package/dist/skill/docs/start/first-api.md +1 -1
- package/dist/skill/docs/start/hand-crafted.md +3 -3
- package/dist/skill/docs/start/index.md +3 -3
- package/dist/skill/docs/start/quickstart.md +3 -3
- package/dist/skill/docs/start/template-blog.md +2 -2
- package/dist/skill/docs/start/template-cloudflare.md +2 -2
- package/dist/skill/docs/start/template-empty.md +1 -1
- package/dist/skill/docs/start/templates.md +1 -1
- package/dist/skill/docs/tooling/claude-skill.md +1 -1
- package/dist/skill/docs/tooling/cli.md +20 -15
- package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
- package/dist/skill/docs/tooling/cloud-compiler/index.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
- package/dist/skill/docs/tooling/output.md +23 -2
- package/dist/skill/docs/tooling/troubleshooting.md +1 -1
- package/dist/skill/docs/ui/account/environment-variables.md +2 -2
- package/dist/skill/docs/ui/account/features/admin.md +1 -1
- package/dist/skill/docs/ui/account/features/avatars.md +24 -8
- package/dist/skill/docs/ui/account/features/index.md +9 -5
- package/dist/skill/docs/ui/account/features/organizations.md +3 -2
- package/dist/skill/docs/ui/account/index.md +3 -1
- package/dist/skill/docs/ui/account/with-quickback.md +1 -1
- package/dist/skill/docs/ui/admin/actions.md +97 -3
- package/dist/skill/docs/ui/admin/components.md +4 -6
- package/dist/skill/docs/ui/admin/connecting.md +15 -3
- package/dist/skill/docs/ui/admin/index.md +71 -6
- package/dist/skill/docs/ui/admin/inline-editing.md +38 -4
- package/dist/skill/docs/ui/admin/record-layouts.md +22 -21
- package/dist/skill/docs/ui/admin/schema-format.md +39 -2
- package/dist/skill/docs/ui/admin/schema-registry.md +107 -7
- package/dist/skill/docs/ui/admin/security.md +19 -4
- package/dist/skill/docs/ui/admin/table-views.md +59 -12
- package/package.json +1 -1
- package/src/cursor/quickback.mdc +1 -1
- package/src/skill/SKILL.md +6 -6
- package/src/skill/docs/api/crud.md +7 -0
- package/src/skill/docs/api/index.md +1 -1
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/changelog/index.md +19 -1
- package/src/skill/docs/configure/agents.md +1 -1
- package/src/skill/docs/configure/index.md +8 -3
- package/src/skill/docs/configure/providers.md +1 -0
- package/src/skill/docs/configure/variables.md +3 -3
- package/src/skill/docs/define/access.md +7 -0
- package/src/skill/docs/define/actions/defining.md +35 -7
- package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/src/skill/docs/define/actions/scoped-db.md +46 -16
- package/src/skill/docs/define/areas.md +1 -1
- package/src/skill/docs/define/diagnostics.md +1 -0
- package/src/skill/docs/define/encryption.md +1 -1
- package/src/skill/docs/define/feature.md +14 -7
- package/src/skill/docs/define/guards.md +27 -3
- package/src/skill/docs/define/schema.md +24 -14
- package/src/skill/docs/define/security.md +1 -1
- package/src/skill/docs/define/transitions.md +35 -4
- package/src/skill/docs/define/views.md +33 -0
- package/src/skill/docs/index.md +2 -2
- package/src/skill/docs/platform/auth/api-keys.md +1 -1
- package/src/skill/docs/platform/auth/using-auth.md +37 -0
- package/src/skill/docs/platform/database/d1.md +2 -2
- package/src/skill/docs/platform/database/neon.md +4 -4
- package/src/skill/docs/platform/email/index.md +1 -1
- package/src/skill/docs/platform/queues/handlers.md +1 -1
- package/src/skill/docs/platform/queues/using-queues.md +1 -1
- package/src/skill/docs/platform/schedules/index.md +1 -1
- package/src/skill/docs/platform/storage/index.md +3 -3
- package/src/skill/docs/platform/storage/r2.md +87 -37
- package/src/skill/docs/platform/storage/using-r2.md +99 -19
- package/src/skill/docs/platform/webhooks/inbound.md +40 -0
- package/src/skill/docs/start/deploy-browser.md +39 -44
- package/src/skill/docs/start/deploy-owner-access.md +28 -19
- package/src/skill/docs/start/deploy.md +2 -2
- package/src/skill/docs/start/first-api.md +1 -1
- package/src/skill/docs/start/hand-crafted.md +3 -3
- package/src/skill/docs/start/index.md +3 -3
- package/src/skill/docs/start/quickstart.md +3 -3
- package/src/skill/docs/start/template-blog.md +2 -2
- package/src/skill/docs/start/template-cloudflare.md +2 -2
- package/src/skill/docs/start/template-empty.md +1 -1
- package/src/skill/docs/start/templates.md +1 -1
- package/src/skill/docs/tooling/claude-skill.md +1 -1
- package/src/skill/docs/tooling/cli.md +20 -15
- package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
- package/src/skill/docs/tooling/cloud-compiler/index.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
- package/src/skill/docs/tooling/output.md +23 -2
- package/src/skill/docs/tooling/troubleshooting.md +1 -1
- package/src/skill/docs/ui/account/environment-variables.md +2 -2
- package/src/skill/docs/ui/account/features/admin.md +1 -1
- package/src/skill/docs/ui/account/features/avatars.md +24 -8
- package/src/skill/docs/ui/account/features/index.md +9 -5
- package/src/skill/docs/ui/account/features/organizations.md +3 -2
- package/src/skill/docs/ui/account/index.md +3 -1
- package/src/skill/docs/ui/account/with-quickback.md +1 -1
- package/src/skill/docs/ui/admin/actions.md +97 -3
- package/src/skill/docs/ui/admin/components.md +4 -6
- package/src/skill/docs/ui/admin/connecting.md +15 -3
- package/src/skill/docs/ui/admin/index.md +71 -6
- package/src/skill/docs/ui/admin/inline-editing.md +38 -4
- package/src/skill/docs/ui/admin/record-layouts.md +22 -21
- package/src/skill/docs/ui/admin/schema-format.md +39 -2
- package/src/skill/docs/ui/admin/schema-registry.md +107 -7
- package/src/skill/docs/ui/admin/security.md +19 -4
- package/src/skill/docs/ui/admin/table-views.md +59 -12
|
@@ -33,6 +33,43 @@ app.get('/api/me', async (c) => {
|
|
|
33
33
|
|
|
34
34
|
`ctx` also carries `authMethod` (`'session' | 'jwt' | 'api-key' | 'oauth' | 'principal'`), `userRole` (the global user-table role), `activeTeamId`, and `scope`. In action and CRUD handlers this same object arrives as the `ctx` argument — you rarely call `c.get('ctx')` directly.
|
|
35
35
|
|
|
36
|
+
## Application Profiles
|
|
37
|
+
|
|
38
|
+
Treat the Better Auth user row as login identity, not automatically as the
|
|
39
|
+
application's complete client or customer model. Before defining feature
|
|
40
|
+
tables, decide whether signed-in people need domain data beyond the identity
|
|
41
|
+
already available on `ctx.user`—for example a customer number, onboarding
|
|
42
|
+
state, preferences, billing metadata, clinical details, or relationships that
|
|
43
|
+
other feature records must reference.
|
|
44
|
+
|
|
45
|
+
If the auth identity fields are enough, use `ctx.userId` / `ctx.user` directly
|
|
46
|
+
and do not create an empty duplicate profile. If the product needs domain data
|
|
47
|
+
or relationships, create a first-class feature resource such as `customers`,
|
|
48
|
+
`clientProfiles`, or `patientProfiles`. Give it its own feature-table primary
|
|
49
|
+
key and normal access, firewall, masking, and guard rules.
|
|
50
|
+
|
|
51
|
+
Use `userId: q.text().required().index()` for the basic link to the Better Auth
|
|
52
|
+
identity. Quickback emits the physical `user_id` column. Treat it as a plain
|
|
53
|
+
text **logical foreign key**: a self-create/bootstrap action derives it from
|
|
54
|
+
`ctx.userId`, and generic clients must not supply or update it through
|
|
55
|
+
`guards.createable` / `guards.updatable`. If the model permits one profile per
|
|
56
|
+
identity globally, add `unique: [{ columns: ["userId"] }]`; if it permits one
|
|
57
|
+
per organization, use `unique: [{ columns: ["organizationId", "userId"] }]`
|
|
58
|
+
instead. Declare explicitly when `userId` is also the row-ownership firewall
|
|
59
|
+
column rather than relying on its name.
|
|
60
|
+
|
|
61
|
+
Do not write `.references(() => user.id)` or `.references(() => users.id)` on
|
|
62
|
+
that link. With the default split-D1 provider, Better Auth lives in `AUTH_DB`
|
|
63
|
+
and feature resources live in `DB`, so SQLite cannot enforce a cross-database
|
|
64
|
+
foreign key. A provider may place both stores in one physical database, but the
|
|
65
|
+
auth schema remains compiler-owned rather than an authored feature-table
|
|
66
|
+
import; keeping this link logical makes the definition portable. Other feature
|
|
67
|
+
tables should use a real feature-database FK such as
|
|
68
|
+
`profileId: q.text().required().references(() => profiles.id)` so the CMS can
|
|
69
|
+
resolve the profile label. See [Schema → References](/define/schema#references),
|
|
70
|
+
[Firewall → ownerId vs userId](/define/firewall#ownerid-vs-userid), and
|
|
71
|
+
[Start patterns → Referencing users](/start/patterns).
|
|
72
|
+
|
|
36
73
|
## Organization Context
|
|
37
74
|
|
|
38
75
|
When organizations are enabled, the active organization is on the auth context as `activeOrgId`:
|
|
@@ -93,7 +93,7 @@ Quickback generates migrations automatically at compile time based on your schem
|
|
|
93
93
|
|
|
94
94
|
```bash
|
|
95
95
|
# Compile your project (generates migrations)
|
|
96
|
-
quickback
|
|
96
|
+
quickback build
|
|
97
97
|
|
|
98
98
|
# Apply migrations locally
|
|
99
99
|
wrangler d1 migrations apply DB --local
|
|
@@ -104,7 +104,7 @@ wrangler d1 migrations apply DB --remote
|
|
|
104
104
|
|
|
105
105
|
Migration files are generated in `quickback/drizzle/` and version-controlled with your code. You never need to manually generate migrations—just define your schema and compile.
|
|
106
106
|
|
|
107
|
-
Generation runs locally: `quickback
|
|
107
|
+
Generation runs locally: `quickback build` invokes your project's own
|
|
108
108
|
`drizzle-kit` against migration state that never leaves your machine. Note that
|
|
109
109
|
generating a migration is not the same as applying one — `_journal.json` records
|
|
110
110
|
which migration files *exist*, while D1's own `d1_migrations` table records which
|
|
@@ -359,11 +359,11 @@ connection string from the Hyperdrive configuration identified by `id`.
|
|
|
359
359
|
## Better Auth schema generation
|
|
360
360
|
|
|
361
361
|
`src/auth/schema.ts` is a compiler-owned artifact derived with the Better Auth
|
|
362
|
-
CLI during `quickback
|
|
362
|
+
CLI during `quickback build`. The generated `build` script is deliberately
|
|
363
363
|
read-only with respect to generated source:
|
|
364
364
|
|
|
365
365
|
```bash
|
|
366
|
-
quickback
|
|
366
|
+
quickback build # regenerates src/auth/schema.ts and the project output
|
|
367
367
|
npm run build # runs tsc only; does not rewrite generated files
|
|
368
368
|
```
|
|
369
369
|
|
|
@@ -382,7 +382,7 @@ generated `package.json` — that's the Better Auth CLI package (the
|
|
|
382
382
|
The qualifier script adjusts the CLI output for Postgres schema placement.
|
|
383
383
|
`auth:schema` produces the intermediate Better Auth output and may remove
|
|
384
384
|
Quickback's generated-file envelope. Do not commit that intermediate file;
|
|
385
|
-
rerun `quickback
|
|
385
|
+
rerun `quickback build` to restore the canonical project bytes. Don't
|
|
386
386
|
hand-edit `src/auth/schema.ts`.
|
|
387
387
|
|
|
388
388
|
Recompiling also replaces previously generated `package.json` lifecycle
|
|
@@ -397,7 +397,7 @@ Drizzle journal covers auth tables, feature tables, indexes, FK/cascade
|
|
|
397
397
|
semantics, and the RLS layer:
|
|
398
398
|
|
|
399
399
|
```bash
|
|
400
|
-
quickback
|
|
400
|
+
quickback build # generates migrations under quickback/drizzle/
|
|
401
401
|
npm run db:migrate # applies schema AND the RLS layer, in order
|
|
402
402
|
```
|
|
403
403
|
|
|
@@ -59,7 +59,7 @@ Two `../` — up from `services/email/` to `quickback/`, then down into `feature
|
|
|
59
59
|
## What the compiler emits
|
|
60
60
|
|
|
61
61
|
1. **`deliverInboundEmail(message, env)`** in `src/lib/email.ts` — the shared dispatcher.
|
|
62
|
-
2. **`email(cfMessage, env, ctx)`** on the Worker default export — Cloudflare adapter. Regenerated on every `quickback
|
|
62
|
+
2. **`email(cfMessage, env, ctx)`** on the Worker default export — Cloudflare adapter. Regenerated on every `quickback build`.
|
|
63
63
|
3. **No wrangler inbound binding.** Cloudflare: configure Email Routing in the dashboard. SES: Receipt rule + S3 + SNS; call `deliverInboundEmail` with the fetched `.eml`.
|
|
64
64
|
4. The existing outbound `[[send_email]]` binding (Cloudflare) / SES plugin (aws-ses) is unchanged.
|
|
65
65
|
|
|
@@ -41,7 +41,7 @@ Two `../` — up from `services/schedules/` to `quickback/`, then down into `fea
|
|
|
41
41
|
|
|
42
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.
|
|
43
43
|
2. **`[triggers] crons = [...]`** in `wrangler.toml` — one deduped, sorted list across all schedules.
|
|
44
|
-
3. **`src/lib/schedules.ts`** — the generated runner. Regenerated on every `quickback
|
|
44
|
+
3. **`src/lib/schedules.ts`** — the generated runner. Regenerated on every `quickback build`, so there's nothing to hand-maintain.
|
|
45
45
|
|
|
46
46
|
## Execute context
|
|
47
47
|
|
|
@@ -7,11 +7,11 @@ The Quickback Stack uses Cloudflare's storage primitives for different use cases
|
|
|
7
7
|
| Service | Use Case | Pages |
|
|
8
8
|
|---------|----------|-------|
|
|
9
9
|
| **KV** | Sessions, caching, rate limiting | [Setup](/platform/storage/kv) · [Usage](/platform/storage/using-kv) |
|
|
10
|
-
| **R2** |
|
|
10
|
+
| **R2** | Hosted file bytes (listing photos, avatars, attachments) | [Setup](/platform/storage/r2) · [Usage](/platform/storage/using-r2) |
|
|
11
11
|
|
|
12
12
|
## Getting Started
|
|
13
13
|
|
|
14
14
|
- **[KV Setup](/platform/storage/kv)** — Namespace and bindings configuration
|
|
15
15
|
- **[Using KV](/platform/storage/using-kv)** — Sessions, caching, rate limiting
|
|
16
|
-
- **[R2 Setup](/platform/storage/r2)** —
|
|
17
|
-
- **[Using R2](/platform/storage/using-r2)** —
|
|
16
|
+
- **[R2 Setup](/platform/storage/r2)** — Public vs signed reads, buckets, bindings
|
|
17
|
+
- **[Using R2](/platform/storage/using-r2)** — URL fields, public buckets, signed uploads
|
|
@@ -9,12 +9,12 @@ Quickback provides built-in file storage using Cloudflare R2.
|
|
|
9
9
|
- **Presign-only (default)** — emits just the `ctx.storage` signer (presigned
|
|
10
10
|
PUT/GET URLs straight to R2). **No new D1, no `/storage/v1/*` endpoints, no
|
|
11
11
|
files worker.** You compute keys and store file references in your own table.
|
|
12
|
-
|
|
13
|
-
|
|
12
|
+
Use this when you already have a media table and only need to sign large or
|
|
13
|
+
confidential transfers — see [Presigned uploads](#presigned-uploads).
|
|
14
14
|
- **Managed (`managed: true`)** — adds the turnkey subsystem on top: a FILES_DB
|
|
15
15
|
metadata database (buckets + objects), the `/storage/v1/*` upload/download/
|
|
16
|
-
manage endpoints, and a
|
|
17
|
-
|
|
16
|
+
manage endpoints, and a files worker for serving. Use this for listing photos,
|
|
17
|
+
avatars, and other files that should be **public-if-you-have-the-link**.
|
|
18
18
|
|
|
19
19
|
```ts
|
|
20
20
|
// Presign-only (default) — ctx.storage against a bucket, nothing else
|
|
@@ -24,12 +24,50 @@ defineFileStorage("cloudflare-r2", { bucketName: "my-app-media" })
|
|
|
24
24
|
defineFileStorage("cloudflare-r2", { managed: true, bucketName: "my-app-files" })
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
New projects can omit `bucketName` — it defaults to `<project>-media
|
|
28
|
-
|
|
29
|
-
|
|
27
|
+
New projects can omit `bucketName` — it defaults to `<project>-media`. Existing
|
|
28
|
+
projects set `bucketName` to a bucket they already have. A browser deploy
|
|
29
|
+
creates the bucket; it cannot mint the R2 API-token secrets that presigning
|
|
30
|
+
needs.
|
|
30
31
|
|
|
31
|
-
The sections below document the **managed** subsystem
|
|
32
|
-
|
|
32
|
+
The sections below document the **managed** subsystem. For signed PUT/GET only,
|
|
33
|
+
jump to [Presigned uploads](#presigned-uploads).
|
|
34
|
+
|
|
35
|
+
## Read models
|
|
36
|
+
|
|
37
|
+
Most files should be **semi-private**: anyone who has the exact URL can GET
|
|
38
|
+
them; anyone who does not, cannot. That is a public bucket
|
|
39
|
+
(`readScope: "public"`) plus a UUID in the object path. Signed URLs are the
|
|
40
|
+
smaller case — confidential files that must stay unreadable even if the URL
|
|
41
|
+
leaks.
|
|
42
|
+
|
|
43
|
+
| Read model | Who can GET | Use for |
|
|
44
|
+
|---|---|---|
|
|
45
|
+
| **Public bucket** (`readScope: "public"`) | Anyone with the exact URL | Listing photos, avatars, public media, shareable attachments |
|
|
46
|
+
| **Session-gated** (`organization` / `user`) | Signed-in caller who passes RBAC | Org-internal docs the CMS should still gate |
|
|
47
|
+
| **Signed GET** (`storage.signGetUrl`) | Holder of a short-lived URL | IDs, payroll, medical, anything that must expire |
|
|
48
|
+
|
|
49
|
+
Public is not a directory listing. The files worker serves `/public/...` with
|
|
50
|
+
no auth. Put a UUID in the key so `/public/org/listings/hero.jpg` is not
|
|
51
|
+
guessable:
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
public/{orgId}/listings/{uuid}-hero.jpg
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Do **not** enable Cloudflare's `r2.dev` public-bucket domain for this. That
|
|
58
|
+
publishes every object in the bucket. Quickback's `readScope: "public"` keeps
|
|
59
|
+
the R2 bucket private and only the `public/` prefix anonymous — so a later
|
|
60
|
+
private object is not world-readable.
|
|
61
|
+
|
|
62
|
+
A Cloudflare-public bucket (`PUT …/domains/managed { enabled: true }`) is OK
|
|
63
|
+
only when that bucket will **only ever** hold public objects. PUTs stay
|
|
64
|
+
authenticated either way. Presign still needs
|
|
65
|
+
`R2_ACCOUNT_ID` / `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY`; through-Worker
|
|
66
|
+
uploads (`POST /object`) do not.
|
|
67
|
+
|
|
68
|
+
If the file already lives on the internet, store a URL instead of R2 —
|
|
69
|
+
`photoUrl: q.url()`. No bucket, no secrets, no files worker. See
|
|
70
|
+
[Using R2](/platform/storage/using-r2#store-a-url-instead).
|
|
33
71
|
|
|
34
72
|
## Architecture
|
|
35
73
|
|
|
@@ -118,10 +156,11 @@ export default {
|
|
|
118
156
|
| GET | `/object` | List objects |
|
|
119
157
|
| POST | `/url` | Get file URL for serving |
|
|
120
158
|
|
|
121
|
-
> For anything larger than a small image — video, audio, big PDFs —
|
|
122
|
-
> **presigned
|
|
123
|
-
> request-body cap
|
|
124
|
-
>
|
|
159
|
+
> For anything larger than a small image — video, audio, big PDFs — upload with a
|
|
160
|
+
> **presigned PUT**. The bytes go straight to R2, so you skip the Worker's
|
|
161
|
+
> request-body cap. Serving those files can still be a public URL; presign is the
|
|
162
|
+
> upload path, not the default read model. See
|
|
163
|
+
> [Presigned uploads](#presigned-uploads).
|
|
125
164
|
|
|
126
165
|
|
|
127
166
|
### Files Worker (files.yourdomain.com)
|
|
@@ -140,20 +179,21 @@ Buckets organize files and define access control policies.
|
|
|
140
179
|
```bash
|
|
141
180
|
POST /storage/v1/bucket
|
|
142
181
|
{
|
|
143
|
-
"name": "
|
|
144
|
-
"readScope": "
|
|
182
|
+
"name": "listings",
|
|
183
|
+
"readScope": "public",
|
|
145
184
|
"writeScope": "organization",
|
|
146
|
-
"
|
|
147
|
-
"writeRoles": ["admin"],
|
|
148
|
-
"deleteRoles": ["admin"]
|
|
185
|
+
"writeRoles": ["admin", "member"]
|
|
149
186
|
}
|
|
150
187
|
```
|
|
151
188
|
|
|
189
|
+
`readScope: "public"` is the default for listing photos and avatars. Switch to
|
|
190
|
+
`organization` or `user` only when a signed-in session must gate the GET.
|
|
191
|
+
|
|
152
192
|
### Scope Options
|
|
153
193
|
|
|
154
194
|
| Scope | Read Behavior | Write Behavior |
|
|
155
195
|
|-------|---------------|----------------|
|
|
156
|
-
| `public` | Anyone
|
|
196
|
+
| `public` | Anyone with the exact URL (no auth) | N/A |
|
|
157
197
|
| `organization` | Org members only | Org members only |
|
|
158
198
|
| `user` | Owner only | Owner only |
|
|
159
199
|
|
|
@@ -222,18 +262,20 @@ Response:
|
|
|
222
262
|
"name": "profile.jpg",
|
|
223
263
|
"size": 12345,
|
|
224
264
|
"mimeType": "image/jpeg",
|
|
225
|
-
"readScope": "
|
|
265
|
+
"readScope": "public"
|
|
226
266
|
}
|
|
227
267
|
```
|
|
228
268
|
|
|
229
|
-
## Presigned uploads
|
|
269
|
+
## Presigned uploads
|
|
270
|
+
|
|
271
|
+
Streaming bytes through the Worker (`POST /object`) is fine for listing photos
|
|
272
|
+
and other small files. It needs no R2 API token — the bucket binding is enough.
|
|
230
273
|
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
Worker.
|
|
274
|
+
Use a **presigned PUT** for large media (video, audio, big PDFs) or when the
|
|
275
|
+
object itself is confidential. The Worker runs the access checks and hands back
|
|
276
|
+
a short-lived URL the client uploads to **directly**. The bytes never touch your
|
|
277
|
+
Worker. Presigned **GET** (`storage.signGetUrl`) is the matching read model for
|
|
278
|
+
those confidential files — not for listing photos.
|
|
237
279
|
|
|
238
280
|
```bash
|
|
239
281
|
# 1. Ask the API to sign an upload URL (auth + bucket + role checks run here)
|
|
@@ -321,17 +363,20 @@ action — the JSON body parser and its ~1 MiB cap stay on for every other route
|
|
|
321
363
|
|
|
322
364
|
## Serving Files
|
|
323
365
|
|
|
324
|
-
### Public
|
|
366
|
+
### Public (semi-private) files — the usual case
|
|
325
367
|
|
|
326
|
-
Files in buckets with `readScope: "public"` are stored with a `public/` prefix
|
|
368
|
+
Files in buckets with `readScope: "public"` are stored with a `public/` prefix
|
|
369
|
+
and served with **no authentication**. Anyone who has the exact URL can open
|
|
370
|
+
the file. Put a UUID in the path so the URL is not guessable:
|
|
327
371
|
|
|
328
372
|
```
|
|
329
|
-
https://files.yourdomain.com/public/org_abc/
|
|
373
|
+
https://files.yourdomain.com/public/org_abc/listings/3f2a…-hero.jpg
|
|
330
374
|
```
|
|
331
375
|
|
|
332
|
-
|
|
376
|
+
Store that URL on the listing row. Send it to the public listing page. This is
|
|
377
|
+
the right model for property photos, avatars, and shareable media.
|
|
333
378
|
|
|
334
|
-
###
|
|
379
|
+
### Session-gated private files
|
|
335
380
|
|
|
336
381
|
Private files require a valid Better Auth session cookie:
|
|
337
382
|
|
|
@@ -367,7 +412,9 @@ When file storage is configured, the compiler generates:
|
|
|
367
412
|
|
|
368
413
|
The compiler also adds [`aws4fetch`](https://github.com/mhart/aws4fetch) to your
|
|
369
414
|
`package.json` (used by the presigner) and the R2 presign secrets to your
|
|
370
|
-
generated `CloudflareBindings` type.
|
|
415
|
+
generated `CloudflareBindings` type. Package-mode compiles (Start browser
|
|
416
|
+
deploys) resolve it from the compiler image's `/deps/node_modules`, not from
|
|
417
|
+
an `npm install` of that generated `package.json`.
|
|
371
418
|
|
|
372
419
|
## Deployment
|
|
373
420
|
|
|
@@ -400,8 +447,9 @@ After compiling:
|
|
|
400
447
|
wrangler deploy
|
|
401
448
|
```
|
|
402
449
|
|
|
403
|
-
6. **Set the R2 presign secrets**
|
|
404
|
-
|
|
450
|
+
6. **Set the R2 presign secrets** only if you use signed PUT/GET. Public-bucket
|
|
451
|
+
uploads through `POST /object` do not need them. See
|
|
452
|
+
[Presigned uploads](#presigned-uploads):
|
|
405
453
|
```bash
|
|
406
454
|
wrangler secret put R2_ACCOUNT_ID
|
|
407
455
|
wrangler secret put R2_ACCESS_KEY_ID
|
|
@@ -442,7 +490,9 @@ Both paths answer `413` with the actual and permitted byte counts.
|
|
|
442
490
|
|
|
443
491
|
## Security Model
|
|
444
492
|
|
|
445
|
-
- **Upload security**: Enforced by API worker (auth
|
|
446
|
-
|
|
493
|
+
- **Upload security**: Enforced by the API worker (auth, org, role). A public
|
|
494
|
+
read scope never implies a public write.
|
|
495
|
+
- **Serve security**: Public prefix = URL is the capability. Session-gated
|
|
496
|
+
paths re-check membership on every GET. Signed GET expires.
|
|
447
497
|
- **Soft deletes**: Files are marked deleted in metadata but retained in R2
|
|
448
498
|
- **Tenant isolation**: All files are prefixed with organization ID
|
|
@@ -1,15 +1,87 @@
|
|
|
1
1
|
# Using R2
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Most "files" on a listing, profile, or gallery are **a URL**. Host the bytes in
|
|
4
|
+
R2 only when this app must own the upload.
|
|
4
5
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
Pick the first row that fits:
|
|
7
|
+
|
|
8
|
+
| What you need | What to build |
|
|
9
|
+
|---|---|
|
|
10
|
+
| Photo already on the web, or the user pastes a link | `photoUrl: q.url()` — no R2, no secrets |
|
|
11
|
+
| This app hosts the bytes; anyone with the link may view | Managed public bucket (`readScope: "public"`) + UUID in the key |
|
|
12
|
+
| Large or confidential bytes; the URL itself must expire | Signed PUT/GET — needs an R2 API token |
|
|
13
|
+
|
|
14
|
+
Public-if-you-have-the-link is the usual read model (listing photos, avatars).
|
|
15
|
+
Signed URLs are the smaller case. Details:
|
|
16
|
+
[R2 Setup → Read models](/platform/storage/r2#read-models).
|
|
17
|
+
|
|
18
|
+
By default `defineFileStorage("cloudflare-r2")` is **presign-only**: you get
|
|
19
|
+
the `ctx.storage` signer and nothing else. The `/storage/v1/*` endpoints
|
|
20
|
+
further down exist only in the [managed subsystem](/platform/storage/r2#two-modes)
|
|
8
21
|
(`managed: true`).
|
|
9
22
|
|
|
10
|
-
##
|
|
23
|
+
## Store a URL instead
|
|
24
|
+
|
|
25
|
+
A property listing, avatar, or hero image that is already a link does not need
|
|
26
|
+
R2. Store the URL on the row. The CMS gets a URL input; the public listing page
|
|
27
|
+
renders it. A browser deploy does not ask for R2 secrets.
|
|
28
|
+
|
|
29
|
+
```ts title="quickback/features/listings/listings.ts"
|
|
30
|
+
import { q, defineTable } from "@quickback/compiler";
|
|
31
|
+
|
|
32
|
+
export const listings = q.table("listings", {
|
|
33
|
+
id: q.id(),
|
|
34
|
+
title: q.text().required(),
|
|
35
|
+
photoUrl: q.url(),
|
|
36
|
+
organizationId: q.scope("organization"),
|
|
37
|
+
...q.audit(),
|
|
38
|
+
...q.softDelete(),
|
|
39
|
+
});
|
|
40
|
+
|
|
41
|
+
export default defineTable(listings, {
|
|
42
|
+
read: { access: { roles: ["member+"] } },
|
|
43
|
+
crud: {
|
|
44
|
+
create: { access: { roles: ["member+"] } },
|
|
45
|
+
update: { access: { roles: ["admin+"] } },
|
|
46
|
+
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
47
|
+
},
|
|
48
|
+
guards: { createable: ["title", "photoUrl"], updatable: ["title", "photoUrl"] },
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`q.url()` rejects `javascript:` / `data:` URIs at the validation edge. Use
|
|
53
|
+
`q.text()` only when you must store a non-http value.
|
|
54
|
+
|
|
55
|
+
## Upload into a public bucket (managed)
|
|
56
|
+
|
|
57
|
+
With `managed: true`, create a bucket with `readScope: "public"` and PUT bytes
|
|
58
|
+
through the Worker. No R2 API token. The files worker serves the object at
|
|
59
|
+
`/public/...` with no auth. Put a UUID in the path so the URL is not guessable.
|
|
11
60
|
|
|
12
|
-
|
|
61
|
+
```bash
|
|
62
|
+
# 1. Create the bucket once (write stays org-gated)
|
|
63
|
+
curl -X POST https://api.example.com/storage/v1/bucket \
|
|
64
|
+
-H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
|
|
65
|
+
-d '{ "name": "listings", "readScope": "public", "writeScope": "organization", "writeRoles": ["admin", "member"] }'
|
|
66
|
+
|
|
67
|
+
# 2. Upload — bytes go through the Worker, binding only
|
|
68
|
+
curl -X POST https://api.example.com/storage/v1/object/listings/3f2a9c…-hero.jpg \
|
|
69
|
+
-H "Authorization: Bearer <token>" -H "Content-Type: image/jpeg" \
|
|
70
|
+
--data-binary @hero.jpg
|
|
71
|
+
# → { "key": "public/org_abc/listings/3f2a9c…-hero.jpg", "readScope": "public", … }
|
|
72
|
+
|
|
73
|
+
# 3. Store that URL on the listing (or POST /storage/v1/url to resolve it)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Serve:
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
https://files.yourdomain.com/public/org_abc/listings/3f2a9c…-hero.jpg
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Signed upload (large or confidential files)
|
|
83
|
+
|
|
84
|
+
Write a `defineAction` that signs a presigned URL and stores the key in
|
|
13
85
|
**your own table**. Bytes go directly to R2 — the Worker only signs.
|
|
14
86
|
|
|
15
87
|
```ts title="quickback/features/media/actions/signUpload.ts"
|
|
@@ -38,7 +110,7 @@ curl -X POST https://api.example.com/api/v1/media/sign-upload \
|
|
|
38
110
|
-d '{ "filename": "report.pdf", "contentType": "application/pdf" }'
|
|
39
111
|
# → { "uploadUrl": "https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...", "key": "...", "headers": { "Content-Type": "application/pdf" } }
|
|
40
112
|
|
|
41
|
-
# 2. Upload the bytes straight to R2 (replay the returned headers)
|
|
113
|
+
# 2. Upload the bytes straight to R2 (replay the returned headers verbatim)
|
|
42
114
|
curl -X PUT "<uploadUrl>" -H "Content-Type: application/pdf" --data-binary @report.pdf
|
|
43
115
|
```
|
|
44
116
|
|
|
@@ -48,12 +120,16 @@ returns a presigned GET URL. Pass `bucket` to target a bucket other than the
|
|
|
48
120
|
configured default.
|
|
49
121
|
|
|
50
122
|
Presigning needs an R2 API token — set the `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`,
|
|
51
|
-
and `R2_SECRET_ACCESS_KEY` secrets.
|
|
123
|
+
and `R2_SECRET_ACCESS_KEY` secrets. A [browser deploy](/start/deploy-browser)
|
|
124
|
+
refuses the project until those exist; it cannot mint them. Create the token in
|
|
125
|
+
the Cloudflare dashboard (R2 → Manage API Tokens, Object Read & Write) and set
|
|
126
|
+
the secrets with `wrangler secret put` / `quickback deploy`. See
|
|
127
|
+
[R2 Setup → Presigned uploads](/platform/storage/r2#presigned-uploads).
|
|
52
128
|
|
|
53
|
-
|
|
129
|
+
### Managed presign endpoints
|
|
54
130
|
|
|
55
131
|
With `managed: true`, the generated API also exposes turnkey presigned
|
|
56
|
-
endpoints backed by
|
|
132
|
+
endpoints backed by FILES_DB:
|
|
57
133
|
|
|
58
134
|
```bash
|
|
59
135
|
# 1. Request a presigned upload URL
|
|
@@ -72,12 +148,12 @@ curl -X POST https://api.example.com/storage/v1/confirm/documents/report.pdf \
|
|
|
72
148
|
|
|
73
149
|
## Download Flow
|
|
74
150
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
151
|
+
**Public bucket / URL field** — GET the stored URL. No session, no signature.
|
|
152
|
+
|
|
153
|
+
**Presign-only, confidential files** — mint a short-lived download URL with
|
|
154
|
+
`storage.signGetUrl(key, { downloadFilename })` from your action.
|
|
78
155
|
|
|
79
|
-
|
|
80
|
-
checks applied:
|
|
156
|
+
**Managed, session-gated buckets** — the files worker re-checks membership:
|
|
81
157
|
|
|
82
158
|
```bash
|
|
83
159
|
# Download a file (auth + firewall enforced)
|
|
@@ -93,12 +169,16 @@ The download endpoint:
|
|
|
93
169
|
|
|
94
170
|
## Role-Based Access
|
|
95
171
|
|
|
96
|
-
File
|
|
172
|
+
File **writes** always respect the same security layers as your API:
|
|
173
|
+
|
|
174
|
+
- **Firewall** — Users can only upload files belonging to their organization
|
|
175
|
+
- **Access** — Role-based upload / delete permissions
|
|
97
176
|
|
|
98
|
-
|
|
99
|
-
|
|
177
|
+
File **reads** follow the bucket's `readScope`. `public` does not run those
|
|
178
|
+
checks on GET — the URL is the capability.
|
|
100
179
|
|
|
101
180
|
## See Also
|
|
102
181
|
|
|
103
|
-
- [R2 Setup](/platform/storage/r2) —
|
|
182
|
+
- [R2 Setup](/platform/storage/r2) — Read models, bucket creation, wrangler bindings
|
|
104
183
|
- [Avatars](/ui/account/features/avatars) — Avatar upload UI integration
|
|
184
|
+
- [Deploy from your browser](/start/deploy-browser) — R2 secrets block Start deploys
|
|
@@ -338,3 +338,43 @@ which re-send the original signed envelope.
|
|
|
338
338
|
**Fail-closed runtime posture for every scheme:** an unset secret env is a
|
|
339
339
|
500 rejection — never a verify-skip; any signature failure is a 401 Problem
|
|
340
340
|
before the body is ever parsed.
|
|
341
|
+
|
|
342
|
+
### Per-organization secrets: verify in the action
|
|
343
|
+
|
|
344
|
+
`webhook:` resolves its secret from **env** — one secret per deployment. When
|
|
345
|
+
each organization connects its own provider account (a per-org Resend or
|
|
346
|
+
Svix signing secret in an `.encrypted()` column), declare `rawBody: true`
|
|
347
|
+
instead and verify inside `execute`. The route reads the body once (bounded,
|
|
348
|
+
pre-auth, exactly like the `webhook:` gate), parses `input` from those bytes,
|
|
349
|
+
and hands the same bytes to your handler — so the MAC runs over what the
|
|
350
|
+
provider signed, never over re-serialised JSON.
|
|
351
|
+
|
|
352
|
+
{/* doc-compile: skip — excerpt: `decryptValue` and the `connections` table live in the generated project; the fence shows the shape only. */}
|
|
353
|
+
```ts title="quickback/features/comms/actions/resendEvents.ts"
|
|
354
|
+
import { z } from "zod";
|
|
355
|
+
import { defineAction } from "../.quickback/define-action";
|
|
356
|
+
import { decryptValue } from "../../../../src/lib/encryption";
|
|
357
|
+
|
|
358
|
+
export default defineAction({
|
|
359
|
+
description: "Per-org Resend events — secret lives on the connection row",
|
|
360
|
+
path: "/resend/events/:orgId",
|
|
361
|
+
method: "POST",
|
|
362
|
+
access: { roles: ["PUBLIC"] },
|
|
363
|
+
rawBody: true,
|
|
364
|
+
input: z.object({ type: z.string(), data: z.record(z.unknown()) }),
|
|
365
|
+
execute: async ({ c, env, db, rawBody, input }) => {
|
|
366
|
+
const orgId = c.req.param("orgId");
|
|
367
|
+
const row = await db.query.connections.findFirst({ where: (t, { eq }) => eq(t.organizationId, orgId) });
|
|
368
|
+
// ctx.crypto is hydrated for authenticated requests only — a PUBLIC
|
|
369
|
+
// action reads an .encrypted() column through decryptValue directly.
|
|
370
|
+
const secret = await decryptValue(env, db, orgId, row.signingSecret);
|
|
371
|
+
// verify `rawBody` + the provider's signature headers with `secret`; throw a 401 ActionError on failure
|
|
372
|
+
return { ok: true, type: input.type };
|
|
373
|
+
},
|
|
374
|
+
});
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
`rawBody` is only ever populated on standalone, non-GET actions; a `GET`
|
|
378
|
+
declaring it is a compile error. Actions with `webhook:` get `rawBody` too —
|
|
379
|
+
useful when a provider signs the body and *also* nests a second signed
|
|
380
|
+
payload inside it.
|