@fabrika/app 0.9.0-dev.13 → 0.9.0-dev.15

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 (89) hide show
  1. package/package.json +14 -9
  2. package/skill/SKILL.md +3 -2
  3. package/skill/references/app-setup.md +17 -9
  4. package/skill/references/endpoint.md +15 -2
  5. package/skill/references/errors.md +7 -6
  6. package/skill/references/jobs.md +10 -0
  7. package/skill/references/relations.md +145 -21
  8. package/skill/references/table-and-migration.md +4 -1
  9. package/skill/references/webhooks-links-connectors.md +2 -1
  10. package/src/build-contract-child.ts +16 -0
  11. package/src/build.ts +48 -2
  12. package/src/bun.ts +10 -0
  13. package/src/client/contract.ts +6 -4
  14. package/src/cloudflare/application.ts +3 -0
  15. package/src/contract/artifact-schema.ts +367 -299
  16. package/src/contract/attachment.ts +4 -3
  17. package/src/contract/build.ts +76 -18
  18. package/src/contract/compile.ts +3 -2
  19. package/src/contract/context.ts +2 -3
  20. package/src/contract/define.ts +19 -6
  21. package/src/contract/group.ts +18 -8
  22. package/src/contract/index.ts +1 -1
  23. package/src/contract/kit.ts +4 -3
  24. package/src/contract/problems.ts +4 -0
  25. package/src/contract/schema-shape.ts +14 -2
  26. package/src/contract/token.ts +4 -3
  27. package/src/disk-assets.ts +15 -3
  28. package/src/from-row.ts +12 -6
  29. package/src/implement/approved.ts +57 -0
  30. package/src/implement/attachment.ts +2 -1
  31. package/src/implement/boot.ts +118 -17
  32. package/src/implement/capability.ts +82 -12
  33. package/src/implement/dispatch.ts +265 -45
  34. package/src/implement/egress.ts +410 -9
  35. package/src/implement/faults.ts +1 -0
  36. package/src/implement/implement.ts +23 -3
  37. package/src/implement/invocation.ts +10 -9
  38. package/src/implement/project.ts +3 -1
  39. package/src/implement/tokens.ts +3 -2
  40. package/src/implement/types.ts +33 -10
  41. package/src/implement/webhook.ts +8 -0
  42. package/src/jobs/runner.ts +7 -2
  43. package/src/react/hooks.ts +12 -11
  44. package/src/react/provider.tsx +2 -1
  45. package/src/react/types.ts +2 -2
  46. package/src/schema/builder.ts +146 -0
  47. package/src/schema/data-schema.ts +365 -0
  48. package/src/schema/index.ts +18 -0
  49. package/src/schema/replay.ts +623 -0
  50. package/src/source-map-path.ts +21 -0
  51. package/src/testing/caller.ts +20 -9
  52. package/src/testing/kit.ts +3 -3
  53. package/src/testing/membership.ts +9 -5
  54. package/types/src/build-contract-child.d.ts +1 -0
  55. package/types/src/build.d.ts +16 -1
  56. package/types/src/client/contract.d.ts +3 -4
  57. package/types/src/cloudflare/application.d.ts +2 -0
  58. package/types/src/contract/artifact-schema.d.ts +8 -0
  59. package/types/src/contract/attachment.d.ts +3 -2
  60. package/types/src/contract/context.d.ts +2 -3
  61. package/types/src/contract/define.d.ts +16 -6
  62. package/types/src/contract/group.d.ts +14 -7
  63. package/types/src/contract/index.d.ts +1 -1
  64. package/types/src/contract/kit.d.ts +4 -5
  65. package/types/src/contract/problems.d.ts +1 -0
  66. package/types/src/contract/schema-shape.d.ts +3 -2
  67. package/types/src/contract/token.d.ts +3 -3
  68. package/types/src/from-row.d.ts +9 -5
  69. package/types/src/implement/approved.d.ts +11 -0
  70. package/types/src/implement/boot.d.ts +12 -0
  71. package/types/src/implement/capability.d.ts +14 -5
  72. package/types/src/implement/dispatch.d.ts +9 -1
  73. package/types/src/implement/egress.d.ts +36 -1
  74. package/types/src/implement/faults.d.ts +1 -0
  75. package/types/src/implement/implement.d.ts +19 -3
  76. package/types/src/implement/invocation.d.ts +3 -3
  77. package/types/src/implement/project.d.ts +2 -1
  78. package/types/src/implement/types.d.ts +17 -8
  79. package/types/src/jobs/runner.d.ts +3 -0
  80. package/types/src/react/hooks.d.ts +4 -5
  81. package/types/src/react/types.d.ts +2 -2
  82. package/types/src/schema/builder.d.ts +45 -0
  83. package/types/src/schema/data-schema.d.ts +124 -0
  84. package/types/src/schema/index.d.ts +3 -0
  85. package/types/src/schema/replay.d.ts +27 -0
  86. package/types/src/source-map-path.d.ts +4 -0
  87. package/types/src/testing/caller.d.ts +6 -1
  88. package/types/src/testing/kit.d.ts +2 -3
  89. package/types/src/testing/membership.d.ts +1 -1
@@ -3,6 +3,7 @@
3
3
  // zod schema of what the handler returns (the rows' array), marked with what it declares beside it.
4
4
 
5
5
  import { z } from 'zod/v4'
6
+ import { type ZodOf, zodOf } from '../schema/data-schema'
6
7
  import { type AttachmentDeclaration, unknownOptions } from './declaration'
7
8
  import type { InputSchema, NotLoose, Schema } from './define'
8
9
 
@@ -17,8 +18,8 @@ export interface AttachmentMark {
17
18
  /** The marks `attachmentOutput` made: a property another module set on a schema is no attachment. */
18
19
  const marks = new WeakSet<object>()
19
20
 
20
- /** An attachment output of rows `R`: the handler returns `z.input<R>[]`, and the caller receives a file. */
21
- export type Attachment<R extends InputSchema> = z.ZodArray<R> & AttachmentBrand
21
+ /** An attachment output of rows `R`: the handler returns `SchemaInput<R>[]`, and the caller receives a file. */
22
+ export type Attachment<R extends InputSchema> = z.ZodArray<ZodOf<R>> & AttachmentBrand
22
23
 
23
24
  /** What tells an attachment output from a JSON one in the types. */
24
25
  export interface AttachmentBrand {
@@ -60,7 +61,7 @@ export function attachment<R extends InputSchema>(options: AttachmentOptions<R &
60
61
  export function attachmentOutput<R extends InputSchema>(row: R, declaration: AttachmentDeclaration): Attachment<R> {
61
62
  const mark: AttachmentMark = Object.freeze({ declaration: Object.freeze({ ...declaration }), row })
62
63
  marks.add(mark)
63
- return Object.assign(z.array(row), { [ATTACHMENT]: mark })
64
+ return Object.assign(z.array(zodOf(row)), { [ATTACHMENT]: mark })
64
65
  }
65
66
 
66
67
  /** The mark of an `attachment()` output, or `null` for any other schema. */
@@ -18,6 +18,7 @@ import {
18
18
  type ContractArtifact,
19
19
  type CspExtensions,
20
20
  type CspSource,
21
+ type DeclaredEgress,
21
22
  type DeclaredReach,
22
23
  type DimensionArtifact,
23
24
  directoryReach,
@@ -54,6 +55,7 @@ import {
54
55
  planEndpoint,
55
56
  type ProcedureArtifact,
56
57
  type ProcedureChallenge,
58
+ PUBLIC_EGRESS,
57
59
  type RoleArtifact,
58
60
  type SchemaShape,
59
61
  type ScopeBinding,
@@ -150,7 +152,7 @@ const FRAMEWORK_TABLE_PREFIX = 'fabrika_'
150
152
  /** The most origins one site calls: a site that reaches more is an integration hub, which a connector import serves. */
151
153
  const MAX_EGRESS_ORIGINS = 16
152
154
  const DECLARED_ALLOWED =
153
- "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>']"
155
+ "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>'] | 'public' (a cron job)"
154
156
  const CSP_FIELDS = ['connectSrc', 'imgSrc', 'frameAncestors', 'scriptSrc', 'frameSrc', 'styleSrc', 'fontSrc']
155
157
  /** An environment variable an application reads; a challenge names its secret by one. */
156
158
  const APPLICATION_VARIABLE = /^[A-Z][A-Z0-9_]*$/
@@ -498,7 +500,10 @@ class ArtifactBuilder {
498
500
  return roles
499
501
  }
500
502
 
501
- /** Each relation names a dimension of the contract, and exactly one table's rows confer it. */
503
+ /**
504
+ * Each relation names a dimension of the contract, and is reached through at most one table's rows that confer it,
505
+ * through access views (ADR-0076), or both; never through neither.
506
+ */
502
507
  #relations(): Record<string, { readonly dimension: string }> {
503
508
  const relations: Record<string, { readonly dimension: string }> = {}
504
509
  for (const [name, relation] of Object.entries(this.#contract.relations ?? {})) {
@@ -508,8 +513,12 @@ class ArtifactBuilder {
508
513
  this.#problem(where, `names the dimension '${relation.dimension}', which is not a dimension of the contract`)
509
514
  }
510
515
  const sources = Object.entries(this.#tables).filter(([, table]) => table.confers !== undefined && Object.hasOwn(table.confers, name))
511
- if (sources.length !== 1) {
512
- this.#problem(where, `is conferred by ${sources.length} tables; exactly one table declares confers.${name}`)
516
+ const viewed = Object.values(this.#tables).some((table) => table.access !== undefined && Object.hasOwn(table.access, name))
517
+ if (sources.length > 1 || (sources.length === 0 && !viewed)) {
518
+ this.#problem(
519
+ where,
520
+ `is conferred by ${sources.length} tables; exactly one table declares confers.${name}, or a table names an access view for it`,
521
+ )
513
522
  }
514
523
  relations[name] = { dimension: relation.dimension }
515
524
  }
@@ -519,23 +528,39 @@ class ArtifactBuilder {
519
528
  this.#problem(`table '${table}'`, `confers '${relation}', which is not a relation of the vocabulary`)
520
529
  }
521
530
  }
531
+ for (const relation of Object.keys(policy.access ?? {})) {
532
+ if (!Object.hasOwn(relations, relation)) {
533
+ this.#problem(`table '${table}'`, `names an access view for '${relation}', which is not a relation of the vocabulary`)
534
+ }
535
+ }
522
536
  }
523
537
  return relations
524
538
  }
525
539
 
526
540
  /**
527
- * A role's `via`: known relations and actions, on an application-wide internal role only (ADR-0051 keeps an
528
- * external principal to its membership roles), and never an action that inserts a relation's rows, so a relation
529
- * never delegates itself onward.
541
+ * A role's `via`: known relations and actions, on an internal role only (ADR-0051 keeps an external principal to its
542
+ * membership roles' own grants), and never an action that inserts a relation's rows, so a relation never delegates
543
+ * itself onward. A membership role holds a relation inside the value it is held in, so the relation's dimension is
544
+ * the role's or lies inside it.
530
545
  */
531
546
  #via(where: string, role: RoleDeclaration): Record<string, readonly string[]> | undefined {
532
547
  if (role.via === undefined) {
533
548
  return undefined
534
549
  }
535
- if (role.member !== undefined || role.external === true) {
536
- this.#problem(where, 'holds actions via a relation and is a membership or external role: only an application-wide role declares via')
550
+ if (role.external === true) {
551
+ this.#problem(where, 'holds actions via a relation and is an external role: an external principal holds no relation')
537
552
  }
538
553
  const relations = this.#contract.relations ?? {}
554
+ const member = role.member?.scope
555
+ for (const relation of Object.keys(role.via)) {
556
+ const dimension = relations[relation]?.dimension
557
+ if (member !== undefined && dimension !== undefined && !this.#lies(dimension, member)) {
558
+ this.#problem(
559
+ where,
560
+ `holds actions via '${relation}', whose dimension '${dimension}' is not '${member}' and does not lie inside it: a membership role holds a relation inside the value it is held in`,
561
+ )
562
+ }
563
+ }
539
564
  const assigning = new Set<string>()
540
565
  for (const policy of Object.values(this.#tables)) {
541
566
  if (policy.confers === undefined) continue
@@ -562,6 +587,18 @@ class ArtifactBuilder {
562
587
  return via
563
588
  }
564
589
 
590
+ /** Whether `dimension` is `ancestor` or lies inside it, by the contract's declared containment. */
591
+ #lies(dimension: string, ancestor: string): boolean {
592
+ const seen: string[] = []
593
+ let at: string | undefined = dimension
594
+ while (at !== undefined && !seen.includes(at)) {
595
+ if (at === ancestor) return true
596
+ seen.push(at)
597
+ at = this.#contract.dimensions[at]?.in
598
+ }
599
+ return false
600
+ }
601
+
565
602
  // ── Mounts ──────────────────────────────────────────────────────────────────────────────────
566
603
 
567
604
  #mount(name: string, mount: MountDeclaration<SchemaShape>): MountArtifact | null {
@@ -2215,7 +2252,7 @@ class ArtifactBuilder {
2215
2252
  ...(kicks.length === 0 ? {} : { kicks }),
2216
2253
  ...(binds === undefined ? {} : { binds }),
2217
2254
  ...(signs.length === 0 ? {} : { signs }),
2218
- ...(egress.length === 0 ? {} : { egress }),
2255
+ ...(egress === null ? {} : { egress }),
2219
2256
  }
2220
2257
  if (place.kind !== 'rpc') {
2221
2258
  this.#rpcOnly(where, 'connect', value['connect'])
@@ -2419,12 +2456,13 @@ class ArtifactBuilder {
2419
2456
 
2420
2457
  /**
2421
2458
  * The HTTPS origins a site's code calls: a credentialed procedure of an RPC mount, a webhook or a job, never a public,
2422
- * export or link procedure. Each is an exact origin or a one-label pattern (`parseEgressEntry`), once; `[]` when it
2423
- * declares none or after a problem.
2459
+ * export or link procedure. Each is an exact origin or a one-label pattern (`parseEgressEntry`), once. Or `'public'`,
2460
+ * every public host (ADR-0075), which only a cron job declares: it calls outside any transaction, and its schedule,
2461
+ * not a caller, decides when. `null` when it declares none or after a problem.
2424
2462
  */
2425
- #egress(where: string, value: unknown, place: DeclaringSite): string[] {
2463
+ #egress(where: string, value: unknown, place: DeclaringSite): DeclaredEgress | null {
2426
2464
  if (value === undefined) {
2427
- return []
2465
+ return null
2428
2466
  }
2429
2467
  const refusedBy = place.kind === 'export'
2430
2468
  ? 'an export procedure'
@@ -2435,15 +2473,35 @@ class ArtifactBuilder {
2435
2473
  : null
2436
2474
  if (refusedBy !== null) {
2437
2475
  this.#problem(where, `declares egress, which ${refusedBy} never does: a credentialed procedure, a webhook or a job calls out`)
2438
- return []
2476
+ return null
2477
+ }
2478
+ if (value === PUBLIC_EGRESS) {
2479
+ if (place.kind !== 'job') {
2480
+ this.#problem(
2481
+ where,
2482
+ `declares egress: '${PUBLIC_EGRESS}', which only a cron job declares: a procedure or a webhook names its origins (allowed: egress: ['https://api.example.com'])`,
2483
+ )
2484
+ return null
2485
+ }
2486
+ return PUBLIC_EGRESS
2439
2487
  }
2440
2488
  if (!Array.isArray(value) || value.length === 0 || !value.every((origin) => typeof origin === 'string')) {
2441
- this.#problem(where, "egress is not a list of origins (allowed: egress: ['https://api.example.com'])")
2442
- return []
2489
+ this.#problem(
2490
+ where,
2491
+ place.kind === 'job'
2492
+ ? "egress is not a list of origins or 'public' (allowed: egress: ['https://api.example.com'] or egress: 'public')"
2493
+ : "egress is not a list of origins (allowed: egress: ['https://api.example.com'])",
2494
+ )
2495
+ return null
2443
2496
  }
2444
2497
  const origins: string[] = value.filter((origin) => typeof origin === 'string')
2445
2498
  if (origins.length > MAX_EGRESS_ORIGINS) {
2446
- this.#problem(where, `${origins.length} egress origins exceed the limit of ${MAX_EGRESS_ORIGINS}`)
2499
+ this.#problem(
2500
+ where,
2501
+ `${origins.length} egress origins exceed the limit of ${MAX_EGRESS_ORIGINS}${
2502
+ place.kind === 'job' ? " (a cron job that calls the websites its operators name declares egress: 'public')" : ''
2503
+ }`,
2504
+ )
2447
2505
  }
2448
2506
  for (const origin of origins) {
2449
2507
  const parsed = parseEgressEntry(origin)
@@ -4,6 +4,7 @@
4
4
  import type { ContractArtifact, SchemaShape, TablePolicyArtifact } from '@fabrika/auth-core'
5
5
  import { isTables, tablePolicies, type Tables } from '@fabrika/db/tables'
6
6
  import { z } from 'zod/v4'
7
+ import { DataSchema } from '../schema/data-schema'
7
8
  import { attachmentOf } from './attachment'
8
9
  import { buildArtifact } from './build'
9
10
  import {
@@ -173,7 +174,7 @@ class SchemaReader {
173
174
  }
174
175
  }
175
176
 
176
- /** Whether `value` is a zod schema: what a contract writes where a schema stands. */
177
+ /** Whether `value` is a schema, zod or held as data: what a contract writes where a schema stands. */
177
178
  function isSchema(value: unknown): value is Schema {
178
- return value instanceof z.ZodType
179
+ return value instanceof z.ZodType || value instanceof DataSchema
179
180
  }
@@ -20,7 +20,6 @@ import type {
20
20
  UnscopedTables,
21
21
  WithinTables,
22
22
  } from '@fabrika/db/tables'
23
- import type { z } from 'zod/v4'
24
23
  import type { StoredFilesHandle, StoredFilesReadHandle } from '../files/handle'
25
24
  import type { AppCapability, Ref, Within } from '../implement/capability'
26
25
  import type { ApplicationDirectory, LinkIssuing, MemberDirectory, MemberLookup, MemberManagement } from '../implement/membership'
@@ -30,7 +29,7 @@ import type { CapabilityOf, ConnectCall, RequestContext } from '../implement/typ
30
29
  import type { WebhookDelivery, WebhookPrincipal } from '../implement/webhook'
31
30
  import type { AppMail, JobContext } from '../jobs/types'
32
31
  import type { ConnectSnapshot } from './connect'
33
- import type { MemberAccess, Schema } from './define'
32
+ import type { MemberAccess, Schema, SchemaOutput } from './define'
34
33
  import type { App } from './kit'
35
34
  import type { TokenPurposes, TokenSigning } from './token'
36
35
  import type { WebhookBindings } from './webhook-binding'
@@ -116,7 +115,7 @@ export type SqlValue = string | number | boolean | bigint | Date | null | readon
116
115
  * transaction; each row is parsed (snake_case → camelCase, `Date` → ISO text, then `Row`).
117
116
  */
118
117
  export interface SqlTag<Ix extends AnyDbIndex = AnyDbIndex, M extends SqlMode = SqlMode> {
119
- <Row extends Schema>(row: Row): (text: TemplateStringsArray, ...values: readonly (SqlValue | SqlScope)[]) => Promise<z.output<Row>[]>
118
+ <Row extends Schema>(row: Row): (text: TemplateStringsArray, ...values: readonly (SqlValue | SqlScope)[]) => Promise<SchemaOutput<Row>[]>
120
119
  /**
121
120
  * The capability's whole predicate on `table`: the object's key and every link of its chain for a `Ref`, what
122
121
  * `ctx.db.within` matches for a `Within`, every row for `ctx.app`. Interpolated as
@@ -3,6 +3,7 @@
3
3
 
4
4
  import type { BuiltinRoleKey, ChallengeProvider, Locale, MailTemplates, RpcCaller, WebhookScheme } from '@fabrika/auth-core'
5
5
  import type { z } from 'zod/v4'
6
+ import type { DataObject, DataSchema, ZodOf } from '../schema/data-schema'
6
7
  import {
7
8
  type CronDeclaration,
8
9
  type CspDeclaration,
@@ -36,19 +37,30 @@ export interface JobLimitsOption {
36
37
  readonly timeoutMs?: number
37
38
  }
38
39
 
39
- /** Any zod 4 schema. `compileContract` refuses every form outside the contract subset. */
40
- export type Schema = z.core.$ZodType
40
+ /**
41
+ * Any zod 4 schema, or one held as data (`@fabrika/app/schema`). `compileContract` refuses every form outside the
42
+ * contract subset.
43
+ */
44
+ export type Schema = z.core.$ZodType | DataSchema
45
+
46
+ /** What a schema admits once parsed. */
47
+ export type SchemaOutput<S> = z.output<ZodOf<S>>
48
+
49
+ /** What a schema takes before parsing. */
50
+ export type SchemaInput<S> = z.input<ZodOf<S>>
41
51
 
42
52
  /**
43
53
  * An input object. zod 4's types do not tell `z.object` from `z.strictObject`, so the type refuses only loose
44
54
  * objects; `compileContract` and `@fabrika/check` refuse `z.object` too.
45
55
  */
46
- export type InputSchema = z.ZodObject<z.core.$ZodShape, z.core.$ZodObjectConfig>
56
+ export type InputSchema = z.ZodObject<z.core.$ZodShape, z.core.$ZodObjectConfig> | DataObject<z.core.$ZodShape, z.core.$ZodObjectConfig>
47
57
 
48
58
  type LooseMessage = 'a loose object admits undeclared keys: declare it with z.strictObject({ … })'
49
59
 
50
60
  /** `S`, unless it is an object that admits undeclared keys (`.loose()`, `.passthrough()`, `.catchall()`). */
51
- export type NotLoose<S> = S extends z.ZodObject<z.core.$ZodShape, infer Config extends z.core.$ZodObjectConfig>
61
+ export type NotLoose<S> = S extends Schema ? LooseChecked<S, ZodOf<S>> : S
62
+
63
+ type LooseChecked<S, Z> = Z extends z.ZodObject<z.core.$ZodShape, infer Config extends z.core.$ZodObjectConfig>
52
64
  ? string extends keyof Config['out'] ? LooseMessage : S
53
65
  : S
54
66
 
@@ -97,7 +109,8 @@ export interface RoleDef<A extends string, D extends string, R extends string> {
97
109
  readonly external?: true
98
110
  /**
99
111
  * Relation → actions: a holder of this role, granted globally, holds them at each node a row of the relation's
100
- * source names them at (`via: { owner: ['projects.edit'] }`). A scoped grant of the role carries none of them.
112
+ * source names them at (`via: { owner: ['projects.edit'] }`). A grant at a value holds them only on rows inside that
113
+ * value, so a membership role's relation has the role's dimension or one inside it. An external role takes none.
101
114
  */
102
115
  readonly via?: { readonly [relation: string]: readonly A[] }
103
116
  }
@@ -229,7 +242,7 @@ export interface PublicAccess {
229
242
  }
230
243
 
231
244
  /** Without an `input`, TS infers `I` as its whole constraint, not the `null` default; both mean "no input". */
232
- export type InputOf<I> = [I] extends [InputSchema] ? z.output<I> : Record<never, never>
245
+ export type InputOf<I> = [I] extends [InputSchema] ? SchemaOutput<I> : Record<never, never>
233
246
 
234
247
  /** Input fields of string type: the only fields a scope value can be read from. */
235
248
  export type StringField<In> = { [K in keyof In]-?: In[K] extends string ? K : never }[keyof In] & string
@@ -4,7 +4,6 @@
4
4
 
5
5
  import type { EndpointCache, RpcCaller } from '@fabrika/auth-core'
6
6
  import type { AnyDbIndex, ReadOnlyUnscoped, Unavailable, UnscopedDeclaration, UnscopedMode } from '@fabrika/db/tables'
7
- import type { z } from 'zod/v4'
8
7
  import type { Snake } from '../from-row'
9
8
  import type { ExtraKeys, HandlerInput, IsAny } from '../implement/types'
10
9
  import type { AttachmentBrand } from './attachment'
@@ -38,6 +37,8 @@ import type {
38
37
  PublicAccess,
39
38
  QueryAccess,
40
39
  Schema,
40
+ SchemaInput,
41
+ SchemaOutput,
41
42
  } from './define'
42
43
  import type { WithClaims } from './token'
43
44
 
@@ -115,7 +116,16 @@ export type SignsField<Sg, Purposes extends string> =
115
116
  * guard on the global `fetch` refuses any other while the site runs; a public procedure declares none.
116
117
  */
117
118
  export interface EgressField {
118
- readonly egress?: readonly `https://${string}`[]
119
+ readonly egress?: readonly `https://${string}`[] | Unavailable<"egress: 'public' is a cron job's only: record a row and kick a job that declares it">
120
+ }
121
+
122
+ /**
123
+ * A cron job's `egress`: its exact HTTPS origins, or `'public'`, every public host over HTTPS or HTTP on its default
124
+ * port, for a job that calls the websites its operators name (ADR-0075). The guard refuses IP addresses, local and
125
+ * internal names and the installation's own hosts, checks each redirect, and bounds each request's time and body.
126
+ */
127
+ export interface JobEgressField {
128
+ readonly egress?: readonly `https://${string}`[] | 'public'
119
129
  }
120
130
 
121
131
  /** Each purpose `signs` names is one of `defineApp`'s `tokens`. */
@@ -218,7 +228,7 @@ export type ListOf<U extends string, Listed extends string = ''> = [U] extends [
218
228
  : ListOf<Exclude<U, LastOf<U>>, Listed extends '' ? LastOf<U> & string : `${LastOf<U> & string}, ${Listed}`>
219
229
 
220
230
  /** The fields, at any depth, that a handler `F` returns and the output `O` does not declare. */
221
- export type UndeclaredFields<F, O extends Schema> = ExtraKeys<Returned<F>, z.input<O>>
231
+ export type UndeclaredFields<F, O extends Schema> = ExtraKeys<Returned<F>, SchemaInput<O>>
222
232
 
223
233
  /** An object with a camelCase field, which a database row names in snake_case. */
224
234
  type HasCamel<V> = { [K in keyof V]: K extends string ? (Snake<K> extends K ? never : K) : never }[keyof V]
@@ -237,10 +247,10 @@ type RowShaped<V> = V extends readonly (infer Item)[] ? readonly RowShaped<Item>
237
247
  * `ExactReturn` refuses with the fix, as it refuses anything but rows from an attachment's handler. Any other mistake
238
248
  * keeps the compiler's own message about the output.
239
249
  */
240
- export type HandlerReturn<F, O extends Schema> = [Returned<F>] extends [z.input<O>] ? z.input<O>
250
+ export type HandlerReturn<F, O extends Schema> = [Returned<F>] extends [SchemaInput<O>] ? SchemaInput<O>
241
251
  : [O] extends [AttachmentBrand] ? unknown
242
- : [Returned<F>] extends [RowShaped<z.input<O>>] ? RowShaped<z.input<O>>
243
- : z.input<O>
252
+ : [Returned<F>] extends [RowShaped<SchemaInput<O>>] ? RowShaped<SchemaInput<O>>
253
+ : SchemaInput<O>
244
254
 
245
255
  /** A kit endpoint's handler, returning `R`; `X` adds what its HTTP shape reads beside the input (`query`). */
246
256
  export type KitHandler<In, Ctx, R, X = unknown> = (args: { readonly input: In; readonly ctx: Ctx } & X) => R | Promise<R>
@@ -250,7 +260,7 @@ export type KitHandler<In, Ctx, R, X = unknown> = (args: { readonly input: In; r
250
260
  * as the claims of its purpose.
251
261
  */
252
262
  export type QueryArgs<Q, T = Record<never, never>> = [Q] extends [never] ? unknown
253
- : Q extends InputSchema ? { readonly query: WithClaims<z.output<Q>, T> }
263
+ : Q extends InputSchema ? { readonly query: WithClaims<SchemaOutput<Q>, T> }
254
264
  : unknown
255
265
 
256
266
  /**
@@ -273,7 +283,7 @@ export interface HttpOption<Q> {
273
283
  * returns a database row where the output is camelCase, anything but rows for an attachment, or, at any depth, a
274
284
  * field the output does not declare. A field whose type is an error elsewhere in the handler is not reported again here.
275
285
  */
276
- export type ExactReturn<F, O extends Schema, E> = [Returned<F>] extends [z.input<O>] ? [UndeclaredFields<F, O>] extends [never] ? E
286
+ export type ExactReturn<F, O extends Schema, E> = [Returned<F>] extends [SchemaInput<O>] ? [UndeclaredFields<F, O>] extends [never] ? E
277
287
  : IsAny<UndeclaredFields<F, O>> extends true ? E
278
288
  : Unavailable<`the handler returns ${ListOf<UndeclaredFields<F, O> & string>}, which the output does not declare: return only declared fields`>
279
289
  : [O] extends [AttachmentBrand] ? Unavailable<'an attachment handler returns its rows: an array of its row schema, with nothing around it'>
@@ -1,7 +1,7 @@
1
1
  // @fabrika/app/contract — the contract of an application: the staged kit (`defineVocabulary`, `defineApp`, its
2
2
  // groups), `defineContract`, `compileContract`, the artifact parser, and the IAM schema it compiles to. Browser-safe:
3
3
  // no server runtime, no Node or Bun API.
4
- export { contractArtifactSchema, parseContractArtifact, schemaShapeSchema } from './artifact-schema'
4
+ export { contractArtifactSchema, isEncodedArtifact, parseContractArtifact, parseEncodedArtifact, schemaShapeSchema } from './artifact-schema'
5
5
  export {
6
6
  type Attachment,
7
7
  attachment,
@@ -5,7 +5,6 @@
5
5
 
6
6
  import type { JobMailer, RpcCaller, WebhookScheme } from '@fabrika/auth-core'
7
7
  import type { AnyDbIndex, DbIndex, Tables, Unavailable, UnscopedDeclaration, UnscopedMode } from '@fabrika/db/tables'
8
- import type { z } from 'zod/v4'
9
8
  import type { Declared, JobKitContext, KickContext, KitImports, KitTypes, NoTablesIndex, SqlMode, TokensContext, WebhookKitContext } from './context'
10
9
  import {
11
10
  type AccessDeclaration,
@@ -43,6 +42,7 @@ import {
43
42
  type ProcedureTree,
44
43
  type RpcMount,
45
44
  type Schema,
45
+ type SchemaOutput,
46
46
  type Surface,
47
47
  surfaceKit,
48
48
  terminalOf,
@@ -57,6 +57,7 @@ import type {
57
57
  GroupBuild,
58
58
  GroupInput,
59
59
  GroupKit,
60
+ JobEgressField,
60
61
  KicksField,
61
62
  LimitsOption,
62
63
  LinkGroupKit,
@@ -96,7 +97,7 @@ export type CronOptions<Acts, S, U, Is, Ix extends AnyDbIndex, M = never, Ks = n
96
97
  & MailerField<M>
97
98
  & KicksField<Ks>
98
99
  & SignsField<Sg, Purposes>
99
- & EgressField
100
+ & JobEgressField
100
101
 
101
102
  /** The mail transport a job reaches, inferred from its optional field and then required, like a declared field. */
102
103
  type MailerField<M> =
@@ -156,7 +157,7 @@ export interface WebhookBuilder<
156
157
  > {
157
158
  handle(
158
159
  handler: (
159
- args: { readonly input: z.output<I>; readonly ctx: WebhookKitContext<K, B, Acts, D> & KickContext<Ks> & TokensContext<K, Sg> },
160
+ args: { readonly input: SchemaOutput<I>; readonly ctx: WebhookKitContext<K, B, Acts, D> & KickContext<Ks> & TokensContext<K, Sg> },
160
161
  ) => void | Promise<void>,
161
162
  ): KitWebhook<B, Acts, I, D>
162
163
  }
@@ -17,6 +17,10 @@ export class Problems {
17
17
  this.#problems.push(`${where}: ${problem}`)
18
18
  }
19
19
 
20
+ isEmpty(): boolean {
21
+ return this.#problems.length === 0
22
+ }
23
+
20
24
  throwIfAny(): void {
21
25
  if (this.#problems.length > 0) {
22
26
  throw new ContractError([...this.#problems])
@@ -3,6 +3,8 @@
3
3
 
4
4
  import type { ArrayShape, NumberShape, SchemaShape, StringShape } from '@fabrika/auth-core'
5
5
  import { z } from 'zod/v4'
6
+ import { type DataSchema, zodSchemaOf } from '../schema/data-schema'
7
+ import { SchemaRefusal } from '../schema/replay'
6
8
  import { attachmentOf } from './attachment'
7
9
  import { fileOf } from './file'
8
10
  import type { Problems } from './problems'
@@ -18,8 +20,18 @@ function isStringFormat(format: string): format is StringFormat {
18
20
  return STRING_FORMATS.has(format)
19
21
  }
20
22
 
21
- /** A schema's shape, or `null` after recording why it has none. */
22
- export function describeSchema(schema: z.core.$ZodType, where: string, problems: Problems): SchemaShape | null {
23
+ /** A schema's shape, or `null` after recording why it has none. A schema held as data is read as the zod it builds. */
24
+ export function describeSchema(described: z.core.$ZodType | DataSchema, where: string, problems: Problems): SchemaShape | null {
25
+ let schema: z.core.$ZodType
26
+ try {
27
+ schema = zodSchemaOf(described)
28
+ } catch (error) {
29
+ if (error instanceof SchemaRefusal) {
30
+ problems.add(where, `${error.message} (allowed: ${error.allowed})`)
31
+ return null
32
+ }
33
+ throw error
34
+ }
23
35
  if (attachmentOf(schema) !== null) {
24
36
  problems.add(where, "an attachment() is a procedure's whole output, never part of a schema or an input (allowed: output: attachment({ … }))")
25
37
  return null
@@ -4,7 +4,7 @@
4
4
  // handler the purpose's typed claims. A token is single-purpose and no credential: it opens no mount.
5
5
 
6
6
  import { z } from 'zod/v4'
7
- import type { InputSchema, NotLoose, Schema } from './define'
7
+ import type { InputSchema, NotLoose, Schema, SchemaInput, SchemaOutput } from './define'
8
8
 
9
9
  const SIGNED_TOKEN = Symbol('fabrika.signedToken')
10
10
 
@@ -77,7 +77,8 @@ export type TokenPurposeOf<V> = V extends { readonly [z.core.$brand]: infer B }
77
77
  /** One field as the handler holds it: a signed token as the claims of its purpose, any other field as it is. */
78
78
  type ClaimsField<V, T> = [TokenPurposeOf<NonNullable<V>>] extends [never] ? V
79
79
  :
80
- | (TokenPurposeOf<NonNullable<V>> extends keyof T ? T[TokenPurposeOf<NonNullable<V>>] extends TokenPurpose<infer C> ? z.output<C> : never : never)
80
+ | (TokenPurposeOf<NonNullable<V>> extends keyof T ? T[TokenPurposeOf<NonNullable<V>>] extends TokenPurpose<infer C> ? SchemaOutput<C> : never
81
+ : never)
81
82
  | (undefined extends V ? undefined : never)
82
83
 
83
84
  /** An input as its handler receives it: each signed token field replaced by the verified claims of its purpose. */
@@ -85,5 +86,5 @@ export type WithClaims<In, T> = [keyof In] extends [never] ? In : { readonly [F
85
86
 
86
87
  /** `ctx.tokens` of a site that declares `signs`: a token of one of those purposes, valid for `days`. */
87
88
  export interface TokenSigning<T extends TokenPurposes, S extends string> {
88
- sign<const P extends S & keyof T & string>(purpose: P, claims: z.input<T[P]['claims']>, options: { readonly days: number }): string
89
+ sign<const P extends S & keyof T & string>(purpose: P, claims: SchemaInput<T[P]['claims']>, options: { readonly days: number }): string
89
90
  }
@@ -2,8 +2,10 @@
2
2
  // test kit serves a built directory the same way.
3
3
 
4
4
  import { rawRequestTarget } from '@fabrika/auth-core'
5
- import { join, resolve, sep } from 'node:path'
5
+ import type { BunFile } from 'bun'
6
+ import { basename, join, resolve, sep } from 'node:path'
6
7
  import type { SpaAssets } from './implement/dispatch.js'
8
+ import { isSourceMapName } from './source-map-path.js'
7
9
  import { isPageRoute } from './spa-fallback.js'
8
10
 
9
11
  /**
@@ -18,8 +20,8 @@ export function diskAssets(root: string): SpaAssets {
18
20
  const relative = mount.prefix === '/' ? pathname.slice(1) : pathname.slice(mount.prefix.length + 1)
19
21
  // The path is canonical, so every segment decodes and none is `.` or `..`.
20
22
  const file = join(dir, ...relative.split('/').filter((segment) => segment !== '').map((segment) => decodeURIComponent(segment)))
21
- const candidate = file.startsWith(`${dir}${sep}`) ? Bun.file(file) : null
22
- const found = candidate !== null && (await candidate.exists()) ? candidate : null
23
+ // The mount refuses a source map before it asks; this holds for any caller that serves through it directly.
24
+ const found = file.startsWith(`${dir}${sep}`) && !isSourceMapName(basename(file)) ? await existing(file) : null
23
25
  const served = found ?? (isPageRoute(request) ? Bun.file(join(dir, 'index.html')) : null)
24
26
  if (served === null || !(await served.exists())) {
25
27
  return new Response('Not found', { status: 404 })
@@ -28,3 +30,13 @@ export function diskAssets(root: string): SpaAssets {
28
30
  },
29
31
  }
30
32
  }
33
+
34
+ /** The file at `path` when it exists. A name no file can have (a decoded control character) is a missing asset, not a fault. */
35
+ async function existing(path: string): Promise<BunFile | null> {
36
+ try {
37
+ const file = Bun.file(path)
38
+ return (await file.exists()) ? file : null
39
+ } catch {
40
+ return null
41
+ }
42
+ }
package/src/from-row.ts CHANGED
@@ -5,7 +5,12 @@
5
5
  // `YYYY-MM-DD` text from the data layer.
6
6
 
7
7
  import { z } from 'zod/v4'
8
+ import type { SchemaInput, SchemaOutput } from './contract/define'
8
9
  import { project } from './implement/project'
10
+ import { type DataObject, zodOf } from './schema/data-schema'
11
+
12
+ /** An object schema: a zod one, or one held as data. */
13
+ type ObjectSchema = z.ZodObject | DataObject<z.core.$ZodShape, z.core.$ZodObjectConfig>
9
14
 
10
15
  /** `companyId` → `company_id`: the column a field is read from. */
11
16
  export type Snake<S extends string> = S extends `${infer Head}${infer Tail}`
@@ -16,7 +21,7 @@ export type Snake<S extends string> = S extends `${infer Head}${infer Tail}`
16
21
  type Widened<V> = V extends string ? string | Date : V
17
22
 
18
23
  /** The row `fromRow` takes for `S`: one column per declared field; any other column is allowed and dropped. */
19
- export type RowInput<S extends z.ZodObject> = { readonly [K in keyof z.input<S> as Snake<K & string>]: Widened<z.input<S>[K]> }
24
+ export type RowInput<S extends ObjectSchema> = { readonly [K in keyof SchemaInput<S> as Snake<K & string>]: Widened<SchemaInput<S>[K]> }
20
25
 
21
26
  function camel(column: string): string {
22
27
  return column.replace(/_([a-z0-9])/g, (_match, next: string) => next.toUpperCase())
@@ -35,19 +40,20 @@ function dateText(schema: z.ZodObject, field: string, value: Date): string {
35
40
  }
36
41
 
37
42
  /** The row as `schema`'s output; a row the schema refuses throws, as a handler's bug. */
38
- export function fromRow<const S extends z.ZodObject>(schema: S, row: RowInput<S>): z.output<S> {
43
+ export function fromRow<const S extends ObjectSchema>(schema: S, row: RowInput<S>): SchemaOutput<S> {
44
+ const object = zodOf(schema)
39
45
  const fields: Record<string, unknown> = {}
40
46
  for (const [column, value] of Object.entries(row)) {
41
47
  const field = camel(column)
42
- Object.defineProperty(fields, field, { value: value instanceof Date ? dateText(schema, field, value) : value, enumerable: true })
48
+ Object.defineProperty(fields, field, { value: value instanceof Date ? dateText(object, field, value) : value, enumerable: true })
43
49
  }
44
- return z.parse(schema, project(schema, fields))
50
+ return z.parse(object, project(object, fields))
45
51
  }
46
52
 
47
53
  /** A list's page as a page output: each row through `fromRow`, and `next` as the list answered it. */
48
- export function fromPage<const S extends z.ZodObject>(
54
+ export function fromPage<const S extends ObjectSchema>(
49
55
  schema: S,
50
56
  page: { readonly items: readonly RowInput<S>[]; readonly next: string | null },
51
- ): { items: z.output<S>[]; next: string | null } {
57
+ ): { items: SchemaOutput<S>[]; next: string | null } {
52
58
  return { items: page.items.map((row) => fromRow(schema, row)), next: page.next }
53
59
  }