@fabrika/app 0.9.0-dev.1 → 0.9.0-dev.11

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.
Files changed (222) hide show
  1. package/package.json +32 -26
  2. package/skill/SKILL.md +46 -15
  3. package/skill/references/app-setup.md +43 -12
  4. package/skill/references/dev.md +5 -2
  5. package/skill/references/endpoint.md +39 -28
  6. package/skill/references/errors.md +50 -37
  7. package/skill/references/files.md +8 -4
  8. package/skill/references/jobs.md +39 -7
  9. package/skill/references/table-and-migration.md +47 -3
  10. package/skill/references/tests.md +73 -16
  11. package/skill/references/webhooks-links-connectors.md +1 -1
  12. package/src/build-recipe.ts +198 -0
  13. package/src/build.ts +60 -4
  14. package/src/bun.ts +181 -13
  15. package/src/cloudflare/application.ts +822 -0
  16. package/src/cloudflare/bindings.ts +159 -0
  17. package/src/cloudflare/export.ts +621 -0
  18. package/src/cloudflare/import.ts +888 -0
  19. package/src/cloudflare/maintenance.ts +518 -0
  20. package/src/cloudflare/names.ts +16 -0
  21. package/src/cloudflare/ops.ts +375 -0
  22. package/src/cloudflare/r2-files.ts +172 -0
  23. package/src/cloudflare/restore.ts +167 -0
  24. package/src/cloudflare/tracker.ts +192 -0
  25. package/src/cloudflare.ts +100 -146
  26. package/src/contract/app-id.ts +5 -0
  27. package/src/contract/artifact-schema.ts +9 -1
  28. package/src/contract/build.ts +40 -2
  29. package/src/contract/capability-cases.ts +30 -0
  30. package/src/contract/compile.ts +1 -0
  31. package/src/contract/containers.ts +19 -0
  32. package/src/contract/context.ts +35 -9
  33. package/src/contract/declaration.ts +2 -0
  34. package/src/contract/defaults.ts +27 -4
  35. package/src/contract/define.ts +29 -3
  36. package/src/contract/index.ts +1 -0
  37. package/src/contract/kit.ts +4 -1
  38. package/src/contract/platform.ts +3 -2
  39. package/src/contract/vocabulary.ts +26 -8
  40. package/src/dev/changes.ts +5 -43
  41. package/src/dev/contract-digest.ts +17 -0
  42. package/src/dev/index.ts +1 -1
  43. package/src/dev/launcher.ts +197 -41
  44. package/src/dev/output.ts +13 -3
  45. package/src/dev/wire.ts +11 -1
  46. package/src/disk-assets.ts +8 -3
  47. package/src/files/archive.ts +2 -2
  48. package/src/files/handle.ts +2 -1
  49. package/src/files/job-names.ts +12 -0
  50. package/src/files/kinds.ts +74 -32
  51. package/src/files/scan.ts +3 -4
  52. package/src/files/streams.ts +3 -1
  53. package/src/implement/anonymous.ts +12 -11
  54. package/src/implement/boot.ts +84 -27
  55. package/src/implement/bounded.ts +21 -2
  56. package/src/implement/capability.ts +16 -4
  57. package/src/implement/dispatch.ts +423 -178
  58. package/src/implement/failures.ts +59 -4
  59. package/src/implement/faults.ts +5 -1
  60. package/src/implement/index.ts +1 -0
  61. package/src/implement/invocation.ts +62 -11
  62. package/src/implement/principal.ts +25 -2
  63. package/src/implement/terminals.ts +93 -0
  64. package/src/implement/tokens.ts +4 -2
  65. package/src/implement/types.ts +22 -4
  66. package/src/implement/workload.ts +42 -16
  67. package/src/jobs/mail.ts +8 -0
  68. package/src/jobs/report.ts +5 -1
  69. package/src/jobs/runner.ts +702 -126
  70. package/src/jobs/schedule.ts +7 -1
  71. package/src/jobs/scrub.ts +14 -1
  72. package/src/jobs/types.ts +6 -0
  73. package/src/spa-fallback.ts +12 -0
  74. package/src/testing/endpoint-access.ts +493 -202
  75. package/src/testing/index.ts +1 -1
  76. package/src/testing/isolation.ts +8 -1
  77. package/src/testing/kit.ts +86 -4
  78. package/src/testing/policy-isolation.ts +2 -2
  79. package/src/testing/proxy.ts +15 -10
  80. package/types/src/agent-skill.d.ts +29 -0
  81. package/types/src/build-recipe.d.ts +70 -0
  82. package/types/src/build.d.ts +29 -0
  83. package/types/src/bun.d.ts +99 -0
  84. package/types/src/client/caller.d.ts +19 -0
  85. package/types/src/client/contract.d.ts +131 -0
  86. package/types/src/client/error-reporting.d.ts +66 -0
  87. package/types/src/client/index.d.ts +4 -0
  88. package/types/src/client/rpc.d.ts +14 -0
  89. package/types/src/client/share.d.ts +2 -0
  90. package/types/src/client/transport.d.ts +42 -0
  91. package/types/src/cloudflare/application.d.ts +73 -0
  92. package/types/src/cloudflare/bindings.d.ts +33 -0
  93. package/types/src/cloudflare/export.d.ts +16 -0
  94. package/types/src/cloudflare/import.d.ts +47 -0
  95. package/types/src/cloudflare/maintenance.d.ts +117 -0
  96. package/types/src/cloudflare/names.d.ts +11 -0
  97. package/types/src/cloudflare/ops.d.ts +81 -0
  98. package/types/src/cloudflare/r2-files.d.ts +9 -0
  99. package/types/src/cloudflare/restore.d.ts +9 -0
  100. package/types/src/cloudflare/tracker.d.ts +29 -0
  101. package/types/src/cloudflare.d.ts +43 -0
  102. package/types/src/contract/app-id.d.ts +2 -0
  103. package/types/src/contract/artifact-schema.d.ts +10 -0
  104. package/types/src/contract/attachment.d.ts +41 -0
  105. package/types/src/contract/build.d.ts +12 -0
  106. package/types/src/contract/capability-cases.d.ts +9 -0
  107. package/types/src/contract/compile.d.ts +11 -0
  108. package/types/src/contract/connect.d.ts +51 -0
  109. package/types/src/contract/containers.d.ts +3 -0
  110. package/types/src/contract/context.d.ts +525 -0
  111. package/types/src/contract/declaration.d.ts +307 -0
  112. package/types/src/contract/defaults.d.ts +228 -0
  113. package/types/src/contract/define.d.ts +376 -0
  114. package/types/src/contract/file.d.ts +44 -0
  115. package/types/src/contract/group.d.ts +274 -0
  116. package/types/src/contract/handled.d.ts +18 -0
  117. package/types/src/contract/index.d.ts +20 -0
  118. package/types/src/contract/kit.d.ts +211 -0
  119. package/types/src/contract/platform.d.ts +9 -0
  120. package/types/src/contract/problems.d.ts +14 -0
  121. package/types/src/contract/redirect.d.ts +25 -0
  122. package/types/src/contract/schema-from-shape.d.ts +10 -0
  123. package/types/src/contract/schema-shape.d.ts +5 -0
  124. package/types/src/contract/snapshot-source.d.ts +15 -0
  125. package/types/src/contract/token.d.ts +58 -0
  126. package/types/src/contract/vocabulary.d.ts +32 -0
  127. package/types/src/contract/webhook-binding.d.ts +24 -0
  128. package/types/src/contract/webhook-scheme.d.ts +23 -0
  129. package/types/src/dev/changes.d.ts +7 -0
  130. package/types/src/dev/contract-digest.d.ts +1 -0
  131. package/types/src/dev/index.d.ts +2 -0
  132. package/types/src/dev/launcher.d.ts +32 -0
  133. package/types/src/dev/output.d.ts +28 -0
  134. package/types/src/dev/wire.d.ts +126 -0
  135. package/types/src/disk-assets.d.ts +6 -0
  136. package/types/src/errors.d.ts +46 -0
  137. package/types/src/fetch.d.ts +7 -0
  138. package/types/src/files/archive.d.ts +26 -0
  139. package/types/src/files/clamscan.d.ts +32 -0
  140. package/types/src/files/handle.d.ts +107 -0
  141. package/types/src/files/job-names.d.ts +9 -0
  142. package/types/src/files/kinds.d.ts +112 -0
  143. package/types/src/files/scan.d.ts +78 -0
  144. package/types/src/files/sniff.d.ts +7 -0
  145. package/types/src/files/streams.d.ts +17 -0
  146. package/types/src/files/treatment.d.ts +18 -0
  147. package/types/src/from-row.d.ts +20 -0
  148. package/types/src/honeypot.d.ts +2 -0
  149. package/types/src/implement/anonymous.d.ts +24 -0
  150. package/types/src/implement/attachment.d.ts +14 -0
  151. package/types/src/implement/boot.d.ts +128 -0
  152. package/types/src/implement/bounded.d.ts +32 -0
  153. package/types/src/implement/browser-config.d.ts +19 -0
  154. package/types/src/implement/capability.d.ts +142 -0
  155. package/types/src/implement/challenge.d.ts +75 -0
  156. package/types/src/implement/client-address.d.ts +11 -0
  157. package/types/src/implement/connect.d.ts +67 -0
  158. package/types/src/implement/crashes.d.ts +31 -0
  159. package/types/src/implement/dispatch.d.ts +251 -0
  160. package/types/src/implement/egress.d.ts +14 -0
  161. package/types/src/implement/environment.d.ts +14 -0
  162. package/types/src/implement/failures.d.ts +58 -0
  163. package/types/src/implement/faults.d.ts +48 -0
  164. package/types/src/implement/headers.d.ts +7 -0
  165. package/types/src/implement/implement.d.ts +58 -0
  166. package/types/src/implement/index.d.ts +25 -0
  167. package/types/src/implement/invocation.d.ts +136 -0
  168. package/types/src/implement/membership.d.ts +201 -0
  169. package/types/src/implement/multipart.d.ts +36 -0
  170. package/types/src/implement/params.d.ts +7 -0
  171. package/types/src/implement/principal.d.ts +57 -0
  172. package/types/src/implement/project.d.ts +11 -0
  173. package/types/src/implement/public.d.ts +61 -0
  174. package/types/src/implement/serve.d.ts +25 -0
  175. package/types/src/implement/terminals.d.ts +33 -0
  176. package/types/src/implement/tokens.d.ts +49 -0
  177. package/types/src/implement/types.d.ts +263 -0
  178. package/types/src/implement/urls.d.ts +15 -0
  179. package/types/src/implement/verifiers.d.ts +19 -0
  180. package/types/src/implement/webhook.d.ts +55 -0
  181. package/types/src/implement/workload.d.ts +61 -0
  182. package/types/src/implement/xlsx.d.ts +6 -0
  183. package/types/src/index.d.ts +12 -0
  184. package/types/src/jobs/exception.d.ts +40 -0
  185. package/types/src/jobs/mail.d.ts +67 -0
  186. package/types/src/jobs/report.d.ts +56 -0
  187. package/types/src/jobs/runner.d.ts +218 -0
  188. package/types/src/jobs/schedule.d.ts +17 -0
  189. package/types/src/jobs/scrub.d.ts +12 -0
  190. package/types/src/jobs/types.d.ts +98 -0
  191. package/types/src/react/caller.d.ts +30 -0
  192. package/types/src/react/errors.d.ts +40 -0
  193. package/types/src/react/hooks.d.ts +110 -0
  194. package/types/src/react/index.d.ts +5 -0
  195. package/types/src/react/provider.d.ts +58 -0
  196. package/types/src/react/store.d.ts +68 -0
  197. package/types/src/react/testing.d.ts +28 -0
  198. package/types/src/react/types.d.ts +33 -0
  199. package/types/src/rpc/builder.d.ts +52 -0
  200. package/types/src/rpc/contract.d.ts +23 -0
  201. package/types/src/rpc/dispatcher.d.ts +11 -0
  202. package/types/src/rpc/types.d.ts +62 -0
  203. package/types/src/service/define.d.ts +42 -0
  204. package/types/src/service/index.d.ts +3 -0
  205. package/types/src/service/serve.d.ts +28 -0
  206. package/types/src/spa-fallback.d.ts +2 -0
  207. package/types/src/standard-schema.d.ts +55 -0
  208. package/types/src/testing/caller.d.ts +95 -0
  209. package/types/src/testing/challenge.d.ts +11 -0
  210. package/types/src/testing/dev.d.ts +97 -0
  211. package/types/src/testing/endpoint-access.d.ts +132 -0
  212. package/types/src/testing/index.d.ts +12 -0
  213. package/types/src/testing/isolation.d.ts +3 -0
  214. package/types/src/testing/kit.d.ts +207 -0
  215. package/types/src/testing/membership.d.ts +132 -0
  216. package/types/src/testing/policy-isolation.d.ts +113 -0
  217. package/types/src/testing/preload.d.ts +1 -0
  218. package/types/src/testing/proxy.d.ts +40 -0
  219. package/types/src/testing/runner.d.ts +8 -0
  220. package/types/src/testing/sample-file.d.ts +5 -0
  221. package/types/src/testing/status.d.ts +4 -0
  222. package/types/src/undumpable.d.ts +5 -0
@@ -2,7 +2,8 @@
2
2
  // the table's policy is its authority. This module stages a file (an incoming part or a `ctx.files.put`): its pending
3
3
  // row first, on a connection of its own, then its object, sniffed and bounded by the kind. It serves and opens a file
4
4
  // only through a reference the work holds and may read, and only a live one, by its scanned version. The sweep
5
- // deletes the files no declared column references, and the scan job decides about the quarantined ones (`scan.ts`).
5
+ // deletes the files no declared column references, and their objects once past the runtime's retention window, and the
6
+ // scan job decides about the quarantined ones (`scan.ts`).
6
7
 
7
8
  import type { ContractArtifact, FileKindArtifact } from '@fabrika/auth-core'
8
9
  import {
@@ -17,6 +18,7 @@ import {
17
18
  type StoredFiles,
18
19
  } from '@fabrika/db/framework'
19
20
  import { type FileObjectStore, type StoredObject, uuidv7 } from '@fabrika/platform'
21
+ import { RESERVED_FILE_KIND_PREFIX } from '../contract/artifact-schema'
20
22
  import type { FileRef } from '../contract/file'
21
23
  import { HttpError, NotFoundError } from '../errors'
22
24
  import { CapabilityRefusedError } from '../implement/capability'
@@ -29,16 +31,15 @@ import { bytesAreOfType, SNIFF_BYTES, SNIFFABLE_TYPES } from './sniff'
29
31
  import { cleanName, digesting, isNamed, readExactly, readHead } from './streams'
30
32
  import { FileDownload } from './treatment'
31
33
 
32
- /**
33
- * The framework's sweep job: hourly, it deletes the files no declared column references and the pending ones past the
34
- * grace, so none waits for the next request. A reserved name with `-`, which no `c.cron` name can take;
35
- * `@fabrika/provider-zerops` writes it into the crontab on this schedule (`ZEROPS_FILE_SWEEP_JOB`).
36
- */
37
- export const FILE_SWEEP_JOB = 'fabrika-file-sweep'
38
- export const FILE_SWEEP_SCHEDULE = '41 * * * *'
34
+ export { FILE_SWEEP_JOB, FILE_SWEEP_SCHEDULE } from './job-names'
39
35
  export const FILE_SWEEP_TIMEOUT_MS = 10 * 60_000
40
36
  /** How long a staged file waits for its first reference before the sweep may delete it. */
41
37
  export const FILE_PENDING_GRACE_MS = 60 * 60 * 1000
38
+ /**
39
+ * How long a removed file's object outlives its row on Cloudflare, so the rows of a restored backup still find their
40
+ * files: the 30 days backups are kept, which never exceeds this window.
41
+ */
42
+ export const FILE_TOMBSTONE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000
42
43
  /** How many files one sweep batch handles; the next batch, or the next run, takes the rest. */
43
44
  const SWEEP_BATCH = 20
44
45
 
@@ -67,6 +68,7 @@ export class FileWork {
67
68
  readonly holder: object
68
69
  readonly request: string
69
70
  readonly #staged: string[] = []
71
+ readonly #written = new Map<string, string>()
70
72
 
71
73
  constructor(holder: object, request: string) {
72
74
  this.holder = holder
@@ -77,9 +79,18 @@ export class FileWork {
77
79
  this.#staged.push(id)
78
80
  }
79
81
 
82
+ /** The work wrote the object of a file it staged, under a key no other file has. */
83
+ wrote(id: string, objectKey: string): void {
84
+ this.#written.set(id, objectKey)
85
+ }
86
+
80
87
  get stagedIds(): readonly string[] {
81
88
  return [...this.#staged]
82
89
  }
90
+
91
+ writtenKey(id: string): string | null {
92
+ return this.#written.get(id) ?? null
93
+ }
83
94
  }
84
95
 
85
96
  interface Kind {
@@ -92,12 +103,16 @@ export class StoredFileKinds {
92
103
  readonly #store: FileObjectStore
93
104
  readonly #files: StoredFiles
94
105
  readonly #columns: readonly FileColumnRef[]
106
+ readonly #retentionMs: number
107
+ /** Serializes each object deletion of the sweep with a cancel, so no deletion is in flight once a cancel resolves. */
108
+ #deletions: Promise<void> = Promise.resolve()
95
109
 
96
- constructor(kinds: readonly Kind[], store: FileObjectStore, files: StoredFiles, columns: readonly FileColumnRef[]) {
110
+ constructor(kinds: readonly Kind[], store: FileObjectStore, files: StoredFiles, columns: readonly FileColumnRef[], retentionMs: number) {
97
111
  this.#kinds = new Map(kinds.map((kind) => [kind.name, kind]))
98
112
  this.#store = store
99
113
  this.#files = files
100
114
  this.#columns = columns
115
+ this.#retentionMs = retentionMs
101
116
  }
102
117
 
103
118
  /** Whether the contract declares kind `name`. */
@@ -188,6 +203,7 @@ export class StoredFileKinds {
188
203
  const body = digesting(stream, null)
189
204
  try {
190
205
  const { size } = await this.#store.write(objectKey, body.stream, { contentType: type, maxBytes: artifact.maxBytes })
206
+ work.wrote(id, objectKey)
191
207
  const sha256 = body.digest()
192
208
  await this.#files.written(id, { size, sha256 })
193
209
  return fileReference({ id, kind: kind.name, name, type, size, status: 'pending' }, work.holder, true)
@@ -212,6 +228,13 @@ export class StoredFileKinds {
212
228
  try {
213
229
  const objectKey = await this.#files.abandon(id, work.request)
214
230
  if (objectKey === null) {
231
+ // On SQLite the pending row is written in the work's own transaction and rolled back with it, so only the
232
+ // work knows the object; a row still there is a file something claimed, whose object stays.
233
+ const written = work.writtenKey(id)
234
+ if (written !== null && (await this.#files.find(id)) === null) {
235
+ step = 'object_delete_failed'
236
+ await this.#store.delete(written)
237
+ }
215
238
  return
216
239
  }
217
240
  step = 'object_delete_failed'
@@ -247,7 +270,7 @@ export class StoredFileKinds {
247
270
  if (holding === undefined || !holdsFile(work.holder, holding.id)) {
248
271
  throw new CapabilityRefusedError(
249
272
  'wrong_capability',
250
- `${where} takes a file reference this request holds and may read: an input file, a put, or a file column read under its table's read action`,
273
+ `${where} takes a file reference this request holds and may read: an input file, a put, or a file column read under its table's read action (or claimed by a job that holds it)`,
251
274
  )
252
275
  }
253
276
  const file = await this.#files.find(holding.id)
@@ -304,41 +327,54 @@ export class StoredFileKinds {
304
327
  return new FileDownload({ body: object.body, size: file.size, contentType: file.type, name: file.name })
305
328
  }
306
329
 
330
+ #serialized<T>(work: () => Promise<T>): Promise<T> {
331
+ const result = this.#deletions.then(work)
332
+ this.#deletions = result.then(() => undefined, () => undefined)
333
+ return result
334
+ }
335
+
336
+ /**
337
+ * Cancels the tombstones of `objectKeys`, so their objects stay: a restore cancels every key its restored rows
338
+ * reference. Once it resolves, no deletion of this sweep is in flight. Answers how many it cancelled.
339
+ */
340
+ cancelDeletions(objectKeys: readonly string[]): Promise<number> {
341
+ return this.#serialized(() => this.#files.cancelDeletions(objectKeys))
342
+ }
343
+
307
344
  /**
308
- * The sweep: it finishes deletions a crash interrupted, adopts the migrated files a declared column references, then
309
- * deletes, batch by batch, every file past the grace that no declared column references: its row and the record of
310
- * its object in one transaction (the foreign key keeps a referenced one), then the object, then the record.
345
+ * The sweep: it adopts the migrated files a declared column references, then removes, batch by batch, every file past
346
+ * the grace that no declared column references: its row and the record of its object in one transaction (the foreign
347
+ * key keeps a referenced one). Last it claims each recorded object past the retention window, then deletes it.
311
348
  */
312
349
  async sweep(signal: AbortSignal): Promise<void> {
313
350
  let step = 'rows_read_failed'
314
351
  try {
315
- for (let keys = await this.#files.unfinishedDeletions(SWEEP_BATCH); keys.length > 0 && !signal.aborted;) {
316
- for (const key of keys) {
317
- step = 'object_delete_failed'
318
- await this.#store.delete(key)
319
- step = 'deletion_record_failed'
320
- await this.#files.forgetDeletion(key)
321
- }
322
- step = 'rows_read_failed'
323
- keys = keys.length === SWEEP_BATCH ? await this.#files.unfinishedDeletions(SWEEP_BATCH) : []
324
- }
325
352
  await this.#files.adoptReferenced(this.#columns)
326
353
  for (let more = true; more && !signal.aborted;) {
327
354
  step = 'rows_read_failed'
328
355
  const batch = await this.#files.unreferenced(this.#columns, SWEEP_BATCH, FILE_PENDING_GRACE_MS)
329
356
  for (const id of batch) {
330
357
  step = 'row_delete_failed'
331
- const key = await this.#files.remove(id, FILE_PENDING_GRACE_MS)
332
- if (key === null) {
333
- continue
334
- }
335
- step = 'object_delete_failed'
336
- await this.#store.delete(key)
337
- step = 'deletion_record_failed'
338
- await this.#files.forgetDeletion(key)
358
+ await this.#files.remove(id, FILE_PENDING_GRACE_MS)
339
359
  }
340
360
  more = batch.length === SWEEP_BATCH
341
361
  }
362
+ const cutoff = new Date(Date.now() - this.#retentionMs)
363
+ for (let more = true; more && !signal.aborted;) {
364
+ step = 'rows_read_failed'
365
+ const keys = await this.#files.dueDeletions(SWEEP_BATCH, cutoff)
366
+ for (const key of keys) {
367
+ await this.#serialized(async () => {
368
+ step = 'deletion_claim_failed'
369
+ // A crash or a failed delete after the claim leaks this object's bytes; it loses no data.
370
+ if (await this.#files.claimDeletion(key, cutoff)) {
371
+ step = 'object_delete_failed'
372
+ await this.#store.delete(key)
373
+ }
374
+ })
375
+ }
376
+ more = keys.length === SWEEP_BATCH
377
+ }
342
378
  } catch {
343
379
  console.error(`fabrika: stored files sweep: ${step}`)
344
380
  throw new ServerFault('file_sweep_failed', 'the sweep of stored files failed; the next run retries it')
@@ -418,13 +454,15 @@ function fileColumns(artifact: ContractArtifact): FileColumnRef[] {
418
454
 
419
455
  /**
420
456
  * The file kinds of `artifact`, or `null` when it declares none. Every reason a kind cannot be served goes into
421
- * `problems`, so `boot` refuses to start rather than take a file it cannot check.
457
+ * `problems`, so `boot` refuses to start rather than take a file it cannot check. A removed file's object outlives its
458
+ * row by `retentionMs`.
422
459
  */
423
460
  export function storedFileKinds(
424
461
  artifact: ContractArtifact,
425
462
  database: ImplementationDatabase | null,
426
463
  store: FileObjectStore | undefined,
427
464
  problems: string[],
465
+ retentionMs: number,
428
466
  ): StoredFileKinds | null {
429
467
  const entries = Object.entries(artifact.fileKinds ?? {})
430
468
  if (entries.length === 0) {
@@ -438,6 +476,9 @@ export function storedFileKinds(
438
476
  return null
439
477
  }
440
478
  for (const [name, kind] of entries) {
479
+ if (name.startsWith(RESERVED_FILE_KIND_PREFIX)) {
480
+ problems.push(`files '${name}' is a file kind name the framework reserves (${RESERVED_FILE_KIND_PREFIX}*)`)
481
+ }
441
482
  for (const type of kind.types.filter((candidate) => !SNIFFABLE_TYPES.includes(candidate))) {
442
483
  problems.push(`files '${name}' admits '${type}', whose bytes the framework cannot verify (allowed: ${SNIFFABLE_TYPES.join(', ')})`)
443
484
  }
@@ -450,5 +491,6 @@ export function storedFileKinds(
450
491
  store,
451
492
  frameworkTablesOf(database).files,
452
493
  fileColumns(artifact),
494
+ retentionMs,
453
495
  )
454
496
  }
package/src/files/scan.ts CHANGED
@@ -7,13 +7,12 @@
7
7
 
8
8
  import type { QuarantinedStoredFile } from '@fabrika/db/framework'
9
9
  import type { FileObjectStore } from '@fabrika/platform'
10
+ import { createHash } from 'node:crypto'
10
11
  import type { OperationsReporter } from '../jobs/report'
11
12
  import { type ArchiveRefusal, checkArchive } from './archive'
12
13
  import { ZIP_TYPES } from './sniff'
13
14
 
14
- /** The reserved name of the scan job: a `c.cron` job name cannot contain `-`, so no application job takes it. */
15
- export const FILE_SCAN_JOB = 'fabrika-file-scan'
16
- export const FILE_SCAN_SCHEDULE = '* * * * *'
15
+ export { FILE_SCAN_JOB, FILE_SCAN_SCHEDULE } from './job-names'
17
16
 
18
17
  export const SCAN_LIMITS = {
19
18
  /** One pass scans at most this many files, and at most `batchBytes` of them; the next pass takes the rest. */
@@ -181,7 +180,7 @@ class ScanPass {
181
180
  }
182
181
  const bytes = object.size === file.size ? await readExactly(object.body, file.size, signal) : null
183
182
  if (object.size !== file.size) await object.body.cancel()
184
- if (bytes === null || new Bun.CryptoHasher('sha256').update(bytes).digest('hex') !== file.sha256) {
183
+ if (bytes === null || createHash('sha256').update(bytes).digest('hex') !== file.sha256) {
185
184
  if (!signal.aborted) this.#states.set(file.id, { kind: 'mismatch' })
186
185
  throw new Error('the object differs from its upload')
187
186
  }
@@ -1,6 +1,8 @@
1
1
  // The byte streams of a stored file on its way in and out: the head the sniff reads, the digest and the deadline of a
2
2
  // write, the exact read of a file a site opens, and the client's file name as metadata.
3
3
 
4
+ import { createHash } from 'node:crypto'
5
+
4
6
  const MAX_NAME_CODE_POINTS = 255
5
7
 
6
8
  /** The client's file name, metadata only: at most 255 code points, never half a character, no control characters. */
@@ -62,7 +64,7 @@ export function digesting(body: ReadableStream<Uint8Array>, timeoutMs: number |
62
64
  timedOut(): boolean
63
65
  stop(): void
64
66
  } {
65
- const hasher = new Bun.CryptoHasher('sha256')
67
+ const hasher = createHash('sha256')
66
68
  let timer: ReturnType<typeof setTimeout> | undefined
67
69
  let expired = false
68
70
  const stream = body.pipeThrough(
@@ -2,18 +2,9 @@
2
2
  // body, so the framework enforces it) and the share SPA's fragment bootstrap. A form's admission is
3
3
  // `form-admission.ts`, a webhook's signature `verifiers.ts`.
4
4
 
5
- import { LINK_BOOTSTRAP_FILE, SHARE_KEY_GLOBAL } from '../contract/defaults'
5
+ import { bodyDeadlineMs, LINK_BOOTSTRAP_FILE, SHARE_KEY_GLOBAL } from '../contract/defaults'
6
6
  import { HttpError } from '../errors'
7
- import { readBoundedBytes } from './bounded'
8
-
9
- /** The slowest body a procedure waits for, in bytes per second: its deadline is `maxBytes` at this rate, 30 s at least. */
10
- export const BODY_RATE_FLOOR = 16 * 1024
11
- const MIN_BODY_DEADLINE_MS = 30_000
12
-
13
- /** How long a body of at most `maxBytes` may take to arrive. */
14
- export function bodyDeadlineMs(maxBytes: number): number {
15
- return Math.max(MIN_BODY_DEADLINE_MS, Math.ceil((maxBytes / BODY_RATE_FLOOR) * 1000))
16
- }
7
+ import { deadline, readBoundedBytes } from './bounded'
17
8
 
18
9
  /**
19
10
  * The body as bytes, read until `maxBytes`; a longer one stops the read and is a 413. A body whose stream fails before
@@ -36,6 +27,16 @@ export async function readBoundedBody(request: Request, maxBytes: number, deadli
36
27
  return body
37
28
  }
38
29
 
30
+ /** `readBoundedBody` within the deadline `maxBytes` derives; the deadline ends with the read. */
31
+ export async function readBodyInTime(request: Request, maxBytes: number): Promise<Uint8Array<ArrayBuffer>> {
32
+ const timer = deadline(bodyDeadlineMs(maxBytes))
33
+ try {
34
+ return await readBoundedBody(request, maxBytes, timer.signal)
35
+ } finally {
36
+ timer.clear()
37
+ }
38
+ }
39
+
39
40
  /** What a request answers whose body did not arrive whole: nobody reads it, and no failure is reported. */
40
41
  export function abortedBody(): HttpError {
41
42
  return new HttpError(400, 'aborted', 'The body could not be read to its end')
@@ -17,13 +17,22 @@ import {
17
17
  FABRIKA_IAM_APP_ID,
18
18
  FABRIKA_PROXY_SECRET,
19
19
  type IamMembershipRpc,
20
+ type IamTerminalRpc,
20
21
  isLoopbackHost,
21
22
  type Jwks,
22
23
  parseAppEnvironmentId,
23
24
  } from '@fabrika/auth-core'
24
25
  import type { Database } from '@fabrika/db'
25
26
  import type { CapabilityAuthority } from '@fabrika/db/capability'
26
- import { bindScopedDatabase, type DataAccess, dataAccessOf, type FrameworkTables, frameworkTablesOf, isScopedDatabase } from '@fabrika/db/framework'
27
+ import {
28
+ bindScopedDatabaseProvisionally,
29
+ type DataAccess,
30
+ dataAccessOf,
31
+ type FrameworkTables,
32
+ frameworkTablesOf,
33
+ isScopedDatabase,
34
+ type Session,
35
+ } from '@fabrika/db/framework'
27
36
  import type { DataKind } from '@fabrika/db/tables'
28
37
  import type { EmailProviderRegistry } from '@fabrika/email'
29
38
  import { builtinEmailProviders } from '@fabrika/email/providers'
@@ -31,6 +40,7 @@ import { TokenVerifier } from '@fabrika/jwks'
31
40
  import type { FileObjectStore } from '@fabrika/platform'
32
41
  import { compileContract } from '../contract/compile'
33
42
  import { exportDescription } from '../contract/connect'
43
+ import { containersOf } from '../contract/containers'
34
44
  import { isProcedure, type ProcedureDeclaration, type ProcedureTreeDeclaration, SURFACE_SECTIONS } from '../contract/declaration'
35
45
  import { challengeRowId, exportBase, spaPrefixRowId } from '../contract/defaults'
36
46
  import type { AnyContract, Schema } from '../contract/define'
@@ -41,7 +51,7 @@ import { FILE_SWEEP_JOB, FILE_SWEEP_SCHEDULE, FILE_SWEEP_TIMEOUT_MS, storedFileK
41
51
  import { FILE_SCAN_JOB, FILE_SCAN_SCHEDULE, type FileScanner, SCAN_LIMITS } from '../files/scan'
42
52
  import { type MailStandIn, resolveMailTransports } from '../jobs/mail'
43
53
  import { logReporter, type OperationsReporter, operationsReporter, operationsSettings, type ReportSource } from '../jobs/report'
44
- import { bindJobs, type ContractJobs, type HandlerErrorSink } from '../jobs/runner'
54
+ import { bindJobs, type ContractJobs } from '../jobs/runner'
45
55
  import { environmentScrubber } from '../jobs/scrub'
46
56
  import { browserConfigs } from './browser-config'
47
57
  import { createCapabilityIssuer, requestIsReadOnly } from './capability'
@@ -59,7 +69,7 @@ import {
59
69
  } from './dispatch'
60
70
  import { installEgressGuard, platformCall, platformFacility } from './egress'
61
71
  import type { CapturedEnvironment } from './environment'
62
- import { FailureReports } from './failures'
72
+ import { FailureReports, type HandlerErrorSink } from './failures'
63
73
  import { applicationPolicy } from './headers'
64
74
  import type { ContractDatabase, ContractImplementation, ImplementationDatabase } from './implement'
65
75
  import { approvedDeclaration, approvedReach, isSiteHandler, type SiteDeclaration } from './invocation'
@@ -91,6 +101,11 @@ export interface BootOptions {
91
101
  readonly requireProxySecret?: boolean
92
102
  /** The object storage of the stored files, which the Bun adapter opens. Without it, a contract with file kinds does not boot. */
93
103
  readonly files?: FileObjectStore
104
+ /**
105
+ * How long a removed file's object outlives its row, so a restored backup's rows find their files:
106
+ * `FILE_TOMBSTONE_RETENTION_MS` on Cloudflare. Zero when omitted, as on Bun.
107
+ */
108
+ readonly fileRetentionMs?: number
94
109
  /**
95
110
  * The malware scanner of the scan job of `scan: true` file kinds, which the Bun adapter supplies to a job run
96
111
  * (`clamscanScanner`). Without it the scan job leaves every quarantined file quarantined and reports.
@@ -101,6 +116,11 @@ export interface BootOptions {
101
116
  * creates scopes, manages members or issues share links does not boot.
102
117
  */
103
118
  readonly membership?: IamMembershipRpc
119
+ /**
120
+ * IAM's identification operations at a terminal (ADR-0067): the IAM binding on Cloudflare, `HttpIamTerminals`
121
+ * elsewhere. Without it, a contract that declares a terminal does not boot.
122
+ */
123
+ readonly terminals?: IamTerminalRpc
104
124
  /**
105
125
  * Cloudflare service bindings to the owners' proxy Workers, by binding name (`FABRIKA_CONNECT_<IMPORT>`). An import
106
126
  * without one calls its owner with `fetch`.
@@ -126,8 +146,10 @@ export interface BootOptions {
126
146
  */
127
147
  readonly challengeWork?: ChallengeWork
128
148
  /**
129
- * The developer's own machine only (`fabrika app dev`): what a job's handler threw, which every log of a deployed
130
- * application withholds because it may carry a credential.
149
+ * The author's own run only (`fabrika app dev`, a test that passes it to the kit): what a request's 5xx or a job
150
+ * attempt threw, whole, beside the code and reason its log line names: a handler's own error, or a framework failure
151
+ * (a refusal of the data layer or of a capability, a `ServerFault`) with its message. Every log of a deployed
152
+ * application withholds both, because either may carry request data or a credential (ADR-0059).
131
153
  */
132
154
  readonly revealHandlerErrors?: HandlerErrorSink
133
155
  /** The providers `FABRIKA_EMAIL_PROVIDER` may name for the jobs that declare `mailer: 'installation'`; the built-in ones by default. */
@@ -150,6 +172,11 @@ export interface BootOptions {
150
172
  * then `null`.
151
173
  */
152
174
  readonly clientAddress?: 'vouched'
175
+ /**
176
+ * Runs in the transaction of every change of a job's wakes or lease (`DataLayerRuntime.projectWakes`): the Cloudflare
177
+ * object arms its alarm there. Bun supplies none.
178
+ */
179
+ readonly projectWakes?: (transaction: Session) => Promise<void>
153
180
  }
154
181
 
155
182
  /** The pool size a runtime adapter that names none is assumed to have: the Bun adapter's default. */
@@ -228,21 +255,6 @@ function checkContractDigest(framework: Readonly<Record<string, string>>, artifa
228
255
  }
229
256
  }
230
257
 
231
- /** Every dimension's containers, nearest first (`note → [workspace, organization]`); `buildArtifact` refuses a cycle. */
232
- function containersOf(artifact: ContractArtifact): ReadonlyMap<string, readonly string[]> {
233
- const containers = new Map<string, readonly string[]>()
234
- for (const dimension of Object.keys(artifact.dimensions)) {
235
- const chain: string[] = []
236
- let next = artifact.dimensions[dimension]?.in ?? null
237
- while (next !== null && !chain.includes(next)) {
238
- chain.push(next)
239
- next = artifact.dimensions[next]?.in ?? null
240
- }
241
- containers.set(dimension, chain)
242
- }
243
- return containers
244
- }
245
-
246
258
  /** The shortest secret accepted; Control generates 32 random bytes. */
247
259
  const MIN_PROXY_SECRET_LENGTH = 32
248
260
 
@@ -262,6 +274,18 @@ function readProxySecret(framework: Readonly<Record<string, string>>, required:
262
274
  return proxySecretDigest(secret)
263
275
  }
264
276
 
277
+ /** What an application's SQLite database (a Durable Object's, ADR-0065) cannot serve: a scanning file kind. */
278
+ function sqliteProblems(artifact: ContractArtifact, database: Database | undefined, problems: string[]): void {
279
+ if (database?.dialect !== 'sqlite') {
280
+ return
281
+ }
282
+ for (const [name, kind] of Object.entries(artifact.fileKinds ?? {})) {
283
+ if (kind.scan === true) {
284
+ problems.push(`files '${name}' declares scan: true; no malware scanner runs on Cloudflare, so a scanning file kind is not served there`)
285
+ }
286
+ }
287
+ }
288
+
265
289
  /** What this version cannot serve yet; a contract that declares it does not boot rather than answer nothing. */
266
290
  function unservable(
267
291
  artifact: ContractArtifact,
@@ -350,6 +374,8 @@ interface BoundDatabase {
350
374
  readonly framework: FrameworkTables | null
351
375
  /** The mini-ORM behind a staged-kit site's `ctx.db`; only a `scoped(tables)` layer has it. */
352
376
  readonly data: DataAccess | null
377
+ /** Disconnects a `scoped(tables)` layer this boot bound; `null` for any other database. */
378
+ readonly release: (() => void) | null
353
379
  }
354
380
 
355
381
  /**
@@ -360,6 +386,7 @@ function contractDatabase(
360
386
  database: ImplementationDatabase | null,
361
387
  connection: Database | undefined,
362
388
  capabilities: CapabilityAuthority,
389
+ projectWakes: ((transaction: Session) => Promise<void>) | undefined,
363
390
  problems: string[],
364
391
  ): BoundDatabase | null {
365
392
  if (database === null) {
@@ -367,7 +394,7 @@ function contractDatabase(
367
394
  }
368
395
  if (!isScopedDatabase(database)) {
369
396
  if ('locate' in database) {
370
- return { database, framework: null, data: null }
397
+ return { database, framework: null, data: null, release: null }
371
398
  }
372
399
  problems.push('serve(contract, { database }) takes the scoped(tables) result of @fabrika/db itself, not a copy or a wrapper of it')
373
400
  return null
@@ -377,8 +404,13 @@ function contractDatabase(
377
404
  return null
378
405
  }
379
406
  try {
380
- const locate = bindScopedDatabase(database, { database: connection, capabilities, readOnly: requestIsReadOnly })
381
- return { database: { tables: database.tables, locate }, framework: frameworkTablesOf(database), data: dataAccessOf(database) }
407
+ const { locate, release } = bindScopedDatabaseProvisionally(database, {
408
+ database: connection,
409
+ capabilities,
410
+ readOnly: requestIsReadOnly,
411
+ ...(projectWakes === undefined ? {} : { projectWakes }),
412
+ })
413
+ return { database: { tables: database.tables, locate }, framework: frameworkTablesOf(database), data: dataAccessOf(database), release }
382
414
  } catch {
383
415
  problems.push('the data layer was bound before boot; only the framework binds it, so remove @fabrika/db/framework from the application')
384
416
  return null
@@ -651,11 +683,28 @@ function runtimePurposes(contract: AnyContract, artifact: ContractArtifact): Rea
651
683
  }
652
684
 
653
685
  export function boot(app: ContractImplementation, options: BootOptions): ContractApp {
686
+ const binding: Binding = { release: null }
687
+ try {
688
+ return bootOnce(app, options, binding)
689
+ } catch (error) {
690
+ // A failed boot releases the data layer it bound, so a later boot of the same application binds it again.
691
+ binding.release?.()
692
+ throw error
693
+ }
694
+ }
695
+
696
+ /** What `bootOnce` bound: released when the boot fails, kept when it succeeds. */
697
+ interface Binding {
698
+ release: (() => void) | null
699
+ }
700
+
701
+ function bootOnce(app: ContractImplementation, options: BootOptions, binding: Binding): ContractApp {
654
702
  const problems: string[] = []
655
703
  installEgressGuard()
656
704
  // What a handler reaches through these is the platform's own request, which no site's egress covers.
657
705
  const objects = options.files === undefined ? undefined : platformFacility(options.files)
658
706
  const membershipRpc = options.membership === undefined ? undefined : platformFacility(options.membership)
707
+ const terminalRpc = options.terminals === undefined ? undefined : platformFacility(options.terminals)
659
708
  const workloadTokens = options.workloadTokens === undefined ? undefined : platformFacility(options.workloadTokens)
660
709
  const variables = readFramework(options.environment.framework, app.contract.vocabulary.app, problems)
661
710
  const artifact = compileContract(app.contract, app.database?.tables ?? {})
@@ -671,12 +720,14 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
671
720
  ? null
672
721
  : operationsReporter({ ...operations, source, scrubber, ...(options.operationsFetch === undefined ? {} : { fetch: options.operationsFetch }) })
673
722
  const owned = new Set(Object.values(artifact.tables).flatMap((table) => table.scope.mode === 'dimension' ? [table.scope.dimension] : []))
674
- const containers = containersOf(artifact)
723
+ const containers = containersOf(artifact.dimensions)
675
724
  unservable(artifact, options.assets, owned, containers, problems)
725
+ sqliteProblems(artifact, options.database, problems)
676
726
  // This runtime's own: what another `boot` call mints, application code's included, its stores refuse.
677
727
  const issuer = createCapabilityIssuer()
678
- const fileKinds = storedFileKinds(artifact, app.database, objects, problems)
679
- const bound = contractDatabase(app.database, options.database, issuer.authority, problems)
728
+ const fileKinds = storedFileKinds(artifact, app.database, objects, problems, options.fileRetentionMs ?? 0)
729
+ const bound = contractDatabase(app.database, options.database, issuer.authority, options.projectWakes, problems)
730
+ binding.release = bound?.release ?? null
680
731
  const framework = bound?.framework ?? null
681
732
  frameworkProblems(artifact, framework, problems)
682
733
  const database = bound?.database ?? null
@@ -896,6 +947,11 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
896
947
  if (site !== undefined && data === null) {
897
948
  problems.push(`'${site.row.id}' reaches data through ctx.db, which runs on @fabrika/db: pass serve(contract, { database: scoped(tables) })`)
898
949
  }
950
+ if (artifact.terminal !== undefined && options.terminals === undefined) {
951
+ problems.push(
952
+ 'the contract declares a terminal, and the runtime adapter supplies no IAM transport for its identifications (the IAM binding on Cloudflare; FABRIKA_IAM_RPC_URL and FABRIKA_IAM_RPC_KEY on Bun)',
953
+ )
954
+ }
899
955
  const asking = [...endpoints.values()].find(asksIam)
900
956
  if (asking !== undefined && options.membership === undefined) {
901
957
  problems.push(
@@ -919,12 +975,13 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
919
975
  containers,
920
976
  assets: options.assets ?? null,
921
977
  membership,
978
+ terminals: artifact.terminal === undefined ? null : (terminalRpc ?? null),
922
979
  framework,
923
980
  mint: issuer.mint,
924
981
  capabilities: issuer.authority,
925
982
  data,
926
983
  fileKinds,
927
- failures: new FailureReports(reporterFor('fabrika.requests')),
984
+ failures: new FailureReports(reporterFor('fabrika.requests'), { reveal: options.revealHandlerErrors ?? null }),
928
985
  kick: jobs.kick,
929
986
  actions: Object.freeze(Object.keys(artifact.actions).sort()),
930
987
  publicShare: new InFlightShare(publicShareOf(options.connections ?? DEFAULT_CONNECTIONS)),
@@ -8,9 +8,28 @@
8
8
  */
9
9
  export const REQUEST_BUDGET_MS = 10_000
10
10
 
11
+ /** A signal that aborts once its time passed, and a `clear` its work calls when it settles. */
12
+ export interface Deadline {
13
+ readonly signal: AbortSignal
14
+ clear(): void
15
+ }
16
+
17
+ /**
18
+ * Aborts like `AbortSignal.timeout(ms)`, or when `parent` aborts. Its timer is cleared by `clear`, which every caller
19
+ * runs in `finally`: workerd counts a pending timer as work, so an uncleared one keeps a Durable Object awake.
20
+ */
21
+ export function deadline(ms: number, parent?: AbortSignal): Deadline {
22
+ const controller = new AbortController()
23
+ const timer = setTimeout(() => controller.abort(new DOMException('The operation timed out.', 'TimeoutError')), ms)
24
+ return {
25
+ signal: parent === undefined ? controller.signal : AbortSignal.any([parent, controller.signal]),
26
+ clear: () => clearTimeout(timer),
27
+ }
28
+ }
29
+
11
30
  /** A handler's `ctx.signal`: aborted when the client leaves (`request.signal`) or once `budgetMs` passed. */
12
- export function handlerSignal(request: Request, budgetMs: number = REQUEST_BUDGET_MS): AbortSignal {
13
- return AbortSignal.any([request.signal, AbortSignal.timeout(budgetMs)])
31
+ export function handlerSignal(request: Request, budgetMs: number = REQUEST_BUDGET_MS): Deadline {
32
+ return deadline(budgetMs, request.signal)
14
33
  }
15
34
 
16
35
  export interface BoundedRead {
@@ -44,7 +44,7 @@ export type CapabilityRefusal = keyof typeof CAPABILITY_REFUSALS
44
44
  /** A capability that is forged, from a request that has ended, or from another request than the current one. */
45
45
  export class CapabilityRefusedError extends Error {
46
46
  override readonly name = 'CapabilityRefusedError'
47
- /** What a log may say; the message is for the author's own run. */
47
+ /** What a log may say; the message is for the author's own run (`revealHandlerErrors`). */
48
48
  readonly reason: CapabilityRefusal
49
49
 
50
50
  constructor(reason: CapabilityRefusal, message: string) {
@@ -269,14 +269,18 @@ export class Within<D extends string, A extends string> implements WithinCapabil
269
269
  principal: string,
270
270
  values: readonly string[] | 'all',
271
271
  containers: readonly ContainerGrant[],
272
+ contained: readonly ContainerGrant[],
272
273
  ) {
273
274
  if (token !== MINT) {
274
275
  throw new CapabilityRefusedError('not_minted', 'a Within is minted by the framework only; declare the access form in fabrika.contract.ts')
275
276
  }
276
277
  const held = values === 'all' ? freeze([]) : containerGrantsOf(containers)
278
+ const inside = values === 'all' ? freeze([]) : containerGrantsOf(contained)
277
279
  let count = values === 'all' ? 0 : values.length
278
- for (let index = 0; index < held.length; index++) {
279
- count += held[index]?.values.length ?? 0
280
+ for (const group of [held, inside]) {
281
+ for (let index = 0; index < group.length; index++) {
282
+ count += group[index]?.values.length ?? 0
283
+ }
280
284
  }
281
285
  if (count > MAX_WITHIN_VALUES) {
282
286
  throw new CapabilityLimitError(
@@ -292,6 +296,7 @@ export class Within<D extends string, A extends string> implements WithinCapabil
292
296
  principal,
293
297
  values: values === 'all' ? 'all' : copyOf(values),
294
298
  containers: held,
299
+ contained: inside,
295
300
  })
296
301
  this.#frame = frame
297
302
  this.#issuer = issuer
@@ -315,6 +320,11 @@ export class Within<D extends string, A extends string> implements WithinCapabil
315
320
  return this.#grant.containers
316
321
  }
317
322
 
323
+ /** The dimensions inside this one in which the caller holds the action: `note → [n1]` for a workspace list. */
324
+ get contained(): readonly ContainerGrant[] {
325
+ return this.#grant.contained
326
+ }
327
+
318
328
  static {
319
329
  readWithin = (value) =>
320
330
  typeof value === 'object' && value !== null && #grant in value ? { grant: value.#grant, frame: value.#frame, issuer: value.#issuer } : undefined
@@ -434,6 +444,7 @@ export interface CapabilityMint {
434
444
  principal: string,
435
445
  values: readonly string[] | 'all',
436
446
  containers?: readonly ContainerGrant[],
447
+ contained?: readonly ContainerGrant[],
437
448
  ): Within<D, A>
438
449
  app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A>
439
450
  }
@@ -469,8 +480,9 @@ export function createCapabilityIssuer(): CapabilityIssuer {
469
480
  principal: string,
470
481
  values: readonly string[] | 'all',
471
482
  containers: readonly ContainerGrant[] = [],
483
+ contained: readonly ContainerGrant[] = [],
472
484
  ): Within<D, A> {
473
- return new Within(MINT, issuer, frame, dimension, action, principal, values, containers)
485
+ return new Within(MINT, issuer, frame, dimension, action, principal, values, containers, contained)
474
486
  },
475
487
  app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A> {
476
488
  return new AppCapability(MINT, issuer, frame, action, principal)