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

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.
@@ -335,17 +335,25 @@ export const tables = defineTables(vocabulary, columns)({
335
335
  interface is `<Pascal>View`, every column is `| null`, and its column list entry says `view: true`. A view needs no
336
336
  policy; without one only `ctx.sql` reads it. With one, `ctx.db` reads it like a child table, typed and scoped, and nothing writes it:
337
337
 
338
- - `scope: { child: '<parent>' }` puts it under its parent's `Ref`, with the child's conventions: the view selects the
339
- parent column (`<parent dimension>_id`) and every chain column of the parent. A view of one row per parent states
338
+ - `scope: { child: '<parent>' }` puts it under its parent: the view selects the parent column (`<parent dimension>_id`,
339
+ or `column: '<name>'`), and needs none of the parent's chain columns. A view of one row per parent states
340
340
  `key: '<parent column>'` (`{ child: 'deals', key: 'deal_id' }`), and a handler `on` the parent reads that row with
341
341
  `ctx.db.target.<view>.get(ctx.target.value)`.
342
342
  - `scope: { reference: '<why>' }` is a view every endpoint reads, through `ctx.db.reference.<view>`.
343
- - It takes `actions: { read, appRead?, appCount? }` and column `read` actions only. `insert`, `update`, `delete`,
343
+ - A child view takes a `when` on its read actions, as a table does (`references/relations.md`): a path may start at
344
+ its parent column (`'deal_id.stage'`), though no foreign key declares it, and follows the parent's foreign keys from
345
+ there. The parent's own `when` does not narrow the view; state the view's. Every view column is nullable, so a
346
+ `not` over such a path is refused: state the condition without the `not`.
347
+ - It takes `actions: { read, appRead?, appCount? }`, column `read` actions and a child view's `when` only. `insert`, `update`, `delete`,
344
348
  `version`, `createdBy`, `queue`, `files`, a column `write` and `unscoped: { <view>: 'write' }` are refused by tsc and
345
349
  the checker; its handles' writes are `Unavailable`, and the data layer refuses them.
346
- - No foreign key ties a view's rows to its parent: its SQL is what puts a row in a scope, and the approver reviews it.
347
- Select the parent and chain columns from the parent row itself, or from a row whose foreign keys tie it there. A row
348
- whose parent column is null is read by no `Ref`, but a `Within` reaches it through the chain columns it carries.
350
+ - Every read reaches a view's rows through the parent row their parent column names: a `Ref` of the parent, a
351
+ `Within` that reaches the parent (its relations and reveals included) and `ctx.db.within.<view>` wherever the
352
+ parent is listed, under the parent's own dimension too (a view of `deals` under a `Within` of `deal`). A row whose
353
+ parent column is null, or names a parent that does not exist or that the capability does not reach, is never read
354
+ through a `Ref` or a `Within`, one of every value included (only `ctx.db.app` lists every row of a view); a chain
355
+ column the view carries does not place a row. The view's SQL decides which parent each row names, and the approver
356
+ reviews it. `ctx.sql.scope` refuses a `Ref` or a `Within` of a view: read it through `ctx.db`.
349
357
  - A column of a type the data layer does not read (an array, `numeric` on SQLite) is left out, and every codegen run
350
358
  names it. On SQLite an expression has a type only through `CAST(… AS INTEGER | REAL | TEXT)`; on Postgres cast a
351
359
  count you want as a number (`count(*)::int4`).
@@ -6,6 +6,8 @@ import {
6
6
  type ArrayShape,
7
7
  type AttachmentShape,
8
8
  BUILTIN_ROLE_KEYS,
9
+ type ColumnTestArtifact,
10
+ type ConditionArtifact,
9
11
  CONTRACT_FORMAT,
10
12
  type ContractArtifact,
11
13
  CROSS_ORIGIN_KINDS,
@@ -23,6 +25,7 @@ import {
23
25
  type OutputShape,
24
26
  parseEgressEntry,
25
27
  type RecordShape,
28
+ type RowsTestArtifact,
26
29
  type SchemaShape,
27
30
  type StringShape,
28
31
  type TablePolicyArtifact,
@@ -303,6 +306,45 @@ const tableAction = z.union([
303
306
  z.array(action).min(2).refine((list) => new Set(list).size === list.length, 'a table operation names each action once'),
304
307
  ])
305
308
 
309
+ const literal = z.union([z.string(), z.number().finite(), z.boolean()])
310
+ const ordered = z.union([literal, z.strictObject({ now: z.literal(true) })])
311
+
312
+ /** Exactly one operator per column test, as the policy parse reads it. */
313
+ const columnTest: z.ZodType<ColumnTestArtifact> = z.strictObject({
314
+ eq: literal.optional(),
315
+ notEq: literal.optional(),
316
+ in: z.array(literal).nonempty().optional(),
317
+ notIn: z.array(literal).nonempty().optional(),
318
+ isNull: z.boolean().optional(),
319
+ lt: ordered.optional(),
320
+ lte: ordered.optional(),
321
+ gt: ordered.optional(),
322
+ gte: ordered.optional(),
323
+ }).refine((test) => Object.values(test).filter((value) => value !== undefined).length === 1, 'a column test states exactly one operator')
324
+
325
+ /** `some` or `none` of one table's rows: a condition of its own, or the test at the end of a path. */
326
+ const rowsTest: z.ZodType<RowsTestArtifact> = z.lazy(() =>
327
+ z.union([
328
+ z.strictObject({ some: z.record(name, condition).refine((rows) => Object.keys(rows).length === 1, 'some names exactly one table') }),
329
+ z.strictObject({ none: z.record(name, condition).refine((rows) => Object.keys(rows).length === 1, 'none names exactly one table') }),
330
+ ])
331
+ )
332
+
333
+ const condition: z.ZodType<ConditionArtifact> = z.lazy(() =>
334
+ z.union([
335
+ z.strictObject({ allOf: z.array(condition).nonempty() }),
336
+ z.strictObject({ anyOf: z.array(condition).nonempty() }),
337
+ z.strictObject({ not: condition }),
338
+ rowsTest,
339
+ z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*){0,3}$/), z.union([columnTest, rowsTest])).refine(
340
+ (tests) =>
341
+ Object.keys(tests).length > 0 && !('allOf' in tests) && !('anyOf' in tests) && !('not' in tests) && !('some' in tests)
342
+ && !('none' in tests),
343
+ 'a condition tests at least one column',
344
+ ),
345
+ ])
346
+ )
347
+
306
348
  const tablePolicy: z.ZodType<TablePolicyArtifact> = z.strictObject({
307
349
  scope: z.discriminatedUnion('mode', [
308
350
  z.strictObject({
@@ -331,6 +373,26 @@ const tablePolicy: z.ZodType<TablePolicyArtifact> = z.strictObject({
331
373
  columns: record(z.strictObject({ read: action.optional(), write: action.optional() })),
332
374
  files: z.record(name, name).optional(),
333
375
  view: z.literal(true).optional(),
376
+ confers: record(z.strictObject({
377
+ principal: name,
378
+ node: name,
379
+ expires: nullableName,
380
+ when: condition.optional(),
381
+ assign: z.strictObject({ maxDays: z.int().positive().nullable(), self: z.boolean() }).nullable(),
382
+ })).optional(),
383
+ when: z.record(action, condition).optional(),
384
+ reveals: record(z.strictObject({
385
+ to: name,
386
+ actions: z.array(action).nonempty(),
387
+ when: condition.optional(),
388
+ assign: z.strictObject({ self: z.boolean() }).optional(),
389
+ })).optional(),
390
+ readThrough: z.record(name, name).optional(),
391
+ memberReveals: record(z.strictObject({
392
+ to: name,
393
+ actions: z.array(action).nonempty(),
394
+ when: condition.optional(),
395
+ })).optional(),
334
396
  })
335
397
 
336
398
  export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObject({
@@ -349,11 +411,16 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
349
411
  grants: actions,
350
412
  member: z.strictObject({ scope: name, assignableBy: z.array(roleKey) }).nullable(),
351
413
  external: z.literal(true).optional(),
414
+ via: record(actions.nonempty()).optional(),
352
415
  }).refine((role) => role.external !== true || role.member !== null, {
353
416
  path: ['external'],
354
417
  message: 'only a membership role admits external principals',
418
+ }).refine((role) => role.via === undefined || (role.member === null && role.external !== true), {
419
+ path: ['via'],
420
+ message: 'a relation holds actions through an application-wide role only, never a membership or external one',
355
421
  }),
356
422
  ),
423
+ relations: record(z.strictObject({ dimension: name })).optional(),
357
424
  mounts: record(mount),
358
425
  files: record(z.strictObject({
359
426
  owner: name,
@@ -86,6 +86,7 @@ import {
86
86
  type MountDeclaration,
87
87
  type ProcedureDeclaration,
88
88
  type ProcedureTreeDeclaration,
89
+ type RoleDeclaration,
89
90
  type SpaAccessDeclaration,
90
91
  } from './declaration'
91
92
  import {
@@ -207,6 +208,7 @@ class ArtifactBuilder {
207
208
  }
208
209
  const actions = this.#actions()
209
210
  const dimensions = this.#dimensions()
211
+ const relations = this.#relations()
210
212
  const roles = this.#roles()
211
213
  const tokens = this.#tokens()
212
214
  this.#fileKinds = this.#readFileKinds()
@@ -256,6 +258,7 @@ class ArtifactBuilder {
256
258
  dimensions,
257
259
  actions,
258
260
  roles,
261
+ ...(Object.keys(relations).length === 0 ? {} : { relations }),
259
262
  mounts,
260
263
  files: {},
261
264
  ...(Object.keys(this.#fileKinds).length === 0 ? {} : { fileKinds: this.#fileKinds }),
@@ -456,8 +459,8 @@ class ArtifactBuilder {
456
459
  if (BUILTIN_ROLE_KEYS.includes(name)) {
457
460
  this.#problem(where, `is a role IAM defines itself for every application (reserved: ${BUILTIN_ROLE_KEYS.join(', ')}); choose another name`)
458
461
  }
459
- if (role.grants.length === 0) {
460
- this.#problem(where, 'grants nothing (allowed: grants: [<exact actions>])')
462
+ if (role.grants.length === 0 && Object.keys(role.via ?? {}).length === 0) {
463
+ this.#problem(where, 'grants nothing (allowed: grants: [<exact actions>], or via: { <relation>: [<exact actions>] })')
461
464
  }
462
465
  this.#unique(where, 'grants', role.grants)
463
466
  for (const action of role.grants) {
@@ -484,15 +487,81 @@ class ArtifactBuilder {
484
487
  if (role.external === true && role.member === undefined) {
485
488
  this.#problem(where, 'is declared external and is not a membership role: only a role with member: { scope, … } may admit externals')
486
489
  }
490
+ const via = this.#via(where, role)
487
491
  roles[name] = {
488
492
  grants: [...role.grants],
489
493
  member: role.member === undefined ? null : { scope: role.member.scope, assignableBy: [...role.member.assignableBy] },
490
494
  ...(role.external === true ? { external: true } : {}),
495
+ ...(via === undefined ? {} : { via }),
491
496
  }
492
497
  }
493
498
  return roles
494
499
  }
495
500
 
501
+ /** Each relation names a dimension of the contract, and exactly one table's rows confer it. */
502
+ #relations(): Record<string, { readonly dimension: string }> {
503
+ const relations: Record<string, { readonly dimension: string }> = {}
504
+ for (const [name, relation] of Object.entries(this.#contract.relations ?? {})) {
505
+ const where = `relation '${name}'`
506
+ this.#name(where, name)
507
+ if (!Object.hasOwn(this.#contract.dimensions, relation.dimension)) {
508
+ this.#problem(where, `names the dimension '${relation.dimension}', which is not a dimension of the contract`)
509
+ }
510
+ 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}`)
513
+ }
514
+ relations[name] = { dimension: relation.dimension }
515
+ }
516
+ for (const [table, policy] of Object.entries(this.#tables)) {
517
+ for (const relation of Object.keys(policy.confers ?? {})) {
518
+ if (!Object.hasOwn(relations, relation)) {
519
+ this.#problem(`table '${table}'`, `confers '${relation}', which is not a relation of the vocabulary`)
520
+ }
521
+ }
522
+ }
523
+ return relations
524
+ }
525
+
526
+ /**
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.
530
+ */
531
+ #via(where: string, role: RoleDeclaration): Record<string, readonly string[]> | undefined {
532
+ if (role.via === undefined) {
533
+ return undefined
534
+ }
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')
537
+ }
538
+ const relations = this.#contract.relations ?? {}
539
+ const assigning = new Set<string>()
540
+ for (const policy of Object.values(this.#tables)) {
541
+ if (policy.confers === undefined) continue
542
+ const insert = policy.actions.insert
543
+ for (const action of insert === null ? [] : typeof insert === 'string' ? [insert] : insert) assigning.add(action)
544
+ }
545
+ const via: Record<string, readonly string[]> = {}
546
+ for (const [relation, actions] of Object.entries(role.via)) {
547
+ if (!Object.hasOwn(relations, relation)) {
548
+ this.#problem(where, `holds actions via '${relation}', which is not a relation of the vocabulary`)
549
+ }
550
+ if (actions.length === 0) {
551
+ this.#problem(where, `holds nothing via '${relation}' (allowed: via: { ${relation}: [<exact actions>] })`)
552
+ }
553
+ this.#unique(where, `via.${relation}`, actions)
554
+ for (const action of actions) {
555
+ this.#knownAction(where, action)
556
+ if (assigning.has(action)) {
557
+ this.#problem(where, `holds '${action}' via '${relation}', which inserts a relation's rows: a relation never delegates itself onward`)
558
+ }
559
+ }
560
+ via[relation] = [...actions]
561
+ }
562
+ return via
563
+ }
564
+
496
565
  // ── Mounts ──────────────────────────────────────────────────────────────────────────────────
497
566
 
498
567
  #mount(name: string, mount: MountDeclaration<SchemaShape>): MountArtifact | null {
@@ -2200,6 +2269,9 @@ class ArtifactBuilder {
2200
2269
  this.#problem(where, `declares unscoped '${table}': 'write', and it runs read-only (allowed: 'read')`)
2201
2270
  }
2202
2271
  const policy = Object.hasOwn(this.#tables, table) ? this.#tables[table] : undefined
2272
+ if (mode === 'write' && policy?.confers !== undefined) {
2273
+ this.#problem(where, `declares unscoped '${table}': 'write', and its rows confer a relation: write them through a capability`)
2274
+ }
2203
2275
  if (mode === 'write' && policy?.view === true) {
2204
2276
  this.#problem(where, `declares unscoped '${table}': 'write', and no site writes a view: its rows come from the tables it reads (allowed: 'read')`)
2205
2277
  } else if (mode === 'write' && policy?.scope.mode === 'reference') {
@@ -69,6 +69,7 @@ export function describeContract(contract: AnyContract): ContractDeclaration<Sch
69
69
  dimensions: vocabulary.dimensions,
70
70
  actions: vocabulary.actions,
71
71
  roles: vocabulary.roles,
72
+ ...(vocabulary.relations === undefined ? {} : { relations: vocabulary.relations }),
72
73
  mounts,
73
74
  files: surface.files ?? {},
74
75
  jobs: surface.jobs ?? {},
@@ -9,6 +9,8 @@ export interface ContractDeclaration<S> {
9
9
  readonly dimensions: Readonly<Record<string, DimensionDeclaration>>
10
10
  readonly actions: Readonly<Record<string, string>>
11
11
  readonly roles: Readonly<Record<string, RoleDeclaration>>
12
+ /** The vocabulary's relations, by name; absent without any. */
13
+ readonly relations?: Readonly<Record<string, { readonly dimension: string }>>
12
14
  readonly mounts: Readonly<Record<string, MountDeclaration<S>>>
13
15
  readonly files: Readonly<Record<string, FileKindDeclaration>>
14
16
  readonly jobs: Readonly<Record<string, CronDeclaration>>
@@ -134,6 +136,8 @@ export interface RoleDeclaration {
134
136
  readonly member?: { readonly scope: string; readonly assignableBy: readonly string[] }
135
137
  /** `true` only; `buildArtifact` refuses another value, and refuses it on a role without `member`. */
136
138
  readonly external?: boolean
139
+ /** Relation → the actions a global holder of the role holds where a row of the relation names them. */
140
+ readonly via?: Readonly<Record<string, readonly string[]>>
137
141
  }
138
142
 
139
143
  export type AccessDeclaration =
@@ -95,6 +95,16 @@ export interface RoleDef<A extends string, D extends string, R extends string> {
95
95
  * only internal people hold it. Only a role with `member` may declare it; an internal person may hold it too.
96
96
  */
97
97
  readonly external?: true
98
+ /**
99
+ * 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.
101
+ */
102
+ readonly via?: { readonly [relation: string]: readonly A[] }
103
+ }
104
+
105
+ /** A relation of the vocabulary: a table's rows name a principal at a node of `dimension` (`confers` on that table). */
106
+ export interface RelationDef<D extends string> {
107
+ readonly dimension: D
98
108
  }
99
109
 
100
110
  export interface Vocabulary<A extends string, D extends string, R extends string> extends Presentation, AppPeople<A>, AppTerminal {
@@ -102,6 +112,7 @@ export interface Vocabulary<A extends string, D extends string, R extends string
102
112
  readonly dimensions: { readonly [K in D]: DimensionDef<A, D, R> }
103
113
  readonly actions: { readonly [K in A]: string }
104
114
  readonly roles: { readonly [K in R]: RoleDef<A, D, R> }
115
+ readonly relations?: { readonly [name: string]: RelationDef<D> }
105
116
  }
106
117
 
107
118
  /** The actions that manage and list the application's own people. */
@@ -555,6 +555,7 @@ function runtimeApp(vocabulary: AnyAppVocabulary, options: KitOptions | undefine
555
555
  dimensions: vocabulary.dimensions,
556
556
  actions: vocabulary.actions,
557
557
  roles: vocabulary.roles,
558
+ ...(vocabulary.relations === undefined ? {} : { relations: vocabulary.relations }),
558
559
  ...presentationOf(vocabulary),
559
560
  ...peopleOf(vocabulary),
560
561
  ...terminalOf(vocabulary),
@@ -96,6 +96,7 @@ function roleDef(key: string, role: RoleArtifact): RoleDef {
96
96
  permissions: [...role.grants],
97
97
  ...(role.member === null ? {} : { member: { scope: role.member.scope, assignableBy: [...role.member.assignableBy] } }),
98
98
  ...(role.external === true ? { external: true } : {}),
99
+ ...(role.via === undefined ? {} : { via: Object.fromEntries(Object.entries(role.via).map(([relation, actions]) => [relation, [...actions]])) }),
99
100
  }
100
101
  }
101
102
 
@@ -7,6 +7,7 @@ import {
7
7
  type DimensionDef,
8
8
  type Presentation,
9
9
  presentationOf,
10
+ type RelationDef,
10
11
  type RoleDefs,
11
12
  type TerminalDeclaration,
12
13
  type Vocabulary,
@@ -49,6 +50,7 @@ export function defineVocabulary<
49
50
  readonly dimensions: Dims & { readonly [K in D]: DimensionDef<NoInfer<A>, NoInfer<D>, NoInfer<R>> }
50
51
  readonly actions: { readonly [K in A]: K extends `${string}*${string}` ? WildcardMessage : string }
51
52
  readonly roles: RoleDefs<NoInfer<A>, NoInfer<D>, R>
53
+ readonly relations?: { readonly [name: string]: RelationDef<NoInfer<D>> }
52
54
  readonly members?: M
53
55
  readonly directory?: 'labels'
54
56
  readonly terminal?: T
@@ -60,6 +62,7 @@ export function defineVocabulary<
60
62
  dimensions: vocabulary.dimensions,
61
63
  actions: vocabulary.actions,
62
64
  roles: vocabulary.roles,
65
+ ...(vocabulary.relations === undefined ? {} : { relations: vocabulary.relations }),
63
66
  ...presentationOf(vocabulary),
64
67
  ...(people === undefined ? {} : { members: people }),
65
68
  ...(vocabulary.directory === undefined ? {} : { directory: vocabulary.directory }),
@@ -63,6 +63,7 @@ import {
63
63
  NO_FACILITIES,
64
64
  type ProcedureQuery,
65
65
  proxySecretDigest,
66
+ type RevealedNode,
66
67
  type ServedEndpoint,
67
68
  type ServedSite,
68
69
  type SpaAssets,
@@ -404,13 +405,18 @@ function contractDatabase(
404
405
  return null
405
406
  }
406
407
  try {
407
- const { locate, release } = bindScopedDatabaseProvisionally(database, {
408
+ const { locate, relates, reveals, release } = bindScopedDatabaseProvisionally(database, {
408
409
  database: connection,
409
410
  capabilities,
410
411
  readOnly: requestIsReadOnly,
411
412
  ...(projectWakes === undefined ? {} : { projectWakes }),
412
413
  })
413
- return { database: { tables: database.tables, locate }, framework: frameworkTablesOf(database), data: dataAccessOf(database), release }
414
+ return {
415
+ database: { tables: database.tables, locate, relates, reveals },
416
+ framework: frameworkTablesOf(database),
417
+ data: dataAccessOf(database),
418
+ release,
419
+ }
414
420
  } catch {
415
421
  problems.push('the data layer was bound before boot; only the framework binds it, so remove @fabrika/db/framework from the application')
416
422
  return null
@@ -669,6 +675,28 @@ function bindsOf(
669
675
  return { binds: { name, path: mount.path, scheme: mount.scheme, boundTo: mount.boundTo } }
670
676
  }
671
677
 
678
+ /** Each relation's reveals, from its tables' policies: the ancestor a row it reaches reveals, and for which actions. */
679
+ function revealsOf(artifact: ContractArtifact): ReadonlyMap<string, readonly RevealedNode[]> {
680
+ const reveals = new Map<string, RevealedNode[]>()
681
+ for (const table of Object.values(artifact.tables)) {
682
+ for (const [relation, reveal] of Object.entries(table.reveals ?? {})) {
683
+ reveals.set(relation, [...(reveals.get(relation) ?? []), { dimension: reveal.to, actions: reveal.actions }])
684
+ }
685
+ }
686
+ return reveals
687
+ }
688
+
689
+ /** Each dimension's member reveals, from its table's policy: the ancestor a row reveals to a grant at it, and for which actions. */
690
+ function memberRevealsOf(artifact: ContractArtifact): ReadonlyMap<string, readonly RevealedNode[]> {
691
+ const reveals = new Map<string, RevealedNode[]>()
692
+ for (const table of Object.values(artifact.tables)) {
693
+ for (const [dimension, reveal] of Object.entries(table.memberReveals ?? {})) {
694
+ reveals.set(dimension, [...(reveals.get(dimension) ?? []), { dimension: reveal.to, actions: reveal.actions }])
695
+ }
696
+ }
697
+ return reveals
698
+ }
699
+
672
700
  /** Each approved token purpose with the claims schema the application declared for it. */
673
701
  function runtimePurposes(contract: AnyContract, artifact: ContractArtifact): ReadonlyMap<string, RuntimePurpose> {
674
702
  const declared = contract.surface.tokens ?? {}
@@ -973,6 +1001,9 @@ function bootOnce(app: ContractImplementation, options: BootOptions, binding: Bi
973
1001
  database,
974
1002
  ownedDimensions: owned,
975
1003
  containers,
1004
+ relations: new Map(Object.entries(artifact.relations ?? {}).map(([name, relation]) => [name, relation.dimension])),
1005
+ reveals: revealsOf(artifact),
1006
+ memberReveals: memberRevealsOf(artifact),
976
1007
  assets: options.assets ?? null,
977
1008
  membership,
978
1009
  terminals: artifact.terminal === undefined ? null : (terminalRpc ?? null),
@@ -168,6 +168,8 @@ interface RefFacts {
168
168
  readonly principal: string
169
169
  readonly id: string
170
170
  readonly chain: Chain
171
+ /** The relations through which the caller holds the action on the object; empty for an IAM grant. */
172
+ readonly relations: readonly string[]
171
173
  }
172
174
 
173
175
  interface Bound {
@@ -200,13 +202,14 @@ export class Ref<D extends string, A extends string> implements RefCapability<D,
200
202
  principal: string,
201
203
  id: string,
202
204
  chain: ReadonlyMap<string, string>,
205
+ relations: readonly string[],
203
206
  ) {
204
207
  if (token !== MINT) {
205
208
  throw new CapabilityRefusedError('not_minted', 'a Ref is minted by the framework only; declare the access form in fabrika.contract.ts')
206
209
  }
207
210
  this.#dimension = dimension
208
211
  this.#action = action
209
- this.#facts = freeze({ dimension, action, principal, id, chain: chainOf(chain) })
212
+ this.#facts = freeze({ dimension, action, principal, id, chain: chainOf(chain), relations: copyOf(relations) })
210
213
  this.#frame = frame
211
214
  this.#issuer = issuer
212
215
  }
@@ -242,6 +245,7 @@ export class Ref<D extends string, A extends string> implements RefCapability<D,
242
245
  principal: facts.principal,
243
246
  id: facts.id,
244
247
  chain: mapOf(facts.chain),
248
+ relations: facts.relations,
245
249
  })
246
250
  return { grant, frame: value.#frame, issuer: value.#issuer }
247
251
  }
@@ -270,14 +274,17 @@ export class Within<D extends string, A extends string> implements WithinCapabil
270
274
  values: readonly string[] | 'all',
271
275
  containers: readonly ContainerGrant[],
272
276
  contained: readonly ContainerGrant[],
277
+ relations: readonly string[],
278
+ revealing: readonly ContainerGrant[],
273
279
  ) {
274
280
  if (token !== MINT) {
275
281
  throw new CapabilityRefusedError('not_minted', 'a Within is minted by the framework only; declare the access form in fabrika.contract.ts')
276
282
  }
277
283
  const held = values === 'all' ? freeze([]) : containerGrantsOf(containers)
278
284
  const inside = values === 'all' ? freeze([]) : containerGrantsOf(contained)
285
+ const revealed = values === 'all' ? freeze([]) : containerGrantsOf(revealing)
279
286
  let count = values === 'all' ? 0 : values.length
280
- for (const group of [held, inside]) {
287
+ for (const group of [held, inside, revealed]) {
281
288
  for (let index = 0; index < group.length; index++) {
282
289
  count += group[index]?.values.length ?? 0
283
290
  }
@@ -297,6 +304,8 @@ export class Within<D extends string, A extends string> implements WithinCapabil
297
304
  values: values === 'all' ? 'all' : copyOf(values),
298
305
  containers: held,
299
306
  contained: inside,
307
+ relations: values === 'all' ? freeze([]) : copyOf(relations),
308
+ revealing: revealed,
300
309
  })
301
310
  this.#frame = frame
302
311
  this.#issuer = issuer
@@ -436,6 +445,7 @@ export interface CapabilityMint {
436
445
  principal: string,
437
446
  id: string,
438
447
  chain: ReadonlyMap<string, string>,
448
+ relations?: readonly string[],
439
449
  ): Ref<D, A>
440
450
  within<D extends string, A extends string>(
441
451
  frame: RequestFrame,
@@ -445,6 +455,8 @@ export interface CapabilityMint {
445
455
  values: readonly string[] | 'all',
446
456
  containers?: readonly ContainerGrant[],
447
457
  contained?: readonly ContainerGrant[],
458
+ relations?: readonly string[],
459
+ revealing?: readonly ContainerGrant[],
448
460
  ): Within<D, A>
449
461
  app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A>
450
462
  }
@@ -470,8 +482,9 @@ export function createCapabilityIssuer(): CapabilityIssuer {
470
482
  principal: string,
471
483
  id: string,
472
484
  chain: ReadonlyMap<string, string>,
485
+ relations: readonly string[] = [],
473
486
  ): Ref<D, A> {
474
- return new Ref(MINT, issuer, frame, dimension, action, principal, id, chain)
487
+ return new Ref(MINT, issuer, frame, dimension, action, principal, id, chain, relations)
475
488
  },
476
489
  within<D extends string, A extends string>(
477
490
  frame: RequestFrame,
@@ -481,8 +494,10 @@ export function createCapabilityIssuer(): CapabilityIssuer {
481
494
  values: readonly string[] | 'all',
482
495
  containers: readonly ContainerGrant[] = [],
483
496
  contained: readonly ContainerGrant[] = [],
497
+ relations: readonly string[] = [],
498
+ revealing: readonly ContainerGrant[] = [],
484
499
  ): Within<D, A> {
485
- return new Within(MINT, issuer, frame, dimension, action, principal, values, containers, contained)
500
+ return new Within(MINT, issuer, frame, dimension, action, principal, values, containers, contained, relations, revealing)
486
501
  },
487
502
  app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A> {
488
503
  return new AppCapability(MINT, issuer, frame, action, principal)