@fabrika/app 0.9.0-dev.10 → 0.9.0-dev.12
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 +10 -10
- package/skill/SKILL.md +2 -2
- package/skill/references/app-setup.md +8 -8
- package/skill/references/endpoint.md +12 -4
- package/skill/references/files.md +11 -1
- package/skill/references/table-and-migration.md +22 -0
- package/skill/references/tests.md +12 -6
- package/src/contract/artifact-schema.ts +27 -5
- package/src/contract/build.ts +53 -32
- package/src/contract/declaration.ts +4 -2
- package/src/contract/defaults.ts +5 -2
- package/src/contract/define.ts +7 -1
- package/src/contract/group.ts +12 -10
- package/src/contract/index.ts +2 -0
- package/src/dev/launcher.ts +14 -15
- package/src/dev/output.ts +8 -11
- package/src/files/kinds.ts +1 -1
- package/src/files/sniff.ts +18 -1
- package/src/files/treatment.ts +12 -10
- package/src/implement/client-address.ts +5 -71
- package/src/implement/dispatch.ts +6 -4
- package/src/implement/egress.ts +30 -12
- package/src/implement/public.ts +3 -3
- package/src/jobs/report.ts +32 -5
- package/src/jobs/scrub.ts +1 -1
- package/src/testing/endpoint-access.ts +190 -60
- package/src/testing/sample-file.ts +4 -1
- package/types/src/contract/declaration.d.ts +3 -1
- package/types/src/contract/defaults.d.ts +4 -2
- package/types/src/contract/define.d.ts +6 -1
- package/types/src/contract/group.d.ts +5 -3
- package/types/src/contract/index.d.ts +1 -0
- package/types/src/dev/output.d.ts +7 -6
- package/types/src/files/treatment.d.ts +4 -3
- package/types/src/implement/client-address.d.ts +0 -5
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.12",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -105,18 +105,18 @@
|
|
|
105
105
|
}
|
|
106
106
|
},
|
|
107
107
|
"scripts": {
|
|
108
|
-
"typecheck": "
|
|
108
|
+
"typecheck": "tsrs --build tsconfig.test.json",
|
|
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.12",
|
|
113
|
+
"@fabrika/auth-core": "0.9.0-dev.12",
|
|
114
|
+
"@fabrika/db": "0.9.0-dev.12",
|
|
115
|
+
"@fabrika/email": "0.9.0-dev.12",
|
|
116
|
+
"@fabrika/jwks": "0.9.0-dev.12",
|
|
117
|
+
"@fabrika/platform": "0.9.0-dev.12",
|
|
118
|
+
"@fabrika/platform-node": "0.9.0-dev.12",
|
|
119
|
+
"@fabrika/proxy-core": "0.9.0-dev.12",
|
|
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.12
|
|
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
|
|
@@ -231,7 +231,7 @@ the access check. `references/spa.md` shows the stack.
|
|
|
231
231
|
| a share link | `issues: '<link mount>'` | `ctx.links.issue` |
|
|
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
|
-
| an outside HTTPS API | `egress: ['https://api.example.com']` | `fetch` to
|
|
234
|
+
| an outside HTTPS API | `egress: ['https://api.example.com']` | `fetch` to those (`https://*.<domain>`: one label) |
|
|
235
235
|
| a signed link (unsubscribe) | `signs: ['<purpose>']` | `ctx.tokens.sign` |
|
|
236
236
|
| a webhook binding | `binds: '<webhook>'` | `ctx.webhooks('<webhook>').bind` and `.unbind` |
|
|
237
237
|
| 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.12",
|
|
23
|
+
"@fabrika/db": "0.9.0-dev.12",
|
|
24
|
+
"@fabrika/provider-zerops": "0.9.0-dev.12",
|
|
25
|
+
"@fabrika/proxy-core": "0.9.0-dev.12",
|
|
26
|
+
"@fabrika/ui": "0.9.0-dev.12",
|
|
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.12",
|
|
34
|
+
"@fabrika/cli": "0.9.0-dev.12",
|
|
35
|
+
"@fabrika/platform": "0.9.0-dev.12",
|
|
36
36
|
"@happy-dom/global-registrator": "^20.11.2",
|
|
37
37
|
"@types/bun": "^1.4.3",
|
|
38
38
|
"@types/react": "^19.0.0",
|
|
@@ -654,10 +654,18 @@ export const app = defineApp(vocabulary, tables, {
|
|
|
654
654
|
## Outside calls: `egress`
|
|
655
655
|
|
|
656
656
|
A credentialed procedure, a webhook or a job that calls an outside HTTPS API declares its origins:
|
|
657
|
-
`egress: ['https://api.example.com']`, exact origins, no path
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
657
|
+
`egress: ['https://api.example.com']`, exact origins, no path, at most 16. `fetch` to any other origin is refused
|
|
658
|
+
while the site runs (`capability_refused: undeclared_egress`). A public, link or export procedure declares none. The
|
|
659
|
+
checker's `cross-app-fetch` accepts an absolute URL only under an origin some site declares. The approver sees every
|
|
660
|
+
origin. The guard stops mistakes; it is no sandbox.
|
|
661
|
+
|
|
662
|
+
A provider with one host per customer is one pattern: `egress: ['https://*.tenants.example.com']` reaches
|
|
663
|
+
`https://acme.tenants.example.com`, exactly one label in front of the domain, over `https` on the default port
|
|
664
|
+
(`https://*.tenants.example.com:8443` for another). It does not reach `a.b.tenants.example.com`,
|
|
665
|
+
`tenants.example.com` or `evil-tenants.example.com`. Write it in lower case and punycode, without a trailing dot; the
|
|
666
|
+
build names the spelling it wants. It refuses `http`, a second wildcard, and a wildcard on a public suffix (`*.com`,
|
|
667
|
+
`*.co.uk`). The checker accepts ``fetch(`https://${tenant}.tenants.example.com/v1`)`` under it. The approver reads a
|
|
668
|
+
pattern as every host under that domain, so prefer exact origins when there are a few.
|
|
661
669
|
|
|
662
670
|
On Cloudflare a procedure waits for its outside call inside the object's transaction, so the whole environment waits
|
|
663
671
|
with it (`SKILL.md`). A mutation records a row and kicks a job, which declares the `egress` and calls outside
|
|
@@ -70,7 +70,7 @@ task_attachments: {
|
|
|
70
70
|
- A file column is `UUID REFERENCES fabrika_files (id)` with an index on it; the checker's `file-column-migration`
|
|
71
71
|
verifies both for every column the policy names in `files`. `fabrika_files` is the framework's table: never write
|
|
72
72
|
it.
|
|
73
|
-
- A file kind (`c.files({ types, maxBytes, scan? })`) has no owner, no actions and no endpoint. The table's actions
|
|
73
|
+
- A file kind (`c.files({ types, maxBytes, scan?, inline? })`) has no owner, no actions and no endpoint. The table's actions
|
|
74
74
|
are the file's authority, and the approver reads "`tasks.write` writes `task_attachments.file` (attachments)".
|
|
75
75
|
- A file reaches what its row reaches, now: a moved task moves its files. Deleting the row (here with its task, by the
|
|
76
76
|
cascade) or clearing a nullable column removes the reference; the framework's sweep deletes a file no column
|
|
@@ -159,6 +159,16 @@ export const attachments = app.group({ callers: ['human'] }, (r) => ({
|
|
|
159
159
|
- A public image (a catalog picture in a page or an e-mail) is a public `GET` query with `http: { cache: 'immutable' }`
|
|
160
160
|
whose input names the file as well as its row (`{ product, file }`), so a new image changes the URL. The handler
|
|
161
161
|
refuses a file id that is not the row's.
|
|
162
|
+
- A download is an attachment (`Content-Disposition: attachment`); only `image/png`, `image/jpeg`, `image/gif` and
|
|
163
|
+
`image/webp` are shown inline. A file a machine reads at its URL (an RSS or Atom feed, a sitemap, an e-shop import)
|
|
164
|
+
is of a kind declared `inline: true`, e.g. `c.files({ types: ['application/rss+xml'], maxBytes: 1048576, inline: true })`,
|
|
165
|
+
served by a public `GET` query (`http: { path: '/feed.xml' }`). An inline kind admits only those images and
|
|
166
|
+
`application/xml`, `text/xml`, `application/rss+xml`, `application/atom+xml`; the build refuses SVG, HTML and every
|
|
167
|
+
other type there. Only `ctx.files.put` fills an inline kind, with a document the handler renders from checked data
|
|
168
|
+
(a feed built from rows, its text escaped), never bytes the caller sent or a file it opened: XML in the XHTML or SVG
|
|
169
|
+
namespace still renders as a page. The build refuses a procedure input of `file('<inline kind>')`; a user upload goes
|
|
170
|
+
into a kind without `inline`. An XML
|
|
171
|
+
file is UTF-8 whose bytes start with `<` (after a byte order mark and white space), or the upload is 415.
|
|
162
172
|
|
|
163
173
|
The SPA calls them through the typed client, never a hand-written `fetch`. `api.attachments.download.url(input)` is
|
|
164
174
|
the URL of a `GET` file procedure for a same-origin page (`<img src>`, `<a download>`), and
|
|
@@ -328,3 +328,25 @@ export const tables = defineTables(vocabulary, columns)({
|
|
|
328
328
|
- IAM already audits sign-ins (its auth log, refusals included) and every grant and revocation (its admin events
|
|
329
329
|
`iam.grant.create` and `iam.grant.revoke`): do not rebuild either in the application. An operator's access to the
|
|
330
330
|
database or to the provider's console is outside Fabrika.
|
|
331
|
+
|
|
332
|
+
## A view read as a table
|
|
333
|
+
|
|
334
|
+
`fabrika db codegen` reads every view a migration creates (not a materialized view: read one with `ctx.sql`): its
|
|
335
|
+
interface is `<Pascal>View`, every column is `| null`, and its column list entry says `view: true`. A view needs no
|
|
336
|
+
policy; without one only `ctx.sql` reads it. With one, `ctx.db` reads it like a child table, typed and scoped, and nothing writes it:
|
|
337
|
+
|
|
338
|
+
- `scope: { child: '<parent>' }` puts it under its parent's `Ref`, with the child's conventions: the view selects the
|
|
339
|
+
parent column (`<parent dimension>_id`) and every chain column of the parent. A view of one row per parent states
|
|
340
|
+
`key: '<parent column>'` (`{ child: 'deals', key: 'deal_id' }`), and a handler `on` the parent reads that row with
|
|
341
|
+
`ctx.db.target.<view>.get(ctx.target.value)`.
|
|
342
|
+
- `scope: { reference: '<why>' }` is a view every endpoint reads, through `ctx.db.reference.<view>`.
|
|
343
|
+
- It takes `actions: { read, appRead?, appCount? }` and column `read` actions only. `insert`, `update`, `delete`,
|
|
344
|
+
`version`, `createdBy`, `queue`, `files`, a column `write` and `unscoped: { <view>: 'write' }` are refused by tsc and
|
|
345
|
+
the checker; its handles' writes are `Unavailable`, and the data layer refuses them.
|
|
346
|
+
- No foreign key ties a view's rows to its parent: its SQL is what puts a row in a scope, and the approver reviews it.
|
|
347
|
+
Select the parent and chain columns from the parent row itself, or from a row whose foreign keys tie it there. A row
|
|
348
|
+
whose parent column is null is read by no `Ref`, but a `Within` reaches it through the chain columns it carries.
|
|
349
|
+
- A column of a type the data layer does not read (an array, `numeric` on SQLite) is left out, and every codegen run
|
|
350
|
+
names it. On SQLite an expression has a type only through `CAST(… AS INTEGER | REAL | TEXT)`; on Postgres cast a
|
|
351
|
+
count you want as a number (`count(*)::int4`).
|
|
352
|
+
- `fabrika db test-scaffold` writes no policy isolation test for a view: its parent's cases cover the rows it reads.
|
|
@@ -43,6 +43,11 @@ export const members = { 'api.tasks.assign': ['assignee'] }
|
|
|
43
43
|
`{ 'api.integrations.connectGithub': { orgId: 'acme', account: 'installation:1' } }`. The checker names each missing one,
|
|
44
44
|
and one of an endpoint that does not exist (`endpoint-fixture`). The access form's `from` field is
|
|
45
45
|
replaced by the seeded scope.
|
|
46
|
+
- A `from` field that admits a fixed set of values (`z.enum(['eu', 'us', 'apac'])`, a literal or a union of them) gets
|
|
47
|
+
two of them, one per scope: an enum's first two in sorted order, a union's first two as written. A row the table that owns the dimension already holds
|
|
48
|
+
under that key (a migration wrote the regions) is used as it is; a row the case inserts is removed once it is over.
|
|
49
|
+
Such a stored row takes no `seeds` or `pins`, and a field of one value cannot be asked from two scopes: both fail the
|
|
50
|
+
case.
|
|
46
51
|
- `members['<endpoint id>']` lists the input fields that name a picked person the handler checks with
|
|
47
52
|
`ctx.members.get` (`assign`'s `assignee`). The generated cases send a real member of the object's org there; without
|
|
48
53
|
it they send a sample, the handler answers 400, and the case fails.
|
|
@@ -55,12 +60,13 @@ export const members = { 'api.tasks.assign': ['assignee'] }
|
|
|
55
60
|
endpoint's dimension in both scopes: `close` answers 409 for an open task, so the seed makes it `doing`. A seed
|
|
56
61
|
sets neither a column that places the row nor a text column that holds a marker; a text column a CHECK lists the
|
|
57
62
|
values of, and a foreign key, it may set.
|
|
58
|
-
- `rows['<endpoint id>']` names the input fields that address a row
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
table of the table that owns it, or a table it contains
|
|
62
|
-
(`endpoint-fixture`).
|
|
63
|
-
|
|
63
|
+
- `rows['<endpoint id>']` names the input fields that address a row in the endpoint's scope, with that row's table:
|
|
64
|
+
`export const rows = { 'api.tasks.editComment': { commentId: 'task_comments' } }`. The generated cases seed one row
|
|
65
|
+
of the table in each scope and send its key there. Under `on` and `in` the table lies directly in the object or
|
|
66
|
+
target (a child table of the table that owns it, or a table it contains), and a table owns the dimension; under
|
|
67
|
+
`over` the dimension lists the table. The checker refuses anything else (`endpoint-fixture`). An endpoint with
|
|
68
|
+
`capabilities` names the capability whose scope the row lies in: `'api.tasks.copyToTask#from': { id:
|
|
69
|
+
'task_attachments' }`. Without it they send a sample, the handler finds no row (404), and the case fails.
|
|
64
70
|
- `appRows['<endpoint id>']` gives the rows of application tables (`scope: { app }`) that the endpoint's handler reads
|
|
65
71
|
for the caller's own scope, by table, with the columns they need: `export const appRows = { 'portal.guide': { guides:
|
|
66
72
|
{ active: true } } }`. Each of its leak and own-object cases seeds one row of each before it asks and removes them
|
|
@@ -12,6 +12,7 @@ import {
|
|
|
12
12
|
displayNameProblem,
|
|
13
13
|
type EndpointRow,
|
|
14
14
|
FILE_RESPONSE_KINDS,
|
|
15
|
+
fileKindsIn,
|
|
15
16
|
isOwnWorkloadName,
|
|
16
17
|
JOB_MAILERS,
|
|
17
18
|
LOCALES,
|
|
@@ -20,6 +21,7 @@ import {
|
|
|
20
21
|
type MessageKind,
|
|
21
22
|
type NumberShape,
|
|
22
23
|
type OutputShape,
|
|
24
|
+
parseEgressEntry,
|
|
23
25
|
type RecordShape,
|
|
24
26
|
type SchemaShape,
|
|
25
27
|
type StringShape,
|
|
@@ -27,7 +29,7 @@ import {
|
|
|
27
29
|
terminalIdentifyProblem,
|
|
28
30
|
type TupleShape,
|
|
29
31
|
} from '@fabrika/auth-core'
|
|
30
|
-
import {
|
|
32
|
+
import { inlineFileTypes, WORKER_BLOB_SOURCE } from '@fabrika/proxy-core/headers'
|
|
31
33
|
import { z } from 'zod/v4'
|
|
32
34
|
import {
|
|
33
35
|
ALTCHA_LIMITS,
|
|
@@ -172,7 +174,7 @@ const rowBase = {
|
|
|
172
174
|
admission: z.strictObject({ contentTypes: z.tuple([name], name), maxBytes: z.int().positive().nullable() }).nullable(),
|
|
173
175
|
input: schemaShapeSchema.nullable(),
|
|
174
176
|
output: outputShapeSchema.nullable(),
|
|
175
|
-
response: z.
|
|
177
|
+
response: z.enum(['file', 'inline-file']).optional(),
|
|
176
178
|
}
|
|
177
179
|
|
|
178
180
|
const endpointRow: z.ZodType<EndpointRow> = z.union([
|
|
@@ -228,7 +230,7 @@ const endpointRow: z.ZodType<EndpointRow> = z.union([
|
|
|
228
230
|
}),
|
|
229
231
|
]).refine(
|
|
230
232
|
// Only a procedure answers a stored file, and exactly when its output is one.
|
|
231
|
-
(row) => (row.response
|
|
233
|
+
(row) => (row.response !== undefined) === (row.output?.type === 'file') && (row.response === undefined || FILE_RESPONSE_KINDS.includes(row.kind)),
|
|
232
234
|
'only a procedure whose output is a file answers a stored file',
|
|
233
235
|
).refine(
|
|
234
236
|
// Only an RPC procedure, a public procedure and a form open to another origin, and only the anonymous two to any (ADR-0022).
|
|
@@ -328,6 +330,7 @@ const tablePolicy: z.ZodType<TablePolicyArtifact> = z.strictObject({
|
|
|
328
330
|
createdBy: nullableName,
|
|
329
331
|
columns: record(z.strictObject({ read: action.optional(), write: action.optional() })),
|
|
330
332
|
files: z.record(name, name).optional(),
|
|
333
|
+
view: z.literal(true).optional(),
|
|
331
334
|
})
|
|
332
335
|
|
|
333
336
|
export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObject({
|
|
@@ -363,7 +366,13 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
|
|
|
363
366
|
link: z.union([z.boolean(), z.array(name).nonempty()]),
|
|
364
367
|
scan: z.literal(true).optional(),
|
|
365
368
|
})),
|
|
366
|
-
fileKinds: z.record(
|
|
369
|
+
fileKinds: z.record(
|
|
370
|
+
fileKindName,
|
|
371
|
+
z.strictObject({ types: names, maxBytes: z.int().positive(), scan: z.literal(true).optional(), inline: z.literal(true).optional() }).refine(
|
|
372
|
+
(kind) => kind.inline === undefined || kind.types.every((type) => inlineFileTypes('inline-file').includes(type)),
|
|
373
|
+
'an inline kind admits only inert images and XML documents',
|
|
374
|
+
),
|
|
375
|
+
).optional(),
|
|
367
376
|
jobs: record(z.strictObject({
|
|
368
377
|
schedule: name,
|
|
369
378
|
actions,
|
|
@@ -417,7 +426,7 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
|
|
|
417
426
|
kicks: z.array(name).nonempty().optional(),
|
|
418
427
|
binds: name.optional(),
|
|
419
428
|
signs: z.array(name).nonempty().optional(),
|
|
420
|
-
egress: z.array(z.string().refine((origin) =>
|
|
429
|
+
egress: z.array(z.string().refine((origin) => parseEgressEntry(origin).ok)).nonempty().optional(),
|
|
421
430
|
})).superRefine((declared, context) => {
|
|
422
431
|
for (const [site, reach] of Object.entries(declared)) {
|
|
423
432
|
if (reach.actions !== undefined && !isOwnWorkloadName('public', site)) {
|
|
@@ -448,6 +457,19 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
|
|
|
448
457
|
tokens: record(z.strictObject({ claims: schemaShapeSchema, maxDays: z.int().positive().max(TOKEN_MAX_DAYS) })).optional(),
|
|
449
458
|
}).superRefine((artifact, context) => {
|
|
450
459
|
for (const row of artifact.endpoints) {
|
|
460
|
+
// A row answering a file of an inline kind shows it, every other row that answers a file downloads it.
|
|
461
|
+
if (row.output?.type === 'file' && (row.response === 'inline-file') !== (artifact.fileKinds?.[row.output.kind]?.inline === true)) {
|
|
462
|
+
context.addIssue({ code: 'custom', path: ['endpoints'], message: `'${row.id}' is inline-file exactly when its file kind is inline` })
|
|
463
|
+
}
|
|
464
|
+
// Only the application writes a file of an inline kind: an uploaded document could render as a page.
|
|
465
|
+
const inline = row.input === null ? undefined : fileKindsIn(row.input).find((kind) => artifact.fileKinds?.[kind]?.inline === true)
|
|
466
|
+
if (inline !== undefined) {
|
|
467
|
+
context.addIssue({
|
|
468
|
+
code: 'custom',
|
|
469
|
+
path: ['endpoints', artifact.endpoints.indexOf(row)],
|
|
470
|
+
message: `'${row.id}' takes a file of the inline kind '${inline}', which only the application writes`,
|
|
471
|
+
})
|
|
472
|
+
}
|
|
451
473
|
if (row.kind === 'public' && row.source.kind !== 'challenge' && artifact.declared?.[row.id]?.actions === undefined) {
|
|
452
474
|
context.addIssue({ code: 'custom', path: ['declared', row.id], message: 'a public procedure declares its workload actions' })
|
|
453
475
|
}
|
package/src/contract/build.ts
CHANGED
|
@@ -29,6 +29,7 @@ import {
|
|
|
29
29
|
type EndpointSource,
|
|
30
30
|
type ExportArtifact,
|
|
31
31
|
type FileKindArtifact,
|
|
32
|
+
fileKindsIn,
|
|
32
33
|
type FileShape,
|
|
33
34
|
FORM_URLENCODED_TYPE,
|
|
34
35
|
type ImportArtifact,
|
|
@@ -49,6 +50,7 @@ import {
|
|
|
49
50
|
type MessageKind,
|
|
50
51
|
type MountArtifact,
|
|
51
52
|
type OutputShape,
|
|
53
|
+
parseEgressEntry,
|
|
52
54
|
planEndpoint,
|
|
53
55
|
type ProcedureArtifact,
|
|
54
56
|
type ProcedureChallenge,
|
|
@@ -62,7 +64,7 @@ import {
|
|
|
62
64
|
type TokenPurposeArtifact,
|
|
63
65
|
type WebhookScheme,
|
|
64
66
|
} from '@fabrika/auth-core'
|
|
65
|
-
import { isPolicyOrigin, MAX_CSP_ORIGINS, WORKER_BLOB_SOURCE } from '@fabrika/proxy-core/headers'
|
|
67
|
+
import { inlineFileTypes, isPolicyOrigin, MAX_CSP_ORIGINS, WORKER_BLOB_SOURCE } from '@fabrika/proxy-core/headers'
|
|
66
68
|
import { z } from 'zod/v4'
|
|
67
69
|
import { CONTRACT_APP_ID_PATTERN as APP_ID } from './app-id'
|
|
68
70
|
import { contractArtifactSchema, RESERVED_FILE_KIND_PREFIX } from './artifact-schema'
|
|
@@ -147,7 +149,7 @@ const FRAMEWORK_TABLE_PREFIX = 'fabrika_'
|
|
|
147
149
|
/** The most origins one site calls: a site that reaches more is an integration hub, which a connector import serves. */
|
|
148
150
|
const MAX_EGRESS_ORIGINS = 16
|
|
149
151
|
const DECLARED_ALLOWED =
|
|
150
|
-
"sql: 'read' | 'write', unscoped: { <table>: 'read' | 'write' }, connect: ['<import>'], issues: '<link mount>', mailer: 'installation' | 'own', kicks: ['<cron job>'], binds: '<webhook>', signs: ['<token purpose>'], egress: ['https://<host>']"
|
|
152
|
+
"sql: 'read' | 'write', unscoped: { <table>: 'read' | 'write' }, connect: ['<import>'], issues: '<link mount>', mailer: 'installation' | 'own', kicks: ['<cron job>'], binds: '<webhook>', signs: ['<token purpose>'], egress: ['https://<host>' | 'https://*.<domain>']"
|
|
151
153
|
const CSP_FIELDS = ['connectSrc', 'imgSrc', 'frameAncestors', 'scriptSrc', 'frameSrc', 'styleSrc', 'fontSrc']
|
|
152
154
|
/** An environment variable an application reads; a challenge names its secret by one. */
|
|
153
155
|
const APPLICATION_VARIABLE = /^[A-Z][A-Z0-9_]*$/
|
|
@@ -223,6 +225,15 @@ class ArtifactBuilder {
|
|
|
223
225
|
if (row.kind === 'webhook' && row.input !== null && containsFile(row.input)) {
|
|
224
226
|
this.#problem(`mount '${row.id}'`, "takes a file in its input, which only a procedure's top-level field does (file('<kind>'))")
|
|
225
227
|
}
|
|
228
|
+
// Only the application writes a file of an inline kind: an uploaded document could render as a page.
|
|
229
|
+
for (const kind of new Set(row.input === null ? [] : fileKindsIn(row.input))) {
|
|
230
|
+
if (Object.hasOwn(this.#fileKinds, kind) && this.#fileKinds[kind]?.inline === true) {
|
|
231
|
+
this.#problem(
|
|
232
|
+
`procedure '${row.id}'`,
|
|
233
|
+
`takes a file of the inline kind '${kind}' in its input, which only the application writes: an uploaded document could render as a page (allowed: a kind without inline for an upload; ctx.files.put of a document the application renders)`,
|
|
234
|
+
)
|
|
235
|
+
}
|
|
236
|
+
}
|
|
226
237
|
}
|
|
227
238
|
const jobs = this.#jobs()
|
|
228
239
|
const exports = this.#exports()
|
|
@@ -1456,7 +1467,15 @@ class ArtifactBuilder {
|
|
|
1456
1467
|
if (row.output !== null && isSchemaOutput(row.output)) {
|
|
1457
1468
|
this.#tokenFields(`${where} output`, row.output, false)
|
|
1458
1469
|
}
|
|
1459
|
-
|
|
1470
|
+
// A file of an inline kind is shown (`inline-file`), any other downloaded; the proxy reads which from the row.
|
|
1471
|
+
this.#endpoints.push(
|
|
1472
|
+
row.output?.type === 'file'
|
|
1473
|
+
? {
|
|
1474
|
+
...row,
|
|
1475
|
+
response: Object.hasOwn(this.#fileKinds, row.output.kind) && this.#fileKinds[row.output.kind]?.inline === true ? 'inline-file' : 'file',
|
|
1476
|
+
}
|
|
1477
|
+
: row,
|
|
1478
|
+
)
|
|
1460
1479
|
}
|
|
1461
1480
|
|
|
1462
1481
|
/**
|
|
@@ -1679,8 +1698,8 @@ class ArtifactBuilder {
|
|
|
1679
1698
|
|
|
1680
1699
|
// ── Sections ────────────────────────────────────────────────────────────────────────────────
|
|
1681
1700
|
|
|
1682
|
-
/** The media types and the
|
|
1683
|
-
#fileTypes(where: string, declared: Pick<FileKindDeclaration, 'types' | 'maxBytes' | 'scan'>): void {
|
|
1701
|
+
/** The media types, the scan and the inline serving of a file kind: exact types, a scan that can vouch for each file. */
|
|
1702
|
+
#fileTypes(where: string, declared: Pick<FileKindDeclaration, 'types' | 'maxBytes' | 'scan' | 'inline'>): void {
|
|
1684
1703
|
this.#unique(where, 'types', declared.types)
|
|
1685
1704
|
for (const type of declared.types) {
|
|
1686
1705
|
if (!MIME_TYPE.test(type)) {
|
|
@@ -1693,6 +1712,18 @@ class ArtifactBuilder {
|
|
|
1693
1712
|
if (declared.scan !== undefined && typeof declared.scan !== 'boolean') {
|
|
1694
1713
|
this.#problem(where, 'scan is true or false')
|
|
1695
1714
|
}
|
|
1715
|
+
if (declared.inline !== undefined && typeof declared.inline !== 'boolean') {
|
|
1716
|
+
this.#problem(where, 'inline is true or false')
|
|
1717
|
+
}
|
|
1718
|
+
const shown = inlineFileTypes('inline-file')
|
|
1719
|
+
for (const type of declared.inline === true ? declared.types.filter((candidate) => !shown.includes(candidate)) : []) {
|
|
1720
|
+
this.#problem(
|
|
1721
|
+
where,
|
|
1722
|
+
`is served inline and admits '${type}', which a browser could run or render as a page (allowed: ${
|
|
1723
|
+
shown.join(', ')
|
|
1724
|
+
}; or leave out inline, so each file is an attachment)`,
|
|
1725
|
+
)
|
|
1726
|
+
}
|
|
1696
1727
|
for (const type of declared.scan === true ? declared.types.filter((candidate) => FILE_LIMITS.unscannedTypes.includes(candidate)) : []) {
|
|
1697
1728
|
this.#problem(
|
|
1698
1729
|
where,
|
|
@@ -1707,7 +1738,7 @@ class ArtifactBuilder {
|
|
|
1707
1738
|
}
|
|
1708
1739
|
}
|
|
1709
1740
|
|
|
1710
|
-
/** The file kinds (`c.files({ types, maxBytes, scan? })`), before the mounts that name them. */
|
|
1741
|
+
/** The file kinds (`c.files({ types, maxBytes, scan?, inline? })`), before the mounts that name them. */
|
|
1711
1742
|
#readFileKinds(): Record<string, FileKindArtifact> {
|
|
1712
1743
|
const kinds: Record<string, FileKindArtifact> = {}
|
|
1713
1744
|
for (const [name, declared] of Object.entries(this.#contract.files)) {
|
|
@@ -1735,7 +1766,12 @@ class ArtifactBuilder {
|
|
|
1735
1766
|
)
|
|
1736
1767
|
}
|
|
1737
1768
|
this.#fileTypes(where, declared)
|
|
1738
|
-
kinds[name] = {
|
|
1769
|
+
kinds[name] = {
|
|
1770
|
+
types: [...declared.types],
|
|
1771
|
+
maxBytes: declared.maxBytes,
|
|
1772
|
+
...(declared.scan === true ? { scan: true } : {}),
|
|
1773
|
+
...(declared.inline === true ? { inline: true } : {}),
|
|
1774
|
+
}
|
|
1739
1775
|
}
|
|
1740
1776
|
return kinds
|
|
1741
1777
|
}
|
|
@@ -2163,8 +2199,10 @@ class ArtifactBuilder {
|
|
|
2163
2199
|
if (readOnly && mode === 'write') {
|
|
2164
2200
|
this.#problem(where, `declares unscoped '${table}': 'write', and it runs read-only (allowed: 'read')`)
|
|
2165
2201
|
}
|
|
2166
|
-
const
|
|
2167
|
-
if (mode === 'write' &&
|
|
2202
|
+
const policy = Object.hasOwn(this.#tables, table) ? this.#tables[table] : undefined
|
|
2203
|
+
if (mode === 'write' && policy?.view === true) {
|
|
2204
|
+
this.#problem(where, `declares unscoped '${table}': 'write', and no site writes a view: its rows come from the tables it reads (allowed: 'read')`)
|
|
2205
|
+
} else if (mode === 'write' && policy?.scope.mode === 'reference') {
|
|
2168
2206
|
this.#problem(
|
|
2169
2207
|
where,
|
|
2170
2208
|
`declares unscoped '${table}': 'write', and no site writes a reference table: its rows come from a migration (allowed: 'read')`,
|
|
@@ -2309,8 +2347,8 @@ class ArtifactBuilder {
|
|
|
2309
2347
|
|
|
2310
2348
|
/**
|
|
2311
2349
|
* The HTTPS origins a site's code calls: a credentialed procedure of an RPC mount, a webhook or a job, never a public,
|
|
2312
|
-
* export or link procedure. Each is an exact origin
|
|
2313
|
-
* a problem.
|
|
2350
|
+
* export or link procedure. Each is an exact origin or a one-label pattern (`parseEgressEntry`), once; `[]` when it
|
|
2351
|
+
* declares none or after a problem.
|
|
2314
2352
|
*/
|
|
2315
2353
|
#egress(where: string, value: unknown, place: DeclaringSite): string[] {
|
|
2316
2354
|
if (value === undefined) {
|
|
@@ -2336,8 +2374,9 @@ class ArtifactBuilder {
|
|
|
2336
2374
|
this.#problem(where, `${origins.length} egress origins exceed the limit of ${MAX_EGRESS_ORIGINS}`)
|
|
2337
2375
|
}
|
|
2338
2376
|
for (const origin of origins) {
|
|
2339
|
-
|
|
2340
|
-
|
|
2377
|
+
const parsed = parseEgressEntry(origin)
|
|
2378
|
+
if (!parsed.ok) {
|
|
2379
|
+
this.#problem(where, `egress '${origin}' ${parsed.problem} (allowed: 'https://api.example.com' or 'https://*.example.com')`)
|
|
2341
2380
|
}
|
|
2342
2381
|
}
|
|
2343
2382
|
this.#unique(where, 'egress', origins)
|
|
@@ -2638,25 +2677,7 @@ function fileField(shape: SchemaShape): { readonly kind: string; readonly count:
|
|
|
2638
2677
|
|
|
2639
2678
|
/** Whether a schema holds a file anywhere. */
|
|
2640
2679
|
export function containsFile(shape: SchemaShape): boolean {
|
|
2641
|
-
|
|
2642
|
-
case 'file':
|
|
2643
|
-
return true
|
|
2644
|
-
case 'array':
|
|
2645
|
-
return containsFile(shape.items)
|
|
2646
|
-
case 'tuple':
|
|
2647
|
-
return shape.items.some(containsFile) || (shape.rest !== null && containsFile(shape.rest))
|
|
2648
|
-
case 'record':
|
|
2649
|
-
return containsFile(shape.value)
|
|
2650
|
-
case 'object':
|
|
2651
|
-
return Object.values(shape.fields).some(containsFile)
|
|
2652
|
-
case 'optional':
|
|
2653
|
-
case 'nullable':
|
|
2654
|
-
return containsFile(shape.inner)
|
|
2655
|
-
case 'union':
|
|
2656
|
-
return shape.options.some(containsFile)
|
|
2657
|
-
default:
|
|
2658
|
-
return false
|
|
2659
|
-
}
|
|
2680
|
+
return fileKindsIn(shape).length > 0
|
|
2660
2681
|
}
|
|
2661
2682
|
|
|
2662
2683
|
/** The file fields of an input, by name: the parts a multipart body carries beside its JSON. */
|
|
@@ -56,7 +56,7 @@ export const BUILDER_FIELDS: Readonly<Record<Builder, BuilderFields>> = {
|
|
|
56
56
|
link: { options: ['spa', 'dimension', 'grants', 'issuedBy', 'maxDays', 'procedures'], owned: ['kind', 'prefix'] },
|
|
57
57
|
spa: { options: ['dir', 'access', 'browserConfig'], owned: ['kind', 'prefix'] },
|
|
58
58
|
webhook: { options: ['scheme', 'boundTo', 'actions', 'input', 'limits'], owned: ['kind', 'path'] },
|
|
59
|
-
fileKind: { options: ['types', 'maxBytes', 'scan'], owned: ['kind'] },
|
|
59
|
+
fileKind: { options: ['types', 'maxBytes', 'scan', 'inline'], owned: ['kind'] },
|
|
60
60
|
cron: { options: ['actions', 'limits', 'retries'], owned: ['kind', 'schedule'] },
|
|
61
61
|
export: { options: ['version', 'consumers', 'audience', 'procedures'], owned: ['kind'] },
|
|
62
62
|
attachment: { options: ['format', 'filename', 'row', 'maxBytes', 'maxRows'], owned: [] },
|
|
@@ -283,7 +283,7 @@ export interface WebhookMountDeclaration<S> extends OptionsRecord {
|
|
|
283
283
|
}
|
|
284
284
|
|
|
285
285
|
/**
|
|
286
|
-
* A file kind (`c.files({ types, maxBytes, scan? })`, no `owner`): a class of stored files a table's file column holds.
|
|
286
|
+
* A file kind (`c.files({ types, maxBytes, scan?, inline? })`, no `owner`): a class of stored files a table's file column holds.
|
|
287
287
|
* It has no owner, no actions and no endpoint.
|
|
288
288
|
*/
|
|
289
289
|
export interface FileKindDeclaration extends OptionsRecord {
|
|
@@ -292,6 +292,8 @@ export interface FileKindDeclaration extends OptionsRecord {
|
|
|
292
292
|
readonly maxBytes: number
|
|
293
293
|
/** Every file waits `quarantined` until the scan gives it a clean verdict; a byte consumer answers 409 until then. */
|
|
294
294
|
readonly scan?: boolean
|
|
295
|
+
/** Its files are shown, not downloaded: only inert images and the XML documents a machine reads. */
|
|
296
|
+
readonly inline?: boolean
|
|
295
297
|
}
|
|
296
298
|
|
|
297
299
|
export interface CronDeclaration extends OptionsRecord {
|
package/src/contract/defaults.ts
CHANGED
|
@@ -262,11 +262,14 @@ export const GENERATED_LINK = 'fabrika:link'
|
|
|
262
262
|
|
|
263
263
|
/**
|
|
264
264
|
* The prefix of the value a generated endpoint access case sends in an input field that names a row lying in its object
|
|
265
|
-
* (`rows` of `endpoint-access.fixtures.ts`), followed by the row's table: `fabrika:row:note_comments`. The
|
|
266
|
-
* access kit seeds one such row in each scope
|
|
265
|
+
* or its list (`rows` of `endpoint-access.fixtures.ts`), followed by the row's table: `fabrika:row:note_comments`. The
|
|
266
|
+
* endpoint access kit seeds one such row in each scope and sends that scope's key.
|
|
267
267
|
*/
|
|
268
268
|
export const GENERATED_ROW_PREFIX = 'fabrika:row:'
|
|
269
269
|
|
|
270
|
+
/** What follows a row's table when the row lies in the scope of one capability of an endpoint of several: `@<name>`. */
|
|
271
|
+
export const GENERATED_ROW_CAPABILITY = '@'
|
|
272
|
+
|
|
270
273
|
/**
|
|
271
274
|
* The prefix of the value a generated endpoint access case sends in a file field, followed by the field's file kind:
|
|
272
275
|
* `fabrika:file:attachments`. The endpoint access kit sends a small file of the kind's first type it can write in its place.
|
package/src/contract/define.ts
CHANGED
|
@@ -295,7 +295,7 @@ export interface WebhookMount<B extends string, Acts extends string, I extends S
|
|
|
295
295
|
readonly input: I
|
|
296
296
|
}
|
|
297
297
|
|
|
298
|
-
/** A file kind `c.files({ types, maxBytes, scan? })` declares: what a file column of that kind holds. */
|
|
298
|
+
/** A file kind `c.files({ types, maxBytes, scan?, inline? })` declares: what a file column of that kind holds. */
|
|
299
299
|
export interface FileKind extends FileKindDeclaration {}
|
|
300
300
|
|
|
301
301
|
export interface CronJob<Acts extends string> extends CronDeclaration {
|
|
@@ -427,6 +427,11 @@ export interface Kit<A extends string, D extends string, CD extends string> {
|
|
|
427
427
|
readonly maxBytes: number
|
|
428
428
|
/** Each file is scanned for malware and served only after a clean verdict; until then it answers 409. */
|
|
429
429
|
readonly scan?: boolean
|
|
430
|
+
/**
|
|
431
|
+
* Each file is shown, not downloaded (`Content-Disposition: inline`): a feed or a sitemap a machine reads. Every
|
|
432
|
+
* type is an inert image or `application/xml`, `text/xml`, `application/rss+xml`, `application/atom+xml`.
|
|
433
|
+
*/
|
|
434
|
+
readonly inline?: boolean
|
|
430
435
|
}
|
|
431
436
|
& Owned<'kind'>,
|
|
432
437
|
): FileKind
|
|
@@ -528,6 +533,7 @@ export function surfaceKit<A extends string, D extends string, CD extends string
|
|
|
528
533
|
types: kind.types,
|
|
529
534
|
maxBytes: kind.maxBytes,
|
|
530
535
|
scan: kind.scan,
|
|
536
|
+
inline: kind.inline,
|
|
531
537
|
unknownOptions: unknownOptions(kind, 'fileKind'),
|
|
532
538
|
}),
|
|
533
539
|
cron: (schedule, options) => ({
|
package/src/contract/group.ts
CHANGED
|
@@ -111,8 +111,8 @@ export type SignsField<Sg, Purposes extends string> =
|
|
|
111
111
|
& ([Sg] extends [never] ? unknown : { readonly signs: Sg & NoInfer<KnownPurposes<Sg, Purposes>> })
|
|
112
112
|
|
|
113
113
|
/**
|
|
114
|
-
* The HTTPS origins a site's code calls (`fetch`): each an exact origin, no path
|
|
115
|
-
* `fetch` refuses any other while the site runs; a public procedure declares none.
|
|
114
|
+
* The HTTPS origins a site's code calls (`fetch`): each an exact origin or `https://*.<domain>`, one label, no path. A
|
|
115
|
+
* guard on the global `fetch` refuses any other while the site runs; a public procedure declares none.
|
|
116
116
|
*/
|
|
117
117
|
export interface EgressField {
|
|
118
118
|
readonly egress?: readonly `https://${string}`[]
|
|
@@ -291,16 +291,18 @@ export interface Endpoint<T extends ProcedureType, I extends InputSchema | null,
|
|
|
291
291
|
/**
|
|
292
292
|
* An endpoint before `.handle`: a group refuses it. `Tk` are the kit's token purposes: a signed token field of the input
|
|
293
293
|
* reaches the handler as the claims of its purpose.
|
|
294
|
+
* The parameters are declared invariant, stricter than their structure: measuring that variance through `ExactReturn`
|
|
295
|
+
* exceeds TypeScript 7's instantiation limit (TS2589), and the compiler does not check an `in out` annotation.
|
|
294
296
|
*/
|
|
295
297
|
export interface EndpointBuilder<
|
|
296
|
-
T extends ProcedureType,
|
|
297
|
-
I extends InputSchema | null,
|
|
298
|
-
O extends Schema,
|
|
299
|
-
Acc,
|
|
300
|
-
D,
|
|
301
|
-
Ctx,
|
|
302
|
-
X = unknown,
|
|
303
|
-
Tk = Record<never, never>,
|
|
298
|
+
in out T extends ProcedureType,
|
|
299
|
+
in out I extends InputSchema | null,
|
|
300
|
+
in out O extends Schema,
|
|
301
|
+
in out Acc,
|
|
302
|
+
in out D,
|
|
303
|
+
in out Ctx,
|
|
304
|
+
in out X = unknown,
|
|
305
|
+
in out Tk = Record<never, never>,
|
|
304
306
|
> extends PendingEndpoint {
|
|
305
307
|
/** The endpoint's handler, typed by its access form and declaration; it may return only the output's fields. */
|
|
306
308
|
handle<const F extends KitHandler<WithClaims<HandlerInput<I, Acc>, Tk>, Ctx, HandlerReturn<F, O>, X>>(
|
package/src/contract/index.ts
CHANGED
|
@@ -14,6 +14,8 @@ export {
|
|
|
14
14
|
export { buildArtifact } from './build'
|
|
15
15
|
export { deniedCaseRuledOutBy } from './capability-cases'
|
|
16
16
|
export { compileContract, describeContract } from './compile'
|
|
17
|
+
// The type compileContract answers, so an application's declaration can name it (TS2883 otherwise).
|
|
18
|
+
export type { ContractArtifact } from '@fabrika/auth-core'
|
|
17
19
|
export {
|
|
18
20
|
type ConnectSnapshot,
|
|
19
21
|
describeSnapshot,
|