@quickback-dev/cli 0.38.0 → 0.39.1
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/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +36 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/compile.test.d.ts +2 -0
- package/dist/commands/compile.test.d.ts.map +1 -0
- package/dist/commands/compile.test.js +83 -0
- package/dist/commands/compile.test.js.map +1 -0
- package/dist/commands/create.js +15 -11
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/migrations.d.ts +33 -0
- package/dist/commands/migrations.d.ts.map +1 -1
- package/dist/commands/migrations.js +41 -2
- package/dist/commands/migrations.js.map +1 -1
- package/dist/commands/migrations.test.d.ts +2 -0
- package/dist/commands/migrations.test.d.ts.map +1 -0
- package/dist/commands/migrations.test.js +67 -0
- package/dist/commands/migrations.test.js.map +1 -0
- package/dist/docs/content.js +24 -24
- package/dist/docs/content.js.map +1 -1
- package/dist/examples/recruitment.tar.gz +0 -0
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts +48 -0
- package/dist/lib/action-harvest.d.ts.map +1 -0
- package/dist/lib/action-harvest.js +292 -0
- package/dist/lib/action-harvest.js.map +1 -0
- package/dist/lib/action-harvest.test.d.ts +2 -0
- package/dist/lib/action-harvest.test.d.ts.map +1 -0
- package/dist/lib/action-harvest.test.js +112 -0
- package/dist/lib/action-harvest.test.js.map +1 -0
- package/dist/lib/api-client.d.ts +10 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +17 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/api-client.test.js +19 -0
- package/dist/lib/api-client.test.js.map +1 -1
- package/dist/lib/artifact-routing.d.ts +1 -0
- package/dist/lib/artifact-routing.d.ts.map +1 -1
- package/dist/lib/artifact-routing.js +15 -3
- package/dist/lib/artifact-routing.js.map +1 -1
- package/dist/lib/artifact-routing.test.js +12 -1
- package/dist/lib/artifact-routing.test.js.map +1 -1
- package/dist/lib/file-loader.d.ts +1 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +34 -1
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +28 -4
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/lib/prepare-state-output.d.ts +8 -0
- package/dist/lib/prepare-state-output.d.ts.map +1 -0
- package/dist/lib/prepare-state-output.js +17 -0
- package/dist/lib/prepare-state-output.js.map +1 -0
- package/dist/lib/prepare-state-output.test.d.ts +2 -0
- package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
- package/dist/lib/prepare-state-output.test.js +31 -0
- package/dist/lib/prepare-state-output.test.js.map +1 -0
- package/dist/skill/SKILL.md +1 -1
- package/dist/skill/docs/changelog.md +201 -0
- package/dist/skill/docs/compiler/config/agents.md +1 -1
- package/dist/skill/docs/compiler/config/auth.md +1 -1
- package/dist/skill/docs/compiler/config/index.md +8 -9
- package/dist/skill/docs/compiler/config/providers.md +3 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +65 -73
- package/dist/skill/docs/compiler/definitions/access.md +40 -33
- package/dist/skill/docs/compiler/definitions/actions.md +1 -1
- package/dist/skill/docs/compiler/definitions/firewall.md +1 -1
- package/dist/skill/docs/compiler/definitions/schema.md +8 -2
- package/dist/skill/docs/compiler/getting-started/template-blog.md +7 -7
- package/dist/skill/docs/compiler/getting-started/template-empty.md +1 -4
- package/dist/skill/docs/compiler/getting-started/templates.md +6 -6
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
- package/dist/skill/docs/stack/account-ui/features/admin.md +1 -1
- package/dist/skill/docs/stack/account-ui/features/index.md +2 -2
- package/dist/skill/docs/stack/cms/connecting.md +17 -16
- package/dist/skill/docs/stack/cms/index.md +7 -7
- package/dist/skill/docs/stack/cms/schema-format.md +0 -2
- package/dist/skill/docs/stack/cms/schema-registry.md +0 -6
- package/dist/skill/docs/stack/cms/security.md +6 -6
- package/dist/skill/docs/stack/realtime/durable-objects.md +5 -7
- package/dist/skill/docs/stack/storage/r2.md +112 -3
- package/dist/skill/docs/stack/storage/using-r2.md +30 -10
- package/dist/templates/registry.js +2 -2
- package/dist/templates/registry.js.map +1 -1
- package/package.json +1 -1
- package/src/examples/recruitment.tar.gz +0 -0
- package/src/skill/SKILL.md +1 -1
- package/src/skill/docs/changelog.md +201 -0
- package/src/skill/docs/compiler/config/agents.md +1 -1
- package/src/skill/docs/compiler/config/auth.md +1 -1
- package/src/skill/docs/compiler/config/index.md +8 -9
- package/src/skill/docs/compiler/config/providers.md +3 -0
- package/src/skill/docs/compiler/config/single-tenant.md +65 -73
- package/src/skill/docs/compiler/definitions/access.md +40 -33
- package/src/skill/docs/compiler/definitions/actions.md +1 -1
- package/src/skill/docs/compiler/definitions/firewall.md +1 -1
- package/src/skill/docs/compiler/definitions/schema.md +8 -2
- package/src/skill/docs/compiler/getting-started/template-blog.md +7 -7
- package/src/skill/docs/compiler/getting-started/template-empty.md +1 -4
- package/src/skill/docs/compiler/getting-started/templates.md +6 -6
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
- package/src/skill/docs/stack/account-ui/features/admin.md +1 -1
- package/src/skill/docs/stack/account-ui/features/index.md +2 -2
- package/src/skill/docs/stack/cms/connecting.md +17 -16
- package/src/skill/docs/stack/cms/index.md +7 -7
- package/src/skill/docs/stack/cms/schema-format.md +0 -2
- package/src/skill/docs/stack/cms/schema-registry.md +0 -6
- package/src/skill/docs/stack/cms/security.md +6 -6
- package/src/skill/docs/stack/realtime/durable-objects.md +5 -7
- package/src/skill/docs/stack/storage/r2.md +112 -3
- package/src/skill/docs/stack/storage/using-r2.md +30 -10
|
@@ -1,10 +1,12 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Pinned Organization Mode
|
|
2
2
|
|
|
3
|
-
Single-tenant mode
|
|
3
|
+
Single-tenant mode has been removed. If you want a one-org deployment without org switching overhead, use `features.pinnedOrganizationId` instead.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Pinned organization mode keeps Better Auth's organization plugin, organization membership roles, and org-scoped firewalls enabled. The only difference is that Quickback hard-codes one active organization id at runtime and hides the switching UI.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Enabling Pinned Organization Mode
|
|
8
|
+
|
|
9
|
+
Set a real organization id in your config:
|
|
8
10
|
|
|
9
11
|
```typescript
|
|
10
12
|
import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickback/compiler";
|
|
@@ -13,7 +15,7 @@ export default defineConfig({
|
|
|
13
15
|
name: "my-site",
|
|
14
16
|
template: "hono",
|
|
15
17
|
features: {
|
|
16
|
-
|
|
18
|
+
pinnedOrganizationId: "org_123",
|
|
17
19
|
},
|
|
18
20
|
providers: {
|
|
19
21
|
runtime: defineRuntime("cloudflare"),
|
|
@@ -23,100 +25,90 @@ export default defineConfig({
|
|
|
23
25
|
});
|
|
24
26
|
```
|
|
25
27
|
|
|
26
|
-
|
|
28
|
+
> **Use a Real Organization ID**
|
|
29
|
+
>
|
|
30
|
+
> `pinnedOrganizationId` must point at an organization that actually exists in your Better Auth data. The compiler does not create the organization for you.
|
|
27
31
|
|
|
28
|
-
| Aspect | Multi-Tenant (default) | Single-Tenant |
|
|
29
|
-
|--------|----------------------|---------------|
|
|
30
|
-
| Organization plugin | Enabled | Disabled |
|
|
31
|
-
| `organizationId` columns | Required on resources | Not used |
|
|
32
|
-
| Role source | Org membership table | `user.role` field |
|
|
33
|
-
| Firewall scopes | `owner`, `organization`, `team`, `exception` | `owner`, `exception` only |
|
|
34
|
-
| Admin org endpoints | Use Better Auth's `/auth/v1/organization/list` (caller's orgs) and `/auth/v1/admin/list-organizations` when `cms.sysadmin: true` (cross-tenant) | N/A (no org plugin) |
|
|
35
|
-
| `ctx.activeOrgId` | From session/JWT | Always `undefined` |
|
|
36
|
-
| `ctx.roles` | From org member role | From `user.role` |
|
|
37
32
|
|
|
38
|
-
##
|
|
33
|
+
## Removed Single-Tenant Settings
|
|
39
34
|
|
|
40
|
-
|
|
35
|
+
These older settings now fail the compile with a migration error:
|
|
41
36
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
firewall: [{ field: 'ownerId', equals: 'ctx.userId' }],
|
|
46
|
-
read: {
|
|
47
|
-
access: { roles: ['user', 'admin'] },
|
|
48
|
-
},
|
|
49
|
-
create: { access: { roles: ['admin'] } },
|
|
50
|
-
});
|
|
37
|
+
- `features.organizations: false`
|
|
38
|
+
- `providers.database.config.organizations: false`
|
|
39
|
+
- `providers.auth.config.plugins.organization = false`
|
|
51
40
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
read: {
|
|
56
|
-
access: { roles: ['PUBLIC'] },
|
|
57
|
-
},
|
|
58
|
-
create: { access: { roles: ['admin'] } },
|
|
59
|
-
update: { access: { roles: ['admin'] } },
|
|
60
|
-
delete: { access: { roles: ['admin'] } },
|
|
61
|
-
});
|
|
62
|
-
```
|
|
41
|
+
Replace them with `features.pinnedOrganizationId`.
|
|
42
|
+
|
|
43
|
+
## What Changes
|
|
63
44
|
|
|
64
|
-
|
|
45
|
+
| Aspect | Default Org Mode | Pinned Organization Mode |
|
|
46
|
+
|--------|------------------|--------------------------|
|
|
47
|
+
| Organization plugin | Enabled | Enabled |
|
|
48
|
+
| Role source | Org membership table | Org membership table in the pinned org |
|
|
49
|
+
| Firewall scopes | `owner`, `organization`, `team`, `exception` | Same |
|
|
50
|
+
| `ctx.activeOrgId` | From session / JWT / API key context | Always the configured org id |
|
|
51
|
+
| CMS org selector | Visible when caller can switch orgs | Hidden |
|
|
52
|
+
| CMS org gate | Requires an active org selection | Bypassed; pinned org is injected automatically |
|
|
65
53
|
|
|
54
|
+
## Access and Roles
|
|
66
55
|
|
|
67
|
-
|
|
56
|
+
Pinned organization mode does **not** bring back the old `user.role` mirror on `ctx.roles`.
|
|
68
57
|
|
|
69
|
-
Use
|
|
58
|
+
- Use `roles: ["owner" | "admin" | "member"]` for data-plane access based on membership in the pinned org.
|
|
59
|
+
- Use `userRole: [...]` for platform-wide Better Auth roles stored on `user.role` (`appmanager`, `sysadmin`, etc.).
|
|
70
60
|
|
|
71
61
|
```typescript
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
62
|
+
export default defineActions({
|
|
63
|
+
publish: {
|
|
64
|
+
access: {
|
|
65
|
+
or: [
|
|
66
|
+
{ roles: ["admin"] }, // admin in the pinned org
|
|
67
|
+
{ userRole: ["appmanager"] }, // platform control-plane role
|
|
68
|
+
],
|
|
69
|
+
},
|
|
70
|
+
execute: async () => ({ ok: true }),
|
|
71
|
+
},
|
|
72
|
+
});
|
|
76
73
|
```
|
|
77
74
|
|
|
78
|
-
##
|
|
75
|
+
## Firewalls and Resource Scopes
|
|
79
76
|
|
|
80
|
-
|
|
77
|
+
Organization-scoped resources keep working in pinned mode. `q.scope("organization")`, `q.scope("team")`, and any firewall predicate that references `ctx.activeOrgId` still compile and run normally — they just see the pinned organization id instead of a user-selected one.
|
|
81
78
|
|
|
82
|
-
|
|
79
|
+
Owner-scoped and public resources are unchanged.
|
|
83
80
|
|
|
81
|
+
## CMS Behavior
|
|
84
82
|
|
|
83
|
+
When `features.pinnedOrganizationId` is set:
|
|
85
84
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
| `PUBLIC` | Unauthenticated access (special keyword) |
|
|
85
|
+
- the CMS hides the org switcher
|
|
86
|
+
- the CMS skips the org-selection gate
|
|
87
|
+
- API calls and realtime connections use the pinned org automatically
|
|
88
|
+
- role checks still come from the caller's membership in that org
|
|
91
89
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
},
|
|
101
|
-
},
|
|
102
|
-
});
|
|
103
|
-
```
|
|
90
|
+
This is the intended replacement for the old single-tenant CMS flow.
|
|
91
|
+
|
|
92
|
+
## Migration from Single-Tenant Mode
|
|
93
|
+
|
|
94
|
+
1. Remove `features.organizations: false`.
|
|
95
|
+
2. Add `features.pinnedOrganizationId: "<real-org-id>"`.
|
|
96
|
+
3. Remove any assumptions that `ctx.roles` mirrors `user.role`.
|
|
97
|
+
4. If you need platform-wide roles, keep those checks on `userRole`, not `roles`.
|
|
104
98
|
|
|
105
99
|
## Consuming the API
|
|
106
100
|
|
|
107
|
-
|
|
101
|
+
Pinned organization mode still produces the same JSON API shape. Pair it with any frontend framework:
|
|
108
102
|
|
|
109
103
|
```typescript
|
|
110
|
-
|
|
111
|
-
const posts = await fetch('https://api.mysite.com/api/v1/posts').then(r => r.json());
|
|
104
|
+
const posts = await fetch("https://api.mysite.com/api/v1/posts").then((r) => r.json());
|
|
112
105
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
method: 'POST',
|
|
106
|
+
const res = await fetch("https://api.mysite.com/api/v1/posts", {
|
|
107
|
+
method: "POST",
|
|
116
108
|
headers: {
|
|
117
|
-
|
|
118
|
-
|
|
109
|
+
Authorization: `Bearer ${token}`,
|
|
110
|
+
"Content-Type": "application/json",
|
|
119
111
|
},
|
|
120
|
-
body: JSON.stringify({ title:
|
|
112
|
+
body: JSON.stringify({ title: "New Post", content: "..." }),
|
|
121
113
|
});
|
|
122
114
|
```
|
|
@@ -56,7 +56,7 @@ delete: { access: { roles: ["owner"] } }, // owner only (no +)
|
|
|
56
56
|
The `+` suffix expands at compile time — `"member+"` becomes `["member", "admin", "owner"]` in the generated code. You can mix hierarchical and exact roles: `roles: ["member+", "finance"]` expands to `["member", "admin", "owner", "finance"]`.
|
|
57
57
|
|
|
58
58
|
- Roles without `+` are exact matches (no expansion)
|
|
59
|
-
- Pseudo-roles (`PUBLIC`, `AUTHENTICATED`, `USER`, `ADMIN`, `SYSADMIN`) cannot use the `+` suffix — they're terminal markers
|
|
59
|
+
- Pseudo-roles / reserved markers (`PUBLIC`, `AUTHENTICATED`, `USER`, `ADMIN`, `SYSADMIN`) cannot use the `+` suffix — they're terminal markers
|
|
60
60
|
- Using `+` with a role not in the hierarchy throws a compile error
|
|
61
61
|
- Using `+` without configuring `auth.roleHierarchy` throws a compile error
|
|
62
62
|
|
|
@@ -89,50 +89,50 @@ interface Access {
|
|
|
89
89
|
|
|
90
90
|
| Primitive | Checks | Source | Example values |
|
|
91
91
|
|-----------|--------|--------|----------------|
|
|
92
|
-
| `roles` | `ctx.roles` | Org membership
|
|
93
|
-
| `userRole` | `ctx.userRole` | The `user.role` column (Better Auth
|
|
92
|
+
| `roles` | `ctx.roles` | Org membership roles | `"owner"`, `"admin"`, `"member"` |
|
|
93
|
+
| `userRole` | `ctx.userRole` | The `user.role` column (Better Auth / platform control-plane roles) | `"user"`, `"appmanager"`, `"sysadmin"` |
|
|
94
94
|
|
|
95
|
-
In multi-tenant mode, **`roles: ["admin"]` means "org admin" — not a platform-wide
|
|
95
|
+
In multi-tenant mode, **`roles: ["admin"]` means "org admin" — not a platform-wide role.** An org-admin of Acme Corp has no elevated rights across other orgs. If you want platform control-plane operators through regardless of org membership (CMS, Better Auth admin surfaces, support tooling), use `userRole: ["appmanager"]`. If you need true cross-tenant data-plane access, use `roles: ["SYSADMIN"]` (with `cms: { sysadmin: true }`).
|
|
96
96
|
|
|
97
|
-
|
|
97
|
+
Pinned organization mode does not change this split. `roles` still come from organization membership in the pinned org, while `userRole` still comes from Better Auth's `user.role` column.
|
|
98
98
|
|
|
99
99
|
### When to use `userRole`
|
|
100
100
|
|
|
101
101
|
```typescript
|
|
102
|
-
// Platform
|
|
102
|
+
// Platform control-plane users can see SSNs on every customer record, regardless of org
|
|
103
103
|
masking: {
|
|
104
|
-
ssn: { type: 'ssn', show: { userRole: ['
|
|
104
|
+
ssn: { type: 'ssn', show: { userRole: ['appmanager'] } },
|
|
105
105
|
}
|
|
106
106
|
|
|
107
|
-
//
|
|
107
|
+
// Platform ops (user.role === 'appmanager') OR the org owner can refund
|
|
108
108
|
access: {
|
|
109
109
|
or: [
|
|
110
|
-
{ userRole: ['
|
|
110
|
+
{ userRole: ['appmanager'] },
|
|
111
111
|
{ roles: ['owner'] },
|
|
112
112
|
],
|
|
113
113
|
}
|
|
114
114
|
|
|
115
|
-
// CMS-internal resource: only platform
|
|
116
|
-
read: { access: { userRole: ['
|
|
117
|
-
create: { access: { userRole: ['
|
|
118
|
-
update: { access: { userRole: ['
|
|
119
|
-
delete: { access: { userRole: ['
|
|
115
|
+
// CMS-internal resource: only platform control-plane users
|
|
116
|
+
read: { access: { userRole: ['appmanager'] } },
|
|
117
|
+
create: { access: { userRole: ['appmanager'] } },
|
|
118
|
+
update: { access: { userRole: ['appmanager'] } },
|
|
119
|
+
delete: { access: { userRole: ['appmanager'] } },
|
|
120
120
|
```
|
|
121
121
|
|
|
122
122
|
When `roles` and `userRole` both appear in a single `Access` node, they're combined with AND — the user must satisfy both. Use `or:` to express "one or the other".
|
|
123
123
|
|
|
124
|
-
`userRole` doesn't expand with the `+` hierarchy suffix — user-table roles are flat (typically just `"user"` and `"
|
|
124
|
+
`userRole` doesn't expand with the `+` hierarchy suffix — user-table roles are flat (typically just `"user"`, `"appmanager"`, and `"sysadmin"`). If you've added custom user-table roles via Better Auth, list them explicitly.
|
|
125
125
|
|
|
126
126
|
### Pseudo-roles
|
|
127
127
|
|
|
128
|
-
Quickback ships five UPPERCASE
|
|
128
|
+
Quickback ships five reserved UPPERCASE markers. Four are real pseudo-roles handled directly by the compiler; `ADMIN` is retained only as a reserved legacy marker so the compiler can fail loudly with migration guidance. The casing carries the boundary: UPPERCASE = compiler-owned marker, lowercase = real role from a plugin's table (e.g. `members.role` from the org plugin).
|
|
129
129
|
|
|
130
130
|
| Role | Auth gate | Compile-time requirement | Runtime check |
|
|
131
131
|
|------|-----------|-------------------------|---------------|
|
|
132
132
|
| `PUBLIC` | bypassed | none — explicit opt-in for unauthenticated access | always passes (auth skipped) |
|
|
133
133
|
| `AUTHENTICATED` | required | none | `ctx.authenticated === true` |
|
|
134
134
|
| `USER` | required | resource firewall **must** scope by `userId` | `ctx.authenticated` AND (`ctx.userRole` is unset OR `ctx.userRole === "user"`) |
|
|
135
|
-
| `ADMIN` | required |
|
|
135
|
+
| `ADMIN` | required | reserved legacy marker — compiler rejects it | `false` |
|
|
136
136
|
| `SYSADMIN` | required | `cms: { sysadmin: true }` **must** be set on the project | `ctx.authenticated && ctx.userRole === "sysadmin"` |
|
|
137
137
|
|
|
138
138
|
You can mix pseudo-roles with real roles in the same list — they're OR'd together.
|
|
@@ -198,18 +198,22 @@ If you forget the `userId` firewall predicate, the compiler throws:
|
|
|
198
198
|
|
|
199
199
|
> `roles: ["USER"]` requires the resource to be scoped per-user. Add a `userId` column (auto-scoped) or an explicit owner predicate. If you want any signed-in user to read all records, use `roles: ["AUTHENTICATED"]` instead.
|
|
200
200
|
|
|
201
|
-
When the Better Auth admin plugin is enabled, `USER` matches `user.role === "user"` specifically —
|
|
201
|
+
When the Better Auth admin plugin is enabled, `USER` matches `user.role === "user"` specifically — appmanagers and sysadmins are excluded. If the same route should serve both, express it explicitly with `or: [{ roles: ["USER"] }, { userRole: ["appmanager"] }]`.
|
|
202
202
|
|
|
203
|
-
#### `ADMIN` —
|
|
203
|
+
#### `ADMIN` — legacy reserved marker (compile-time error)
|
|
204
204
|
|
|
205
|
-
|
|
205
|
+
`roles: ["ADMIN"]` is no longer supported. The compiler fails hard on any use of `ADMIN` so platform and tenant roles can't be confused.
|
|
206
206
|
|
|
207
207
|
```typescript
|
|
208
|
-
// Platform-
|
|
209
|
-
read: { access: {
|
|
208
|
+
// Platform control-plane audit log
|
|
209
|
+
read: { access: { userRole: ["appmanager"] } }
|
|
210
210
|
```
|
|
211
211
|
|
|
212
|
-
|
|
212
|
+
Use one of these instead:
|
|
213
|
+
|
|
214
|
+
- `userRole: ["appmanager"]` for platform control-plane access
|
|
215
|
+
- `roles: ["admin"]` for org-membership admin access
|
|
216
|
+
- `roles: ["SYSADMIN"]` for true cross-tenant access
|
|
213
217
|
|
|
214
218
|
#### `SYSADMIN` — cross-tenant DB-admin tier
|
|
215
219
|
|
|
@@ -220,23 +224,23 @@ Use `roles: ["SYSADMIN"]` for endpoints that should only be reachable by platfor
|
|
|
220
224
|
read: { access: { roles: ["SYSADMIN"] } }
|
|
221
225
|
```
|
|
222
226
|
|
|
223
|
-
`
|
|
227
|
+
`SYSADMIN` is distinct from `userRole: ["appmanager"]`. Appmanager is the platform control-plane tier (CMS shell, Better Auth admin surfaces, support tooling); sysadmin is the cross-tenant data-plane tier. The one place sysadmin gets implicit extra powers is **the firewall escape hatch**: when `cms.sysadmin: true`, every `buildFirewallConditions` emits an `if (ctx.userRole === 'sysadmin') return undefined;` (or just the soft-delete predicate when present) at the top — so sysadmins see every tenant's rows, not just their own org's. That escape hatch does NOT fire for `userRole === 'appmanager'`; appmanagers still go through the firewall like everyone else.
|
|
224
228
|
|
|
225
|
-
This separation exists so Better Auth admin-plugin powers (user management, impersonation) and DB-admin powers (cross-tenant data inspection) stay decoupled. A user can have `user.role === '
|
|
229
|
+
This separation exists so Better Auth admin-plugin powers (user management, impersonation, org creation) and DB-admin powers (cross-tenant data inspection) stay decoupled. A user can have `user.role === 'appmanager'` without DB-level cross-tenant access; a user can have `user.role === 'sysadmin'` without org-membership context. See [CMS Configuration](/compiler/config#cms-configuration) for the `cms.sysadmin` flag, the cross-tenant `/auth/v1/admin/list-organizations` endpoint, and the SPA's "All organizations" sentinel.
|
|
226
230
|
|
|
227
231
|
#### Mixing pseudo-roles with real roles
|
|
228
232
|
|
|
229
233
|
Pseudo-roles and lowercase real roles compose with OR:
|
|
230
234
|
|
|
231
235
|
```typescript
|
|
232
|
-
// Record owner OR a
|
|
233
|
-
read: { access: { roles: ["USER", "
|
|
236
|
+
// Record owner OR a platform control-plane user can read
|
|
237
|
+
read: { access: { or: [{ roles: ["USER"] }, { userRole: ["appmanager"] }] } }
|
|
234
238
|
|
|
235
|
-
// Org owner OR
|
|
236
|
-
delete: { access: { roles: ["owner", "
|
|
239
|
+
// Org owner OR sysadmin
|
|
240
|
+
delete: { access: { or: [{ roles: ["owner"] }, { roles: ["SYSADMIN"] }] } }
|
|
237
241
|
```
|
|
238
242
|
|
|
239
|
-
> Note:
|
|
243
|
+
> Note: `userRole: ["appmanager"]` never bypasses a `userId` firewall scope. If you need cross-user visibility, expose a separate route with `firewall: { exception: true }` or a `SYSADMIN`-gated cross-tenant surface.
|
|
240
244
|
|
|
241
245
|
#### Quick reference
|
|
242
246
|
|
|
@@ -250,8 +254,11 @@ access: { roles: ["AUTHENTICATED"] }
|
|
|
250
254
|
// Per-user records (requires userId firewall scope)
|
|
251
255
|
access: { roles: ["USER"] }
|
|
252
256
|
|
|
253
|
-
//
|
|
254
|
-
access: {
|
|
257
|
+
// Platform control-plane
|
|
258
|
+
access: { userRole: ["appmanager"] }
|
|
259
|
+
|
|
260
|
+
// Cross-tenant DB-admin tier
|
|
261
|
+
access: { roles: ["SYSADMIN"] }
|
|
255
262
|
|
|
256
263
|
// Org-membership roles with hierarchy expansion
|
|
257
264
|
access: { roles: ["member+"] } // expands to ["member", "admin", "owner"]
|
|
@@ -374,7 +381,7 @@ if (!ctx.activeTeamId) return c.json(AccessErrors.noTeam(), 403);
|
|
|
374
381
|
|
|
375
382
|
These ran **before** the relationship resolver, which 403'd attendees whose sessions don't carry an active tenant claim (the canonical event-attendee shape).
|
|
376
383
|
|
|
377
|
-
v0.20 makes these preconditions **conditional on relationship supply**. If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER /
|
|
384
|
+
v0.20 makes these preconditions **conditional on relationship supply**. If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / SYSADMIN) and `firewall: { exception: true }` still bypass the preconditions as before. `ADMIN` is now rejected at compile time.
|
|
378
385
|
|
|
379
386
|
Typical event-attendee setup (`guests` table carries `organizationId`): the org precondition is dropped on every action whose access references `attendee` or `eventStaff`. Org admins still get `ctx.activeOrgId` from their session as today; attendees get it from the relationship row, mid-request. Both paths converge on a valid tenant claim before `execute()` runs.
|
|
380
387
|
|
|
@@ -686,7 +686,7 @@ export default defineAction({
|
|
|
686
686
|
Unsafe cross-tenant actions are generated with:
|
|
687
687
|
|
|
688
688
|
- Better Auth authentication required (no unauthenticated path)
|
|
689
|
-
-
|
|
689
|
+
- sysadmin gate (`ctx.userRole === "sysadmin"`)
|
|
690
690
|
- mandatory audit logging on deny/success/error
|
|
691
691
|
|
|
692
692
|
`PUBLIC` actions also receive mandatory audit logging (same audit table), since unauthenticated endpoints are high-risk by nature.
|
|
@@ -269,7 +269,7 @@ The escape branch is **only** emitted when:
|
|
|
269
269
|
- The table has at least one tenant-scope predicate (org / owner / team / `via:` relationship). Tables with no tenant scopes already return what a sysadmin would see, so the runtime check would be dead code.
|
|
270
270
|
- The firewall does not declare `{ exception: true }` (no tenant scopes to drop).
|
|
271
271
|
|
|
272
|
-
**Sysadmin is distinct from
|
|
272
|
+
**Sysadmin is distinct from appmanager.** `userRole === 'appmanager'` callers still go through the firewall normally — only `userRole === 'sysadmin'` triggers the bypass. Appmanager is the platform control-plane tier, expressed with plain `userRole` checks; sysadmin is the opt-in cross-tenant DB-admin tier. See [CMS Configuration](/compiler/config#cms-configuration).
|
|
273
273
|
|
|
274
274
|
If your project doesn't set `cms.sysadmin: true`, the escape branch is never emitted and the role value is functionally inert.
|
|
275
275
|
|
|
@@ -71,7 +71,7 @@ Produces byte-identical output to the `feature()` form above — the compiler ex
|
|
|
71
71
|
A few mechanics to know:
|
|
72
72
|
|
|
73
73
|
- **Column names** default to snake_case of the JS key — `organizationId` ↔ `organization_id`, `salaryMin` ↔ `salary_min`. Pass a positional argument to override: `q.text('custom_name')`.
|
|
74
|
-
- **`q.id()`** emits `text('id').primaryKey()` with a
|
|
74
|
+
- **`q.id()`** emits `text('id').primaryKey()` with a provider-driven app-layer default.
|
|
75
75
|
- **`.required()` / `.optional()`** control NOT NULL. Chain before or after `.default(x)`.
|
|
76
76
|
- **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`.
|
|
77
77
|
- **Indexes:** column-level `.index()` or table-level `indexes` / `unique` as a third arg to `q.table(name, cols, { indexes, unique })`. With `feature()`, pass `indexes` and `unique` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts.
|
|
@@ -95,7 +95,13 @@ A few mechanics to know:
|
|
|
95
95
|
|
|
96
96
|
`q.url()` is `q.text()` plus `z.string().url()` at the validation edge, so `javascript:` / `data:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
|
|
97
97
|
|
|
98
|
-
`q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting
|
|
98
|
+
`q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting. This keeps q's output decoupled from any specific ID library.
|
|
99
|
+
|
|
100
|
+
For `generateId: "cuid"`, there is one important nuance: import-capable runtime
|
|
101
|
+
paths can emit real `createId()` usage, but compiler-managed schema
|
|
102
|
+
auto-injection may keep the same `createId()` call site and back it with a
|
|
103
|
+
file-local `crypto.randomUUID()` polyfill so schema-generation sandboxes do not
|
|
104
|
+
depend on project `node_modules`.
|
|
99
105
|
|
|
100
106
|
### q.scope() — tenant scope columns
|
|
101
107
|
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# Blog Template
|
|
2
2
|
|
|
3
|
-
The blog template creates a
|
|
3
|
+
The blog template creates a fixed-org backend for a blog or CMS, deployed to Cloudflare Workers with D1. Public visitors can read content without authentication, while admins manage posts through their membership in one pinned organization.
|
|
4
4
|
|
|
5
|
-
This template uses [
|
|
5
|
+
This template uses [pinned organization mode](/compiler/config/single-tenant). Organization support stays on, but the generated project hard-codes one organization id and hides org switching UI.
|
|
6
6
|
|
|
7
7
|
## Create the Project
|
|
8
8
|
|
|
@@ -16,7 +16,7 @@ This scaffolds a project with:
|
|
|
16
16
|
```
|
|
17
17
|
my-site/
|
|
18
18
|
├── quickback/
|
|
19
|
-
│ ├── quickback.config.ts #
|
|
19
|
+
│ ├── quickback.config.ts # Pinned-organization config
|
|
20
20
|
│ └── features/
|
|
21
21
|
│ └── posts/
|
|
22
22
|
│ ├── posts.ts # Schema + security (defineTable)
|
|
@@ -37,7 +37,7 @@ export default {
|
|
|
37
37
|
name: "my-site",
|
|
38
38
|
template: "hono",
|
|
39
39
|
features: {
|
|
40
|
-
|
|
40
|
+
pinnedOrganizationId: "org_replace_me",
|
|
41
41
|
},
|
|
42
42
|
providers: {
|
|
43
43
|
runtime: { name: "cloudflare", config: {} },
|
|
@@ -50,7 +50,7 @@ export default {
|
|
|
50
50
|
};
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
-
|
|
53
|
+
Replace `org_replace_me` with a real Better Auth organization id before deploying. Unlike the removed single-tenant mode, this template keeps the Better Auth organization plugin and resolves roles from membership in that pinned org. See [Pinned Organization Mode](/compiler/config/single-tenant) for details.
|
|
54
54
|
|
|
55
55
|
### Posts Feature (posts.ts)
|
|
56
56
|
|
|
@@ -91,7 +91,7 @@ export default defineTable(posts, {
|
|
|
91
91
|
```
|
|
92
92
|
|
|
93
93
|
- **`PUBLIC`** role on `read.access` means no authentication required for `GET /` and `GET /:id`
|
|
94
|
-
- **`admin`** role on `create`, `update`, and `delete` requires an authenticated user with `role
|
|
94
|
+
- **`admin`** role on `create`, `update`, and `delete` requires an authenticated user with `member.role === "admin"` in the pinned organization
|
|
95
95
|
- **`owner`** firewall scope tracks who created each post via `ownerId`
|
|
96
96
|
- **`softDelete`** marks posts as deleted rather than removing them from the database
|
|
97
97
|
|
|
@@ -270,7 +270,7 @@ npm run deploy
|
|
|
270
270
|
|
|
271
271
|
## Next Steps
|
|
272
272
|
|
|
273
|
-
- [
|
|
273
|
+
- [Pinned Organization Mode](/compiler/config/single-tenant) — How fixed-org mode works
|
|
274
274
|
- [Access Control](/compiler/definitions/access) — PUBLIC role and role-based permissions
|
|
275
275
|
- [Custom Actions](/compiler/definitions/actions) — Add business logic beyond CRUD
|
|
276
276
|
- [Cloudflare Template](/compiler/getting-started/template-cloudflare) — Multi-tenant alternative
|
|
@@ -33,9 +33,6 @@ my-app/
|
|
|
33
33
|
export default {
|
|
34
34
|
name: "my-app",
|
|
35
35
|
template: "hono",
|
|
36
|
-
features: {
|
|
37
|
-
organizations: true,
|
|
38
|
-
},
|
|
39
36
|
providers: {
|
|
40
37
|
runtime: { name: "cloudflare", config: {} },
|
|
41
38
|
database: {
|
|
@@ -47,7 +44,7 @@ export default {
|
|
|
47
44
|
};
|
|
48
45
|
```
|
|
49
46
|
|
|
50
|
-
|
|
47
|
+
Organization-backed auth is the default. If you want a fixed-org deployment with no org switching UI, add `features.pinnedOrganizationId` as described in [Pinned Organization Mode](/compiler/config/single-tenant).
|
|
51
48
|
|
|
52
49
|
## Adding Your First Feature
|
|
53
50
|
|
|
@@ -23,13 +23,13 @@ Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member
|
|
|
23
23
|
|
|
24
24
|
The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus actions and views in ~80 lines you can scan in five minutes.
|
|
25
25
|
|
|
26
|
-
###
|
|
26
|
+
### Fixed-org starter (free)
|
|
27
27
|
|
|
28
28
|
| Template | Includes | Command |
|
|
29
29
|
|----------|----------|---------|
|
|
30
|
-
| `blog` |
|
|
30
|
+
| `blog` | Blog with PUBLIC reads, admin writes, `publish` / `unpublish` actions, and a pinned organization id placeholder | `quickback create blog my-site` |
|
|
31
31
|
|
|
32
|
-
The **blog** template uses
|
|
32
|
+
The **blog** template uses [pinned organization mode](/compiler/config/single-tenant) and scaffolds `features.pinnedOrganizationId: "org_replace_me"`.
|
|
33
33
|
|
|
34
34
|
### Empty scaffold (free)
|
|
35
35
|
|
|
@@ -68,9 +68,9 @@ Best when you already know the conventions and want empty walls. Multi-tenant or
|
|
|
68
68
|
|
|
69
69
|
Best for learning by reading. Full multi-tenant security pillars, two actions, a named view (`/api/v1/todos/views/dashboard`), and field masking on the `description` column — all in a single ~80-line file you can copy-edit into your own table.
|
|
70
70
|
|
|
71
|
-
### Blog (
|
|
71
|
+
### Blog (pinned-organization CMS)
|
|
72
72
|
|
|
73
|
-
Best for personal sites, blogs, or any app
|
|
73
|
+
Best for personal sites, blogs, or any app that only needs one organization at runtime. Uses [pinned organization mode](/compiler/config/single-tenant) — organization support stays on, but the generated app hard-codes one org id and hides org switching.
|
|
74
74
|
|
|
75
75
|
- Public JSON API for content
|
|
76
76
|
- Admin-only editing
|
|
@@ -110,4 +110,4 @@ See the individual template guides for detailed setup:
|
|
|
110
110
|
- [Cloudflare Template](/compiler/getting-started/template-cloudflare)
|
|
111
111
|
- [Blog Template](/compiler/getting-started/template-blog)
|
|
112
112
|
- [Empty Scaffolding](/compiler/getting-started/template-empty)
|
|
113
|
-
- [
|
|
113
|
+
- [Pinned Organization Mode](/compiler/config/single-tenant)
|
|
@@ -131,7 +131,7 @@ execute: async ({ db, ctx, input }) => {
|
|
|
131
131
|
}
|
|
132
132
|
```
|
|
133
133
|
|
|
134
|
-
If you need unscoped access (for example, audited
|
|
134
|
+
If you need unscoped access (for example, audited cross-tenant sysadmin operations), declare `unsafe` on the action:
|
|
135
135
|
|
|
136
136
|
```typescript
|
|
137
137
|
adminReport: {
|
|
@@ -152,7 +152,7 @@ adminReport: {
|
|
|
152
152
|
Cross-tenant unsafe actions are generated with:
|
|
153
153
|
|
|
154
154
|
- Better Auth authentication required
|
|
155
|
-
-
|
|
155
|
+
- sysadmin gate (`ctx.userRole === 'sysadmin'`)
|
|
156
156
|
- mandatory audit logging on denial/success/error
|
|
157
157
|
|
|
158
158
|
Without unsafe mode, `unsafeDb` is `undefined`.
|
|
@@ -67,7 +67,7 @@ When both CMS and Account UI are enabled, the admin panel's profile page shows a
|
|
|
67
67
|
cms: { domain: "cms.example.com", access: "admin" },
|
|
68
68
|
```
|
|
69
69
|
|
|
70
|
-
With `access: "admin"`,
|
|
70
|
+
With `access: "admin"`, callers outside the platform control-plane roles can't access the CMS at any layer: the link is hidden in Account UI, the SPA shell returns `403` before serving `index.html`, `/api/v1/schema` returns `403`, and the `custom_view` CRUD is locked to `userRole: ["appmanager"]` (plus `sysadmin` when enabled). See [CMS Connecting](/stack/cms/connecting#restrict-cms-access-to-admin-users-only) for the full enforcement model.
|
|
71
71
|
|
|
72
72
|
## Related
|
|
73
73
|
|
|
@@ -196,7 +196,7 @@ ENABLE_ORGANIZATIONS=false
|
|
|
196
196
|
ENABLE_ADMIN=false
|
|
197
197
|
```
|
|
198
198
|
|
|
199
|
-
Simple email/password authentication for
|
|
199
|
+
Simple email/password authentication for apps that do not need advanced auth methods.
|
|
200
200
|
|
|
201
201
|
### Maximum Security
|
|
202
202
|
|
|
@@ -256,7 +256,7 @@ import { setAppConfig } from '@/config/app';
|
|
|
256
256
|
|
|
257
257
|
setAppConfig({
|
|
258
258
|
features: {
|
|
259
|
-
organizations: false, //
|
|
259
|
+
organizations: false, // Hide organization-management UI
|
|
260
260
|
passkey: true, // Enable passkey
|
|
261
261
|
},
|
|
262
262
|
});
|