@fabrika/app 0.9.0-cloudflare.3 → 0.9.0-dev.10

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 (54) hide show
  1. package/package.json +9 -9
  2. package/skill/SKILL.md +6 -3
  3. package/skill/references/app-setup.md +8 -8
  4. package/skill/references/dev.md +3 -1
  5. package/skill/references/endpoint.md +9 -9
  6. package/skill/references/errors.md +42 -34
  7. package/skill/references/files.md +4 -2
  8. package/skill/references/jobs.md +18 -12
  9. package/skill/references/table-and-migration.md +31 -4
  10. package/skill/references/tests.md +22 -10
  11. package/src/bun.ts +0 -10
  12. package/src/cloudflare/import.ts +3 -212
  13. package/src/contract/artifact-schema.ts +1 -6
  14. package/src/contract/build.ts +10 -33
  15. package/src/contract/capability-cases.ts +30 -0
  16. package/src/contract/containers.ts +19 -0
  17. package/src/contract/group.ts +1 -10
  18. package/src/contract/index.ts +1 -0
  19. package/src/contract/kit.ts +1 -2
  20. package/src/files/handle.ts +2 -1
  21. package/src/files/kinds.ts +1 -1
  22. package/src/implement/boot.ts +12 -30
  23. package/src/implement/capability.ts +1 -4
  24. package/src/implement/dispatch.ts +8 -5
  25. package/src/implement/egress.ts +8 -367
  26. package/src/implement/failures.ts +42 -3
  27. package/src/implement/faults.ts +4 -1
  28. package/src/implement/invocation.ts +13 -11
  29. package/src/implement/tokens.ts +4 -2
  30. package/src/implement/types.ts +22 -4
  31. package/src/jobs/runner.ts +32 -20
  32. package/src/testing/endpoint-access.ts +30 -23
  33. package/src/testing/index.ts +1 -1
  34. package/src/testing/kit.ts +6 -2
  35. package/src/testing/policy-isolation.ts +2 -2
  36. package/types/src/cloudflare/import.d.ts +1 -12
  37. package/types/src/contract/capability-cases.d.ts +9 -0
  38. package/types/src/contract/containers.d.ts +3 -0
  39. package/types/src/contract/group.d.ts +1 -9
  40. package/types/src/contract/index.d.ts +1 -0
  41. package/types/src/contract/kit.d.ts +2 -2
  42. package/types/src/files/handle.d.ts +2 -1
  43. package/types/src/implement/boot.d.ts +6 -9
  44. package/types/src/implement/capability.d.ts +1 -3
  45. package/types/src/implement/dispatch.d.ts +1 -2
  46. package/types/src/implement/egress.d.ts +1 -36
  47. package/types/src/implement/failures.d.ts +21 -2
  48. package/types/src/implement/faults.d.ts +4 -1
  49. package/types/src/implement/invocation.d.ts +6 -5
  50. package/types/src/implement/types.d.ts +25 -5
  51. package/types/src/jobs/runner.d.ts +14 -8
  52. package/types/src/testing/endpoint-access.d.ts +4 -3
  53. package/types/src/testing/index.d.ts +1 -1
  54. package/types/src/testing/kit.d.ts +6 -2
@@ -2,6 +2,8 @@
2
2
  // declares `signs`, and the verification of each token field of a procedure's input and `http.query` as they are parsed.
3
3
  // A token is `<key id>.<payload>.<signature>`: the payload is the purpose, the expiry and the claims as base64url JSON,
4
4
  // and the signature an HMAC-SHA256 over the key id and the payload, so a token of one purpose never passes as another.
5
+ // The signature is compared as its text: its last character carries two padding bits that decode to nothing, so
6
+ // comparing decoded bytes would let four spellings of one token verify, and a token has exactly one.
5
7
 
6
8
  import { type ContractArtifact, FABRIKA_TOKEN_KEYS, type SchemaShape } from '@fabrika/auth-core'
7
9
  import { createHmac, timingSafeEqual } from 'node:crypto'
@@ -129,8 +131,8 @@ export class SignedTokens {
129
131
  if (rest.length > 0 || key === undefined || declared === undefined || !BASE64URL.test(payload) || !BASE64URL.test(given)) {
130
132
  throw invalid()
131
133
  }
132
- const expected = Buffer.from(signature(key, payload), 'base64url')
133
- const presented = Buffer.from(given, 'base64url')
134
+ const expected = Buffer.from(signature(key, payload))
135
+ const presented = Buffer.from(given)
134
136
  if (presented.byteLength !== expected.byteLength || !timingSafeEqual(presented, expected)) {
135
137
  throw invalid()
136
138
  }
@@ -93,10 +93,28 @@ type LinksContext<C, Acc> = TargetOf<Acc> extends readonly [infer D extends stri
93
93
  /** What a procedure's context carries for its access form in this contract. */
94
94
  export type ContractContext<C, Acc> = AccessContext<Acc> & MembersContext<C, Acc> & LinksContext<C, Acc>
95
95
 
96
- /** The input without the `from` field: the only copy of that id a handler has is the checked capability. */
97
- export type HandlerInput<I, Acc> = Acc extends { readonly from: infer F extends string }
98
- ? { readonly [K in keyof InputOf<I> as K extends F ? never : K]: InputOf<I>[K] }
99
- : InputOf<I>
96
+ /**
97
+ * The `from` fields an access form reads: its own, or under `capabilities` each `on` and `in` one's (`over` reads none).
98
+ * The runtime removes the same fields (`#access` and `#capabilities` in `dispatch.ts`). A widened `from` (`string`, or
99
+ * the union of the input's string fields an access widened to its declared constraint carries) removes every field it
100
+ * may name: the runtime removes one of them, and the declaration refuses such an access anyway.
101
+ */
102
+ type FromFields<Acc> = Acc extends { readonly capabilities: infer C } ? { [N in keyof C]: FieldRead<C[N]> }[keyof C] : FieldRead<Acc>
103
+
104
+ /** The field one access form reads, for each member of a form typed as a union; `never` for a form that reads none. */
105
+ type FieldRead<F> = F extends { readonly from: infer K extends string } ? K : never
106
+
107
+ /**
108
+ * The input as the runtime hands it to the handler: without the `from` fields and frozen under a form that reads one and
109
+ * under every `capabilities` access (`Object.freeze` in `takeField` and `#capabilities`); as parsed under any other.
110
+ */
111
+ export type HandlerInput<I, Acc> = IsAny<Acc> extends true ? InputOf<I>
112
+ : Acc extends { readonly capabilities: unknown } ? Without<InputOf<I>, FromFields<Acc>>
113
+ : Acc extends unknown ? [FromFields<Acc>] extends [never] ? InputOf<I> : Without<InputOf<I>, FromFields<Acc>>
114
+ : never
115
+
116
+ /** `In` without the fields `F`, read-only: the only copy of each removed id a handler has is the checked capability. */
117
+ type Without<In, F> = { readonly [K in keyof In as K extends F ? never : K]: In[K] }
100
118
 
101
119
  export type Handler<In, Ctx, O extends Schema> = (args: { readonly input: In; readonly ctx: Ctx }) => z.input<O> | Promise<z.input<O>>
102
120
 
@@ -34,8 +34,8 @@ import {
34
34
  type Within,
35
35
  } from '../implement/capability'
36
36
  import { admitInvocation, type InvocationAdmission } from '../implement/dispatch'
37
- import { type PublicEgressRules, runAsSite, siteEgress } from '../implement/egress'
38
- import { failureCode, type FailureReason, failureReason } from '../implement/failures'
37
+ import { runAsSite } from '../implement/egress'
38
+ import { failureCode, type FailureReason, failureReason, type HandlerErrorSink, reveal } from '../implement/failures'
39
39
  import { ServerFault } from '../implement/faults'
40
40
  import type { ContractDatabase } from '../implement/implement'
41
41
  import {
@@ -88,6 +88,13 @@ export type JobFailureCode =
88
88
  | 'query_refused'
89
89
  /** A capability or a handle was refused: forged, ended, of other work, or of another kind than the call takes. */
90
90
  | 'capability_refused'
91
+ /** The framework failed the attempt (`ServerFault`): its reason names why, as a request's 500 names it. */
92
+ | 'framework_fault'
93
+ /**
94
+ * The framework could not reach a service it needs (a `ServerFault` with status 503), as a request's 503 names it. IAM
95
+ * is the exception: met inside the handler as at the attempt's start, it is `iam_unavailable` or `unauthorized`.
96
+ */
97
+ | 'unavailable'
91
98
  | 'driver_failed'
92
99
  | 'crashed'
93
100
  /** IAM refused the job's key: the attempt mints no capability. */
@@ -101,7 +108,10 @@ export type JobFailureCode =
101
108
 
102
109
  export type JobRunResult =
103
110
  | { readonly status: 'succeeded'; readonly attempts: number }
104
- /** `reason` is a framework refusal's catalog key (`query_refused`, `capability_refused`), present only for one. */
111
+ /**
112
+ * `reason` is a framework failure's catalog key (`query_refused`, `capability_refused`, `framework_fault`,
113
+ * `unavailable`) or the `EmailDeliveryError` code (`mail_failed`), present only for one of those.
114
+ */
105
115
  | { readonly status: 'failed'; readonly attempts: number; readonly code: JobFailureCode; readonly reason?: string }
106
116
  /** Another run holds the lease: an overlapping run does not start. */
107
117
  | { readonly status: 'skipped' }
@@ -264,13 +274,8 @@ interface RunnerContext {
264
274
  /** The environment's signed tokens: `ctx.tokens` of a job that declares `signs`. */
265
275
  readonly tokens: SignedTokens | null
266
276
  readonly url: AppUrl
267
- /** What a job that declares `egress: 'public'` reaches; such a job reaches nothing without it. */
268
- readonly publicEgress: PublicEgressRules | null
269
277
  }
270
278
 
271
- /** Where `fabrika app dev` shows what a handler threw, on the developer's own machine; nothing else sets one. */
272
- export type HandlerErrorSink = (where: string, error: unknown) => void
273
-
274
279
  export interface JobBindingInput {
275
280
  readonly artifact: ContractArtifact
276
281
  /** The handler tree `boot` binds; a job's handler is `handlers.jobs.<name>`. */
@@ -297,7 +302,7 @@ export interface JobBindingInput {
297
302
  readonly capabilities: CapabilityAuthority
298
303
  /** Each dimension's containers, nearest first: a link's chain. */
299
304
  readonly containers: ReadonlyMap<string, readonly string[]>
300
- /** What a job's handler threw, for `fabrika app dev`; without it the error is only its fixed code. */
305
+ /** What a job attempt threw, for the author's own run; without it the error is only its fixed code. */
301
306
  readonly revealHandlerErrors?: HandlerErrorSink
302
307
  /** The transports of the jobs that declare `mailer`, which `boot` resolved. */
303
308
  readonly mail: MailTransports
@@ -305,8 +310,6 @@ export interface JobBindingInput {
305
310
  readonly tokens?: SignedTokens
306
311
  /** `ctx.url`: absolute links to the application's own procedures; without it every link is refused. */
307
312
  readonly url?: AppUrl
308
- /** The rules of public egress, which `boot` reads from the environment; without them a public job reaches nothing. */
309
- readonly publicEgress?: PublicEgressRules
310
313
  }
311
314
 
312
315
  interface BoundFrameworkJob {
@@ -417,7 +420,6 @@ export function bindJobs(input: JobBindingInput, problems: string[]): BoundJobs
417
420
  mail: input.mail,
418
421
  tokens: input.tokens ?? null,
419
422
  url: input.url ?? appUrl(input.artifact, null),
420
- publicEgress: input.publicEgress ?? null,
421
423
  // A job's kicks run only after the job is bound, so `kick` below is defined by then.
422
424
  kick: (name: string) => kick(name),
423
425
  })
@@ -1250,12 +1252,13 @@ async function attemptOnce(
1250
1252
  if (site === null) {
1251
1253
  await job.handler({ ctx })
1252
1254
  } else {
1253
- await runAsSite(`job '${job.name}'`, siteEgress(site.egress, context.publicEgress), async () => await job.handler({ ctx }))
1255
+ await runAsSite(`job '${job.name}'`, site.egress, async () => await job.handler({ ctx }))
1254
1256
  }
1255
1257
  kicked.recorder = kicks
1256
1258
  }).then(() => null, (error: unknown) => {
1257
1259
  const failed = failureOf(error, job.mailer === null ? null : (context.mail[job.mailer]?.sender.capabilities ?? null))
1258
- if (failed.code === 'handler_failed') context.revealHandlerErrors?.(`job '${job.name}' attempt ${attempt}`, error)
1260
+ // What the attempt threw: the handler's own error, or a framework failure whose message the log line withholds.
1261
+ if ('thrown' in failed) reveal(context.revealHandlerErrors, `job '${job.name}' attempt ${attempt}`, error)
1259
1262
  return failed
1260
1263
  })
1261
1264
  // Its settlement, not only the end of its frame: a drain waits for a handler that outlived the attempt.
@@ -1275,8 +1278,9 @@ async function attemptOnce(
1275
1278
  const UNKNOWN_TRANSPORT: EmailSenderCapabilities = Object.freeze({ idempotent: false, confirmation: 'queued', maxBatch: 1 })
1276
1279
 
1277
1280
  /**
1278
- * By class, never by name: an application error can call itself anything. A refusal is classified as a request's is
1279
- * (`failureCode`), so both name it alike; every other thrown value is `handler_failed`.
1281
+ * By class, never by name: an application error can call itself anything. A framework failure (a refusal or a
1282
+ * `ServerFault`) is classified as a request's is (`failureCode`), so both name it alike, with its reason; every other
1283
+ * thrown value, an `HttpError` of a 5xx status included, is `handler_failed`.
1280
1284
  */
1281
1285
  function failureOf(error: unknown, transport: EmailSenderCapabilities | null): JobFailure {
1282
1286
  if (error instanceof LeaseLostError) {
@@ -1287,10 +1291,14 @@ function failureOf(error: unknown, transport: EmailSenderCapabilities | null): J
1287
1291
  // ADR-0019's one retry rule: a repeat over a non-idempotent transport may deliver the message twice.
1288
1292
  return { code: 'mail_failed', why: { reason: error.code, text }, final: !mayRetryDelivery(error, transport ?? UNKNOWN_TRANSPORT) }
1289
1293
  }
1294
+ if (error instanceof ServerFault && (error.reason === 'iam_unavailable' || error.reason === 'workload_unauthorized')) {
1295
+ // IAM met inside the handler is named as at the attempt's start, so an alert on the code sees both.
1296
+ return { code: error.reason === 'iam_unavailable' ? 'iam_unavailable' : 'unauthorized', why: null, thrown: error, final: false }
1297
+ }
1290
1298
  const code = failureCode(error)
1291
- return code === 'query_refused' || code === 'capability_refused'
1292
- ? { code, why: failureReason(error), thrown: error, final: false }
1293
- : { code: 'handler_failed', why: null, thrown: error, final: false }
1299
+ return code === 'handler_failed' || code === 'handler_status'
1300
+ ? { code: 'handler_failed', why: null, thrown: error, final: false }
1301
+ : { code, why: failureReason(error), thrown: error, final: false }
1294
1302
  }
1295
1303
 
1296
1304
  function jobContext(
@@ -1344,6 +1352,8 @@ function jobContext(
1344
1352
  checkAction(action)
1345
1353
  return context.mint.app(frame, action, principal.id)
1346
1354
  }
1355
+ // What `checkAction` admits: a job mints each of these over the whole application.
1356
+ const holds = job.artifact.actions.filter((action) => permits([...perms], action))
1347
1357
  return Object.freeze({
1348
1358
  principal,
1349
1359
  runId: frame.id,
@@ -1362,6 +1372,7 @@ function jobContext(
1362
1372
  ref,
1363
1373
  app,
1364
1374
  periodAt(job.schedule, new Date()) ?? undefined,
1375
+ holds,
1365
1376
  )),
1366
1377
  ...(job.links === null || context.membership === null ? {} : { links: jobLinksOf(job, job.links, context.membership, frame, context) }),
1367
1378
  ...(job.mailer === null ? {} : { mail: jobMailOf(job, job.mailer, frame, signal, context) }),
@@ -1439,11 +1450,12 @@ function kitJobContext(
1439
1450
  ref: (action: string, dimension: string, id: string, using: Session) => Promise<Ref<string, string>>,
1440
1451
  app: (action: string) => AppCapability<string>,
1441
1452
  tickMs: number | undefined,
1453
+ holds: readonly string[],
1442
1454
  ): Readonly<Record<string, unknown>> {
1443
1455
  // One attempt's files: what it reads, puts and writes, inside its transactions and outside them, belongs to it.
1444
1456
  const work = new FileWork(frame, frame.id)
1445
1457
  const binding = kinds?.binding(work)
1446
- const reads = jobHandles(frame, data, site, principal, 'job', async () => data.direct(), () => false, tickMs, binding)
1458
+ const reads = jobHandles(frame, data, site, principal, 'job', async () => data.direct(), () => false, tickMs, binding, holds)
1447
1459
  const job = `job '${name}'`
1448
1460
  const putAndOpen = (check: () => void) => storedFilesHandle(kinds, work, { where: job, check, writes: true })
1449
1461
  return {
@@ -7,6 +7,7 @@
7
7
  import {
8
8
  type AccessForm,
9
9
  type Caller,
10
+ type CapabilitiesRequirement,
10
11
  type ContractArtifact,
11
12
  type EndpointDirectory,
12
13
  endpointDirectory,
@@ -25,6 +26,7 @@ import { basename } from 'node:path'
25
26
  import { fileURLToPath } from 'node:url'
26
27
  import { z } from 'zod/v4'
27
28
  import type { RpcFetch } from '../client/transport'
29
+ import { deniedCaseRuledOutBy } from '../contract/capability-cases'
28
30
  import { compileContract } from '../contract/compile'
29
31
  import {
30
32
  FILE_INPUT_PART,
@@ -101,9 +103,10 @@ export interface EndpointAccessKit {
101
103
  global(endpoint: string, input: Readonly<Record<string, unknown>>): Promise<ReachOutcome>
102
104
  /**
103
105
  * One capability of an endpoint of several, refused while every other one passes: the caller holds each other one's
104
- * action in a scope of its own and addresses its object or value there (or, for `over`, holds the action globally).
105
- * For an `on` or `in` capability it also holds the named one's action in its own scope and addresses the other's
106
- * object (404) or value (403); for `over` it holds the named action nowhere (403). `seed` is the named one's.
106
+ * action in a scope of its own and addresses its object or value there. For an `on` or `in` capability it also holds
107
+ * the named one's action in its own scope and addresses the other's object (404) or value (403); for `over` it holds
108
+ * the named action only where the others need it (403). An `over` capability without a denied case
109
+ * (`deniedCaseRuledOutBy`) throws. `seed` is the named one's.
107
110
  */
108
111
  capability(endpoint: string, capability: string, input: Readonly<Record<string, unknown>>, seed?: Seed): Promise<DeniedOutcome>
109
112
  /**
@@ -393,14 +396,16 @@ export function endpointAccessKit<DB, P>(
393
396
  )
394
397
  }
395
398
 
396
- /** An endpoint of several capabilities, as one `ActionEndpoint` per capability, by its name. */
397
- const capabilitiesEndpointOf = (id: string): ReadonlyMap<string, ActionEndpoint> => {
399
+ /** An endpoint of several capabilities: its requirement, and one `ActionEndpoint` per capability, by its name. */
400
+ const capabilitiesEndpointOf = (
401
+ id: string,
402
+ ): { readonly requirement: CapabilitiesRequirement; readonly capabilities: ReadonlyMap<string, ActionEndpoint> } => {
398
403
  const row = kit.artifact.endpoints.find((candidate) => candidate.id === id)
399
404
  const requirement = row?.requirement
400
405
  if (row === undefined || requirement?.kind !== 'capabilities') {
401
406
  throw new Error(`${id} is not an endpoint of the contract with several capabilities`)
402
407
  }
403
- return new Map(
408
+ const capabilities = new Map(
404
409
  Object.entries(requirement.capabilities).map(([name, capability]) => [name, {
405
410
  id: row.id,
406
411
  link: null,
@@ -415,6 +420,7 @@ export function endpointAccessKit<DB, P>(
415
420
  links: [],
416
421
  }]),
417
422
  )
423
+ return { requirement, capabilities }
418
424
  }
419
425
 
420
426
  const globalEndpointOf = (id: string): ActionEndpoint => {
@@ -434,21 +440,14 @@ export function endpointAccessKit<DB, P>(
434
440
  return parent?.mode === 'dimension' ? (parent.container?.dimension ?? parent.dimension) : undefined
435
441
  }
436
442
 
437
- const callerFor = (
438
- row: ActionEndpoint,
439
- grants: readonly Grant[],
440
- global: readonly { readonly action: string }[] = [],
441
- ): { readonly caller: TestCaller; readonly fetch: RpcFetch } => {
442
- const asGrants: TestGrant<AnyContract>[] = [
443
- ...grants.map((grant) => ('role' in grant ? { role: grant.role, scope: grant.scope } : { action: grant.action, scope: grant.scope })),
444
- ...global,
445
- ]
443
+ /** A new caller holding `grants`; an action without a scope is held globally. */
444
+ const callerFor = (row: ActionEndpoint, grants: readonly TestGrant<AnyContract>[]): { readonly caller: TestCaller; readonly fetch: RpcFetch } => {
446
445
  if (row.callers.some((caller) => caller === 'human')) {
447
- const caller = kit.testCaller(asGrants)
446
+ const caller = kit.testCaller(grants)
448
447
  return { caller, fetch: kit.browser(caller) }
449
448
  }
450
449
  if (row.callers.some((caller) => caller === 'machine')) {
451
- const caller = kit.testCaller(asGrants, { kind: 'machine' })
450
+ const caller = kit.testCaller(grants, { kind: 'machine' })
452
451
  return {
453
452
  caller,
454
453
  fetch: (input, init) => {
@@ -951,36 +950,44 @@ export function endpointAccessKit<DB, P>(
951
950
  },
952
951
  async global(endpoint, input) {
953
952
  const row = globalEndpointOf(endpoint)
954
- const { status } = await askAs(row, callerFor(row, [], [{ action: row.action }]).fetch, input)
953
+ const { status } = await askAs(row, callerFor(row, [{ action: row.action }]).fetch, input)
955
954
  // Neither form refuses with 404, so a 404 is the handler's own answer (a row the sampled input names is missing).
956
955
  return status >= 500 || status === 401 || status === 403 ? { answered: false, status } : { answered: true }
957
956
  },
958
957
  async capability(endpoint, capability, input, seed = {}) {
959
- const capabilities = capabilitiesEndpointOf(endpoint)
958
+ const { requirement, capabilities } = capabilitiesEndpointOf(endpoint)
960
959
  const named = capabilities.get(capability)
961
960
  if (named === undefined) {
962
961
  throw new Error(`${endpoint} has no capability '${capability}' (capabilities: ${[...capabilities.keys()].join(', ')})`)
963
962
  }
963
+ const { access } = named
964
+ const ruledOutBy = deniedCaseRuledOutBy(requirement.capabilities, capability, kit.artifact.dimensions)
965
+ if (ruledOutBy !== undefined) {
966
+ throw new Error(
967
+ `${endpoint}: capability '${capability}' has no denied case: '${ruledOutBy}' needs its action too, ${named.action}, in a related dimension, so every caller that passes it is answered the list`,
968
+ )
969
+ }
964
970
  const grants: Grant[] = []
965
- const global: { readonly action: string }[] = []
966
971
  let asked = input
967
972
  for (const [name, other] of capabilities) {
968
973
  if (name === capability) continue
974
+ // Each other one in a scope of its own, apart from the named one's: a global grant would also meet the named
975
+ // capability when both share an action. An `over` one lists from any value it is held in, so a fresh uuid does,
976
+ // a valid key whether the dimension's is text or uuid, and no row of it is seeded.
969
977
  if (other.access.form === 'over') {
970
- global.push({ action: other.action })
978
+ grants.push({ action: other.action, scope: { type: other.access.dimension, value: crypto.randomUUID() } })
971
979
  } else if (other.access.form === 'on' || other.access.form === 'in') {
972
980
  const { own } = await scopesOf(other.action, other.access.dimension, fieldOf(other.input, other.access.from), {}, input)
973
981
  asked = addressing(asked, other.access.from, own)
974
982
  grants.push(...own.grants)
975
983
  }
976
984
  }
977
- const { access } = named
978
985
  if (access.form === 'on' || access.form === 'in') {
979
986
  const scopes = await scopesOf(named.action, access.dimension, fieldOf(named.input, access.from), seed, input, pinningOf(endpoint))
980
987
  asked = addressing(asked, access.from, scopes.other)
981
988
  grants.push(...scopes.own.grants)
982
989
  }
983
- const { status } = await askAs(named, callerFor(named, grants, global).fetch, asked)
990
+ const { status } = await askAs(named, callerFor(named, grants).fetch, asked)
984
991
  return { status }
985
992
  },
986
993
  }
@@ -7,8 +7,8 @@ export type { IamMembershipRpc } from '@fabrika/auth-core'
7
7
  export { type MemoryEmail, MemoryEmailSender, type MemoryHandoff } from '@fabrika/email/memory'
8
8
  export type { FileScanner } from '../files/scan'
9
9
  export type { ChallengeFetch } from '../implement/challenge'
10
+ export type { HandlerErrorSink } from '../implement/failures'
10
11
  export { mailKeyPrefix, type MailKeyScope, transportMailKey } from '../jobs/mail'
11
- export type { HandlerErrorSink } from '../jobs/runner'
12
12
  export type {
13
13
  LabelledTestCaller,
14
14
  LinkTestCaller,
@@ -53,11 +53,11 @@ import { boot, type BootOptions, type ContractApp } from '../implement/boot'
53
53
  import { type ChallengeFetch, MINIMAL_CHALLENGE_WORK } from '../implement/challenge'
54
54
  import { type ConnectFetch, connectVariables } from '../implement/connect'
55
55
  import type { SpaAssets } from '../implement/dispatch'
56
+ import type { HandlerErrorSink } from '../implement/failures'
56
57
  import type { ApplicationEnvironment, ContractImplementation } from '../implement/implement'
57
58
  import { readTokenKeys, SignedTokens } from '../implement/tokens'
58
59
  import type { WorkloadKindOf, WorkloadTokenSource } from '../implement/workload'
59
60
  import type { MailKeyScope } from '../jobs/mail'
60
- import type { HandlerErrorSink } from '../jobs/runner'
61
61
  import type { JobRunOptions, JobRunResult } from '../jobs/runner'
62
62
  import {
63
63
  type LabelledTestCaller,
@@ -136,7 +136,11 @@ export interface TestKitOptions {
136
136
  readonly connect?: Readonly<Record<string, TestConnection>>
137
137
  /** What answers a public procedure's challenge verification in place of the provider: a stand-in for its siteverify. */
138
138
  readonly challengeFetch?: ChallengeFetch
139
- /** What a job's handler threw, shown on the developer's own machine: `fabrika app dev` sets it, a test need not. */
139
+ /**
140
+ * Where the author's own run shows what a request's 5xx or a job attempt threw, whole: a handler's own error, or a
141
+ * framework failure (a refused `ctx.sql`, a capability refusal, a `ServerFault`) whose message the log line withholds.
142
+ * `fabrika app dev` sets it; a test passes one to see why a call failed. Off unless passed.
143
+ */
140
144
  readonly revealHandlerErrors?: HandlerErrorSink
141
145
  /**
142
146
  * The stand-in for every job's mail transport; a new `MemoryEmailSender` by default. Pass one with other capabilities
@@ -690,7 +690,7 @@ export function policyIsolationKit<C extends AnyContract, DB, P>(
690
690
  required('insert')
691
691
  const worlds = await seed()
692
692
  const api = session(worlds)
693
- const tag = tagged(await postgres.sampleInsert(tables, table))
693
+ const tag = tagged(await postgres.sampleInsert(tables, table, worlds[into]))
694
694
  return wrote(() => api.insert({ scope: worlds[into].scope, tag }))
695
695
  },
696
696
  async update(row) {
@@ -801,7 +801,7 @@ export function policyIsolationKit<C extends AnyContract, DB, P>(
801
801
  required('insert')
802
802
  const worlds = await seed()
803
803
  const api = session(worlds)
804
- const tag = tagged(await postgres.sampleInsert(tables, table))
804
+ const tag = tagged(await postgres.sampleInsert(tables, table, worlds[into]))
805
805
  const { parent: parentKey } = address(worlds, into)
806
806
  return wrote(() => api.insert({ parent: parentKey, tag }))
807
807
  },
@@ -43,16 +43,5 @@ export declare function importInProgress(storage: {
43
43
  * generation and mode it was admitted under still hold when it commits.
44
44
  */
45
45
  export declare function importStep(target: ImportTarget, barrier: MaintenanceBarrier, step: OpsImportRequest): Promise<Response>;
46
- /**
47
- * The schema `planOpsDump` reads, from the PRAGMAs workerd admits, of every table a dump holds. An `INITIALLY DEFERRED`
48
- * clause is read from the table's SQL outside its quotes and comments, and marks every foreign key of its table; the
49
- * names a `CHECK` reads come from the same SQL (`checkNamesOf`).
50
- */
46
+ /** The schema `planOpsDump` reads, of every table a dump holds (`describeOpsDumpSchema`). */
51
47
  export declare function describeDumpSchema(storage: SqliteStorage): OpsDumpSchema;
52
- /**
53
- * The names the `CHECK` clauses of a table's `sql` read: every word and quoted identifier between a `CHECK` keyword's
54
- * parentheses, ASCII-lowercase, keywords and numbers included, so it lists at least every column a `CHECK` reads. A
55
- * string literal and a comment name nothing; a double-quoted string, which SQLite may read as either, counts as a name.
56
- * `null` when the text does not scan (an unclosed quote, comment or parenthesis), which counts as naming every column.
57
- */
58
- export declare function checkNamesOf(sql: string): string[] | null;
@@ -0,0 +1,9 @@
1
+ import type { CapabilityRequirement, DimensionArtifact } from '@fabrika/auth-core';
2
+ /**
3
+ * The capability that rules out `name`'s denied case, or `undefined` when `name` has one. Only an `over` capability
4
+ * loses it: to another capability that needs the same action on its dimension, on a container of it or on a dimension
5
+ * inside it. Every caller that passes that other one holds the action where the runtime lists the `over` dimension from
6
+ * (a value of it, of a container, or of a dimension inside it, through the same `containersOf`), so none is refused the
7
+ * list. Another one on an unrelated dimension leaves the case: a caller holding the action only there is refused (403).
8
+ */
9
+ export declare function deniedCaseRuledOutBy(capabilities: Readonly<Record<string, CapabilityRequirement>>, name: string, dimensions: Readonly<Record<string, DimensionArtifact>>): string | undefined;
@@ -0,0 +1,3 @@
1
+ import type { DimensionArtifact } from '@fabrika/auth-core';
2
+ /** Every dimension's containers, nearest first (`note → [workspace, organization]`); `buildArtifact` refuses a cycle. */
3
+ export declare function containersOf(dimensions: Readonly<Record<string, DimensionArtifact>>): ReadonlyMap<string, readonly string[]>;
@@ -74,15 +74,7 @@ export type SignsField<Sg, Purposes extends string> = {
74
74
  * `fetch` refuses any other while the site runs; a public procedure declares none.
75
75
  */
76
76
  export interface EgressField {
77
- readonly egress?: readonly `https://${string}`[] | Unavailable<"egress: 'public' is a cron job's only: record a row and kick a job that declares it">;
78
- }
79
- /**
80
- * A cron job's `egress`: its exact HTTPS origins, or `'public'`, every public host over HTTPS or HTTP on its default
81
- * port, for a job that calls the websites its operators name (ADR-0071). The guard refuses IP addresses, local and
82
- * internal names and the installation's own hosts, checks each redirect, and bounds each request's time and body.
83
- */
84
- export interface JobEgressField {
85
- readonly egress?: readonly `https://${string}`[] | 'public';
77
+ readonly egress?: readonly `https://${string}`[];
86
78
  }
87
79
  /** Each purpose `signs` names is one of `defineApp`'s `tokens`. */
88
80
  type KnownPurposes<Sg, Purposes extends string> = Sg extends readonly (infer P extends string)[] ? [Exclude<P, Purposes>] extends [never] ? LiteralList<Sg> : Unavailable<`signs names ${ListOf<Exclude<P, Purposes>>}, which defineApp's tokens do not declare`> : unknown;
@@ -1,6 +1,7 @@
1
1
  export { contractArtifactSchema, parseContractArtifact, schemaShapeSchema } from './artifact-schema';
2
2
  export { type Attachment, attachment, type AttachmentBrand, type AttachmentMark, attachmentOf, type AttachmentOptions, attachmentOutput, } from './attachment';
3
3
  export { buildArtifact } from './build';
4
+ export { deniedCaseRuledOutBy } from './capability-cases';
4
5
  export { compileContract, describeContract } from './compile';
5
6
  export { type ConnectSnapshot, describeSnapshot, exportDescription, exportDescriptionSchema, incompatibleChanges, incompatibleMountChanges, parseExportDescription, type SnapshotProcedure, } from './connect';
6
7
  export type * from './context';
@@ -4,7 +4,7 @@ import type { z } from 'zod/v4';
4
4
  import type { Declared, JobKitContext, KickContext, KitImports, KitTypes, NoTablesIndex, SqlMode, TokensContext, WebhookKitContext } from './context';
5
5
  import { type ExportAccessDeclaration, type ImportDeclaration, type LinkAccessDeclaration, type ProcedureType } from './declaration';
6
6
  import { type Contract, type CreatableDimension, type CronJob, type Export, type InputSchema, type JobLimitsOption, type Kit, type LinkMount, type NotLoose, type Path, type ProcedureTree, type RpcMount, type Schema, type Surface, type WebhookMount } from './define';
7
- import type { DeclaredFields, EgressField, Endpoint, ExportKit, Group, GroupBuild, GroupInput, GroupKit, JobEgressField, KicksField, LimitsOption, LinkGroupKit, ListOf, PendingIn, SignsField } from './group';
7
+ import type { DeclaredFields, EgressField, Endpoint, ExportKit, Group, GroupBuild, GroupInput, GroupKit, KicksField, LimitsOption, LinkGroupKit, ListOf, PendingIn, SignsField } from './group';
8
8
  import type { TokenPurposes } from './token';
9
9
  import type { AnyAppVocabulary, AppVocabulary } from './vocabulary';
10
10
  /** Fields a builder sets itself: an options object that carries one does not type-check. */
@@ -31,7 +31,7 @@ export type CronOptions<Acts, S, U, Is, Ix extends AnyDbIndex, M = never, Ks = n
31
31
  readonly actions: Acts;
32
32
  readonly limits?: JobLimitsOption;
33
33
  readonly retries?: number;
34
- } & DeclaredFields<S, U, never, Is, Ix> & MailerField<M> & KicksField<Ks> & SignsField<Sg, Purposes> & JobEgressField;
34
+ } & DeclaredFields<S, U, never, Is, Ix> & MailerField<M> & KicksField<Ks> & SignsField<Sg, Purposes> & EgressField;
35
35
  /** The mail transport a job reaches, inferred from its optional field and then required, like a declared field. */
36
36
  type MailerField<M> = {
37
37
  /** `'installation'`: the installation's mail transport; `'own'`: the application's own. */
@@ -84,7 +84,8 @@ export type StoredFileBody = Uint8Array | ReadableStream<Uint8Array> | Blob;
84
84
  /**
85
85
  * `ctx.files.put` and `ctx.files.open`: the stored files of a site (`c.files` kinds). A put stages a file this request
86
86
  * holds; writing its reference into a file column is what keeps it. `open` reads a live file whose reference this
87
- * request holds and may read: an input file, a put, or a file column read under its table's read action.
87
+ * request holds and may read: an input file, a put, or a file column read under its table's read action (or claimed by
88
+ * a job that holds it).
88
89
  */
89
90
  export interface StoredFilesHandle {
90
91
  /** A file of `kind` with these bytes, which must be of `type`; it is pending until a column references it. */
@@ -6,12 +6,12 @@ import type { FileObjectStore } from '@fabrika/platform';
6
6
  import type { RequestExecutionContext } from '../fetch';
7
7
  import { type FileScanner } from '../files/scan';
8
8
  import { type MailStandIn } from '../jobs/mail';
9
- import { type ContractJobs, type HandlerErrorSink } from '../jobs/runner';
9
+ import { type ContractJobs } from '../jobs/runner';
10
10
  import type { ChallengeFetch, ChallengeWork } from './challenge';
11
11
  import { type ConnectFetch } from './connect';
12
12
  import { type SpaAssets } from './dispatch';
13
- import { type HostResolver } from './egress';
14
13
  import type { CapturedEnvironment } from './environment';
14
+ import { type HandlerErrorSink } from './failures';
15
15
  import type { ContractImplementation } from './implement';
16
16
  import { type WorkloadTokenSource } from './workload';
17
17
  /** Where the token verifier gets IAM's public keys: the IAM binding on Cloudflare, the issuer's JWKS elsewhere. */
@@ -64,11 +64,6 @@ export interface BootOptions {
64
64
  * with a job or a webhook does not boot.
65
65
  */
66
66
  readonly workloadTokens?: WorkloadTokenSource;
67
- /**
68
- * Resolves a host name to its addresses, which the Bun adapter supplies (`node:dns`): a cron job's public egress then
69
- * refuses a public name of a private address before each hop. A Worker exposes no resolution and passes none.
70
- */
71
- readonly resolveHost?: HostResolver;
72
67
  /** What posts a report to Operations' ingest; `fetch` by default. */
73
68
  readonly operationsFetch?: (request: Request) => Promise<Response>;
74
69
  /** What asks a public procedure's challenge provider to verify a token; `fetch` by default. */
@@ -84,8 +79,10 @@ export interface BootOptions {
84
79
  */
85
80
  readonly challengeWork?: ChallengeWork;
86
81
  /**
87
- * The developer's own machine only (`fabrika app dev`): what a job's handler threw, which every log of a deployed
88
- * application withholds because it may carry a credential.
82
+ * 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
83
+ * attempt threw, whole, beside the code and reason its log line names: a handler's own error, or a framework failure
84
+ * (a refusal of the data layer or of a capability, a `ServerFault`) with its message. Every log of a deployed
85
+ * application withholds both, because either may carry request data or a credential (ADR-0059).
89
86
  */
90
87
  readonly revealHandlerErrors?: HandlerErrorSink;
91
88
  /** The providers `FABRIKA_EMAIL_PROVIDER` may name for the jobs that declare `mailer: 'installation'`; the built-in ones by default. */
@@ -11,8 +11,6 @@ export declare const CAPABILITY_REFUSALS: {
11
11
  readonly undeclared_binding: "the site named a webhook it does not declare in binds";
12
12
  readonly undeclared_signs: "the site signed a token of a purpose it does not declare in signs, or for longer than the purpose allows";
13
13
  readonly undeclared_egress: "the site called an origin it does not declare in egress";
14
- readonly refused_egress: "the site's public egress refused the host: an IP address, a local or internal name, a non-default port, a host of this installation, or a name that resolves to a private address";
15
- readonly oversized_egress: "a response to the site's public egress was larger than it reads";
16
14
  readonly wrong_binding: "a webhook binding was handed a capability of another kind or dimension than the webhook is bound to";
17
15
  readonly missing_id: "the job named an object without an id";
18
16
  readonly wrong_capability: "an operation was handed a capability of another dimension or action than it needs";
@@ -21,7 +19,7 @@ export type CapabilityRefusal = keyof typeof CAPABILITY_REFUSALS;
21
19
  /** A capability that is forged, from a request that has ended, or from another request than the current one. */
22
20
  export declare class CapabilityRefusedError extends Error {
23
21
  readonly name = "CapabilityRefusedError";
24
- /** What a log may say; the message is for the author's own run. */
22
+ /** What a log may say; the message is for the author's own run (`revealHandlerErrors`). */
25
23
  readonly reason: CapabilityRefusal;
26
24
  constructor(reason: CapabilityRefusal, message: string);
27
25
  }
@@ -12,7 +12,6 @@ import type { BrowserConfig } from './browser-config';
12
12
  import { type CapabilityMint } from './capability';
13
13
  import type { ChallengeIssuer } from './challenge';
14
14
  import { type ImportWire } from './connect';
15
- import { type SiteEgress } from './egress';
16
15
  import type { FailureReports } from './failures';
17
16
  import { type HeaderPolicy } from './headers';
18
17
  import type { ContractDatabase } from './implement';
@@ -98,7 +97,7 @@ export type ServedEndpoint = {
98
97
  /** A staged-kit site, which gets `ctx.db`; a handler `implement` bound has none. */
99
98
  readonly site?: ServedSite;
100
99
  /** The origins a staged-kit site's `fetch` reaches while its handler runs; absent for a handler `implement` bound. */
101
- readonly egress?: SiteEgress;
100
+ readonly egress?: readonly string[];
102
101
  /** Its buckets and time limit; without them (a generated endpoint) no bucket and the request budget. */
103
102
  readonly admission?: ProcedureAdmission;
104
103
  /** A POST's `query`, parsed from the URL beside the body: its schema and its shape. */
@@ -1,40 +1,5 @@
1
- import { type DeclaredEgress } from '@fabrika/auth-core';
2
- /** The addresses a host name resolves to, where the runtime exposes resolution: Bun's `node:dns`, never a Worker. */
3
- export type HostResolver = (hostname: string) => Promise<readonly string[]>;
4
- /** What public egress refuses beyond what a URL alone shows (`publicEgressRefusal`). */
5
- export interface PublicEgressRules {
6
- /** The installation's own hosts, normalized: every host a framework variable names, and `FABRIKA_EGRESS_REFUSED_HOSTS`. */
7
- readonly refusedHosts: ReadonlySet<string>;
8
- /** Resolves each hop's host before it is sent, so a public name of a private address is refused; `null` on Cloudflare. */
9
- readonly resolve: HostResolver | null;
10
- }
11
- /** What one site's `fetch` reaches: its declared origins, or the rules of public egress. */
12
- export type SiteEgress = readonly string[] | PublicEgressRules;
13
- /**
14
- * The bounds of one request under public egress, the redirects it follows included. The handler's own signal still
15
- * aborts it sooner (`ctx.signal`, an `AbortSignal.timeout` of its own).
16
- */
17
- export declare const PUBLIC_EGRESS_LIMITS: {
18
- /** One request, its redirects and the reading of its body included: the abort also stops a body still streaming. */
19
- readonly timeoutMs: 60000;
20
- /** One response's body as the handler reads it; a larger one is refused, by its `Content-Length` or while it streams. */
21
- readonly maxResponseBytes: number;
22
- /** The redirects one request follows when its `redirect` mode is `follow`, each hop checked again. */
23
- readonly maxRedirects: 10;
24
- };
25
1
  /** Runs a site's handler: every `fetch` it starts reaches only `egress`. */
26
- export declare function runAsSite<T>(site: string, egress: SiteEgress, work: () => Promise<T>): Promise<T>;
27
- /**
28
- * The egress a site runs with: its declared origins, or `rules` for `'public'`. Only a cron job's runner holds rules; a
29
- * site run without them reaches nothing, though the build lets no other site declare `'public'`.
30
- */
31
- export declare function siteEgress(declared: DeclaredEgress, rules: PublicEgressRules | null): SiteEgress;
32
- /**
33
- * The rules of public egress in one environment: the hosts its framework variables name (IAM, Operations, its own
34
- * origin, the platform's receivers, the object store), the installation hosts Control hands it, and the resolver the
35
- * runtime adapter supplies.
36
- */
37
- export declare function publicEgressRules(framework: Readonly<Record<string, string>>, resolve: HostResolver | null): PublicEgressRules;
2
+ export declare function runAsSite<T>(site: string, egress: readonly string[], work: () => Promise<T>): Promise<T>;
38
3
  /**
39
4
  * `facility` with each of its methods run outside any site's scope: a framework facility a handler calls, whose own
40
5
  * requests are the platform's, not the site's.