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

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 (48) hide show
  1. package/package.json +9 -9
  2. package/skill/SKILL.md +7 -4
  3. package/skill/references/app-setup.md +15 -8
  4. package/skill/references/endpoint.md +7 -1
  5. package/skill/references/errors.md +7 -6
  6. package/skill/references/jobs.md +10 -0
  7. package/skill/references/relations.md +682 -0
  8. package/skill/references/table-and-migration.md +18 -7
  9. package/skill/references/webhooks-links-connectors.md +2 -1
  10. package/src/bun.ts +10 -0
  11. package/src/contract/artifact-schema.ts +82 -1
  12. package/src/contract/build.ts +142 -12
  13. package/src/contract/compile.ts +1 -0
  14. package/src/contract/declaration.ts +4 -0
  15. package/src/contract/define.ts +12 -0
  16. package/src/contract/group.ts +10 -1
  17. package/src/contract/kit.ts +3 -1
  18. package/src/contract/platform.ts +1 -0
  19. package/src/contract/vocabulary.ts +3 -0
  20. package/src/disk-assets.ts +15 -3
  21. package/src/implement/boot.ts +59 -5
  22. package/src/implement/capability.ts +91 -6
  23. package/src/implement/dispatch.ts +334 -17
  24. package/src/implement/egress.ts +409 -9
  25. package/src/implement/implement.ts +28 -1
  26. package/src/implement/invocation.ts +10 -9
  27. package/src/implement/types.ts +15 -4
  28. package/src/implement/webhook.ts +8 -0
  29. package/src/jobs/runner.ts +7 -2
  30. package/src/source-map-path.ts +21 -0
  31. package/src/testing/caller.ts +20 -2
  32. package/src/testing/membership.ts +9 -5
  33. package/types/src/contract/declaration.d.ts +6 -0
  34. package/types/src/contract/define.d.ts +15 -0
  35. package/types/src/contract/group.d.ts +9 -1
  36. package/types/src/contract/kit.d.ts +2 -2
  37. package/types/src/contract/vocabulary.d.ts +4 -1
  38. package/types/src/implement/boot.d.ts +6 -0
  39. package/types/src/implement/capability.d.ts +14 -5
  40. package/types/src/implement/dispatch.d.ts +20 -1
  41. package/types/src/implement/egress.d.ts +36 -1
  42. package/types/src/implement/implement.d.ts +24 -1
  43. package/types/src/implement/invocation.d.ts +3 -3
  44. package/types/src/implement/types.d.ts +13 -3
  45. package/types/src/jobs/runner.d.ts +3 -0
  46. package/types/src/source-map-path.d.ts +4 -0
  47. package/types/src/testing/caller.d.ts +6 -1
  48. package/types/src/testing/membership.d.ts +1 -1
@@ -0,0 +1,21 @@
1
+ // Whether a request names a source map. An SPA mount never serves one: the build sends its sources to Operations. The
2
+ // decision reads the path the way the asset servers resolve it, not the way it was spelled: each segment decoded, empty
3
+ // segments dropped, and any case, because a case-insensitive filesystem opens `x.js.MAP` as `x.js.map`.
4
+
5
+ /** The last non-empty segment of `pathname`, decoded, names a `.map` file; an undecodable one is refused too. */
6
+ export function namesSourceMap(pathname: string): boolean {
7
+ const last = pathname.split('/').filter((segment) => segment !== '').at(-1)
8
+ if (last === undefined) return false
9
+ let decoded: string
10
+ try {
11
+ decoded = decodeURIComponent(last)
12
+ } catch {
13
+ return true
14
+ }
15
+ return isSourceMapName(decoded)
16
+ }
17
+
18
+ /** A file name, already decoded, that is a source map in any case. */
19
+ export function isSourceMapName(name: string): boolean {
20
+ return name.toLowerCase().endsWith('.map')
21
+ }
@@ -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, relationInsideScope, type Scope } 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,24 @@ 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 scope = scopeOf(grant.scope)
122
+ const entries: PermissionEntry[] = role.grants.map((action) => ({ action, scope, source: 'grant' }))
123
+ return role.external === true ? entries : [...entries, ...relationEntries(role.via, scope)]
122
124
  })
123
125
  }
126
+
127
+ /**
128
+ * The entries a grant of a role with `via` adds at `scope`, as IAM resolves them: each action through its relation,
129
+ * anywhere (`~rel`) for a global grant and only inside the node (`~relin`) for a scoped one. A name holding `:` adds none.
130
+ */
131
+ export function relationEntries(via: Readonly<Record<string, readonly string[]>> | undefined, scope: Scope | null): PermissionEntry[] {
132
+ const entries: PermissionEntry[] = []
133
+ for (const [relation, actions] of Object.entries(via ?? {})) {
134
+ if (scope !== null && (relation.includes(':') || scope.type.includes(':'))) continue
135
+ const held = scope === null
136
+ ? { type: RELATION_SCOPE_TYPE, value: relation }
137
+ : relationInsideScope({ relation, dimension: scope.type, node: scope.value })
138
+ for (const action of actions) entries.push({ action, scope: held, source: 'grant' })
139
+ }
140
+ return entries
141
+ }
@@ -49,7 +49,7 @@ import {
49
49
  type RevokeMemberResult,
50
50
  type Scope,
51
51
  } from '@fabrika/auth-core'
52
- import type { LabelledTestCaller, TestCaller, TestScope } from './caller'
52
+ import { type LabelledTestCaller, relationEntries, type TestCaller, type TestScope } from './caller'
53
53
 
54
54
  /** A role a test caller holds in one scope value, or globally (`null`). */
55
55
  export interface TestMembership {
@@ -411,10 +411,12 @@ function membershipChanges(artifact: ContractArtifact, callers: DirectoryCallers
411
411
  }
412
412
  }
413
413
 
414
- /** The permissions a role grants in `scope`, as IAM resolves a membership. */
414
+ /** The permissions a role grants in `scope`, its relations' included, as IAM resolves a membership. */
415
415
  function roleEntries(artifact: ContractArtifact, held: TestMembership): PermissionEntry[] {
416
416
  const scope = held.scope === null ? null : { type: held.scope.type, value: held.scope.value }
417
- return (artifact.roles[held.role]?.grants ?? []).map((action) => ({ action, scope, source: 'grant' }))
417
+ const role = artifact.roles[held.role]
418
+ const entries: PermissionEntry[] = (role?.grants ?? []).map((action) => ({ action, scope, source: 'grant' }))
419
+ return role === undefined || role.external === true ? entries : [...entries, ...relationEntries(role.via, scope)]
418
420
  }
419
421
 
420
422
  const samePermission = (left: PermissionEntry, right: PermissionEntry): boolean =>
@@ -521,7 +523,8 @@ export function kitMembership(artifact: ContractArtifact, callers: DirectoryCall
521
523
 
522
524
  /**
523
525
  * Could `caller` give `role` in `scope`: it holds an assigning role — there, or an application-wide role globally —
524
- * and every action the role grants there.
526
+ * and every action the role grants there, through a relation included, by a plain grant (`permits` reads no `~`
527
+ * entry).
525
528
  */
526
529
  const roleProblem = (caller: TestCaller, scope: Scope, role: string): MembershipFailure | null => {
527
530
  const declared = Object.hasOwn(artifact.roles, role) ? artifact.roles[role] : undefined
@@ -536,7 +539,8 @@ export function kitMembership(artifact: ContractArtifact, callers: DirectoryCall
536
539
  const held = [...changes.rolesOf(caller.id, scope), ...appWide.map((grant) => grant.role)]
537
540
  if (!declared.member.assignableBy.some((assigner) => held.includes(assigner))) return NOT_ALLOWED
538
541
  const perms = [...permsOf(caller)]
539
- return declared.grants.every((action) => permits(perms, action, scope)) ? null : NOT_ALLOWED
542
+ const delegated = [...declared.grants, ...Object.values(declared.via ?? {}).flat()]
543
+ return delegated.every((action) => permits(perms, action, scope)) ? null : NOT_ALLOWED
540
544
  }
541
545
 
542
546
  const requestDelegation = (input: RequestDelegationInput): RequestDelegationResult => {
@@ -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,18 @@ 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 grant at a value holds them only on rows inside that
70
+ * value, so a membership role's relation has the role's dimension or one inside it. An external role takes none.
71
+ */
72
+ readonly via?: {
73
+ readonly [relation: string]: readonly A[];
74
+ };
75
+ }
76
+ /** A relation of the vocabulary: a table's rows name a principal at a node of `dimension` (`confers` on that table). */
77
+ export interface RelationDef<D extends string> {
78
+ readonly dimension: D;
67
79
  }
68
80
  export interface Vocabulary<A extends string, D extends string, R extends string> extends Presentation, AppPeople<A>, AppTerminal {
69
81
  readonly app: string;
@@ -76,6 +88,9 @@ export interface Vocabulary<A extends string, D extends string, R extends string
76
88
  readonly roles: {
77
89
  readonly [K in R]: RoleDef<A, D, R>;
78
90
  };
91
+ readonly relations?: {
92
+ readonly [name: string]: RelationDef<D>;
93
+ };
79
94
  }
80
95
  /** The actions that manage and list the application's own people. */
81
96
  export interface AppMembers<A extends string> {
@@ -74,7 +74,15 @@ export type SignsField<Sg, Purposes extends string> = {
74
74
  * guard on the global `fetch` refuses any other while the site runs; a public procedure declares none.
75
75
  */
76
76
  export interface EgressField {
77
- readonly egress?: readonly `https://${string}`[];
77
+ readonly egress?: readonly `https://${string}`[] | Unavailable<"egress: 'public' is a cron job's only: record a row and kick a job that declares it">;
78
+ }
79
+ /**
80
+ * A cron job's `egress`: its exact HTTPS origins, or `'public'`, every public host over HTTPS or HTTP on its default
81
+ * port, for a job that calls the websites its operators name (ADR-0075). The guard refuses IP addresses, local and
82
+ * internal names and the installation's own hosts, checks each redirect, and bounds each request's time and body.
83
+ */
84
+ export interface JobEgressField {
85
+ readonly egress?: readonly `https://${string}`[] | 'public';
78
86
  }
79
87
  /** Each purpose `signs` names is one of `defineApp`'s `tokens`. */
80
88
  type KnownPurposes<Sg, Purposes extends string> = Sg extends readonly (infer P extends string)[] ? [Exclude<P, Purposes>] extends [never] ? LiteralList<Sg> : Unavailable<`signs names ${ListOf<Exclude<P, Purposes>>}, which defineApp's tokens do not declare`> : unknown;
@@ -4,7 +4,7 @@ import type { z } from 'zod/v4';
4
4
  import type { Declared, JobKitContext, KickContext, KitImports, KitTypes, NoTablesIndex, SqlMode, TokensContext, WebhookKitContext } from './context';
5
5
  import { type ExportAccessDeclaration, type ImportDeclaration, type LinkAccessDeclaration, type ProcedureType } from './declaration';
6
6
  import { type Contract, type CreatableDimension, type CronJob, type Export, type InputSchema, type JobLimitsOption, type Kit, type LinkMount, type NotLoose, type Path, type ProcedureTree, type RpcMount, type Schema, type Surface, type WebhookMount } from './define';
7
- import type { DeclaredFields, EgressField, Endpoint, ExportKit, Group, GroupBuild, GroupInput, GroupKit, KicksField, LimitsOption, LinkGroupKit, ListOf, PendingIn, SignsField } from './group';
7
+ import type { DeclaredFields, EgressField, Endpoint, ExportKit, Group, GroupBuild, GroupInput, GroupKit, JobEgressField, KicksField, LimitsOption, LinkGroupKit, ListOf, PendingIn, SignsField } from './group';
8
8
  import type { TokenPurposes } from './token';
9
9
  import type { AnyAppVocabulary, AppVocabulary } from './vocabulary';
10
10
  /** Fields a builder sets itself: an options object that carries one does not type-check. */
@@ -31,7 +31,7 @@ export type CronOptions<Acts, S, U, Is, Ix extends AnyDbIndex, M = never, Ks = n
31
31
  readonly actions: Acts;
32
32
  readonly limits?: JobLimitsOption;
33
33
  readonly retries?: number;
34
- } & DeclaredFields<S, U, never, Is, Ix> & MailerField<M> & KicksField<Ks> & SignsField<Sg, Purposes> & EgressField;
34
+ } & DeclaredFields<S, U, never, Is, Ix> & MailerField<M> & KicksField<Ks> & SignsField<Sg, Purposes> & JobEgressField;
35
35
  /** The mail transport a job reaches, inferred from its optional field and then required, like a declared field. */
36
36
  type MailerField<M> = {
37
37
  /** `'installation'`: the installation's mail transport; `'own'`: the application's own. */
@@ -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;
@@ -10,6 +10,7 @@ import { type ContractJobs } from '../jobs/runner';
10
10
  import type { ChallengeFetch, ChallengeWork } from './challenge';
11
11
  import { type ConnectFetch } from './connect';
12
12
  import { type SpaAssets } from './dispatch';
13
+ import { type HostResolver } from './egress';
13
14
  import type { CapturedEnvironment } from './environment';
14
15
  import { type HandlerErrorSink } from './failures';
15
16
  import type { ContractImplementation } from './implement';
@@ -64,6 +65,11 @@ export interface BootOptions {
64
65
  * with a job or a webhook does not boot.
65
66
  */
66
67
  readonly workloadTokens?: WorkloadTokenSource;
68
+ /**
69
+ * Resolves a host name to its addresses, which the Bun adapter supplies (`node:dns`): a cron job's public egress then
70
+ * refuses a public name of a private address before each hop. A Worker exposes no resolution and passes none.
71
+ */
72
+ readonly resolveHost?: HostResolver;
67
73
  /** What posts a report to Operations' ingest; `fetch` by default. */
68
74
  readonly operationsFetch?: (request: Request) => Promise<Response>;
69
75
  /** What asks a public procedure's challenge provider to verify a token; `fetch` by default. */
@@ -1,4 +1,4 @@
1
- import { type AppCapability as AppCapabilityType, type CapabilityAuthority, type ContainerGrant, type LeaseFence, type Ref as RefCapability, type RowGrant, type RowRef as RowRefCapability, type Within as WithinCapability } from '@fabrika/db/capability';
1
+ import { type AppCapability as AppCapabilityType, type CapabilityAuthority, type ContainerGrant, type LeaseFence, type Ref as RefCapability, type RelationHold, type RowGrant, type RowRef as RowRefCapability, type Within as WithinCapability, type WithinGrant } from '@fabrika/db/capability';
2
2
  /** Why a capability or a handle was refused, as a closed catalog with the fixed text a log may print. */
3
3
  export declare const CAPABILITY_REFUSALS: {
4
4
  readonly not_minted: "a value the framework did not mint was used as a capability; pass the ctx.target or ctx.within of this request";
@@ -11,7 +11,11 @@ export declare const CAPABILITY_REFUSALS: {
11
11
  readonly undeclared_binding: "the site named a webhook it does not declare in binds";
12
12
  readonly undeclared_signs: "the site signed a token of a purpose it does not declare in signs, or for longer than the purpose allows";
13
13
  readonly undeclared_egress: "the site called an origin it does not declare in egress";
14
+ readonly refused_egress: "the site's public egress refused the host: an IP address, a local or internal name, a non-default port, credentials in the URL, a host of this installation, or a name that resolves to a private address";
15
+ readonly oversized_egress: "a response to the site's public egress was larger than it reads";
16
+ readonly encoded_egress: "a response to the site's public egress came compressed, which it neither asks for nor decodes";
14
17
  readonly wrong_binding: "a webhook binding was handed a capability of another kind or dimension than the webhook is bound to";
18
+ readonly conditional_binding: "a webhook binding was handed a Ref held through a relation, a member reveal or a secondary path, which a binding would outlive";
15
19
  readonly missing_id: "the job named an object without an id";
16
20
  readonly wrong_capability: "an operation was handed a capability of another dimension or action than it needs";
17
21
  };
@@ -27,6 +31,8 @@ export declare class CapabilityRefusedError extends Error {
27
31
  export declare class CapabilityLimitError extends Error {
28
32
  readonly name = "CapabilityLimitError";
29
33
  }
34
+ /** The caller's grants of `action` in `dimension`, as a `Within` of it would carry them; no values when it holds none. */
35
+ export type Standing = (dimension: string, action: string) => WithinGrant;
30
36
  /**
31
37
  * One request's lifetime, or one job attempt's. A capability minted in it is usable only while it runs, and only
32
38
  * inside it; a job attempt's writes also need its lease (`fence`).
@@ -39,10 +45,13 @@ export declare class RequestFrame {
39
45
  readonly readOnly: boolean;
40
46
  /** The endpoint the request is served by; `ctx.connect` checks it against each import's `usedBy`. */
41
47
  readonly endpoint: string | null;
48
+ /** What the request's caller holds of an action in a dimension; none for work without a caller (a job, a webhook). */
49
+ readonly standing: Standing | null;
42
50
  constructor(id: string, options?: {
43
51
  readonly fence?: LeaseFence | null;
44
52
  readonly readOnly?: boolean;
45
53
  readonly endpoint?: string | null;
54
+ readonly standing?: Standing | null;
46
55
  });
47
56
  get ended(): boolean;
48
57
  end(): void;
@@ -63,7 +72,7 @@ export declare class Ref<D extends string, A extends string> implements RefCapab
63
72
  readonly dimension: D;
64
73
  readonly action: A;
65
74
  };
66
- constructor(token: typeof MINT, issuer: object, frame: RequestFrame, dimension: D, action: A, principal: string, id: string, chain: ReadonlyMap<string, string>);
75
+ constructor(token: typeof MINT, issuer: object, frame: RequestFrame, dimension: D, action: A, principal: string, id: string, chain: ReadonlyMap<string, string>, relations: readonly RelationHold[], revealing: readonly ContainerGrant[], paths: readonly ContainerGrant[]);
67
76
  get dimension(): D;
68
77
  get action(): A;
69
78
  /** The object's id: the value of its dimension. */
@@ -82,7 +91,7 @@ export declare class Within<D extends string, A extends string> implements Withi
82
91
  readonly dimension: D;
83
92
  readonly action: A;
84
93
  };
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[]);
94
+ 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 RelationHold[], revealing: readonly ContainerGrant[]);
86
95
  get dimension(): D;
87
96
  get action(): A;
88
97
  /** The values of this dimension itself. */
@@ -124,8 +133,8 @@ export declare class RowRef<T extends string, A extends string> implements RowRe
124
133
  }
125
134
  /** Makes the capabilities one authority accepts; a runtime's is held by the `boot` call that made it alone. */
126
135
  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>;
136
+ ref<D extends string, A extends string>(frame: RequestFrame, dimension: D, action: A, principal: string, id: string, chain: ReadonlyMap<string, string>, relations?: readonly RelationHold[], revealing?: readonly ContainerGrant[], paths?: readonly ContainerGrant[]): Ref<D, A>;
137
+ 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 RelationHold[], revealing?: readonly ContainerGrant[]): Within<D, A>;
129
138
  app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A>;
130
139
  }
131
140
  /** A mint and the one authority that accepts what it mints. */
@@ -12,6 +12,7 @@ import type { BrowserConfig } from './browser-config';
12
12
  import { type CapabilityMint } from './capability';
13
13
  import type { ChallengeIssuer } from './challenge';
14
14
  import { type ImportWire } from './connect';
15
+ import { type SiteEgress } from './egress';
15
16
  import type { FailureReports } from './failures';
16
17
  import { type HeaderPolicy } from './headers';
17
18
  import type { ContractDatabase } from './implement';
@@ -97,7 +98,7 @@ export type ServedEndpoint = {
97
98
  /** A staged-kit site, which gets `ctx.db`; a handler `implement` bound has none. */
98
99
  readonly site?: ServedSite;
99
100
  /** The origins a staged-kit site's `fetch` reaches while its handler runs; absent for a handler `implement` bound. */
100
- readonly egress?: readonly string[];
101
+ readonly egress?: SiteEgress;
101
102
  /** Its buckets and time limit; without them (a generated endpoint) no bucket and the request budget. */
102
103
  readonly admission?: ProcedureAdmission;
103
104
  /** A POST's `query`, parsed from the URL beside the body: its schema and its shape. */
@@ -188,6 +189,16 @@ export interface ProcedureQuery {
188
189
  readonly schema: Schema;
189
190
  readonly shape: SchemaShape;
190
191
  }
192
+ /** A relation's reveal: a row it reaches reveals its node in `dimension` for `actions`. */
193
+ export interface RevealedNode {
194
+ readonly dimension: string;
195
+ readonly actions: readonly string[];
196
+ }
197
+ /** A secondary path of a dimension's table: the dimension it reaches, and the actions a Ref holds through it. */
198
+ export interface HeldPath {
199
+ readonly dimension: string;
200
+ readonly actions: readonly string[];
201
+ }
191
202
  export interface RuntimeParts {
192
203
  readonly table: CompiledEndpointTable;
193
204
  readonly endpoints: ReadonlyMap<string, ServedEndpoint>;
@@ -204,6 +215,14 @@ export interface RuntimeParts {
204
215
  readonly ownedDimensions: ReadonlySet<string>;
205
216
  /** Each dimension's containers, nearest first; a grant on one reaches every value inside it. */
206
217
  readonly containers: ReadonlyMap<string, readonly string[]>;
218
+ /** Each relation of the contract with its dimension: a `~rel` entry holds its action at that dimension's nodes. */
219
+ readonly relations: ReadonlyMap<string, string>;
220
+ /** Each relation's reveals: a `~rel` entry of one of their actions also holds it at the ancestor nodes they reveal. */
221
+ readonly reveals: ReadonlyMap<string, readonly RevealedNode[]>;
222
+ /** Each dimension's member reveals: a grant of one of their actions at its node also reads under the ancestor they reveal. */
223
+ readonly memberReveals: ReadonlyMap<string, readonly RevealedNode[]>;
224
+ /** Each dimension's secondary paths that hold actions for a Ref: a grant of one at the node a path names reaches the object. */
225
+ readonly paths: ReadonlyMap<string, readonly HeldPath[]>;
207
226
  readonly assets: SpaAssets | null;
208
227
  /** IAM's membership operations; `boot` refuses a contract that needs them when the adapter supplies none. */
209
228
  readonly membership: IamMembership | null;
@@ -1,5 +1,40 @@
1
+ import { type DeclaredEgress } from '@fabrika/auth-core';
2
+ /** The addresses a host name resolves to, where the runtime exposes resolution: Bun's `node:dns`, never a Worker. */
3
+ export type HostResolver = (hostname: string) => Promise<readonly string[]>;
4
+ /** What public egress refuses beyond what a URL alone shows (`publicEgressRefusal`). */
5
+ export interface PublicEgressRules {
6
+ /** The installation's own hosts, normalized: every host a framework variable names, and `FABRIKA_EGRESS_REFUSED_HOSTS`. */
7
+ readonly refusedHosts: ReadonlySet<string>;
8
+ /** Resolves each hop's host once, before it is sent to an address checked here; `null` on Cloudflare. */
9
+ readonly resolve: HostResolver | null;
10
+ }
11
+ /** What one site's `fetch` reaches: its declared origins, or the rules of public egress. */
12
+ export type SiteEgress = readonly string[] | PublicEgressRules;
13
+ /**
14
+ * The bounds of one request under public egress, the redirects it follows included. The handler's own signal still
15
+ * aborts it sooner (`ctx.signal`, an `AbortSignal.timeout` of its own).
16
+ */
17
+ export declare const PUBLIC_EGRESS_LIMITS: {
18
+ /** One request, its redirects and the reading of its body included: the abort also stops a body still streaming. */
19
+ readonly timeoutMs: 60000;
20
+ /** One response's body as the handler reads it; a larger one is refused, by its `Content-Length` or while it streams. */
21
+ readonly maxResponseBytes: number;
22
+ /** The redirects one request follows when its `redirect` mode is `follow`, each hop checked again. */
23
+ readonly maxRedirects: 10;
24
+ };
1
25
  /** Runs a site's handler: every `fetch` it starts reaches only `egress`. */
2
- export declare function runAsSite<T>(site: string, egress: readonly string[], work: () => Promise<T>): Promise<T>;
26
+ export declare function runAsSite<T>(site: string, egress: SiteEgress, work: () => Promise<T>): Promise<T>;
27
+ /**
28
+ * The egress a site runs with: its declared origins, or `rules` for `'public'`. Only a cron job's runner holds rules; a
29
+ * site run without them reaches nothing, though the build lets no other site declare `'public'`.
30
+ */
31
+ export declare function siteEgress(declared: DeclaredEgress, rules: PublicEgressRules | null): SiteEgress;
32
+ /**
33
+ * The rules of public egress in one environment: the hosts its framework variables name (IAM, Operations, its own
34
+ * origin, the platform's receivers, the object store), the installation hosts Control hands it, and the resolver the
35
+ * runtime adapter supplies.
36
+ */
37
+ export declare function publicEgressRules(framework: Readonly<Record<string, string>>, resolve: HostResolver | null): PublicEgressRules;
3
38
  /**
4
39
  * `facility` with each of its methods run outside any site's scope: a framework facility a handler calls, whose own
5
40
  * requests are the platform's, not the site's.
@@ -1,6 +1,6 @@
1
1
  import type { TablePolicyArtifact } from '@fabrika/auth-core';
2
2
  import type { DataLayer } from '@fabrika/db';
3
- import type { CapabilityAuthority } from '@fabrika/db/capability';
3
+ import type { CapabilityAuthority, ContainerGrant, RelationHold } from '@fabrika/db/capability';
4
4
  import type { Session } from '@fabrika/db/framework';
5
5
  import type { EmailSender } from '@fabrika/email';
6
6
  import type { ConnectSnapshot } from '../contract/connect';
@@ -18,6 +18,29 @@ 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
+ /**
27
+ * Whether a row `relation` reaches for `principal` reveals `node` of `dimension` for `action` now; none in a layer of
28
+ * the application's own.
29
+ */
30
+ reveals?(relation: string, dimension: string, node: string, principal: string, action: string): Promise<boolean>;
31
+ /**
32
+ * Of `relations` and `paths`, the caller's relations and grants of `action` that reach the object through a secondary
33
+ * path that holds the action for a Ref (`writeThrough`); none in a layer of the application's own.
34
+ */
35
+ holdsThrough?(dimension: string, id: string, action: string, principal: string, relations: readonly RelationHold[], paths: readonly ContainerGrant[]): Promise<{
36
+ readonly relations: readonly RelationHold[];
37
+ readonly paths: readonly ContainerGrant[];
38
+ }>;
39
+ /**
40
+ * Of `values`, the caller's grants of `action` at nodes of `revealing`, those whose row reveals `node` of `dimension`
41
+ * to its members now; none in a layer of the application's own.
42
+ */
43
+ revealsToMembers?(revealing: string, values: readonly string[], dimension: string, node: string, action: string): Promise<readonly string[]>;
21
44
  }
22
45
  /** `scoped(tables)` of `@fabrika/db`, which `boot` binds, or a `ContractDatabase` of the application's own. */
23
46
  export type ImplementationDatabase = DataLayer | ContractDatabase;
@@ -1,4 +1,4 @@
1
- import { type ContractArtifact, type JobMailer } from '@fabrika/auth-core';
1
+ import { type ContractArtifact, type DeclaredEgress, type JobMailer } from '@fabrika/auth-core';
2
2
  import { type DataAccess, type DataHandles, type FileBinding, type NewWake, type Session, type SqlTag } from '@fabrika/db/framework';
3
3
  import type { DataKind, UnscopedMode } from '@fabrika/db/tables';
4
4
  import type { SqlMode } from '../contract/context';
@@ -16,8 +16,8 @@ export interface SiteDeclaration {
16
16
  readonly binds: string | null;
17
17
  /** The token purposes `ctx.tokens.sign` may sign. */
18
18
  readonly signs: readonly string[];
19
- /** The HTTPS origins the global `fetch` reaches while the site's handler runs. */
20
- readonly egress: readonly string[];
19
+ /** The HTTPS origins the global `fetch` reaches while the site's handler runs, or `'public'`: every public host (a cron job). */
20
+ readonly egress: DeclaredEgress;
21
21
  }
22
22
  /** A public procedure's reach: the texts the verified signed tokens of its request carry, which name the rows it changes. */
23
23
  export interface PublicReach {
@@ -240,9 +240,19 @@ export type HandlersOf<C, Snap = unknown> = {
240
240
  } & JobHandlersOf<C> & ExportHandlersOf<C>;
241
241
  /** An `any` comes from an error elsewhere in the handler; reporting it here too would only add noise. */
242
242
  export type IsAny<T> = 0 extends 1 & T ? true : false;
243
- /** Fields of `R` that the output `O` does not declare. When `O` is a union, a value that fits one branch has none. */
244
- export type ExtraKeys<R, O> = IsAny<R> extends true ? never : true extends (O extends unknown ? ([ExtraKeysOf<R, O>] extends [never] ? true : false) : never) ? never : ExtraKeysOf<R, O>;
245
- type ExtraKeysOf<R, O> = R extends readonly (infer RE)[] ? (O extends readonly (infer OE)[] ? ExtraKeys<RE, OE> : never) : R extends object ? O extends object ? Exclude<keyof R, keyof O> | {
243
+ /**
244
+ * Fields of `R` that the output `O` does not declare. Each member of a union `R` is paired with `O` on its own, and a
245
+ * member that fits one branch of a union `O` has none.
246
+ */
247
+ export type ExtraKeys<R, O> = IsAny<R> extends true ? never : R extends unknown ? true extends (O extends unknown ? ([ExtraKeysOf<R, O>] extends [never] ? true : false) : never) ? never : ExtraKeysOf<R, O> : never;
248
+ /**
249
+ * Optional keys that can hold only `undefined`: TypeScript adds them when it widens object literals of different
250
+ * shapes to one type (`{ x } | { x, y }` read as `{ x, y?: undefined }`). They carry no value, and projection drops them.
251
+ */
252
+ type EmptyKeys<R> = {
253
+ [K in keyof R]-?: object extends Pick<R, K> ? ([Exclude<R[K], undefined>] extends [never] ? K : never) : never;
254
+ }[keyof R];
255
+ type ExtraKeysOf<R, O> = R extends readonly (infer RE)[] ? (O extends readonly (infer OE)[] ? ExtraKeys<RE, OE> : never) : R extends object ? O extends object ? Exclude<keyof R, keyof O | EmptyKeys<R>> | {
246
256
  [Q in keyof R & keyof O]: ExtraKeys<R[Q], O[Q]>;
247
257
  }[keyof R & keyof O] : never : never;
248
258
  type Returned<F> = F extends (args: never) => infer R ? Awaited<R> : never;
@@ -4,6 +4,7 @@ import type { CapabilityAuthority } from '@fabrika/db/capability';
4
4
  import { type DataAccess, type FrameworkTables, type LeaseFence, type Session } from '@fabrika/db/framework';
5
5
  import { type StoredFileKinds } from '../files/kinds';
6
6
  import { type CapabilityMint } from '../implement/capability';
7
+ import { type PublicEgressRules } from '../implement/egress';
7
8
  import { type HandlerErrorSink } from '../implement/failures';
8
9
  import type { ContractDatabase } from '../implement/implement';
9
10
  import type { SignedTokens } from '../implement/tokens';
@@ -197,6 +198,8 @@ export interface JobBindingInput {
197
198
  readonly tokens?: SignedTokens;
198
199
  /** `ctx.url`: absolute links to the application's own procedures; without it every link is refused. */
199
200
  readonly url?: AppUrl;
201
+ /** The rules of public egress, which `boot` reads from the environment; without them a public job reaches nothing. */
202
+ readonly publicEgress?: PublicEgressRules;
200
203
  }
201
204
  export interface BoundJobs {
202
205
  readonly jobs: ContractJobs;
@@ -0,0 +1,4 @@
1
+ /** The last non-empty segment of `pathname`, decoded, names a `.map` file; an undecodable one is refused too. */
2
+ export declare function namesSourceMap(pathname: string): boolean;
3
+ /** A file name, already decoded, that is a source map in any case. */
4
+ export declare function isSourceMapName(name: string): boolean;
@@ -1,4 +1,4 @@
1
- import type { PermissionEntry, PrincipalAffiliation } from '@fabrika/auth-core';
1
+ import { type PermissionEntry, type PrincipalAffiliation, type Scope } 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';
@@ -92,4 +92,9 @@ export interface LinkTestCaller extends TestCallerCredential {
92
92
  export type TestCaller = LabelledTestCaller | LinkTestCaller;
93
93
  /** The permissions `grants` resolve to: a role becomes each of its actions in the role's scope. */
94
94
  export declare function resolveGrants<C extends AnyContract>(contract: C, grants: readonly TestGrant<C>[]): PermissionEntry[];
95
+ /**
96
+ * The entries a grant of a role with `via` adds at `scope`, as IAM resolves them: each action through its relation,
97
+ * anywhere (`~rel`) for a global grant and only inside the node (`~relin`) for a scoped one. A name holding `:` adds none.
98
+ */
99
+ export declare function relationEntries(via: Readonly<Record<string, readonly string[]>> | undefined, scope: Scope | null): PermissionEntry[];
95
100
  export {};
@@ -1,5 +1,5 @@
1
1
  import { type ContractArtifact, type IamMembershipRpc, type MemberTarget, type PermissionEntry, type RevokeMemberInput, type Scope } from '@fabrika/auth-core';
2
- import type { TestCaller, TestScope } from './caller';
2
+ import { type TestCaller, type TestScope } from './caller';
3
3
  /** A role a test caller holds in one scope value, or globally (`null`). */
4
4
  export interface TestMembership {
5
5
  readonly role: string;