@fabrika/app 0.9.0-dev.11 → 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.
Files changed (46) hide show
  1. package/package.json +10 -10
  2. package/skill/SKILL.md +7 -5
  3. package/skill/references/app-setup.md +8 -8
  4. package/skill/references/endpoint.md +12 -4
  5. package/skill/references/files.md +11 -1
  6. package/skill/references/relations.md +558 -0
  7. package/skill/references/table-and-migration.md +30 -0
  8. package/src/contract/artifact-schema.ts +94 -5
  9. package/src/contract/build.ts +127 -34
  10. package/src/contract/compile.ts +1 -0
  11. package/src/contract/declaration.ts +8 -2
  12. package/src/contract/define.ts +18 -1
  13. package/src/contract/group.ts +12 -10
  14. package/src/contract/index.ts +2 -0
  15. package/src/contract/kit.ts +1 -0
  16. package/src/contract/platform.ts +1 -0
  17. package/src/contract/vocabulary.ts +3 -0
  18. package/src/dev/launcher.ts +14 -15
  19. package/src/dev/output.ts +8 -11
  20. package/src/files/kinds.ts +1 -1
  21. package/src/files/sniff.ts +18 -1
  22. package/src/files/treatment.ts +12 -10
  23. package/src/implement/boot.ts +33 -2
  24. package/src/implement/capability.ts +19 -4
  25. package/src/implement/client-address.ts +5 -71
  26. package/src/implement/dispatch.ts +117 -14
  27. package/src/implement/egress.ts +30 -12
  28. package/src/implement/implement.ts +7 -0
  29. package/src/implement/public.ts +3 -3
  30. package/src/jobs/report.ts +32 -5
  31. package/src/jobs/scrub.ts +1 -1
  32. package/src/testing/caller.ts +9 -2
  33. package/src/testing/endpoint-access.ts +2 -1
  34. package/src/testing/sample-file.ts +4 -1
  35. package/types/src/contract/declaration.d.ts +9 -1
  36. package/types/src/contract/define.d.ts +20 -1
  37. package/types/src/contract/group.d.ts +5 -3
  38. package/types/src/contract/index.d.ts +1 -0
  39. package/types/src/contract/vocabulary.d.ts +4 -1
  40. package/types/src/dev/output.d.ts +7 -6
  41. package/types/src/files/treatment.d.ts +4 -3
  42. package/types/src/implement/capability.d.ts +4 -4
  43. package/types/src/implement/client-address.d.ts +0 -5
  44. package/types/src/implement/dispatch.d.ts +11 -0
  45. package/types/src/implement/implement.d.ts +7 -0
  46. package/types/src/testing/caller.d.ts +1 -1
@@ -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 }),
@@ -19,6 +19,7 @@ import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
19
19
  import { dirname, join } from 'node:path'
20
20
  import { fileURLToPath } from 'node:url'
21
21
  import { z } from 'zod/v4'
22
+ import { environmentScrubber, type Scrubber } from '../jobs/scrub.js'
22
23
  import { makeProcessUndumpable } from '../undumpable.js'
23
24
  import { bootstrapReason, migrationsChanged, webSourceChanged } from './changes.js'
24
25
  import { OutputRing, type OutputSink, type OutputStream, processOutput, readLines } from './output.js'
@@ -152,20 +153,19 @@ const SUPERSEDED = 'a newer bootstrap run replaced this container; it stops foll
152
153
 
153
154
  const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
154
155
 
155
- /** Every value of the environment a log line must never show: the database credentials and every key, secret or token. */
156
- function secretValues(environment: Readonly<Record<string, string>>, runtimeUrl: string | null): string[] {
157
- const values = new Set<string>()
158
- const add = (value: string | undefined): void => {
159
- if (value !== undefined && value.length >= 8) values.add(value)
160
- }
161
- for (const url of [environment[PROVISIONING_DATABASE_URL], runtimeUrl ?? undefined]) {
162
- add(url)
163
- if (url !== undefined && URL.canParse(url)) add(decodeURIComponent(new URL(url).password))
164
- }
156
+ /**
157
+ * The scrubber of every line the launcher logs or reports: Operations' rule over the launcher's environment, with the
158
+ * runtime credential it derives, so the provisioning and `source` credentials count as the framework's secrets.
159
+ */
160
+ function outputScrubber(environment: Readonly<Record<string, string>>, runtimeUrl: string | null): Scrubber {
161
+ const framework: Record<string, string> = {}
162
+ const application: Record<string, string> = {}
165
163
  for (const [name, value] of Object.entries(environment)) {
166
- if (/(KEY|SECRET|PASSWORD|TOKEN|DATABASE_URL)$/.test(name)) add(value)
164
+ if (name.startsWith('FABRIKA_')) framework[name] = value
165
+ else application[name] = value
167
166
  }
168
- return [...values].sort((left, right) => right.length - left.length)
167
+ if (runtimeUrl !== null) framework[RUNTIME_DATABASE_URL] = runtimeUrl
168
+ return environmentScrubber({ framework, application })
169
169
  }
170
170
 
171
171
  const withoutFramework = (environment: Readonly<Record<string, string>>): Record<string, string> =>
@@ -215,7 +215,7 @@ class Launcher {
215
215
  if (runtimeUrl !== null) application[RUNTIME_DATABASE_URL] = runtimeUrl
216
216
  this.applicationEnvironment = application
217
217
  this.commandEnvironment = withoutFramework(options.environment)
218
- this.ring = new OutputRing(RING_LINES, secretValues(options.environment, runtimeUrl), options.output ?? processOutput)
218
+ this.ring = new OutputRing(RING_LINES, outputScrubber(options.environment, runtimeUrl), options.output ?? processOutput)
219
219
  }
220
220
 
221
221
  async start(): Promise<void> {
@@ -584,8 +584,7 @@ class Launcher {
584
584
  const child = Bun.spawn([...argv], { cwd: this.root, env, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
585
585
  const lines: string[] = []
586
586
  const collect = (stream: OutputStream) => (line: string) => {
587
- lines.push(line)
588
- this.ring.push(classify(stream, line), line)
587
+ lines.push(this.ring.push(classify(stream, line), line))
589
588
  }
590
589
  const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs)
591
590
  await Promise.all([readLines(child.stdout, collect('stdout')), readLines(child.stderr, collect('stderr')), child.exited])
package/src/dev/output.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  // The launcher's view of output: every line of the application and of the commands it runs is forwarded to its own
2
2
  // stream, as Zerops' runtime log reads it, and the newest lines are kept to report. Secret values never reach either.
3
3
 
4
+ import type { Scrubber } from '../jobs/scrub.js'
4
5
  import { DEV_REPORT_MAX_LINE_CHARACTERS, type DevLogLine } from './wire.js'
5
6
 
6
7
  export type OutputStream = DevLogLine['stream']
@@ -17,22 +18,24 @@ export const processOutput: OutputSink = {
17
18
  }
18
19
 
19
20
  /**
20
- * The newest `capacity` lines, numbered from 0 since the launcher started, with every known secret value replaced. A
21
- * mark starts the lines a report carries: those of the newest sync or reset, and the output after it.
21
+ * The newest `capacity` lines, numbered from 0 since the launcher started, each scrubbed of secrets once, as it arrives.
22
+ * A mark starts the lines a report carries: those of the newest sync or reset, and the output after it.
22
23
  */
23
24
  export class OutputRing {
24
25
  private readonly lines: DevLogLine[] = []
25
26
  private next = 0
26
27
  private marked = 0
27
28
 
28
- constructor(private readonly capacity: number, private readonly secrets: readonly string[], private readonly sink: OutputSink) {}
29
+ constructor(private readonly capacity: number, private readonly scrubber: Scrubber, private readonly sink: OutputSink) {}
29
30
 
30
- push(stream: OutputStream, text: string): void {
31
- const line = this.redact(text)
31
+ /** Log and keep `text` scrubbed, and return the scrubbed line: a caller keeps that copy and never the raw one. */
32
+ push(stream: OutputStream, text: string): string {
33
+ const line = this.scrubber.scrub(text)
32
34
  this.sink.write(stream, line)
33
35
  this.lines.push({ n: this.next, stream, text: line.slice(0, DEV_REPORT_MAX_LINE_CHARACTERS) })
34
36
  this.next += 1
35
37
  if (this.lines.length > this.capacity) this.lines.shift()
38
+ return line
36
39
  }
37
40
 
38
41
  /** Report from the next line on: the lines before it belong to an older head. */
@@ -45,12 +48,6 @@ export class OutputRing {
45
48
  const since = this.lines.filter((line) => line.n >= this.marked)
46
49
  return since.slice(Math.max(0, since.length - count))
47
50
  }
48
-
49
- private redact(text: string): string {
50
- let line = text
51
- for (const secret of this.secrets) line = line.replaceAll(secret, '[redacted]')
52
- return line
53
- }
54
51
  }
55
52
 
56
53
  /** Feed `stream` to `onLine` one line at a time; a last line without a newline is fed when the stream ends. */
@@ -1,4 +1,4 @@
1
- // The runtime of file kinds (`c.files({ types, maxBytes, scan? })`): a stored file is a value in a table column, and
1
+ // The runtime of file kinds (`c.files({ types, maxBytes, scan?, inline? })`): a stored file is a value in a table column, and
2
2
  // the table's policy is its authority. This module stages a file (an incoming part or a `ctx.files.put`): its pending
3
3
  // row first, on a connection of its own, then its object, sniffed and bounded by the kind. It serves and opens a file
4
4
  // only through a reference the work holds and may read, and only a live one, by its scanned version. The sweep
@@ -2,6 +2,8 @@
2
2
  // a file is stored only when its bytes are that type. A collection may admit only the types listed here, because
3
3
  // the framework cannot verify any other.
4
4
 
5
+ import { INLINE_DOCUMENT_TYPES } from '@fabrika/proxy-core/headers'
6
+
5
7
  /** How many leading bytes an upload is judged by. */
6
8
  export const SNIFF_BYTES = 512
7
9
 
@@ -45,7 +47,10 @@ const BINARY_SIGNATURES: readonly Signature[] = [
45
47
  /** Types judged as text: UTF-8 without NUL bytes, and no binary signature. SVG is text, and always an attachment. */
46
48
  const TEXT_TYPES: readonly string[] = ['text/plain', 'text/csv', 'text/markdown', 'application/json', 'image/svg+xml']
47
49
 
48
- export const SNIFFABLE_TYPES: readonly string[] = [...BINARY_SIGNATURES.flatMap((signature) => signature.types), ...TEXT_TYPES]
50
+ /** XML documents (a feed, a sitemap), the ones an inline kind shows: text whose first character, after a BOM and white space, is `<`. */
51
+ const XML_TYPES: readonly string[] = INLINE_DOCUMENT_TYPES
52
+
53
+ export const SNIFFABLE_TYPES: readonly string[] = [...BINARY_SIGNATURES.flatMap((signature) => signature.types), ...TEXT_TYPES, ...XML_TYPES]
49
54
 
50
55
  function isText(head: Uint8Array): boolean {
51
56
  if (head.includes(0) || BINARY_SIGNATURES.some((signature) => signature.matches(head))) {
@@ -66,5 +71,17 @@ export function bytesAreOfType(type: string, head: Uint8Array): boolean {
66
71
  if (signature !== undefined) {
67
72
  return signature.matches(head)
68
73
  }
74
+ if (XML_TYPES.includes(type)) {
75
+ return isText(head) && startsWithMarkup(head)
76
+ }
69
77
  return TEXT_TYPES.includes(type) && isText(head)
70
78
  }
79
+
80
+ const UTF8_BOM = [0xef, 0xbb, 0xbf]
81
+ const XML_WHITE_SPACE: readonly number[] = [0x20, 0x09, 0x0a, 0x0d]
82
+
83
+ function startsWithMarkup(head: Uint8Array): boolean {
84
+ let offset = bytesAt(head, 0, UTF8_BOM) ? UTF8_BOM.length : 0
85
+ while (offset < head.byteLength && XML_WHITE_SPACE.includes(head[offset] ?? -1)) offset++
86
+ return head[offset] === 0x3c
87
+ }
@@ -1,8 +1,9 @@
1
1
  // The file treatment (ADR-0022 rule 2): the header policy a download carries instead of the application's. Only
2
- // the inert images are shown inline; every other type, SVG and HTML included, is an attachment, and nothing a
3
- // download contains can run as this origin. The proxy applies the same definition, from `@fabrika/proxy-core/headers`.
2
+ // the inert images, and on a row of an inline kind the XML documents, are shown inline; every other type, SVG and HTML
3
+ // included, is an attachment, and nothing a download contains can run as this origin. The proxy applies the same
4
+ // definition, from `@fabrika/proxy-core/headers`.
4
5
 
5
- import { applyFileTreatment, fileDisposition, withResponseHeaders } from '@fabrika/proxy-core/headers'
6
+ import { applyFileTreatment, FILE_TREATMENT, fileDisposition, INLINE_FILE_TYPES, withResponseHeaders } from '@fabrika/proxy-core/headers'
6
7
 
7
8
  /** A file the download endpoint answers. `ContractRuntime` turns it into the response, with the file treatment. */
8
9
  export class FileDownload {
@@ -26,23 +27,24 @@ function filenameParameter(name: string): string {
26
27
  return `; filename*=UTF-8''${encoded}`
27
28
  }
28
29
 
29
- export function contentDisposition(contentType: string, name: string | null): string {
30
- return `${fileDisposition(contentType)}${name === null ? '' : filenameParameter(name)}`
30
+ /** `inline` is the row's `inlineFileTypes`. */
31
+ export function contentDisposition(contentType: string, name: string | null, inline: readonly string[] = INLINE_FILE_TYPES): string {
32
+ return `${fileDisposition(contentType, inline)}${name === null ? '' : filenameParameter(name)}`
31
33
  }
32
34
 
33
- export function fileResponse(file: FileDownload): Response {
35
+ export function fileResponse(file: FileDownload, inline: readonly string[]): Response {
34
36
  const headers = new Headers({
35
37
  'Content-Type': file.contentType,
36
38
  'Content-Length': String(file.size),
37
- 'Content-Disposition': contentDisposition(file.contentType, file.name),
39
+ 'Content-Disposition': contentDisposition(file.contentType, file.name, inline),
38
40
  // A Range request gets the whole file: ignoring Range is always a valid answer, and no partial path exists to get wrong.
39
41
  'Accept-Ranges': 'none',
40
42
  })
41
- applyFileTreatment(headers)
43
+ applyFileTreatment(headers, FILE_TREATMENT, inline)
42
44
  return new Response(file.body, { status: 200, headers })
43
45
  }
44
46
 
45
47
  /** An error of a download endpoint, with the file treatment in place of the header policy. */
46
- export function withFileTreatment(response: Response): Response {
47
- return withResponseHeaders(response, applyFileTreatment)
48
+ export function withFileTreatment(response: Response, inline: readonly string[]): Response {
49
+ return withResponseHeaders(response, (headers) => applyFileTreatment(headers, FILE_TREATMENT, inline))
48
50
  }
@@ -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)
@@ -2,78 +2,11 @@
2
2
  // `Admissions`), so every instance shares them. Admission is not authorization: it only bounds how much one client
3
3
  // calls a public procedure.
4
4
 
5
- import { CLIENT_ADDRESS_HEADER } from '@fabrika/auth-core'
5
+ import { CLIENT_ADDRESS_HEADER, clientAddressKey } from '@fabrika/auth-core'
6
6
  import { createHash } from 'node:crypto'
7
7
 
8
- /** Longest header value read; an IPv6 address with a zone id fits with room to spare. */
9
- const MAX_ADDRESS_LENGTH = 64
10
-
11
- const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(?:\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/
12
- const HEXTET = /^[0-9a-f]{1,4}$/
13
-
14
- /**
15
- * The eight groups of an IPv6 address, or `null`. An embedded IPv4 tail (`::ffff:192.0.2.1`) counts as two groups,
16
- * and a zone id (`%eth0`) is dropped.
17
- */
18
- function ipv6Groups(text: string): number[] | null {
19
- const address = text.split('%')[0] ?? ''
20
- const halves = address.split('::')
21
- if (halves.length > 2) {
22
- return null
23
- }
24
- const groupsOf = (half: string): number[] | null => {
25
- if (half === '') {
26
- return []
27
- }
28
- const groups: number[] = []
29
- const parts = half.split(':')
30
- for (const [index, part] of parts.entries()) {
31
- if (index === parts.length - 1 && IPV4.test(part)) {
32
- const [a = 0, b = 0, c = 0, d = 0] = part.split('.').map(Number)
33
- groups.push(a * 256 + b, c * 256 + d)
34
- } else if (HEXTET.test(part)) {
35
- groups.push(Number.parseInt(part, 16))
36
- } else {
37
- return null
38
- }
39
- }
40
- return groups
41
- }
42
- const head = groupsOf(halves[0] ?? '')
43
- const tail = halves.length === 2 ? groupsOf(halves[1] ?? '') : []
44
- if (head === null || tail === null) {
45
- return null
46
- }
47
- if (halves.length === 1) {
48
- return head.length === 8 ? head : null
49
- }
50
- const missing = 8 - head.length - tail.length
51
- return missing < 1 ? null : [...head, ...Array.from({ length: missing }, () => 0), ...tail]
52
- }
53
-
54
- /**
55
- * The client a per-client limit counts: an IPv4 address, or an IPv6 address's /64 (one subscriber's prefix, of which
56
- * it may hold every address). Anything else, the header's absence included, is one shared `unknown` client.
57
- */
58
- export function clientKey(header: string | null): string {
59
- const value = (header ?? '').split(',')[0]?.trim().toLowerCase() ?? ''
60
- if (value === '' || value.length > MAX_ADDRESS_LENGTH) {
61
- return 'unknown'
62
- }
63
- if (IPV4.test(value)) {
64
- return value
65
- }
66
- const groups = ipv6Groups(value.startsWith('[') && value.endsWith(']') ? value.slice(1, -1) : value)
67
- if (groups === null) {
68
- return 'unknown'
69
- }
70
- const mapped = groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xffff
71
- if (mapped) {
72
- const [high = 0, low = 0] = groups.slice(6)
73
- return [high >> 8, high & 0xff, low >> 8, low & 0xff].join('.')
74
- }
75
- return `${groups.slice(0, 4).map((group) => group.toString(16)).join(':')}::/64`
76
- }
8
+ /** The one client every request without a readable address shares. */
9
+ const UNKNOWN_CLIENT = 'unknown'
77
10
 
78
11
  /**
79
12
  * The bucket of the client the proxy saw. Only `X-Fabrika-Client-Ip` is read: the proxy deletes it and sets it from
@@ -81,5 +14,6 @@ export function clientKey(header: string | null): string {
81
14
  * client can write (`X-Forwarded-For`, `CF-Connecting-IP`) is never read. The address is kept as its digest.
82
15
  */
83
16
  export function clientBucket(request: Request): string {
84
- return `client:${createHash('sha256').update(clientKey(request.headers.get(CLIENT_ADDRESS_HEADER))).digest('hex')}`
17
+ const key = clientAddressKey(request.headers.get(CLIENT_ADDRESS_HEADER)) ?? UNKNOWN_CLIENT
18
+ return `client:${createHash('sha256').update(key).digest('hex')}`
85
19
  }