@fabrika/app 0.9.0-dev.12 → 0.9.0-dev.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +9 -9
- package/skill/SKILL.md +6 -4
- package/skill/references/app-setup.md +8 -8
- package/skill/references/relations.md +558 -0
- package/skill/references/table-and-migration.md +14 -6
- package/src/contract/artifact-schema.ts +67 -0
- package/src/contract/build.ts +74 -2
- package/src/contract/compile.ts +1 -0
- package/src/contract/declaration.ts +4 -0
- package/src/contract/define.ts +11 -0
- package/src/contract/kit.ts +1 -0
- package/src/contract/platform.ts +1 -0
- package/src/contract/vocabulary.ts +3 -0
- package/src/implement/boot.ts +33 -2
- package/src/implement/capability.ts +19 -4
- package/src/implement/dispatch.ts +111 -10
- package/src/implement/implement.ts +7 -0
- package/src/testing/caller.ts +9 -2
- package/types/src/contract/declaration.d.ts +6 -0
- package/types/src/contract/define.d.ts +14 -0
- package/types/src/contract/vocabulary.d.ts +4 -1
- package/types/src/implement/capability.d.ts +4 -4
- package/types/src/implement/dispatch.d.ts +11 -0
- package/types/src/implement/implement.d.ts +7 -0
- package/types/src/testing/caller.d.ts +1 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fabrika/app",
|
|
3
|
-
"version": "0.9.0-dev.
|
|
3
|
+
"version": "0.9.0-dev.13",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -109,14 +109,14 @@
|
|
|
109
109
|
"test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
|
|
110
110
|
},
|
|
111
111
|
"dependencies": {
|
|
112
|
-
"@fabrika/auth": "0.9.0-dev.
|
|
113
|
-
"@fabrika/auth-core": "0.9.0-dev.
|
|
114
|
-
"@fabrika/db": "0.9.0-dev.
|
|
115
|
-
"@fabrika/email": "0.9.0-dev.
|
|
116
|
-
"@fabrika/jwks": "0.9.0-dev.
|
|
117
|
-
"@fabrika/platform": "0.9.0-dev.
|
|
118
|
-
"@fabrika/platform-node": "0.9.0-dev.
|
|
119
|
-
"@fabrika/proxy-core": "0.9.0-dev.
|
|
112
|
+
"@fabrika/auth": "0.9.0-dev.13",
|
|
113
|
+
"@fabrika/auth-core": "0.9.0-dev.13",
|
|
114
|
+
"@fabrika/db": "0.9.0-dev.13",
|
|
115
|
+
"@fabrika/email": "0.9.0-dev.13",
|
|
116
|
+
"@fabrika/jwks": "0.9.0-dev.13",
|
|
117
|
+
"@fabrika/platform": "0.9.0-dev.13",
|
|
118
|
+
"@fabrika/platform-node": "0.9.0-dev.13",
|
|
119
|
+
"@fabrika/proxy-core": "0.9.0-dev.13",
|
|
120
120
|
"altcha-lib": "2.6.0",
|
|
121
121
|
"jose": "^5.9.0"
|
|
122
122
|
},
|
package/skill/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: fabrika-app
|
|
3
|
-
version: 0.9.0-dev.
|
|
3
|
+
version: 0.9.0-dev.13
|
|
4
4
|
description: >
|
|
5
5
|
How to write and change a Fabrika application: src/vocabulary.ts, db/migrations/, src/db/tables.ts, the
|
|
6
6
|
slices' endpoints.ts with their handlers, fabrika.contract.ts, jobs, files, webhooks, share links, connectors
|
|
@@ -349,10 +349,12 @@ their errors, the caller, the components, routing, theming, screen tests), `tabl
|
|
|
349
349
|
`ctx.url`, a mount's `compatibility`, another origin, members and labels), `tests.md` (generated tests, seeds, `testKit`, a reused scope, a caller's label, confirming a file ran),
|
|
350
350
|
`errors.md` (checker findings, type errors, runtime answers), `dev.md` (the seed and the preview), `jobs.md` (which dimension `ctx.within` names, the UTC
|
|
351
351
|
day, queue tables and `claim`, e-mail through `ctx.mail` with attachments and unsubscribe, the outbox and `kicks`),
|
|
352
|
-
`files.md` and `webhooks-links-connectors.md`, all under `references/`.
|
|
352
|
+
`files.md` and `webhooks-links-connectors.md`, all under `references/`. Three are applications of their own:
|
|
353
353
|
`start.md`, a new application before its first table (its first test, adding the first table, installing and updating
|
|
354
|
-
this skill),
|
|
355
|
-
e-mails them, a link holder's files, HR's review with its history.
|
|
354
|
+
this skill), `public-intake.md`, a public page, public procedures, a job that claims their rows, issues links and
|
|
355
|
+
e-mails them, a link holder's files, HR's review with its history, and `relations.md`, access that rows of the
|
|
356
|
+
application grant and narrow (a relation, a role's `via`, a source table's `confers` and `assign`, a table's `when`
|
|
357
|
+
conditions, `readThrough`, `reveals` and `memberReveals`).
|
|
356
358
|
|
|
357
359
|
## Not built yet
|
|
358
360
|
|
|
@@ -19,20 +19,20 @@ the SPA is added with it.
|
|
|
19
19
|
"test": "bun test --isolate"
|
|
20
20
|
},
|
|
21
21
|
"dependencies": {
|
|
22
|
-
"@fabrika/app": "0.9.0-dev.
|
|
23
|
-
"@fabrika/db": "0.9.0-dev.
|
|
24
|
-
"@fabrika/provider-zerops": "0.9.0-dev.
|
|
25
|
-
"@fabrika/proxy-core": "0.9.0-dev.
|
|
26
|
-
"@fabrika/ui": "0.9.0-dev.
|
|
22
|
+
"@fabrika/app": "0.9.0-dev.13",
|
|
23
|
+
"@fabrika/db": "0.9.0-dev.13",
|
|
24
|
+
"@fabrika/provider-zerops": "0.9.0-dev.13",
|
|
25
|
+
"@fabrika/proxy-core": "0.9.0-dev.13",
|
|
26
|
+
"@fabrika/ui": "0.9.0-dev.13",
|
|
27
27
|
"kysely": "0.29.6",
|
|
28
28
|
"react": "^19.0.0",
|
|
29
29
|
"react-dom": "^19.0.0",
|
|
30
30
|
"zod": "^3.25.76"
|
|
31
31
|
},
|
|
32
32
|
"devDependencies": {
|
|
33
|
-
"@fabrika/check": "0.9.0-dev.
|
|
34
|
-
"@fabrika/cli": "0.9.0-dev.
|
|
35
|
-
"@fabrika/platform": "0.9.0-dev.
|
|
33
|
+
"@fabrika/check": "0.9.0-dev.13",
|
|
34
|
+
"@fabrika/cli": "0.9.0-dev.13",
|
|
35
|
+
"@fabrika/platform": "0.9.0-dev.13",
|
|
36
36
|
"@happy-dom/global-registrator": "^20.11.2",
|
|
37
37
|
"@types/bun": "^1.4.3",
|
|
38
38
|
"@types/react": "^19.0.0",
|
|
@@ -0,0 +1,558 @@
|
|
|
1
|
+
# references/relations.md — relation grants and conditions
|
|
2
|
+
|
|
3
|
+
A relation gives a role its actions at the nodes where a row of the application names the person: "the assistants of
|
|
4
|
+
this project, until their assignment ends". A condition (`when`) narrows an action to the rows it admits: "no task is
|
|
5
|
+
written in a project past its end". Both are declarations the approver reads; the data layer applies them to every
|
|
6
|
+
statement. This file is an application of its own (`tasks` with assistants); its `package.json`, `tsconfig.json`,
|
|
7
|
+
`src/app-kit.ts`, `src/app.ts` and `src/schemas.ts` are those of `app-setup.md` and `endpoint.md`.
|
|
8
|
+
|
|
9
|
+
Ask the human before you add a relation, a role's `via`, a table's `confers` or its `assign`: each lets someone reach
|
|
10
|
+
more, and the approver sees each as a widening. A `when` only narrows; removing or changing one widens. They need
|
|
11
|
+
`@fabrika/app` `0.9.0-dev.13` or later: Control refuses to publish them for an application pinned to an earlier release.
|
|
12
|
+
|
|
13
|
+
## The vocabulary: a relation and a role's `via`
|
|
14
|
+
|
|
15
|
+
```ts src/vocabulary.ts
|
|
16
|
+
import { defineVocabulary } from '@fabrika/app/contract'
|
|
17
|
+
|
|
18
|
+
export const vocabulary = defineVocabulary({
|
|
19
|
+
app: 'tasks',
|
|
20
|
+
dimensions: {
|
|
21
|
+
org: { members: { manage: 'members.manage', list: 'tasks.read' } },
|
|
22
|
+
project: { in: 'org' },
|
|
23
|
+
task: { in: 'project' },
|
|
24
|
+
},
|
|
25
|
+
actions: {
|
|
26
|
+
'tasks.read': 'Read projects and tasks',
|
|
27
|
+
'tasks.write': 'Create projects and tasks, and finish tasks',
|
|
28
|
+
'assistants.assign': 'Assign an assistant to a project',
|
|
29
|
+
'members.manage': 'Invite and remove members',
|
|
30
|
+
},
|
|
31
|
+
relations: {
|
|
32
|
+
assisting: { dimension: 'project' },
|
|
33
|
+
},
|
|
34
|
+
roles: {
|
|
35
|
+
owner: {
|
|
36
|
+
grants: ['tasks.read', 'tasks.write', 'assistants.assign', 'members.manage'],
|
|
37
|
+
member: { scope: 'org', assignableBy: ['owner'] },
|
|
38
|
+
},
|
|
39
|
+
coordinator: {
|
|
40
|
+
grants: ['tasks.read', 'assistants.assign'],
|
|
41
|
+
member: { scope: 'org', assignableBy: ['owner'] },
|
|
42
|
+
},
|
|
43
|
+
assistant: {
|
|
44
|
+
grants: [],
|
|
45
|
+
via: { assisting: ['tasks.read', 'tasks.write'] },
|
|
46
|
+
},
|
|
47
|
+
},
|
|
48
|
+
})
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
- `relations: { <name>: { dimension } }` names a relation and the dimension of the node its rows name.
|
|
52
|
+
- `via: { <relation>: [<action>, …] }` on a role: a holder of the role holds those actions at each node where a source
|
|
53
|
+
row names them, and nowhere else. Its `grants` still hold globally, so an assistant's are empty.
|
|
54
|
+
- `via` is only for a global, internal role without `member`: IAM grants `assistant` application-wide (an operator,
|
|
55
|
+
in IAM's console), and the rows say where it applies. A grant of the role in a scope value carries no relation, so
|
|
56
|
+
the proxy refuses its holder (403). A person from outside the organization (`external: true`) holds no relation.
|
|
57
|
+
- The token says only that the role holds those actions through `assisting`. The data layer reads the source rows on
|
|
58
|
+
every statement, so an inserted row grants at the next request and a deleted one stops access at the next request.
|
|
59
|
+
Nothing caches it.
|
|
60
|
+
- A principal a row names reaches nothing unless IAM grants it a role whose `via` names the relation.
|
|
61
|
+
|
|
62
|
+
## The migration
|
|
63
|
+
|
|
64
|
+
```sql db/migrations/20261104090000_assistants.sql
|
|
65
|
+
CREATE TABLE projects (
|
|
66
|
+
id UUID PRIMARY KEY,
|
|
67
|
+
org_id TEXT NOT NULL,
|
|
68
|
+
name TEXT NOT NULL,
|
|
69
|
+
ends_at TIMESTAMPTZ,
|
|
70
|
+
created_by TEXT NOT NULL,
|
|
71
|
+
version INTEGER NOT NULL,
|
|
72
|
+
UNIQUE (id, org_id)
|
|
73
|
+
);
|
|
74
|
+
CREATE INDEX projects_org ON projects (org_id);
|
|
75
|
+
|
|
76
|
+
-- A condition's path follows a single-column foreign key: project_id carries one beside the composite key.
|
|
77
|
+
CREATE TABLE tasks (
|
|
78
|
+
id UUID PRIMARY KEY,
|
|
79
|
+
project_id UUID NOT NULL REFERENCES projects (id),
|
|
80
|
+
org_id TEXT NOT NULL,
|
|
81
|
+
title TEXT NOT NULL,
|
|
82
|
+
done BOOLEAN NOT NULL DEFAULT false,
|
|
83
|
+
created_by TEXT NOT NULL,
|
|
84
|
+
version INTEGER NOT NULL,
|
|
85
|
+
FOREIGN KEY (project_id, org_id) REFERENCES projects (id, org_id) ON UPDATE CASCADE
|
|
86
|
+
);
|
|
87
|
+
CREATE INDEX tasks_project ON tasks (project_id);
|
|
88
|
+
|
|
89
|
+
-- A relation source: each row names one principal at one project until it expires.
|
|
90
|
+
CREATE TABLE project_assistants (
|
|
91
|
+
id UUID PRIMARY KEY,
|
|
92
|
+
project_id UUID NOT NULL,
|
|
93
|
+
org_id TEXT NOT NULL,
|
|
94
|
+
principal_id TEXT NOT NULL,
|
|
95
|
+
expires_at TIMESTAMPTZ NOT NULL,
|
|
96
|
+
created_by TEXT NOT NULL,
|
|
97
|
+
FOREIGN KEY (project_id, org_id) REFERENCES projects (id, org_id) ON UPDATE CASCADE ON DELETE CASCADE
|
|
98
|
+
);
|
|
99
|
+
CREATE INDEX project_assistants_principal ON project_assistants (principal_id, project_id);
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
- A source table is an ordinary child or dimension table with a principal column (`TEXT`, an IAM principal id), the
|
|
103
|
+
node column (by default the table's column of the relation's dimension: `project_id`) and, for a bounded
|
|
104
|
+
delegation, an expiry (`TIMESTAMPTZ NOT NULL`).
|
|
105
|
+
- Give it an index on `(principal, node)`. Every statement under the relation runs
|
|
106
|
+
`node in (select node from <source> where principal = $me …)`, and nothing creates the index for you.
|
|
107
|
+
- After the migration run `fabrika db migrate` and `fabrika db codegen` (on Cloudflare `codegen` only): the policies
|
|
108
|
+
below read the generated `columns`, its foreign keys and which columns are `NOT NULL`.
|
|
109
|
+
|
|
110
|
+
## The policies
|
|
111
|
+
|
|
112
|
+
```ts src/db/tables.ts
|
|
113
|
+
import { defineTables } from '@fabrika/db/tables'
|
|
114
|
+
import { vocabulary } from '../vocabulary'
|
|
115
|
+
import { columns } from './schema.generated'
|
|
116
|
+
|
|
117
|
+
export const tables = defineTables(vocabulary, columns)({
|
|
118
|
+
projects: {
|
|
119
|
+
scope: { dimension: 'project' },
|
|
120
|
+
actions: { read: 'tasks.read', insert: 'tasks.write' },
|
|
121
|
+
insert: ['name', 'ends_at'],
|
|
122
|
+
version: 'version',
|
|
123
|
+
createdBy: 'created_by',
|
|
124
|
+
},
|
|
125
|
+
tasks: {
|
|
126
|
+
scope: { dimension: 'task' },
|
|
127
|
+
actions: { read: 'tasks.read', insert: 'tasks.write', update: 'tasks.write' },
|
|
128
|
+
insert: ['title'],
|
|
129
|
+
update: ['done'],
|
|
130
|
+
version: 'version',
|
|
131
|
+
createdBy: 'created_by',
|
|
132
|
+
when: {
|
|
133
|
+
'tasks.write': {
|
|
134
|
+
anyOf: [
|
|
135
|
+
{ 'project_id.ends_at': { isNull: true } },
|
|
136
|
+
{ 'project_id.ends_at': { gt: { now: true } } },
|
|
137
|
+
],
|
|
138
|
+
},
|
|
139
|
+
},
|
|
140
|
+
},
|
|
141
|
+
project_assistants: {
|
|
142
|
+
scope: { child: 'projects' },
|
|
143
|
+
actions: {
|
|
144
|
+
read: 'tasks.read',
|
|
145
|
+
insert: 'assistants.assign',
|
|
146
|
+
delete: 'assistants.assign',
|
|
147
|
+
},
|
|
148
|
+
insert: ['principal_id', 'expires_at'],
|
|
149
|
+
createdBy: 'created_by',
|
|
150
|
+
confers: {
|
|
151
|
+
assisting: {
|
|
152
|
+
principal: 'principal_id',
|
|
153
|
+
expires: 'expires_at',
|
|
154
|
+
assign: { maxDays: 30 },
|
|
155
|
+
},
|
|
156
|
+
},
|
|
157
|
+
},
|
|
158
|
+
})
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### `confers`: the rows that grant a relation
|
|
162
|
+
|
|
163
|
+
- `confers: { <relation>: { principal, node?, expires?, when?, assign? } }`. `node` defaults to the table's column of
|
|
164
|
+
the relation's dimension. A row confers nothing once `expires` passed, nor while its own `when` does not admit it.
|
|
165
|
+
A source's `when` never reads its `version`. It may follow one foreign key to the row the source names, such as
|
|
166
|
+
`{ 'person_id.active': { eq: true } }`, the far side of a many-to-many table: no update of that table may write the
|
|
167
|
+
column it tests, and the table is no view, queue or top-level dimension table. It takes no second foreign key and no
|
|
168
|
+
`some`. That table joins the source table among those `ctx.sql` of a writing endpoint never names, so a writing
|
|
169
|
+
statement that already names it fails at run time once the condition is added: move that write to `ctx.db` first.
|
|
170
|
+
- Inserting a row is delegation: the coordinator gives the assistant `tasks.read` and `tasks.write` without holding
|
|
171
|
+
`tasks.write` itself. The insert's own action (`assistants.assign`) decides who may write it, and the layer bounds
|
|
172
|
+
what it gives instead:
|
|
173
|
+
- the node is stamped from the writer's `Ref`, so a coordinator delegates only in a project it reaches;
|
|
174
|
+
- `assign.maxDays` caps the expiry; a later or a missing expiry is a 409, and `maxDays` needs `expires`;
|
|
175
|
+
- a row naming its writer is a 409 unless `assign.self: true` allows it. `principal` may name the table's
|
|
176
|
+
`createdBy`: then every row names its writer at the row's node. On `projects`, a relation at `project` makes a
|
|
177
|
+
creator hold it at that project, and one at `org` at the project's org; on a child table such as
|
|
178
|
+
`project_assistants` the writer holds it at the parent project, not at the row. So a table with an insert states
|
|
179
|
+
`assign: { self: true }`, and the policy is refused without it;
|
|
180
|
+
- a table that confers without `assign` takes no insert.
|
|
181
|
+
- `principal` may be read through one foreign key, `'<column>.<principal column>'`: `principal: 'person_id.principal_id'`
|
|
182
|
+
on a staff row that names a person of a directory table, whose own row holds the principal id. `<column>` needs a
|
|
183
|
+
single-column `REFERENCES <table> (id)` to the key of a contained dimension, child or application table (no view, no
|
|
184
|
+
queue table, no top-level dimension), and is not the source's own key, version, file or containment column (an
|
|
185
|
+
`org_id` a move rewrites). No other foreign key holds that column, but a composite one to the same row, such as
|
|
186
|
+
`(person_id, org_id) REFERENCES people (id, org_id)`, and the referenced table's key references nothing. No update of that table may write the principal column, so a person row is replaced, never edited:
|
|
187
|
+
deleting it, or the source row, ends the access at the next request. A row whose person names its writer is a 409
|
|
188
|
+
without `assign.self`, as above. The foreign key needs only the referenced table's key, not a key that holds the
|
|
189
|
+
tenant: a writer may name a person of another organization, which gives no more than naming that principal id
|
|
190
|
+
directly. Index the referenced table on `(principal column, id)` too.
|
|
191
|
+
- A column that holds a principal, on the source or on the table a path reads, has no `REFERENCES`: a key that
|
|
192
|
+
cascades on update would change whom every row names.
|
|
193
|
+
- A source row never moves, and no update writes its principal, node, expiry or a column its `when` reads. Change an
|
|
194
|
+
assignment by deleting the row and inserting a new one. `ctx.sql` of a writing endpoint never names a source table,
|
|
195
|
+
`unscoped` never writes one, and a queue table confers nothing.
|
|
196
|
+
|
|
197
|
+
### `when`: a condition narrows an action
|
|
198
|
+
|
|
199
|
+
- `when: { <action>: <condition> }` is ANDed onto every grant of that action on the table: global, IAM-scoped and
|
|
200
|
+
through a relation alike. The owner cannot add a task to a project past its end either. A row the condition does
|
|
201
|
+
not admit is not there for that action: a read or an update `on` it is 404, a list leaves it out, and an insert
|
|
202
|
+
it refuses is a 409 with nothing written.
|
|
203
|
+
- A condition is data, never SQL: `{ <column>: { <operator>: <value> } }` with `eq`, `notEq`, `in`, `notIn`,
|
|
204
|
+
`isNull`, `lt`, `lte`, `gt` and `gte`; several columns in one object must all hold; `allOf`, `anyOf` and `not` stand
|
|
205
|
+
alone in their object. `{ now: true }` is the statement's clock (`{ gt: { now: true } }`), never the text `now`. A
|
|
206
|
+
JSON column is never compared: extract the value into a typed column.
|
|
207
|
+
- A path follows foreign keys: `'project_id.ends_at'` reads the task's project. The column needs a single-column
|
|
208
|
+
`REFERENCES <table> (id)`, and the hop must stay in the row's tenant: the row's own container or parent column, a
|
|
209
|
+
key into a reference table, or a key that holds every ancestor the two tables share (below). A view's path starts at
|
|
210
|
+
its parent column, which needs no foreign key.
|
|
211
|
+
- `{ some: { <table>: <condition> } }` holds when a row of `<table>` whose single-column foreign key names this row
|
|
212
|
+
meets the condition, `none` when no such row does: on `projects`, `{ some: { tasks: { done: { eq: false } } } }` is
|
|
213
|
+
a project with an open task. The rows' foreign key is held like a path's hop, so it keeps to the row's tenant, and
|
|
214
|
+
a key into a reference table is not followed back: `{ tag_id: { some: { project_tags: … } } }` would count every
|
|
215
|
+
tenant's rows that name the tag, so the policy refuses it.
|
|
216
|
+
- A path may end in `some` or `none`: on `tasks`, `{ project_id: { some: { project_tags: { 'tag_id.name': { eq:
|
|
217
|
+
'urgent' } } } } }` is a task of a project tagged urgent, through the link table `project_tags`. A `null` foreign key
|
|
218
|
+
reaches no row, so neither `some` nor `none` holds there. A `some` nests in a `some`.
|
|
219
|
+
- A `not` follows a path only through columns declared `NOT NULL`, at any depth: on a null key the path's lookup
|
|
220
|
+
would turn on rows of every tenant. `{ not: { 'client_id.active': { eq: true } } }` with a nullable `client_id` is
|
|
221
|
+
refused and names the column: declare it `NOT NULL` in a migration and run `fabrika db codegen`, or say what a row
|
|
222
|
+
without a client gets, `{ anyOf: [{ client_id: { isNull: true } }, { 'client_id.active': { eq: false } }] }`. Like
|
|
223
|
+
the `not`, it leaves out a row whose client's `active` is null.
|
|
224
|
+
- A path follows at most three foreign keys, the path before a `some`, the `some` and every hop inside it counted
|
|
225
|
+
together. Each hop is one more subquery in every statement of the action; shorten a longer path with a stored column.
|
|
226
|
+
- An insert's condition is judged on the written row. One with a path runs in the insert's transaction, every row on
|
|
227
|
+
its paths locked `FOR SHARE` first, so nobody changes the project while the task goes in. An insert action's
|
|
228
|
+
condition may end a path in `some` (`{ project_id: { some: … } }`), whose rows are locked too. It takes no `none`,
|
|
229
|
+
no `some` under `not`, no `some` straight on the inserted row, and no `some` of the inserted table's own rows
|
|
230
|
+
(`{ project_id: { some: { tasks: … } } }` on `tasks`): a row inserted meanwhile could make the first two false,
|
|
231
|
+
nothing names the new row yet, and the last would count the new task itself, since the condition is judged after
|
|
232
|
+
the write. An upsert's conflict update is judged on the stored row.
|
|
233
|
+
|
|
234
|
+
### A key that holds the tenant needs its ancestors NOT NULL
|
|
235
|
+
|
|
236
|
+
A path into another scoped table, other than the container or parent, and a `readThrough` follow a foreign key of
|
|
237
|
+
exactly the column and every ancestor the two tables share, `(team_id, org_id) REFERENCES teams (id, org_id)`, beside
|
|
238
|
+
the column's single-column key. Each ancestor column of that key must be `NOT NULL`: under SQL's matching a null
|
|
239
|
+
`org_id` skips the whole key, so a row written with one could point at another org's team. A policy over a nullable
|
|
240
|
+
one is refused and names the column: add a migration that sets it `NOT NULL`, then run `fabrika db migrate` and
|
|
241
|
+
`fabrika db codegen`, which writes the `notNull` list the policy is checked against.
|
|
242
|
+
|
|
243
|
+
### `readThrough`, `reveals` and `memberReveals`
|
|
244
|
+
|
|
245
|
+
- `readThrough: { <dimension>: <column> }` lets a `Within` of a dimension outside the table's chain, or a relation at
|
|
246
|
+
it, read the row through that column's tenant-holding key: a task in a project, read by the members of the team its
|
|
247
|
+
`team_id` names. Every write still follows the task's containment, and no update writes the column. When the key
|
|
248
|
+
lives on the row's container, name the container's path from the row's own containment column:
|
|
249
|
+
`readThrough: { team: 'task_id.team_id' }` on a task's comments. The container declares `readThrough.team` through
|
|
250
|
+
a column of its own; the row follows it wherever the container's column points now. Such a table takes no reveal
|
|
251
|
+
matched through that path: declare the reveal on the container.
|
|
252
|
+
- `reveals: { <relation>: { to, actions, when? } }` on a table the relation reaches: such a row also gives the
|
|
253
|
+
relation `actions` (those its roles name in `via`) at its ancestor node in `to` while `when` admits the row: an
|
|
254
|
+
assignee of an open task reads its project. A reveal matched through `readThrough` on a table with an insert needs
|
|
255
|
+
`assign: {}` (or `{ self: true }`), because the writer picks the node.
|
|
256
|
+
- `memberReveals: { <own dimension>: { to, actions, when? } }`: a grant at the row's own node holds `actions` at its
|
|
257
|
+
ancestor in `to` too, for an `over` list's reads. Such a row is never written unscoped or by `ctx.sql`, and never
|
|
258
|
+
moves.
|
|
259
|
+
- A view under a parent takes none of them: it is read through its parent row, so a relation, a reveal, a member
|
|
260
|
+
reveal or a secondary path that reaches the parent reaches the view's rows of that parent.
|
|
261
|
+
|
|
262
|
+
## The endpoints
|
|
263
|
+
|
|
264
|
+
```ts src/projects/endpoints.ts
|
|
265
|
+
import { z } from 'zod/v4'
|
|
266
|
+
import { app } from '../app-kit'
|
|
267
|
+
import { Saved } from '../schemas'
|
|
268
|
+
|
|
269
|
+
const DAY_MS = 86_400_000
|
|
270
|
+
const NewProject = z.strictObject({
|
|
271
|
+
orgId: z.string().min(1).max(100),
|
|
272
|
+
name: z.string().min(1).max(200),
|
|
273
|
+
endsAt: z.iso.datetime().optional(),
|
|
274
|
+
})
|
|
275
|
+
const Assign = z.strictObject({
|
|
276
|
+
id: z.uuid(),
|
|
277
|
+
assistant: z.string().min(1).max(200),
|
|
278
|
+
days: z.int().min(1).max(30),
|
|
279
|
+
})
|
|
280
|
+
const Unassign = z.strictObject({ id: z.uuid(), assignment: z.uuid() })
|
|
281
|
+
const Assignment = z.strictObject({ id: z.uuid() })
|
|
282
|
+
|
|
283
|
+
export const projects = app.group({ callers: ['human'] }, (r) => ({
|
|
284
|
+
create: r.mutation({
|
|
285
|
+
input: NewProject,
|
|
286
|
+
output: Saved,
|
|
287
|
+
access: { action: 'tasks.write', in: 'org', from: 'orgId' },
|
|
288
|
+
})
|
|
289
|
+
.handle(({ input, ctx }) =>
|
|
290
|
+
ctx.db.target.projects.insert({
|
|
291
|
+
name: input.name,
|
|
292
|
+
ends_at: input.endsAt ?? null,
|
|
293
|
+
})
|
|
294
|
+
),
|
|
295
|
+
assign: r.mutation({
|
|
296
|
+
input: Assign,
|
|
297
|
+
output: Assignment,
|
|
298
|
+
access: { action: 'assistants.assign', on: 'project', from: 'id' },
|
|
299
|
+
})
|
|
300
|
+
.handle(({ input, ctx }) =>
|
|
301
|
+
ctx.db.target.project_assistants.insert({
|
|
302
|
+
principal_id: input.assistant,
|
|
303
|
+
expires_at: new Date(Date.now() + input.days * DAY_MS),
|
|
304
|
+
})
|
|
305
|
+
),
|
|
306
|
+
unassign: r.mutation({
|
|
307
|
+
input: Unassign,
|
|
308
|
+
output: Assignment,
|
|
309
|
+
access: { action: 'assistants.assign', on: 'project', from: 'id' },
|
|
310
|
+
})
|
|
311
|
+
.handle(async ({ input, ctx }) => {
|
|
312
|
+
await ctx.db.target.project_assistants.remove(input.assignment)
|
|
313
|
+
return { id: input.assignment }
|
|
314
|
+
}),
|
|
315
|
+
}))
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
```ts src/tasks/endpoints.ts
|
|
319
|
+
import { fromPage } from '@fabrika/app'
|
|
320
|
+
import { z } from 'zod/v4'
|
|
321
|
+
import { app } from '../app-kit'
|
|
322
|
+
import { Cursor, Saved, Versioned } from '../schemas'
|
|
323
|
+
|
|
324
|
+
const Task = z.strictObject({
|
|
325
|
+
id: z.uuid(),
|
|
326
|
+
title: z.string(),
|
|
327
|
+
done: z.boolean(),
|
|
328
|
+
version: z.int(),
|
|
329
|
+
})
|
|
330
|
+
const TaskPage = z.strictObject({
|
|
331
|
+
items: z.array(Task),
|
|
332
|
+
next: z.nullable(z.string()),
|
|
333
|
+
})
|
|
334
|
+
const ListTasks = z.strictObject({
|
|
335
|
+
projectId: z.uuid(),
|
|
336
|
+
after: Cursor.optional(),
|
|
337
|
+
})
|
|
338
|
+
const MyTasks = z.strictObject({ after: Cursor.optional() })
|
|
339
|
+
const NewTask = z.strictObject({
|
|
340
|
+
projectId: z.uuid(),
|
|
341
|
+
title: z.string().min(1).max(200),
|
|
342
|
+
})
|
|
343
|
+
|
|
344
|
+
export const tasks = app.group({ callers: ['human'] }, (r) => ({
|
|
345
|
+
list: r.query({
|
|
346
|
+
input: ListTasks,
|
|
347
|
+
output: TaskPage,
|
|
348
|
+
access: { action: 'tasks.read', in: 'project', from: 'projectId' },
|
|
349
|
+
})
|
|
350
|
+
.handle(async ({ input, ctx }) =>
|
|
351
|
+
fromPage(
|
|
352
|
+
Task,
|
|
353
|
+
await ctx.db.target.tasks.list({
|
|
354
|
+
orderBy: [['title', 'asc']],
|
|
355
|
+
after: input.after,
|
|
356
|
+
}),
|
|
357
|
+
)
|
|
358
|
+
),
|
|
359
|
+
mine: r.query({
|
|
360
|
+
input: MyTasks,
|
|
361
|
+
output: TaskPage,
|
|
362
|
+
access: { action: 'tasks.read', over: 'project' },
|
|
363
|
+
})
|
|
364
|
+
.handle(async ({ input, ctx }) =>
|
|
365
|
+
fromPage(
|
|
366
|
+
Task,
|
|
367
|
+
await ctx.db.within.tasks.list({
|
|
368
|
+
where: [['done', '=', false]],
|
|
369
|
+
orderBy: [['title', 'asc']],
|
|
370
|
+
after: input.after,
|
|
371
|
+
}),
|
|
372
|
+
)
|
|
373
|
+
),
|
|
374
|
+
create: r.mutation({
|
|
375
|
+
input: NewTask,
|
|
376
|
+
output: Saved,
|
|
377
|
+
access: { action: 'tasks.write', in: 'project', from: 'projectId' },
|
|
378
|
+
})
|
|
379
|
+
.handle(({ input, ctx }) =>
|
|
380
|
+
ctx.db.target.tasks.insert({ title: input.title })
|
|
381
|
+
),
|
|
382
|
+
finish: r.mutation({
|
|
383
|
+
input: Versioned,
|
|
384
|
+
output: Saved,
|
|
385
|
+
access: { action: 'tasks.write', on: 'task', from: 'id' },
|
|
386
|
+
})
|
|
387
|
+
.handle(({ input, ctx }) =>
|
|
388
|
+
ctx.db.target.update({ done: true }, {
|
|
389
|
+
expectVersion: input.expectVersion,
|
|
390
|
+
})
|
|
391
|
+
),
|
|
392
|
+
}))
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
```ts fabrika.contract.ts
|
|
396
|
+
import { app } from './src/app-kit'
|
|
397
|
+
import { projects } from './src/projects/endpoints'
|
|
398
|
+
import { tasks } from './src/tasks/endpoints'
|
|
399
|
+
|
|
400
|
+
export const contract = app.contract((c) => ({
|
|
401
|
+
api: c.rpc('/api', { projects, tasks }),
|
|
402
|
+
health: c.health('/healthz'),
|
|
403
|
+
}))
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
- The handlers know nothing of relations. An assistant's `on`, `in` and `over` calls reach a project and its tasks
|
|
407
|
+
exactly while a row names it there. Elsewhere an `on` call is 404, an `in` call 403 and an `over` list leaves the
|
|
408
|
+
project out, as for any caller without the action there.
|
|
409
|
+
- `assign` takes the assistant's principal id from the input: that is the person picked, never the caller. `days`
|
|
410
|
+
stops at the policy's `maxDays`, so of the layer's bounds only the writer naming itself answers 409.
|
|
411
|
+
|
|
412
|
+
## Tests
|
|
413
|
+
|
|
414
|
+
Grant the role app-wide (`{ role: 'assistant' }`, no scope), as IAM does, and let the endpoints write the rows:
|
|
415
|
+
|
|
416
|
+
```ts src/__tests__/assistants.test.ts
|
|
417
|
+
import { createClient } from '@fabrika/app/client'
|
|
418
|
+
import { statusOf, testKit } from '@fabrika/app/testing'
|
|
419
|
+
import { testDatabase } from '@fabrika/db/testing'
|
|
420
|
+
import { afterAll, describe, expect, test } from 'bun:test'
|
|
421
|
+
import { contract } from '../../fabrika.contract'
|
|
422
|
+
import app from '../app'
|
|
423
|
+
|
|
424
|
+
const postgres = await testDatabase({
|
|
425
|
+
migrations: new URL('../../db/migrations/', import.meta.url),
|
|
426
|
+
label: 'assistants.test.ts',
|
|
427
|
+
})
|
|
428
|
+
|
|
429
|
+
if (postgres !== null) {
|
|
430
|
+
afterAll(() => postgres.close())
|
|
431
|
+
const kit = testKit(app, { database: postgres.database })
|
|
432
|
+
const acme = kit.scope('org', 'acme')
|
|
433
|
+
const assistant = kit.testCaller([{ role: 'assistant' }])
|
|
434
|
+
const coordinator = kit.testCaller([{ role: 'coordinator', scope: acme }])
|
|
435
|
+
const ownerApi = createClient(contract, 'api', {
|
|
436
|
+
fetch: kit.browser(kit.testCaller([{ role: 'owner', scope: acme }])),
|
|
437
|
+
})
|
|
438
|
+
const coordinatorApi = createClient(contract, 'api', {
|
|
439
|
+
fetch: kit.browser(coordinator),
|
|
440
|
+
})
|
|
441
|
+
const assistantApi = createClient(contract, 'api', {
|
|
442
|
+
fetch: kit.browser(assistant),
|
|
443
|
+
})
|
|
444
|
+
|
|
445
|
+
describe('an assistant', () => {
|
|
446
|
+
test('reaches a project only while a row names it there', async () => {
|
|
447
|
+
const launch = await ownerApi.projects.create({
|
|
448
|
+
orgId: 'acme',
|
|
449
|
+
name: 'Launch',
|
|
450
|
+
})
|
|
451
|
+
const other = await ownerApi.projects.create({
|
|
452
|
+
orgId: 'acme',
|
|
453
|
+
name: 'Other',
|
|
454
|
+
})
|
|
455
|
+
expect(await statusOf(assistantApi.tasks.list({ projectId: launch.id })))
|
|
456
|
+
.toBe(403)
|
|
457
|
+
const assignment = await coordinatorApi.projects.assign({
|
|
458
|
+
id: launch.id,
|
|
459
|
+
assistant: assistant.id,
|
|
460
|
+
days: 7,
|
|
461
|
+
})
|
|
462
|
+
const task = await assistantApi.tasks.create({
|
|
463
|
+
projectId: launch.id,
|
|
464
|
+
title: 'Brief',
|
|
465
|
+
})
|
|
466
|
+
expect((await assistantApi.tasks.mine({})).items.map((item) => item.id))
|
|
467
|
+
.toEqual([task.id])
|
|
468
|
+
expect(await assistantApi.tasks.finish({ id: task.id, expectVersion: 1 }))
|
|
469
|
+
.toEqual({ id: task.id, version: 2 })
|
|
470
|
+
expect(
|
|
471
|
+
await statusOf(
|
|
472
|
+
assistantApi.tasks.create({ projectId: other.id, title: 'No' }),
|
|
473
|
+
),
|
|
474
|
+
).toBe(403)
|
|
475
|
+
await coordinatorApi.projects.unassign({
|
|
476
|
+
id: launch.id,
|
|
477
|
+
assignment: assignment.id,
|
|
478
|
+
})
|
|
479
|
+
expect(
|
|
480
|
+
await statusOf(
|
|
481
|
+
assistantApi.tasks.finish({ id: task.id, expectVersion: 2 }),
|
|
482
|
+
),
|
|
483
|
+
).toBe(404)
|
|
484
|
+
expect((await assistantApi.tasks.mine({})).items).toEqual([])
|
|
485
|
+
})
|
|
486
|
+
|
|
487
|
+
test('a coordinator does not assign itself', async () => {
|
|
488
|
+
const project = await ownerApi.projects.create({
|
|
489
|
+
orgId: 'acme',
|
|
490
|
+
name: 'Self',
|
|
491
|
+
})
|
|
492
|
+
expect(
|
|
493
|
+
await statusOf(coordinatorApi.projects.assign({
|
|
494
|
+
id: project.id,
|
|
495
|
+
assistant: coordinator.id,
|
|
496
|
+
days: 1,
|
|
497
|
+
})),
|
|
498
|
+
).toBe(409)
|
|
499
|
+
})
|
|
500
|
+
|
|
501
|
+
test('a grant of the role in a scope value reaches nothing through the relation', async () => {
|
|
502
|
+
const project = await ownerApi.projects.create({
|
|
503
|
+
orgId: 'acme',
|
|
504
|
+
name: 'Scoped',
|
|
505
|
+
})
|
|
506
|
+
const scoped = kit.testCaller([{ role: 'assistant', scope: acme }])
|
|
507
|
+
await coordinatorApi.projects.assign({
|
|
508
|
+
id: project.id,
|
|
509
|
+
assistant: scoped.id,
|
|
510
|
+
days: 1,
|
|
511
|
+
})
|
|
512
|
+
const scopedApi = createClient(contract, 'api', {
|
|
513
|
+
fetch: kit.browser(scoped),
|
|
514
|
+
})
|
|
515
|
+
expect(await statusOf(scopedApi.tasks.list({ projectId: project.id }))).toBe(
|
|
516
|
+
403,
|
|
517
|
+
)
|
|
518
|
+
})
|
|
519
|
+
})
|
|
520
|
+
|
|
521
|
+
describe('a project past its end', () => {
|
|
522
|
+
test('is read, and takes no new task from anyone', async () => {
|
|
523
|
+
const ended = await ownerApi.projects.create({
|
|
524
|
+
orgId: 'acme',
|
|
525
|
+
name: 'Ended',
|
|
526
|
+
endsAt: '2026-01-01T00:00:00Z',
|
|
527
|
+
})
|
|
528
|
+
await coordinatorApi.projects.assign({
|
|
529
|
+
id: ended.id,
|
|
530
|
+
assistant: assistant.id,
|
|
531
|
+
days: 7,
|
|
532
|
+
})
|
|
533
|
+
expect((await assistantApi.tasks.list({ projectId: ended.id })).items)
|
|
534
|
+
.toEqual([])
|
|
535
|
+
expect(
|
|
536
|
+
await statusOf(
|
|
537
|
+
assistantApi.tasks.create({ projectId: ended.id, title: 'Late' }),
|
|
538
|
+
),
|
|
539
|
+
).toBe(409)
|
|
540
|
+
expect(
|
|
541
|
+
await statusOf(
|
|
542
|
+
ownerApi.tasks.create({ projectId: ended.id, title: 'Late' }),
|
|
543
|
+
),
|
|
544
|
+
).toBe(409)
|
|
545
|
+
})
|
|
546
|
+
})
|
|
547
|
+
}
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
## Not built yet
|
|
551
|
+
|
|
552
|
+
- No widening condition (`admits`): a `when` only narrows. A row that some other rule should open to more people is
|
|
553
|
+
reached by a grant, a relation or an off-road declaration, never by a condition.
|
|
554
|
+
- A relation holds only through a global grant of an internal role without `member`. A relation inside the node of a
|
|
555
|
+
scoped grant, and a relation for a person from outside the organization, are not built.
|
|
556
|
+
- A view is never a relation source: write the source rows to a table, under `assign`.
|
|
557
|
+
- An assignment never changes in place: delete the row and insert a new one.
|
|
558
|
+
- No raw SQL and no JSON column in a condition, and no path longer than three foreign keys.
|