@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fabrika/app",
3
- "version": "0.9.0-dev.10",
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": "tsc --noEmit",
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.10",
113
- "@fabrika/auth-core": "0.9.0-dev.10",
114
- "@fabrika/db": "0.9.0-dev.10",
115
- "@fabrika/email": "0.9.0-dev.10",
116
- "@fabrika/jwks": "0.9.0-dev.10",
117
- "@fabrika/platform": "0.9.0-dev.10",
118
- "@fabrika/platform-node": "0.9.0-dev.10",
119
- "@fabrika/proxy-core": "0.9.0-dev.10",
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.10
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 exactly those origins |
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.10",
23
- "@fabrika/db": "0.9.0-dev.10",
24
- "@fabrika/provider-zerops": "0.9.0-dev.10",
25
- "@fabrika/proxy-core": "0.9.0-dev.10",
26
- "@fabrika/ui": "0.9.0-dev.10",
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.10",
34
- "@fabrika/cli": "0.9.0-dev.10",
35
- "@fabrika/platform": "0.9.0-dev.10",
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 or wildcard, at most 16. `fetch` to any other origin is
658
- refused while the site runs (`capability_refused: undeclared_egress`). A public, link or export procedure declares
659
- none. The checker's `cross-app-fetch` accepts an absolute URL only under an origin some site declares. The approver
660
- sees every origin. The guard stops mistakes; it is no sandbox.
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 lying in the endpoint's object, with that row's
59
- table: `export const rows = { 'api.tasks.editComment': { commentId: 'task_comments' } }`. The generated cases seed
60
- one row of the table in each scope's object and send its key there. The table lies directly in the object: a child
61
- table of the table that owns it, or a table it contains; the checker refuses a row further down
62
- (`endpoint-fixture`). Without it they send a sample, the handler
63
- finds no row (404), and the case fails.
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 { isPolicyOrigin, WORKER_BLOB_SOURCE } from '@fabrika/proxy-core/headers'
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.literal('file').optional(),
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 === 'file') === (row.output?.type === 'file') && (row.response === undefined || FILE_RESPONSE_KINDS.includes(row.kind)),
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(fileKindName, z.strictObject({ types: names, maxBytes: z.int().positive(), scan: z.literal(true).optional() })).optional(),
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) => isPolicyOrigin(origin))).nonempty().optional(),
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
  }
@@ -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
- this.#endpoints.push(row.output?.type === 'file' ? { ...row, response: 'file' } : row)
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 scan of a file kind: exact types, and a scan that can vouch for each file. */
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] = { types: [...declared.types], maxBytes: declared.maxBytes, ...(declared.scan === true ? { scan: true } : {}) }
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 scope = Object.hasOwn(this.#tables, table) ? this.#tables[table]?.scope.mode : undefined
2167
- if (mode === 'write' && scope === 'reference') {
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 with no path or wildcard, once; `[]` when it declares none or after
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
- if (!isPolicyOrigin(origin)) {
2340
- this.#problem(where, `egress '${origin}' is not an https origin (allowed: 'https://api.example.com', no path or wildcard)`)
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
- switch (shape.type) {
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 {
@@ -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 endpoint
266
- * access kit seeds one such row in each scope's object and sends that scope's key.
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.
@@ -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) => ({
@@ -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 or wildcard. A guard on the global
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>>(
@@ -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,