@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.
@@ -21,6 +21,7 @@ import {
21
21
  isFileShape,
22
22
  isRedirectShape,
23
23
  type LinkTokenClaims,
24
+ matchAction,
24
25
  parseEndpointHeader,
25
26
  type PermissionEntry,
26
27
  permits,
@@ -29,6 +30,7 @@ import {
29
30
  PROXY_TOKEN_HEADER,
30
31
  rawRequestTarget,
31
32
  type RedirectShape,
33
+ RELATION_SCOPE_TYPE,
32
34
  sameOriginTarget,
33
35
  satisfies,
34
36
  type SchemaShape,
@@ -308,6 +310,12 @@ export interface ProcedureQuery {
308
310
  readonly shape: SchemaShape
309
311
  }
310
312
 
313
+ /** A relation's reveal: a row it reaches reveals its node in `dimension` for `actions`. */
314
+ export interface RevealedNode {
315
+ readonly dimension: string
316
+ readonly actions: readonly string[]
317
+ }
318
+
311
319
  export interface RuntimeParts {
312
320
  readonly table: CompiledEndpointTable
313
321
  readonly endpoints: ReadonlyMap<string, ServedEndpoint>
@@ -324,6 +332,12 @@ export interface RuntimeParts {
324
332
  readonly ownedDimensions: ReadonlySet<string>
325
333
  /** Each dimension's containers, nearest first; a grant on one reaches every value inside it. */
326
334
  readonly containers: ReadonlyMap<string, readonly string[]>
335
+ /** Each relation of the contract with its dimension: a `~rel` entry holds its action at that dimension's nodes. */
336
+ readonly relations: ReadonlyMap<string, string>
337
+ /** Each relation's reveals: a `~rel` entry of one of their actions also holds it at the ancestor nodes they reveal. */
338
+ readonly reveals: ReadonlyMap<string, readonly RevealedNode[]>
339
+ /** Each dimension's member reveals: a grant of one of their actions at its node also reads under the ancestor they reveal. */
340
+ readonly memberReveals: ReadonlyMap<string, readonly RevealedNode[]>
327
341
  readonly assets: SpaAssets | null
328
342
  /** IAM's membership operations; `boot` refuses a contract that needs them when the adapter supplies none. */
329
343
  readonly membership: IamMembership | null
@@ -931,35 +945,110 @@ export class ContractRuntime {
931
945
  }
932
946
  const held = this.#heldContainers(caller.perms, action, dimension)
933
947
  const inside = this.#heldContained(caller.perms, action, dimension)
934
- if (direct.length === 0 && held.length === 0 && inside.length === 0) {
948
+ const related = this.#heldRelations(caller.perms, action, [dimension, ...(this.#parts.containers.get(dimension) ?? [])])
949
+ const revealing = this.#heldRevealing(caller.perms, action, [dimension, ...(this.#parts.containers.get(dimension) ?? [])])
950
+ if (direct.length === 0 && held.length === 0 && inside.length === 0 && related.length === 0 && revealing.length === 0) {
935
951
  throw new ForbiddenError(`The caller holds '${action}' in no ${dimension}`)
936
952
  }
937
- return this.#parts.mint.within(frame, dimension, action, caller.subject, direct, held, inside)
953
+ return this.#parts.mint.within(frame, dimension, action, caller.subject, direct, held, inside, related, revealing)
938
954
  }
939
955
 
940
956
  /** A scope value the caller acts in: without a grant on it or on a container of it, 403 whether it exists or not. */
941
957
  async #inRef(caller: Caller, action: string, dimension: string, value: string, frame: RequestFrame): Promise<Ref<string, string>> {
942
958
  const direct = permits(caller.perms, action, { type: dimension, value })
943
- if (!direct && this.#heldContainers(caller.perms, action, dimension).length === 0) {
959
+ const candidates = this.#heldRelations(caller.perms, action, [dimension, ...(this.#parts.containers.get(dimension) ?? [])])
960
+ if (!direct && this.#heldContainers(caller.perms, action, dimension).length === 0 && candidates.length === 0) {
944
961
  throw new ForbiddenError(`The caller does not hold '${action}' in this ${dimension}`)
945
962
  }
946
963
  const chain = await this.#chain(dimension, value)
947
- if (!holdsOnChain(caller.perms, action, dimension, value, chain ?? new Map())) {
948
- throw new ForbiddenError(`The caller does not hold '${action}' in this ${dimension}`)
964
+ if (holdsOnChain(caller.perms, action, dimension, value, chain ?? new Map())) {
965
+ if (chain === null) {
966
+ throw new NotFoundError('Not found')
967
+ }
968
+ return this.#parts.mint.ref(frame, dimension, action, caller.subject, value, chain)
949
969
  }
950
- if (chain === null) {
951
- throw new NotFoundError('Not found')
970
+ const related = chain === null ? [] : await this.#relatedOn(caller.subject, candidates, action, dimension, value, chain)
971
+ if (chain === null || related.length === 0) {
972
+ throw new ForbiddenError(`The caller does not hold '${action}' in this ${dimension}`)
952
973
  }
953
- return this.#parts.mint.ref(frame, dimension, action, caller.subject, value, chain)
974
+ return this.#parts.mint.ref(frame, dimension, action, caller.subject, value, chain, related)
954
975
  }
955
976
 
956
977
  /** An object the caller acts on; one it may not act on is indistinguishable from a missing one. */
957
978
  async #onRef(caller: Caller, action: string, dimension: string, value: string, frame: RequestFrame): Promise<Ref<string, string>> {
958
979
  const chain = await this.#chain(dimension, value)
959
- if (chain === null || !holdsOnChain(caller.perms, action, dimension, value, chain)) {
980
+ if (chain === null) {
960
981
  throw new NotFoundError('Not found')
961
982
  }
962
- return this.#parts.mint.ref(frame, dimension, action, caller.subject, value, chain)
983
+ if (holdsOnChain(caller.perms, action, dimension, value, chain)) {
984
+ return this.#parts.mint.ref(frame, dimension, action, caller.subject, value, chain)
985
+ }
986
+ const candidates = this.#heldRelations(caller.perms, action, [dimension, ...chain.keys()])
987
+ const related = await this.#relatedOn(caller.subject, candidates, action, dimension, value, chain)
988
+ if (related.length === 0) {
989
+ throw new NotFoundError('Not found')
990
+ }
991
+ return this.#parts.mint.ref(frame, dimension, action, caller.subject, value, chain, related)
992
+ }
993
+
994
+ /**
995
+ * The relations through which the caller holds `action` at a node of one of `dimensions` (a `~rel` entry, which IAM
996
+ * gives a global grant of a role with `via`), at the relation's own dimension or at an ancestor a reveal of `action`
997
+ * names. An entry of a relation the contract does not declare counts for none.
998
+ */
999
+ #heldRelations(perms: PermissionEntry[], action: string, dimensions: readonly string[]): string[] {
1000
+ const held: string[] = []
1001
+ for (const entry of perms) {
1002
+ const scope = entry.scope
1003
+ if (scope === null || scope.type !== RELATION_SCOPE_TYPE || !matchAction(entry.action, action)) continue
1004
+ const relation = scope.value
1005
+ const at = this.#parts.relations.get(relation)
1006
+ const revealed = this.#revealed(relation, action).some((dimension) => dimensions.includes(dimension))
1007
+ if (at !== undefined && (dimensions.includes(at) || revealed) && !held.includes(relation)) held.push(relation)
1008
+ }
1009
+ return held
1010
+ }
1011
+
1012
+ /** The ancestor dimensions a reveal of `relation` holds `action` at. */
1013
+ #revealed(relation: string, action: string): string[] {
1014
+ return (this.#parts.reveals.get(relation) ?? []).filter((reveal) => reveal.actions.includes(action)).map((reveal) => reveal.dimension)
1015
+ }
1016
+
1017
+ /**
1018
+ * Of `candidates`, the relations a row of which names the caller at the object or at a container on its chain, or
1019
+ * reaches a row that reveals one of them for `action`, now.
1020
+ */
1021
+ async #relatedOn(
1022
+ principal: string,
1023
+ candidates: readonly string[],
1024
+ action: string,
1025
+ dimension: string,
1026
+ value: string,
1027
+ chain: ReadonlyMap<string, string>,
1028
+ ): Promise<string[]> {
1029
+ const relates = this.#parts.database?.relates
1030
+ const reveals = this.#parts.database?.reveals
1031
+ if (relates === undefined) {
1032
+ return []
1033
+ }
1034
+ const nodeOf = (at: string | undefined) => (at === dimension ? value : at === undefined ? undefined : chain.get(at))
1035
+ const related: string[] = []
1036
+ for (const relation of candidates) {
1037
+ const node = nodeOf(this.#parts.relations.get(relation))
1038
+ if (node !== undefined && (await relates(relation, node, principal))) {
1039
+ related.push(relation)
1040
+ continue
1041
+ }
1042
+ if (reveals === undefined) continue
1043
+ for (const revealed of this.#revealed(relation, action)) {
1044
+ const at = nodeOf(revealed)
1045
+ if (at !== undefined && (await reveals(relation, revealed, at, principal))) {
1046
+ related.push(relation)
1047
+ break
1048
+ }
1049
+ }
1050
+ }
1051
+ return related
963
1052
  }
964
1053
 
965
1054
  /**
@@ -1466,6 +1555,18 @@ export class ContractRuntime {
1466
1555
  })
1467
1556
  }
1468
1557
 
1558
+ /**
1559
+ * The caller's grants of `action` at nodes of a dimension whose rows reveal one of `dimensions` for it to their
1560
+ * members; a grant at a container of such a node is not one at the node.
1561
+ */
1562
+ #heldRevealing(perms: PermissionEntry[], action: string, dimensions: readonly string[]): ContainerGrant[] {
1563
+ return [...this.#parts.memberReveals].flatMap(([source, revealed]) => {
1564
+ const reveals = revealed.some((reveal) => reveal.actions.includes(action) && dimensions.includes(reveal.dimension))
1565
+ const values = reveals ? scopedValues(perms, action, source) ?? [] : []
1566
+ return values.length === 0 ? [] : [{ dimension: source, values }]
1567
+ })
1568
+ }
1569
+
1469
1570
  /** The caller's grants of `action` on every dimension that lies inside `dimension`. */
1470
1571
  #heldContained(perms: PermissionEntry[], action: string, dimension: string): ContainerGrant[] {
1471
1572
  return [...this.#parts.containers].flatMap(([inner, containers]) => {
@@ -22,6 +22,13 @@ export interface ContractDatabase {
22
22
  * `using` is a job's transaction, which also sees the object it wrote; a layer of the application's own ignores it.
23
23
  */
24
24
  locate(dimension: string, id: string, using?: Session): Promise<ReadonlyMap<string, string> | null>
25
+ /**
26
+ * Whether a row of `relation`'s source names `principal` at `node` and confers it now. A layer of the application's
27
+ * own has none, so no Ref is ever held through a relation there.
28
+ */
29
+ relates?(relation: string, node: string, principal: string): Promise<boolean>
30
+ /** Whether a row `relation` reaches for `principal` reveals `node` of `dimension` now; none in a layer of the application's own. */
31
+ reveals?(relation: string, dimension: string, node: string, principal: string): Promise<boolean>
25
32
  }
26
33
 
27
34
  /** `scoped(tables)` of `@fabrika/db`, which `boot` binds, or a `ContractDatabase` of the application's own. */
@@ -1,7 +1,7 @@
1
1
  // Test callers: a principal of the test IAM with the permissions its grants resolve to, as IAM resolves them, and
2
2
  // the credential it presents.
3
3
 
4
- import type { PermissionEntry, PrincipalAffiliation } from '@fabrika/auth-core'
4
+ import { type PermissionEntry, type PrincipalAffiliation, RELATION_SCOPE_TYPE } from '@fabrika/auth-core'
5
5
  import type { ActionOf, AnyContract, DimensionOf, RoleOf } from '../contract/define'
6
6
 
7
7
  /** `app` is the connector of another application: its key reaches only the exports that application consumes. */
@@ -118,6 +118,13 @@ export function resolveGrants<C extends AnyContract>(contract: C, grants: readon
118
118
  if (role.member !== undefined && grant.scope?.type !== role.member.scope) {
119
119
  throw new Error(`'${grant.role}' is a membership role: grant it in one ${role.member.scope} (scope: { type: '${role.member.scope}', value })`)
120
120
  }
121
- return role.grants.map((action) => ({ action, scope: scopeOf(grant.scope), source: 'grant' }))
121
+ const entries: PermissionEntry[] = role.grants.map((action) => ({ action, scope: scopeOf(grant.scope), source: 'grant' }))
122
+ // As IAM resolves it: a global grant of a role with `via` also holds each action through its relation.
123
+ if (grant.scope === undefined && role.member === undefined) {
124
+ for (const [relation, held] of Object.entries(role.via ?? {})) {
125
+ for (const action of held) entries.push({ action, scope: { type: RELATION_SCOPE_TYPE, value: relation }, source: 'grant' })
126
+ }
127
+ }
128
+ return entries
122
129
  })
123
130
  }
@@ -4,6 +4,10 @@ export interface ContractDeclaration<S> {
4
4
  readonly dimensions: Readonly<Record<string, DimensionDeclaration>>;
5
5
  readonly actions: Readonly<Record<string, string>>;
6
6
  readonly roles: Readonly<Record<string, RoleDeclaration>>;
7
+ /** The vocabulary's relations, by name; absent without any. */
8
+ readonly relations?: Readonly<Record<string, {
9
+ readonly dimension: string;
10
+ }>>;
7
11
  readonly mounts: Readonly<Record<string, MountDeclaration<S>>>;
8
12
  readonly files: Readonly<Record<string, FileKindDeclaration>>;
9
13
  readonly jobs: Readonly<Record<string, CronDeclaration>>;
@@ -99,6 +103,8 @@ export interface RoleDeclaration {
99
103
  };
100
104
  /** `true` only; `buildArtifact` refuses another value, and refuses it on a role without `member`. */
101
105
  readonly external?: boolean;
106
+ /** Relation → the actions a global holder of the role holds where a row of the relation names them. */
107
+ readonly via?: Readonly<Record<string, readonly string[]>>;
102
108
  }
103
109
  export type AccessDeclaration = {
104
110
  readonly member: true;
@@ -64,6 +64,17 @@ export interface RoleDef<A extends string, D extends string, R extends string> {
64
64
  * only internal people hold it. Only a role with `member` may declare it; an internal person may hold it too.
65
65
  */
66
66
  readonly external?: true;
67
+ /**
68
+ * Relation → actions: a holder of this role, granted globally, holds them at each node a row of the relation's
69
+ * source names them at (`via: { owner: ['projects.edit'] }`). A scoped grant of the role carries none of them.
70
+ */
71
+ readonly via?: {
72
+ readonly [relation: string]: readonly A[];
73
+ };
74
+ }
75
+ /** A relation of the vocabulary: a table's rows name a principal at a node of `dimension` (`confers` on that table). */
76
+ export interface RelationDef<D extends string> {
77
+ readonly dimension: D;
67
78
  }
68
79
  export interface Vocabulary<A extends string, D extends string, R extends string> extends Presentation, AppPeople<A>, AppTerminal {
69
80
  readonly app: string;
@@ -76,6 +87,9 @@ export interface Vocabulary<A extends string, D extends string, R extends string
76
87
  readonly roles: {
77
88
  readonly [K in R]: RoleDef<A, D, R>;
78
89
  };
90
+ readonly relations?: {
91
+ readonly [name: string]: RelationDef<D>;
92
+ };
79
93
  }
80
94
  /** The actions that manage and list the application's own people. */
81
95
  export interface AppMembers<A extends string> {
@@ -1,4 +1,4 @@
1
- import { type AppMembers, type DimensionDef, type Presentation, type RoleDefs, type TerminalDeclaration, type Vocabulary, type WildcardMessage } from './define';
1
+ import { type AppMembers, type DimensionDef, type Presentation, type RelationDef, type RoleDefs, type TerminalDeclaration, type Vocabulary, type WildcardMessage } from './define';
2
2
  /**
3
3
  * The vocabulary as `defineVocabulary` returned it, with its literal names, dimension definitions, the actions of its
4
4
  * people (`M`, `never` when it declares none) and its terminal (`T`, `never` when it declares none).
@@ -26,6 +26,9 @@ export declare function defineVocabulary<const A extends string, const D extends
26
26
  readonly [K in A]: K extends `${string}*${string}` ? WildcardMessage : string;
27
27
  };
28
28
  readonly roles: RoleDefs<NoInfer<A>, NoInfer<D>, R>;
29
+ readonly relations?: {
30
+ readonly [name: string]: RelationDef<NoInfer<D>>;
31
+ };
29
32
  readonly members?: M;
30
33
  readonly directory?: 'labels';
31
34
  readonly terminal?: T;
@@ -63,7 +63,7 @@ export declare class Ref<D extends string, A extends string> implements RefCapab
63
63
  readonly dimension: D;
64
64
  readonly action: A;
65
65
  };
66
- constructor(token: typeof MINT, issuer: object, frame: RequestFrame, dimension: D, action: A, principal: string, id: string, chain: ReadonlyMap<string, string>);
66
+ constructor(token: typeof MINT, issuer: object, frame: RequestFrame, dimension: D, action: A, principal: string, id: string, chain: ReadonlyMap<string, string>, relations: readonly string[]);
67
67
  get dimension(): D;
68
68
  get action(): A;
69
69
  /** The object's id: the value of its dimension. */
@@ -82,7 +82,7 @@ export declare class Within<D extends string, A extends string> implements Withi
82
82
  readonly dimension: D;
83
83
  readonly action: A;
84
84
  };
85
- constructor(token: typeof MINT, issuer: object, frame: RequestFrame, dimension: D, action: A, principal: string, values: readonly string[] | 'all', containers: readonly ContainerGrant[], contained: readonly ContainerGrant[]);
85
+ constructor(token: typeof MINT, issuer: object, frame: RequestFrame, dimension: D, action: A, principal: string, values: readonly string[] | 'all', containers: readonly ContainerGrant[], contained: readonly ContainerGrant[], relations: readonly string[], revealing: readonly ContainerGrant[]);
86
86
  get dimension(): D;
87
87
  get action(): A;
88
88
  /** The values of this dimension itself. */
@@ -124,8 +124,8 @@ export declare class RowRef<T extends string, A extends string> implements RowRe
124
124
  }
125
125
  /** Makes the capabilities one authority accepts; a runtime's is held by the `boot` call that made it alone. */
126
126
  export interface CapabilityMint {
127
- ref<D extends string, A extends string>(frame: RequestFrame, dimension: D, action: A, principal: string, id: string, chain: ReadonlyMap<string, string>): Ref<D, A>;
128
- within<D extends string, A extends string>(frame: RequestFrame, dimension: D, action: A, principal: string, values: readonly string[] | 'all', containers?: readonly ContainerGrant[], contained?: readonly ContainerGrant[]): Within<D, A>;
127
+ ref<D extends string, A extends string>(frame: RequestFrame, dimension: D, action: A, principal: string, id: string, chain: ReadonlyMap<string, string>, relations?: readonly string[]): Ref<D, A>;
128
+ within<D extends string, A extends string>(frame: RequestFrame, dimension: D, action: A, principal: string, values: readonly string[] | 'all', containers?: readonly ContainerGrant[], contained?: readonly ContainerGrant[], relations?: readonly string[], revealing?: readonly ContainerGrant[]): Within<D, A>;
129
129
  app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A>;
130
130
  }
131
131
  /** A mint and the one authority that accepts what it mints. */
@@ -188,6 +188,11 @@ export interface ProcedureQuery {
188
188
  readonly schema: Schema;
189
189
  readonly shape: SchemaShape;
190
190
  }
191
+ /** A relation's reveal: a row it reaches reveals its node in `dimension` for `actions`. */
192
+ export interface RevealedNode {
193
+ readonly dimension: string;
194
+ readonly actions: readonly string[];
195
+ }
191
196
  export interface RuntimeParts {
192
197
  readonly table: CompiledEndpointTable;
193
198
  readonly endpoints: ReadonlyMap<string, ServedEndpoint>;
@@ -204,6 +209,12 @@ export interface RuntimeParts {
204
209
  readonly ownedDimensions: ReadonlySet<string>;
205
210
  /** Each dimension's containers, nearest first; a grant on one reaches every value inside it. */
206
211
  readonly containers: ReadonlyMap<string, readonly string[]>;
212
+ /** Each relation of the contract with its dimension: a `~rel` entry holds its action at that dimension's nodes. */
213
+ readonly relations: ReadonlyMap<string, string>;
214
+ /** Each relation's reveals: a `~rel` entry of one of their actions also holds it at the ancestor nodes they reveal. */
215
+ readonly reveals: ReadonlyMap<string, readonly RevealedNode[]>;
216
+ /** Each dimension's member reveals: a grant of one of their actions at its node also reads under the ancestor they reveal. */
217
+ readonly memberReveals: ReadonlyMap<string, readonly RevealedNode[]>;
207
218
  readonly assets: SpaAssets | null;
208
219
  /** IAM's membership operations; `boot` refuses a contract that needs them when the adapter supplies none. */
209
220
  readonly membership: IamMembership | null;
@@ -18,6 +18,13 @@ export interface ContractDatabase {
18
18
  * `using` is a job's transaction, which also sees the object it wrote; a layer of the application's own ignores it.
19
19
  */
20
20
  locate(dimension: string, id: string, using?: Session): Promise<ReadonlyMap<string, string> | null>;
21
+ /**
22
+ * Whether a row of `relation`'s source names `principal` at `node` and confers it now. A layer of the application's
23
+ * own has none, so no Ref is ever held through a relation there.
24
+ */
25
+ relates?(relation: string, node: string, principal: string): Promise<boolean>;
26
+ /** Whether a row `relation` reaches for `principal` reveals `node` of `dimension` now; none in a layer of the application's own. */
27
+ reveals?(relation: string, dimension: string, node: string, principal: string): Promise<boolean>;
21
28
  }
22
29
  /** `scoped(tables)` of `@fabrika/db`, which `boot` binds, or a `ContractDatabase` of the application's own. */
23
30
  export type ImplementationDatabase = DataLayer | ContractDatabase;
@@ -1,4 +1,4 @@
1
- import type { PermissionEntry, PrincipalAffiliation } from '@fabrika/auth-core';
1
+ import { type PermissionEntry, type PrincipalAffiliation } from '@fabrika/auth-core';
2
2
  import type { ActionOf, AnyContract, DimensionOf, RoleOf } from '../contract/define';
3
3
  /** `app` is the connector of another application: its key reaches only the exports that application consumes. */
4
4
  export type TestCallerKind = 'human' | 'machine' | 'link' | 'app';