@fabrika/app 0.9.0-dev.13 → 0.9.0-dev.14
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 +2 -1
- package/skill/references/app-setup.md +15 -8
- package/skill/references/endpoint.md +7 -1
- package/skill/references/errors.md +7 -6
- package/skill/references/jobs.md +10 -0
- package/skill/references/relations.md +145 -21
- package/skill/references/table-and-migration.md +4 -1
- package/skill/references/webhooks-links-connectors.md +2 -1
- package/src/bun.ts +10 -0
- package/src/contract/artifact-schema.ts +17 -3
- package/src/contract/build.ts +76 -18
- package/src/contract/define.ts +2 -1
- package/src/contract/group.ts +10 -1
- package/src/contract/kit.ts +2 -1
- package/src/disk-assets.ts +15 -3
- package/src/implement/boot.ts +28 -5
- package/src/implement/capability.ts +82 -12
- package/src/implement/dispatch.ts +251 -35
- package/src/implement/egress.ts +409 -9
- package/src/implement/implement.ts +23 -3
- package/src/implement/invocation.ts +10 -9
- package/src/implement/types.ts +15 -4
- package/src/implement/webhook.ts +8 -0
- package/src/jobs/runner.ts +7 -2
- package/src/source-map-path.ts +21 -0
- package/src/testing/caller.ts +20 -9
- package/src/testing/membership.ts +9 -5
- package/types/src/contract/define.d.ts +2 -1
- package/types/src/contract/group.d.ts +9 -1
- package/types/src/contract/kit.d.ts +2 -2
- package/types/src/implement/boot.d.ts +6 -0
- package/types/src/implement/capability.d.ts +14 -5
- package/types/src/implement/dispatch.d.ts +9 -1
- package/types/src/implement/egress.d.ts +36 -1
- package/types/src/implement/implement.d.ts +19 -3
- package/types/src/implement/invocation.d.ts +3 -3
- package/types/src/implement/types.d.ts +13 -3
- package/types/src/jobs/runner.d.ts +3 -0
- package/types/src/source-map-path.d.ts +4 -0
- package/types/src/testing/caller.d.ts +6 -1
- package/types/src/testing/membership.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.14",
|
|
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.14",
|
|
113
|
+
"@fabrika/auth-core": "0.9.0-dev.14",
|
|
114
|
+
"@fabrika/db": "0.9.0-dev.14",
|
|
115
|
+
"@fabrika/email": "0.9.0-dev.14",
|
|
116
|
+
"@fabrika/jwks": "0.9.0-dev.14",
|
|
117
|
+
"@fabrika/platform": "0.9.0-dev.14",
|
|
118
|
+
"@fabrika/platform-node": "0.9.0-dev.14",
|
|
119
|
+
"@fabrika/proxy-core": "0.9.0-dev.14",
|
|
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.14
|
|
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
|
|
@@ -232,6 +232,7 @@ the access check. `references/spa.md` shows the stack.
|
|
|
232
232
|
| e-mail (a cron job only) | `mailer: 'installation'` | `ctx.mail.send` |
|
|
233
233
|
| a file from a public procedure | `file('<kind>')` input, `admission` with `bytesPerHour` | a reference the handler writes into a file column |
|
|
234
234
|
| an outside HTTPS API | `egress: ['https://api.example.com']` | `fetch` to those (`https://*.<domain>`: one label) |
|
|
235
|
+
| any public website (a job) | `egress: 'public'` | `fetch` to public hosts, never the installation |
|
|
235
236
|
| a signed link (unsubscribe) | `signs: ['<purpose>']` | `ctx.tokens.sign` |
|
|
236
237
|
| a webhook binding | `binds: '<webhook>'` | `ctx.webhooks('<webhook>').bind` and `.unbind` |
|
|
237
238
|
| a job run after the commit | `kicks: ['<job>']` | `ctx.kick('<job>')`, `ctx.kick('<job>', { at })` |
|
|
@@ -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.14",
|
|
23
|
+
"@fabrika/db": "0.9.0-dev.14",
|
|
24
|
+
"@fabrika/provider-zerops": "0.9.0-dev.14",
|
|
25
|
+
"@fabrika/proxy-core": "0.9.0-dev.14",
|
|
26
|
+
"@fabrika/ui": "0.9.0-dev.14",
|
|
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.14",
|
|
34
|
+
"@fabrika/cli": "0.9.0-dev.14",
|
|
35
|
+
"@fabrika/platform": "0.9.0-dev.14",
|
|
36
36
|
"@happy-dom/global-registrator": "^20.11.2",
|
|
37
37
|
"@types/bun": "^1.4.3",
|
|
38
38
|
"@types/react": "^19.0.0",
|
|
@@ -245,6 +245,13 @@ zerops:
|
|
|
245
245
|
- bun run build:web
|
|
246
246
|
```
|
|
247
247
|
|
|
248
|
+
`build.base` must be a Bun that reads the committed `bun.lock`: the build installs with `--frozen-lockfile`, and an
|
|
249
|
+
older Bun fails it with `Unknown lockfile version`. A `bun.lock` that Bun 1.4 creates or regenerates has
|
|
250
|
+
`"lockfileVersion": 2`, which needs `alpine/bun@1.4`; versions 0 and 1 build on `alpine/bun@1.3`, which is also the
|
|
251
|
+
base without `build.base`. Raise `build.base` to `alpine/bun@1.4` rather than regenerate the lockfile with Bun 1.3, which
|
|
252
|
+
resolves every dependency afresh. `fabrika app build` refuses a base that cannot read the lockfile and names the one to
|
|
253
|
+
use.
|
|
254
|
+
|
|
248
255
|
The platform's build runs the tests, writes the entrypoint, runs `fabrika-check` and the type check. Its init commands
|
|
249
256
|
run `fabrika db migrate`, `fabrika db codegen --verify` and `fabrika db test-isolation` before the server starts: a
|
|
250
257
|
version does not go live until every generated test passes. It writes every `FABRIKA_*` variable; never set one.
|
|
@@ -671,6 +671,11 @@ On Cloudflare a procedure waits for its outside call inside the object's transac
|
|
|
671
671
|
with it (`SKILL.md`). A mutation records a row and kicks a job, which declares the `egress` and calls outside
|
|
672
672
|
`ctx.transaction` (`references/jobs.md`).
|
|
673
673
|
|
|
674
|
+
A cron job that calls hosts nobody knows when the contract is written (the websites its operators enter: a crawler, an
|
|
675
|
+
auditor, a link checker) declares `egress: 'public'` instead of a list (`references/jobs.md`). Only a cron job may: a
|
|
676
|
+
procedure, a mutation and a webhook name their origins. Never keep `fetch` from before boot or open sockets to get past
|
|
677
|
+
the list; that is hidden reach.
|
|
678
|
+
|
|
674
679
|
## Links to your own procedures: `ctx.url`
|
|
675
680
|
|
|
676
681
|
`ctx.url('<endpoint id>', { input?, query? })` builds an absolute URL of one of the application's own procedures, on
|
|
@@ -698,7 +703,8 @@ containing it, that declares `members`: a task endpoint reads its org's. A dimen
|
|
|
698
703
|
`member.principalId` and `member.label`, never a label from the input.
|
|
699
704
|
- `disabled` is a person an operator disabled in IAM: still a member, but unable to sign in. Refuse to assign one
|
|
700
705
|
(`assign` in `SKILL.md`), and leave them out of a picker.
|
|
701
|
-
- The approver sees each endpoint that
|
|
706
|
+
- The approver sees each endpoint that can read a directory ("can look up one member of `org`"): the first one of an
|
|
707
|
+
action and its callers widens; another endpoint of the same action and callers is shown as unchanged.
|
|
702
708
|
- With the directory's `members.list` action (`tasks.read` here) also `ctx.members.list()`, answering
|
|
703
709
|
`{ principalId, label, roles, disabled }` per member, for an assignee picker. IAM checks that action on the org
|
|
704
710
|
itself too.
|
|
@@ -31,7 +31,8 @@ The refusals agents meet most, and their fix:
|
|
|
31
31
|
| `skipped-test` | `.skip`, `.only`, `.todo` | run the test |
|
|
32
32
|
| `file-column-migration` | a file column without `REFERENCES fabrika_files (id)` or without an index it leads | both, in a new migration (`references/table-and-migration.md`) |
|
|
33
33
|
| `on-conflict-index` | `insert(…, { onConflict: { columns } })` whose columns are no unique index the migrations create | a `UNIQUE` constraint or a `CREATE UNIQUE INDEX` without `WHERE` on exactly those columns |
|
|
34
|
-
| `
|
|
34
|
+
| `access-view-key` | a table that names an access view has no single-column primary or unique key on its key | a `PRIMARY KEY` or `UNIQUE` on that column alone (`references/relations.md`) |
|
|
35
|
+
| `cross-app-fetch` | a `fetch` of an absolute URL under no origin a site declares in `egress`, or one a job's `egress: 'public'` refuses (an IP address, `localhost`) | `egress: ['https://…']` on the site that calls it (`references/endpoint.md`) |
|
|
35
36
|
| `url-endpoint` | `ctx.url('<id>')` names no procedure of the contract | the endpoint id `<mount>.<group>.<procedure>` |
|
|
36
37
|
| `cloudflare-scan` | on Cloudflare, a file kind with `scan: true` | the kind without `scan`, and no public procedure that takes its files |
|
|
37
38
|
| `cloudflare-job-segment` | on Cloudflare, a job whose `limits.timeoutMs` exceeds one 14-minute segment | at most 14 minutes: claim a bounded batch per run, and the next run takes the rest |
|
|
@@ -112,11 +113,11 @@ message. The refusal's own message names the place (`'sqlite_master' at line 2`,
|
|
|
112
113
|
(`references/tests.md`). The codes
|
|
113
114
|
you meet most:
|
|
114
115
|
|
|
115
|
-
| Code | Means
|
|
116
|
-
| -------------------- |
|
|
117
|
-
| `query_refused` | the data layer refused a statement or an operation: `undeclared_reach`, `sql_read_only`, `unknown_column`, `read_only`, `sql_outside_transaction`, `sql_scope`, `sql_name` …; the reason's text names the rule
|
|
118
|
-
| `capability_refused` | a capability of another kind, dimension or action than the call takes (`wrong_capability`, `wrong_action`, `out_of_reach`),
|
|
119
|
-
| `handler_failed` | your handler threw something else; the log has no more: the Operations issue has the stack, `app dev` prints it
|
|
116
|
+
| Code | Means |
|
|
117
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
118
|
+
| `query_refused` | the data layer refused a statement or an operation: `undeclared_reach`, `sql_read_only`, `unknown_column`, `read_only`, `sql_outside_transaction`, `sql_scope`, `sql_name` …; the reason's text names the rule |
|
|
119
|
+
| `capability_refused` | a capability of another kind, dimension or action than the call takes (`wrong_capability`, `wrong_action`, `out_of_reach`), one kept past its request (`ended`, `foreign_work`), or a `fetch` its `egress` refuses (`undeclared_egress`, `refused_egress`, `oversized_egress`, `encoded_egress`) |
|
|
120
|
+
| `handler_failed` | your handler threw something else; the log has no more: the Operations issue has the stack, `app dev` prints it |
|
|
120
121
|
|
|
121
122
|
With an Operations DSN the same 500 is a `RequestFailed` issue in Operations. Its event also carries what your handler
|
|
122
123
|
threw: the error's type, its message, its stack and its `cause` chain. Read the stack there, not in the log. A crash
|
package/skill/references/jobs.md
CHANGED
|
@@ -144,6 +144,16 @@ export const contract = app.contract((c) => ({
|
|
|
144
144
|
- A job may also declare `kicks` (another job; the edges never form a cycle), `signs` (`ctx.tokens.sign`),
|
|
145
145
|
`egress` (the HTTPS origins its `fetch` calls) and `issues` (`references/endpoint.md`). `ctx.url('<endpoint id>', …)`
|
|
146
146
|
builds an absolute link to one of the application's procedures, for an e-mail.
|
|
147
|
+
- A job that calls the websites its operators enter (a crawler, an auditor) declares `egress: 'public'`:
|
|
148
|
+
`app.cron('*/5 * * * *', { actions: ['sites.read'], egress: 'public' })`. Its `fetch` reaches any public host over
|
|
149
|
+
HTTPS or HTTP on the default port. It is refused (`capability_refused: refused_egress`) for an IP address, a name of
|
|
150
|
+
one label (`localhost`, an internal service), a name under `.local`, `.internal`, `.workers.dev`, `.zerops.app` and similar, a port,
|
|
151
|
+
the installation's own hosts (IAM, Control, Operations, every application's domain) and, on Bun (Zerops), a name
|
|
152
|
+
that resolves to a private address. Every redirect is checked again: `redirect: 'manual'` gets the redirect, the default
|
|
153
|
+
follows at most 10. A request has 60 s, a response body at most 16 MiB (`oversized_egress`), read whole before `fetch` answers; a
|
|
154
|
+
compressed answer is refused (`encoded_egress`: the guard asks for `identity`); pass `ctx.signal`, or
|
|
155
|
+
`AbortSignal.any([ctx.signal, AbortSignal.timeout(8_000)])` for a shorter bound per page. The approver reviews it
|
|
156
|
+
closely, as reach to anywhere public. Keep the sites operators enter in a table the job reads.
|
|
147
157
|
- `ctx.signal` aborts when the attempt ends (its timeout, a lost lease). Call `ctx.signal.throwIfAborted()` before
|
|
148
158
|
each external effect and pass the signal to `fetch`, so a stale attempt starts nothing after its replacement.
|
|
149
159
|
- A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, a framework failure
|
|
@@ -8,7 +8,10 @@ statement. This file is an application of its own (`tasks` with assistants); its
|
|
|
8
8
|
|
|
9
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
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
|
|
11
|
+
`@fabrika/app` `0.9.0-dev.13` or later, and a `relationWhen` `0.9.0-dev.14` or later: Control refuses to publish them for
|
|
12
|
+
an application pinned to an earlier release. A relation held inside the node of a scoped grant needs `0.9.0-dev.14`;
|
|
13
|
+
an earlier release holds nothing through it. A table's `access` needs `0.9.0-dev.14` or later, which Control
|
|
14
|
+
checks the same way.
|
|
12
15
|
|
|
13
16
|
## The vocabulary: a relation and a role's `via`
|
|
14
17
|
|
|
@@ -30,6 +33,7 @@ export const vocabulary = defineVocabulary({
|
|
|
30
33
|
},
|
|
31
34
|
relations: {
|
|
32
35
|
assisting: { dimension: 'project' },
|
|
36
|
+
auditing: { dimension: 'org' },
|
|
33
37
|
},
|
|
34
38
|
roles: {
|
|
35
39
|
owner: {
|
|
@@ -44,6 +48,10 @@ export const vocabulary = defineVocabulary({
|
|
|
44
48
|
grants: [],
|
|
45
49
|
via: { assisting: ['tasks.read', 'tasks.write'] },
|
|
46
50
|
},
|
|
51
|
+
auditor: {
|
|
52
|
+
grants: [],
|
|
53
|
+
via: { auditing: ['tasks.read'] },
|
|
54
|
+
},
|
|
47
55
|
},
|
|
48
56
|
})
|
|
49
57
|
```
|
|
@@ -51,9 +59,15 @@ export const vocabulary = defineVocabulary({
|
|
|
51
59
|
- `relations: { <name>: { dimension } }` names a relation and the dimension of the node its rows name.
|
|
52
60
|
- `via: { <relation>: [<action>, …] }` on a role: a holder of the role holds those actions at each node where a source
|
|
53
61
|
row names them, and nowhere else. Its `grants` still hold globally, so an assistant's are empty.
|
|
54
|
-
- `via` is
|
|
55
|
-
|
|
56
|
-
the
|
|
62
|
+
- `via` is for an internal role. A global grant of it (an operator gives `assistant` application-wide, in IAM's
|
|
63
|
+
console) holds the relation wherever the rows name its holder. A grant of it in a scope value, a membership role in
|
|
64
|
+
the value it is held in included, holds the relation only inside that value: a member row in another organization
|
|
65
|
+
reaches nothing, and a table or a reveal above the value gets nothing through it. A membership role's `via` names a
|
|
66
|
+
relation whose dimension is the role's own or lies inside it (`project` inside `org`), and the build refuses any
|
|
67
|
+
other. A person from outside the organization (`external: true`) holds no relation, and an external role takes no
|
|
68
|
+
`via`.
|
|
69
|
+
- Whoever gives a membership role with `via` holds every action of the role, its `via` actions included, at that value
|
|
70
|
+
through a grant; an action they hold only through a relation does not count.
|
|
57
71
|
- The token says only that the role holds those actions through `assisting`. The data layer reads the source rows on
|
|
58
72
|
every statement, so an inserted row grants at the next request and a deleted one stops access at the next request.
|
|
59
73
|
Nothing caches it.
|
|
@@ -97,6 +111,10 @@ CREATE TABLE project_assistants (
|
|
|
97
111
|
FOREIGN KEY (project_id, org_id) REFERENCES projects (id, org_id) ON UPDATE CASCADE ON DELETE CASCADE
|
|
98
112
|
);
|
|
99
113
|
CREATE INDEX project_assistants_principal ON project_assistants (principal_id, project_id);
|
|
114
|
+
|
|
115
|
+
-- An access view: the finished tasks of each organization, for whoever audits it there.
|
|
116
|
+
CREATE VIEW finished_tasks AS
|
|
117
|
+
SELECT id AS task_id, org_id FROM tasks WHERE done;
|
|
100
118
|
```
|
|
101
119
|
|
|
102
120
|
- A source table is an ordinary child or dimension table with a principal column (`TEXT`, an IAM principal id), the
|
|
@@ -137,6 +155,9 @@ export const tables = defineTables(vocabulary, columns)({
|
|
|
137
155
|
],
|
|
138
156
|
},
|
|
139
157
|
},
|
|
158
|
+
access: {
|
|
159
|
+
auditing: { view: 'finished_tasks', row: 'task_id', member: 'org_id' },
|
|
160
|
+
},
|
|
140
161
|
},
|
|
141
162
|
project_assistants: {
|
|
142
163
|
scope: { child: 'projects' },
|
|
@@ -231,6 +252,38 @@ export const tables = defineTables(vocabulary, columns)({
|
|
|
231
252
|
nothing names the new row yet, and the last would count the new task itself, since the condition is judged after
|
|
232
253
|
the write. An upsert's conflict update is judged on the stored row.
|
|
233
254
|
|
|
255
|
+
### `relationWhen`: a condition on what one relation reaches
|
|
256
|
+
|
|
257
|
+
- `relationWhen: { <relation>: { <action>: <condition> } }` narrows only what that relation reaches of the table for
|
|
258
|
+
the action: through `assisting`, only open tasks, while the owner's IAM grant still reaches every task. The table's
|
|
259
|
+
own `when` still applies to every grant; a member reveal and an IAM grant are not narrowed by it.
|
|
260
|
+
- The condition is a `when` in every rule above: the same operators, paths, `not` rule and insert rules. The relation
|
|
261
|
+
must be one the vocabulary declares and the action one the table names, and the relation must reach the table for
|
|
262
|
+
it (its dimension in the table's chain, a `readThrough`, or a reveal of it for that action); otherwise the policy is
|
|
263
|
+
refused. A view checks the relation against its parent, and its own `relationWhen` narrows its rows; the parent's
|
|
264
|
+
does not apply to it.
|
|
265
|
+
- An `on` endpoint whose `Ref` the relation holds sees a row the condition does not admit as absent (404). An insert
|
|
266
|
+
through the relation that the condition refuses, with no other relation to hold it, is a 409 with nothing written.
|
|
267
|
+
- A relation narrowed for an action does not count as holding it when a `writeThrough` column's writer is checked.
|
|
268
|
+
|
|
269
|
+
### `access`: a view decides what a relation reaches
|
|
270
|
+
|
|
271
|
+
When no declaration above says who reaches a row (a published row of another organization, a grant that is active only
|
|
272
|
+
under a join, several paths to one row), write the rule as SQL in a view and name it under the relation (ADR-0076):
|
|
273
|
+
|
|
274
|
+
- `access: { <relation>: { view, row, principal?, member? } }`. `row` is the view's column with the table's key.
|
|
275
|
+
`member` is compared with the nodes the relation is held inside (a grant of the role in a scope value, at the
|
|
276
|
+
relation's own dimension); `principal` with the caller's principal id. At least one is required.
|
|
277
|
+
- The data layer adds `key in (select <row> from <view> where …)` to every statement under the relation, beside the
|
|
278
|
+
action's other grants. `when` and `relationWhen` still narrow it. A `member`-bound view is not narrowed to the node:
|
|
279
|
+
it may list rows of other organizations, and that is how a cross-tenant rule is written.
|
|
280
|
+
- The view takes no policy, and a table's key needs a single-column primary or unique key (`access-view-key`).
|
|
281
|
+
- The view's SQL is the access rule. The approver reads it as database code that decides the relation, and nothing
|
|
282
|
+
checks what it selects: a `cross join` or a missing tenant join widens access to everyone. Whoever writes the rows
|
|
283
|
+
it reads changes who reaches the table, with no bound. Prefer `confers` when a row per grant fits.
|
|
284
|
+
- Test what each principal reads through it, as `an auditor` below does: one inside the node, one outside it, through
|
|
285
|
+
an endpoint that filters nothing itself, so the test fails when the view's filter is wrong.
|
|
286
|
+
|
|
234
287
|
### A key that holds the tenant needs its ancestors NOT NULL
|
|
235
288
|
|
|
236
289
|
A path into another scoped table, other than the container or parent, and a `readThrough` follow a foreign key of
|
|
@@ -244,18 +297,33 @@ one is refused and names the column: add a migration that sets it `NOT NULL`, th
|
|
|
244
297
|
|
|
245
298
|
- `readThrough: { <dimension>: <column> }` lets a `Within` of a dimension outside the table's chain, or a relation at
|
|
246
299
|
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.
|
|
300
|
+
`team_id` names. No update writes the column. When the key
|
|
248
301
|
lives on the row's container, name the container's path from the row's own containment column:
|
|
249
302
|
`readThrough: { team: 'task_id.team_id' }` on a task's comments. The container declares `readThrough.team` through
|
|
250
303
|
a column of its own; the row follows it wherever the container's column points now. Such a table takes no reveal
|
|
251
304
|
matched through that path: declare the reveal on the container.
|
|
305
|
+
- `writeThrough: { <dimension>: [<actions>] }` beside `readThrough` lets the path hold those actions for an `on` or `in`
|
|
306
|
+
endpoint too, writes included: a member of the team a task names updates the task. A path holds reads only without
|
|
307
|
+
it. Whoever inserts a row naming a team must hold every listed action at that team (a grant there or above it, a
|
|
308
|
+
relation row there, or a member-revealing row), or the insert answers 409; so must the container's writer for the actions its rows' paths list.
|
|
309
|
+
A job or a webhook holds nothing there. A `Ref` held through the path never moves a row, the table is never written
|
|
310
|
+
`unscoped` or by `ctx.sql`, and `ctx.sql.scope` refuses such a `Ref`.
|
|
252
311
|
- `reveals: { <relation>: { to, actions, when? } }` on a table the relation reaches: such a row also gives the
|
|
253
312
|
relation `actions` (those its roles name in `via`) at its ancestor node in `to` while `when` admits the row: an
|
|
254
313
|
assignee of an open task reads its project. A reveal matched through `readThrough` on a table with an insert needs
|
|
255
314
|
`assign: {}` (or `{ self: true }`), because the writer picks the node.
|
|
256
315
|
- `memberReveals: { <own dimension>: { to, actions, when? } }`: a grant at the row's own node holds `actions` at its
|
|
257
|
-
ancestor in `to` too,
|
|
258
|
-
|
|
316
|
+
ancestor in `to` too, while `when` admits the row: an `over` list reads through it, and an `on` or `in` endpoint of a
|
|
317
|
+
listed action gets a `Ref` of the ancestor, writes included. A member of an open task renames its project; once the
|
|
318
|
+
task closes, the next statement answers 404. Such a row is never written unscoped or by `ctx.sql`, and never moves.
|
|
319
|
+
`ctx.sql.scope` refuses a `Ref` held this way: read it through `ctx.db`.
|
|
320
|
+
- `memberReveals` may also be keyed by a dimension the table reads through: `memberReveals: { team: { to: 'project',
|
|
321
|
+
actions: ['projects.read'], assign: {} } }` on tasks that name a team in `readThrough.team`: a grant at that team
|
|
322
|
+
reads the project of each open task naming it. A link row (a child of the task naming a team) reveals its task the
|
|
323
|
+
same way. Through a path `to` is the row's nearest container, and a table with an insert states `assign`: without
|
|
324
|
+
`self`, inserting a row that names a team where the writer holds one of the listed actions answers 409, and a job or
|
|
325
|
+
a webhook names no team there. An `on` or `in` endpoint gets a `Ref` through it only for an action the path's
|
|
326
|
+
`writeThrough` also lists.
|
|
259
327
|
- A view under a parent takes none of them: it is read through its parent row, so a relation, a reveal, a member
|
|
260
328
|
reveal or a secondary path that reaches the parent reaches the view's rows of that parent.
|
|
261
329
|
|
|
@@ -356,6 +424,20 @@ export const tasks = app.group({ callers: ['human'] }, (r) => ({
|
|
|
356
424
|
}),
|
|
357
425
|
)
|
|
358
426
|
),
|
|
427
|
+
reachable: r.query({
|
|
428
|
+
input: MyTasks,
|
|
429
|
+
output: TaskPage,
|
|
430
|
+
access: { action: 'tasks.read', over: 'project' },
|
|
431
|
+
})
|
|
432
|
+
.handle(async ({ input, ctx }) =>
|
|
433
|
+
fromPage(
|
|
434
|
+
Task,
|
|
435
|
+
await ctx.db.within.tasks.list({
|
|
436
|
+
orderBy: [['title', 'asc']],
|
|
437
|
+
after: input.after,
|
|
438
|
+
}),
|
|
439
|
+
)
|
|
440
|
+
),
|
|
359
441
|
mine: r.query({
|
|
360
442
|
input: MyTasks,
|
|
361
443
|
output: TaskPage,
|
|
@@ -411,7 +493,8 @@ export const contract = app.contract((c) => ({
|
|
|
411
493
|
|
|
412
494
|
## Tests
|
|
413
495
|
|
|
414
|
-
Grant the role app-wide (`{ role: 'assistant' }`, no scope), as IAM does,
|
|
496
|
+
Grant the role app-wide (`{ role: 'assistant' }`, no scope), as IAM does, or in an organization to hold it only there, and let
|
|
497
|
+
the endpoints write the rows:
|
|
415
498
|
|
|
416
499
|
```ts src/__tests__/assistants.test.ts
|
|
417
500
|
import { createClient } from '@fabrika/app/client'
|
|
@@ -498,26 +581,68 @@ if (postgres !== null) {
|
|
|
498
581
|
).toBe(409)
|
|
499
582
|
})
|
|
500
583
|
|
|
501
|
-
test('a grant of the role in
|
|
584
|
+
test('a grant of the role in an organization reaches only its projects', async () => {
|
|
502
585
|
const project = await ownerApi.projects.create({
|
|
503
586
|
orgId: 'acme',
|
|
504
587
|
name: 'Scoped',
|
|
505
588
|
})
|
|
506
|
-
const
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
589
|
+
const inAcme = kit.testCaller([{ role: 'assistant', scope: acme }])
|
|
590
|
+
const inGlobex = kit.testCaller([
|
|
591
|
+
{ role: 'assistant', scope: kit.scope('org', 'globex') },
|
|
592
|
+
])
|
|
593
|
+
for (const scoped of [inAcme, inGlobex]) {
|
|
594
|
+
await coordinatorApi.projects.assign({
|
|
595
|
+
id: project.id,
|
|
596
|
+
assistant: scoped.id,
|
|
597
|
+
days: 1,
|
|
598
|
+
})
|
|
599
|
+
}
|
|
600
|
+
const acmeApi = createClient(contract, 'api', { fetch: kit.browser(inAcme) })
|
|
601
|
+
const globexApi = createClient(contract, 'api', {
|
|
602
|
+
fetch: kit.browser(inGlobex),
|
|
514
603
|
})
|
|
515
|
-
expect(await
|
|
604
|
+
expect((await acmeApi.tasks.list({ projectId: project.id })).items).toEqual(
|
|
605
|
+
[],
|
|
606
|
+
)
|
|
607
|
+
expect(await statusOf(globexApi.tasks.list({ projectId: project.id }))).toBe(
|
|
516
608
|
403,
|
|
517
609
|
)
|
|
518
610
|
})
|
|
519
611
|
})
|
|
520
612
|
|
|
613
|
+
describe('an auditor', () => {
|
|
614
|
+
test('reads the finished tasks of the organization it audits, and only those', async () => {
|
|
615
|
+
const project = await ownerApi.projects.create({
|
|
616
|
+
orgId: 'acme',
|
|
617
|
+
name: 'Audited',
|
|
618
|
+
})
|
|
619
|
+
const open = await ownerApi.tasks.create({
|
|
620
|
+
projectId: project.id,
|
|
621
|
+
title: 'Open',
|
|
622
|
+
})
|
|
623
|
+
const done = await ownerApi.tasks.create({
|
|
624
|
+
projectId: project.id,
|
|
625
|
+
title: 'Done',
|
|
626
|
+
})
|
|
627
|
+
await ownerApi.tasks.finish({ id: done.id, expectVersion: 1 })
|
|
628
|
+
const auditorApi = createClient(contract, 'api', {
|
|
629
|
+
fetch: kit.browser(kit.testCaller([{ role: 'auditor', scope: acme }])),
|
|
630
|
+
})
|
|
631
|
+
const outsiderApi = createClient(contract, 'api', {
|
|
632
|
+
fetch: kit.browser(
|
|
633
|
+
kit.testCaller([{ role: 'auditor', scope: kit.scope('org', 'globex') }]),
|
|
634
|
+
),
|
|
635
|
+
})
|
|
636
|
+
// `reachable` filters nothing itself: only the view keeps the open task from the auditor.
|
|
637
|
+
const audited = (await auditorApi.tasks.reachable({})).items.map((item) =>
|
|
638
|
+
item.id
|
|
639
|
+
)
|
|
640
|
+
expect(audited).toContain(done.id)
|
|
641
|
+
expect(audited).not.toContain(open.id)
|
|
642
|
+
expect((await outsiderApi.tasks.reachable({})).items).toEqual([])
|
|
643
|
+
})
|
|
644
|
+
})
|
|
645
|
+
|
|
521
646
|
describe('a project past its end', () => {
|
|
522
647
|
test('is read, and takes no new task from anyone', async () => {
|
|
523
648
|
const ended = await ownerApi.projects.create({
|
|
@@ -550,9 +675,8 @@ if (postgres !== null) {
|
|
|
550
675
|
## Not built yet
|
|
551
676
|
|
|
552
677
|
- 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
|
|
554
|
-
- A relation
|
|
555
|
-
scoped grant, and a relation for a person from outside the organization, are not built.
|
|
678
|
+
reached by a grant, a relation or an access view, never by a condition.
|
|
679
|
+
- A relation for a person from outside the organization is not built.
|
|
556
680
|
- A view is never a relation source: write the source rows to a table, under `assign`.
|
|
557
681
|
- An assignment never changes in place: delete the row and insert a new one.
|
|
558
682
|
- No raw SQL and no JSON column in a condition, and no path longer than three foreign keys.
|
|
@@ -167,7 +167,10 @@ INSERT INTO priorities (code, label, rank) VALUES ('low', 'Low', 1), ('normal',
|
|
|
167
167
|
`SET`, transaction control, `SECURITY DEFINER`, a domain, `serial` and sequences (use `GENERATED ALWAYS AS IDENTITY`),
|
|
168
168
|
a function overload, and calls outside the reviewed built-ins.
|
|
169
169
|
- Never edit, rename or delete a committed migration; add a new one. Change a schema by expand, switch, contract, and
|
|
170
|
-
ask before you drop or rename anything.
|
|
170
|
+
ask before you drop or rename anything. A migration statement that is not known to keep every stored value (it
|
|
171
|
+
drops a table or a column, empties, deletes, updates or upserts rows, changes a column's type, renames, or calls its
|
|
172
|
+
own database code) shows a separate line that says it deletes, overwrites or may change data. That line waits for a
|
|
173
|
+
person on a protected environment, and the platform backs the database up before the migration runs.
|
|
171
174
|
|
|
172
175
|
## On Cloudflare: SQLite migrations
|
|
173
176
|
|
|
@@ -52,7 +52,8 @@ export const integrations = app.group({ callers: ['human'] }, (r) => ({
|
|
|
52
52
|
`POST /hooks/github/:bindingId`.
|
|
53
53
|
- A binding is made by a procedure that declares `binds: '<webhook>'` and calls `ctx.webhooks('<webhook>').bind(ref,
|
|
54
54
|
account)` with a capability on the bound value (`ctx.target`, an org here), in its transaction; `unbind(ref, id)`
|
|
55
|
-
removes one.
|
|
55
|
+
removes one. The `Ref` must come from an IAM grant: one held through a relation, a member reveal or a secondary
|
|
56
|
+
path is refused, because the binding would outlive the rows that hold it. A GitHub account is `installation:<id>` or `repository:<id>`. The answer carries the secret and the URL
|
|
56
57
|
once. The generated tests need a fixture for its input (`references/tests.md`).
|
|
57
58
|
- The framework checks the signature, the account and the input (undeclared fields are dropped).
|
|
58
59
|
`ctx.refs['<action>']` is a `Ref` of the bound org for each declared action.
|
package/src/bun.ts
CHANGED
|
@@ -14,6 +14,7 @@ import { directoryEmailProvider } from '@fabrika/email/directory'
|
|
|
14
14
|
import { parseJwks } from '@fabrika/jwks'
|
|
15
15
|
import type { FileObjectStore } from '@fabrika/platform'
|
|
16
16
|
import { applicationRuntimeUrl, S3BlobStore } from '@fabrika/platform-node'
|
|
17
|
+
import { lookup } from 'node:dns/promises'
|
|
17
18
|
import { diskAssets } from './disk-assets.js'
|
|
18
19
|
import type { FetchService, RequestExecutionContext } from './fetch.js'
|
|
19
20
|
import { clamscanScanner } from './files/clamscan.js'
|
|
@@ -550,6 +551,7 @@ async function startContractServer(
|
|
|
550
551
|
membership,
|
|
551
552
|
terminals,
|
|
552
553
|
workloadTokens,
|
|
554
|
+
resolveHost,
|
|
553
555
|
requireProxySecret: true,
|
|
554
556
|
localEmailProviders: LOCAL_EMAIL_PROVIDERS,
|
|
555
557
|
connections: databaseConnections(environment.framework[DATABASE_CONNECTIONS]) ?? DEFAULT_DATABASE_CONNECTIONS,
|
|
@@ -585,6 +587,13 @@ async function startContractServer(
|
|
|
585
587
|
return { port: server.port ?? port, stop }
|
|
586
588
|
}
|
|
587
589
|
|
|
590
|
+
/**
|
|
591
|
+
* Every address `hostname` resolves to, as the operating system's resolver answers Bun's own `fetch`: a cron job's public
|
|
592
|
+
* egress refuses a hop whose name resolves to any private one, and connects to an address it checked (ADR-0075).
|
|
593
|
+
*/
|
|
594
|
+
const resolveHost = async (hostname: string): Promise<readonly string[]> =>
|
|
595
|
+
(await lookup(hostname, { all: true, verbatim: true })).map((entry) => entry.address)
|
|
596
|
+
|
|
588
597
|
/** The application module at `path`, imported when the loader runs; its default export must be what `serve` returned. */
|
|
589
598
|
export function implementationAt(path: string): ImplementationLoader {
|
|
590
599
|
return async () => {
|
|
@@ -631,6 +640,7 @@ export async function runContractJob(
|
|
|
631
640
|
membership,
|
|
632
641
|
terminals,
|
|
633
642
|
workloadTokens,
|
|
643
|
+
resolveHost,
|
|
634
644
|
requireProxySecret: true,
|
|
635
645
|
localEmailProviders: LOCAL_EMAIL_PROVIDERS,
|
|
636
646
|
// ClamAV on PATH, as the provider's build installs it for a `scan: true` file kind; missing, the scan fails closed.
|
|
@@ -17,6 +17,7 @@ import {
|
|
|
17
17
|
fileKindsIn,
|
|
18
18
|
isOwnWorkloadName,
|
|
19
19
|
JOB_MAILERS,
|
|
20
|
+
JOB_SITE_PREFIX,
|
|
20
21
|
LOCALES,
|
|
21
22
|
mailTemplateProblems,
|
|
22
23
|
MAX_CACHE_AGE_SECONDS,
|
|
@@ -24,6 +25,7 @@ import {
|
|
|
24
25
|
type NumberShape,
|
|
25
26
|
type OutputShape,
|
|
26
27
|
parseEgressEntry,
|
|
28
|
+
PUBLIC_EGRESS,
|
|
27
29
|
type RecordShape,
|
|
28
30
|
type RowsTestArtifact,
|
|
29
31
|
type SchemaShape,
|
|
@@ -381,6 +383,7 @@ const tablePolicy: z.ZodType<TablePolicyArtifact> = z.strictObject({
|
|
|
381
383
|
assign: z.strictObject({ maxDays: z.int().positive().nullable(), self: z.boolean() }).nullable(),
|
|
382
384
|
})).optional(),
|
|
383
385
|
when: z.record(action, condition).optional(),
|
|
386
|
+
relationWhen: record(z.record(action, condition)).optional(),
|
|
384
387
|
reveals: record(z.strictObject({
|
|
385
388
|
to: name,
|
|
386
389
|
actions: z.array(action).nonempty(),
|
|
@@ -388,11 +391,19 @@ const tablePolicy: z.ZodType<TablePolicyArtifact> = z.strictObject({
|
|
|
388
391
|
assign: z.strictObject({ self: z.boolean() }).optional(),
|
|
389
392
|
})).optional(),
|
|
390
393
|
readThrough: z.record(name, name).optional(),
|
|
394
|
+
writeThrough: z.record(name, z.array(action).nonempty()).optional(),
|
|
391
395
|
memberReveals: record(z.strictObject({
|
|
392
396
|
to: name,
|
|
393
397
|
actions: z.array(action).nonempty(),
|
|
394
398
|
when: condition.optional(),
|
|
399
|
+
assign: z.strictObject({ self: z.boolean() }).optional(),
|
|
395
400
|
})).optional(),
|
|
401
|
+
access: record(
|
|
402
|
+
z.strictObject({ view: name, row: name, principal: nullableName, member: nullableName }).refine(
|
|
403
|
+
(access) => access.principal !== null || access.member !== null,
|
|
404
|
+
'an access view binds the principal, a member node or both (ADR-0076)',
|
|
405
|
+
),
|
|
406
|
+
).optional(),
|
|
396
407
|
})
|
|
397
408
|
|
|
398
409
|
export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObject({
|
|
@@ -415,9 +426,9 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
|
|
|
415
426
|
}).refine((role) => role.external !== true || role.member !== null, {
|
|
416
427
|
path: ['external'],
|
|
417
428
|
message: 'only a membership role admits external principals',
|
|
418
|
-
}).refine((role) => role.via === undefined ||
|
|
429
|
+
}).refine((role) => role.via === undefined || role.external !== true, {
|
|
419
430
|
path: ['via'],
|
|
420
|
-
message: 'a relation holds actions through an
|
|
431
|
+
message: 'a relation holds actions through an internal role only, never an external one',
|
|
421
432
|
}),
|
|
422
433
|
),
|
|
423
434
|
relations: record(z.strictObject({ dimension: name })).optional(),
|
|
@@ -493,9 +504,12 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
|
|
|
493
504
|
kicks: z.array(name).nonempty().optional(),
|
|
494
505
|
binds: name.optional(),
|
|
495
506
|
signs: z.array(name).nonempty().optional(),
|
|
496
|
-
egress: z.array(z.string().refine((origin) => parseEgressEntry(origin).ok)).nonempty().optional(),
|
|
507
|
+
egress: z.union([z.array(z.string().refine((origin) => parseEgressEntry(origin).ok)).nonempty(), z.literal(PUBLIC_EGRESS)]).optional(),
|
|
497
508
|
})).superRefine((declared, context) => {
|
|
498
509
|
for (const [site, reach] of Object.entries(declared)) {
|
|
510
|
+
if (reach.egress === PUBLIC_EGRESS && !site.startsWith(JOB_SITE_PREFIX)) {
|
|
511
|
+
context.addIssue({ code: 'custom', path: [site, 'egress'], message: "egress: 'public' belongs to a cron job, keyed by job:<name>" })
|
|
512
|
+
}
|
|
499
513
|
if (reach.actions !== undefined && !isOwnWorkloadName('public', site)) {
|
|
500
514
|
context.addIssue({ code: 'custom', path: [site, 'actions'], message: 'workload actions belong to a public procedure, keyed by its endpoint id' })
|
|
501
515
|
}
|