@powerhousedao/reactor-api 6.2.3-dev.78 → 6.2.3-dev.79

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 (25) hide show
  1. package/dist/{base-document-models-By4P20-z.mjs → base-document-models-ux7TZ9X3.mjs} +5 -5
  2. package/dist/{base-document-models-By4P20-z.mjs.map → base-document-models-ux7TZ9X3.mjs.map} +1 -1
  3. package/dist/index.d.mts +843 -780
  4. package/dist/index.d.mts.map +1 -1
  5. package/dist/index.mjs +417 -359
  6. package/dist/index.mjs.map +1 -1
  7. package/dist/{package-subgraph-check-6tK9LMg1.mjs → package-subgraph-check-BGfeyfnc.mjs} +4 -4
  8. package/dist/{package-subgraph-check-6tK9LMg1.mjs.map → package-subgraph-check-BGfeyfnc.mjs.map} +1 -1
  9. package/dist/{pglite-node-DOFZDYCK.mjs → pglite-node-DGms6Ssa.mjs} +18 -5
  10. package/dist/pglite-node-DGms6Ssa.mjs.map +1 -0
  11. package/dist/src/graphql/subgraph-types.mjs +1 -1
  12. package/dist/src/packages/vite-loader.d.mts +2 -2
  13. package/dist/src/packages/vite-loader.d.mts.map +1 -1
  14. package/dist/src/packages/vite-loader.mjs +29 -10
  15. package/dist/src/packages/vite-loader.mjs.map +1 -1
  16. package/dist/src/pglite/pglite-node.d.mts +5 -0
  17. package/dist/src/pglite/pglite-node.d.mts.map +1 -1
  18. package/dist/src/pglite/pglite-node.mjs +4 -4
  19. package/dist/{subgraph-extraction-zUDn2zX_.mjs → subgraph-extraction-BYKOycxo.mjs} +18 -4
  20. package/dist/subgraph-extraction-BYKOycxo.mjs.map +1 -0
  21. package/dist/{types-CCI5IDgT.d.mts → types-BEpxtyKW.d.mts} +2 -2
  22. package/dist/{types-CCI5IDgT.d.mts.map → types-BEpxtyKW.d.mts.map} +1 -1
  23. package/package.json +13 -13
  24. package/dist/pglite-node-DOFZDYCK.mjs.map +0 -1
  25. package/dist/subgraph-extraction-zUDn2zX_.mjs.map +0 -1
package/dist/index.d.mts CHANGED
@@ -1,19 +1,19 @@
1
1
  import { n as PGLITE_UTC_PARSERS, t as PGliteLike } from "./pglite-like-CKQEL_Q0.mjs";
2
- import { a as IPackagePieceSource, c as PackageManagerResult, d as ReportError, f as RunDetachedOptions, i as IPackageManagerOptions, l as PackagePiece, m as runDetached, n as IPackageLoaderOptions, p as reportFailure, r as IPackageManager, t as IPackageLoader, u as PackagePieceEntry } from "./types-CCI5IDgT.mjs";
2
+ import { a as IPackagePieceSource, c as PackageManagerResult, d as ReportError, f as RunDetachedOptions, i as IPackageManagerOptions, l as PackagePiece, m as runDetached, n as IPackageLoaderOptions, p as reportFailure, r as IPackageManager, t as IPackageLoader, u as PackagePieceEntry } from "./types-BEpxtyKW.mjs";
3
3
  import { C as hasOperationSchemas, E as typeDefinitionNames, S as getGeneratedDocumentModelTypes, T as reservedTypeNamesTaken, _ as generateDocumentModelSchema, a as GeneratedDocumentModelTypes, b as getDocumentModelSubgraphName, c as SubgraphSchemaOptions, d as buildDocumentModelSchema, f as buildSubgraphSchemaModule, g as findSubgraphTypeCollisions, h as documentModelSubgraphTypes, i as DocumentModelSource, l as SubgraphTypeCollisionError, m as createSchema, n as DocumentModelSchemaCache, o as ReservedTypeNames, p as createMergedSchema, r as DocumentModelSchemaOptions, s as ResolvedDocumentModelSchema, t as DocumentModelSchema, u as assembleSubgraphTypeDefs, v as generatedTypesOf, w as reservedTypeNames, x as getDocumentModelTypeDefs, y as getDocumentModelSchemaName } from "./create-schema-BUk-IQCT.mjs";
4
+ import { AttachmentBuildResult, AttachmentDownloadOptions, AttachmentDownloadTarget, AttachmentDownloadTargetOptions, AttachmentHeader, AttachmentReferenceIndexBuildResult, AttachmentResponse, AttachmentStatOptions, AttachmentStorageConfig, IAttachmentReferenceReader, IAttachmentReferenceWriter, IAttachmentService, IAttachmentUpload, ReserveAttachmentOptions } from "@powerhousedao/reactor-attachments";
5
+ import { ILogger } from "document-model";
4
6
  import { IAnalyticsStore } from "@powerhousedao/analytics-engine-core";
5
7
  import { AnalyticsModel } from "@powerhousedao/analytics-engine-graphql";
6
8
  import { DocumentNode, GraphQLError, GraphQLResolveInfo, GraphQLScalarType, GraphQLScalarTypeConfig, GraphQLSchema } from "graphql";
7
9
  import { AttachmentRef, CatchUpLoadSample, DocumentModelSource as DocumentModelSource$1, ICatchUpLoadSource, IDocumentModelLoader, IDocumentModelRegistry, IDriveClient, IDriveNodeSource, IInspectableAttachmentStore, IInspector, IInspectorAdmin, IInspectorStorageHealthProvider, INSPECTOR_OPS, IReactorClient, IReactorFactsSink, IReactorProcessorHostModuleBase, IReactorReadClient, IReactorWriteClient, IRelationalDb, ISyncInspector, ISyncManager, InProcessReactorClientModule, InProcessReactorModule, InspectorDocumentReader, InspectorReadOpKey, PagedResults, ParsedDriveUrl, ProcessorFactoryBuilder as ProcessorFactoryBuilder$1, Remote, SYNC_INSPECTION_OPS, SearchFilter, SyncInspectionReadOpKey, SyncScopeGate, ViewFilter, driveIdFromUrl, parseDriveUrl } from "@powerhousedao/reactor";
8
10
  import { AuthSubject, DocumentModelModule, Operation, PHDocument, UpgradeManifest } from "@powerhousedao/shared/document-model";
9
- import { ILogger } from "document-model";
10
11
  import { GraphQLResolverMap } from "@apollo/subgraph";
11
12
  import * as z$1 from "zod";
12
13
  import { DocumentDriveDocument, DocumentDriveGlobalState } from "@powerhousedao/shared/document-drive";
13
- import { AttachmentBuildResult, AttachmentDownloadOptions, AttachmentDownloadTarget, AttachmentDownloadTargetOptions, AttachmentHeader, AttachmentReferenceIndexBuildResult, AttachmentResponse, AttachmentStatOptions, IAttachmentReferenceReader, IAttachmentReferenceWriter, IAttachmentService, IAttachmentUpload, ReserveAttachmentOptions } from "@powerhousedao/reactor-attachments";
14
+ import { AuthorizerResult, IHttpScope, IRelationalDb as IRelationalDb$1, IWebhookEndpoints, IWebhookScope, NodeRouteSpec, ProcessorApp, ProcessorFactory, RouteActor, RouteAuth, RouteAuthorizer, RouteBody, RouteContext, RouteHandler, RouteMethod, RouteOptions, RouteSpec, RouteTransport, RouteUser, RouteUser as RouteUser$1, ScopedRouteHandle, WebhookEndpointInfo, WebhookField, WebhookHashAlgorithm, WebhookPolicy, WebhookReply, WebhookRequest, WebhookScheme, WebhookSignatureEncoding, WebhookSpec, WebhookVerification } from "@powerhousedao/shared/processors";
14
15
  import { IAttachmentClient } from "@powerhousedao/reactor-attachments/client";
15
16
  import { WebSocketServer } from "ws";
16
- import { AuthorizerResult, IHttpScope, IRelationalDb as IRelationalDb$1, IWebhookEndpoints, IWebhookScope, NodeRouteSpec, ProcessorApp, ProcessorFactory, RouteActor, RouteAuth, RouteAuthorizer, RouteBody, RouteContext, RouteHandler, RouteMethod, RouteOptions, RouteSpec, RouteTransport, RouteUser, RouteUser as RouteUser$1, ScopedRouteHandle, WebhookEndpointInfo, WebhookField, WebhookHashAlgorithm, WebhookPolicy, WebhookReply, WebhookRequest, WebhookScheme, WebhookSignatureEncoding, WebhookSpec, WebhookVerification } from "@powerhousedao/shared/processors";
17
17
  import { AttachmentReadGate, IDocumentScopeGate } from "@powerhousedao/reactor-attachments/replication";
18
18
  import { Generated, Kysely } from "kysely";
19
19
  import { PGlite } from "@electric-sql/pglite";
@@ -24,340 +24,172 @@ import { Context as Context$1, GqlDocument as GqlDocument$1, GqlDriveDocument as
24
24
  import { IncomingHttpHeaders } from "http";
25
25
  import { Pool } from "pg";
26
26
  import { PHReactorRenown } from "@powerhousedao/shared/clis";
27
- //#region src/utils/db.d.ts
28
- /**
29
- * Permission levels for documents:
30
- * - READ: Can fetch and read the document
31
- * - WRITE: Can push updates and modify the document
32
- * - ADMIN: Can manage document permissions and settings
33
- */
34
- export type DocumentPermissionLevel = "READ" | "WRITE" | "ADMIN";
35
- /**
36
- * Database schema for document permissions
37
- */
38
- export interface DocumentProtectionTable {
39
- documentId: string;
40
- protected: boolean;
41
- ownerAddress: string | null;
42
- createdAt: Date;
43
- updatedAt: Date;
44
- }
45
- export interface DocumentPermissionDatabase {
46
- DocumentPermission: DocumentPermissionTable;
47
- OperationUserPermission: OperationUserPermissionTable;
48
- DocumentProtection: DocumentProtectionTable;
49
- }
50
- export interface DocumentPermissionTable {
51
- id: Generated<number>;
52
- documentId: string;
53
- userAddress: string;
54
- permission: DocumentPermissionLevel;
55
- grantedBy: string;
56
- createdAt: Date;
57
- updatedAt: Date;
58
- }
59
- export interface OperationUserPermissionTable {
60
- id: Generated<number>;
61
- documentId: string;
62
- operationType: string;
63
- userAddress: string;
64
- grantedBy: string;
65
- createdAt: Date;
66
- }
67
- type Db = Kysely<any>;
68
- export declare function isPostgresConnectionString(connectionString: string): boolean;
69
- /**
70
- * Optional factory used by callers (e.g. Switchboard) to inject a
71
- * version-specific PGLite instance — e.g. `pglite-legacy-02` when an existing
72
- * data dir was created with an older PG major, or a worker-backed
73
- * `ThreadedPGlite`. Anything meeting {@link PGliteLike} works.
74
- */
75
- export type PgliteFactory = (connectionString: string | undefined) => PGliteLike;
76
- export interface DbClient {
77
- db: Db;
78
- knex: Knex;
79
- pglite: PGliteLike | undefined;
80
- }
81
- export declare function getDbClient(connectionString?: string | undefined, pgliteFactory?: PgliteFactory): DbClient;
82
- export declare const initAnalyticsStoreSql: string[];
83
- //#endregion
84
- //#region src/services/permission-cache.d.ts
85
- /**
86
- * Everything an authorization decision reads about one document: its
87
- * protection flag (the configured default when it has no protection row), its
88
- * owner, the users' grant levels and the users granted each operation.
89
- * Addresses are stored lowercase, as the permission service writes them.
90
- */
91
- export declare class DocumentPermissionSnapshot {
92
- readonly documentId: string;
93
- readonly isProtected: boolean;
94
- readonly ownerAddress: string | null;
95
- readonly grants: ReadonlyMap<string, DocumentPermissionLevel>;
96
- readonly operationGrants: ReadonlyMap<string, ReadonlySet<string>>;
97
- constructor(documentId: string, isProtected: boolean, ownerAddress: string | null, grants: ReadonlyMap<string, DocumentPermissionLevel>, operationGrants: ReadonlyMap<string, ReadonlySet<string>>);
98
- grantLevel(userAddress: string): DocumentPermissionLevel | null;
99
- isOperationRestricted(operationType: string): boolean;
100
- hasOperationGrant(operationType: string, userAddress: string): boolean;
101
- }
102
- /** Loads the snapshots of the given documents; every id gets one. */
103
- export type PermissionSnapshotLoader = (documentIds: string[]) => Promise<Map<string, DocumentPermissionSnapshot>>;
104
- export interface PermissionCacheOptions {
105
- /** How long an entry is served without reloading; 0 disables caching. */
106
- ttlMs: number;
107
- /** Entries kept before the least recently used one is dropped. */
108
- maxEntries: number;
109
- now: () => number;
110
- }
111
- export declare const DEFAULT_PERMISSION_CACHE_TTL_MS = 30000;
112
- export declare const DEFAULT_PERMISSION_CACHE_OPTIONS: PermissionCacheOptions;
27
+ //#region src/graphql/gateway/types.d.ts
28
+ export type TlsOptions = {
29
+ keyPath: string;
30
+ certPath: string;
31
+ } | {
32
+ cert: Buffer | string;
33
+ key: Buffer | string;
34
+ } | true;
35
+ export type GatewayContextFactory<TContext = unknown> = (request: Request) => Promise<TContext>;
36
+ /** Under graphql-ws this is `ctx.extra`, created once per socket. */
37
+ export type WsConnection = object;
38
+ export type WsContextFactory<TContext = unknown> = (connectionParams: Record<string, unknown>, connection: WsConnection) => Promise<TContext>;
39
+ export type WsConnectHandler = (connectionParams: Record<string, unknown>, connection: WsConnection) => Promise<boolean>;
40
+ export type WsHandlers<TContext = unknown> = {
41
+ onConnect: WsConnectHandler;
42
+ context: WsContextFactory<TContext>;
43
+ };
44
+ /** No authenticated caller resolved, and REQUIRE_AUTHENTICATED_CALLER wants one. */
45
+ export declare const WS_CLOSE_REASON_AUTHENTICATION_REQUIRED = "authentication-required";
46
+ /** A bearer was sent and could not be verified. */
47
+ export declare const WS_CLOSE_REASON_BEARER_REJECTED = "bearer-rejected";
48
+ /** An admitted connection's credential was revoked or no longer verifies. */
49
+ export declare const WS_CLOSE_REASON_CREDENTIAL_REVOKED = "credential-revoked";
50
+ /** Every reason a refusal closes with, for a client matching on the set. */
51
+ export declare const WS_AUTH_CLOSE_REASONS: readonly ["authentication-required", "bearer-rejected", "credential-revoked"];
52
+ export type WsDisposer = {
53
+ dispose: () => void | Promise<void>;
54
+ };
55
+ export type FetchHandler = (request: Request) => Promise<Response>;
113
56
  /**
114
- * Per-process cache of document permission snapshots, keyed by document id.
57
+ * Handle to a route registered directly on the adapter. Packages hot-reload,
58
+ * so every registration is reversible; disposing a route that is already gone
59
+ * is a no-op.
115
60
  *
116
- * Filled on miss from the store, invalidated by the permission service after
117
- * each of its own writes, and expired after `ttlMs` as the safety net for
118
- * writes made by another process (another switchboard instance on the same
119
- * database) until cross-instance invalidation exists.
61
+ * The handle *is* the capability to remove that one route: holding it is the
62
+ * only way to take the route back, and it cannot name any other. An opaque
63
+ * integer would let any holder remove any route by arithmetic, and a caller
64
+ * that disposed twice would eventually free somebody else's registration once
65
+ * ids were reused.
120
66
  *
121
- * A load that overlaps an invalidation still answers its caller but is not
122
- * stored, so a read that started before a write commits cannot repopulate
123
- * the cache with the pre-write rows.
124
- */
125
- export declare class PermissionCache {
126
- #private;
127
- constructor(load: PermissionSnapshotLoader, options?: PermissionCacheOptions);
128
- get size(): number;
129
- get(documentId: string): Promise<DocumentPermissionSnapshot>;
130
- /** Snapshots for every id, loading the missing and expired ones in one batch. */
131
- getMany(documentIds: string[]): Promise<Map<string, DocumentPermissionSnapshot>>;
132
- invalidate(documentId: string): void;
133
- clear(): void;
134
- }
135
- //#endregion
136
- //#region src/services/document-permission.service.d.ts
137
- export interface DocumentPermissionEntry {
138
- documentId: string;
139
- userAddress: string;
140
- permission: DocumentPermissionLevel;
141
- grantedBy: string;
142
- createdAt: Date;
143
- updatedAt: Date;
144
- }
145
- export interface OperationUserPermissionEntry {
146
- documentId: string;
147
- operationType: string;
148
- userAddress: string;
149
- grantedBy: string;
150
- createdAt: Date;
151
- }
152
- /**
153
- * Function type for getting parent document IDs
154
- * This is injected to avoid circular dependencies with the reactor client
155
- */
156
- export type GetParentIdsFn = (documentId: string) => Promise<string[]>;
157
- /**
158
- * Configuration for the DocumentPermissionService
67
+ * Distinct from the `ScopedRouteHandle` a package's HTTP scope hands back,
68
+ * which also carries the public URL the route answers on — at this layer there
69
+ * is no namespace to build one from and no knowledge of the host's origin.
159
70
  */
160
- export interface DocumentPermissionConfig {
161
- defaultProtection: boolean;
71
+ export interface AdapterRouteHandle {
72
+ dispose(): void;
162
73
  }
163
74
  /**
164
- * Service for managing document-level permissions.
165
- *
166
- * Permission levels for documents:
167
- * - READ: Can fetch and read the document
168
- * - WRITE: Can push updates and modify the document
169
- * - ADMIN: Can manage document permissions and settings
170
- *
171
- * Operation permissions:
172
- * - Users can be granted permission to execute specific operations
75
+ * A framework-agnostic description of one subgraph.
76
+ * Used by IGatewayAdapter.createSupergraphHandler() to compose the supergraph:
77
+ * federation adapters treat it as a service to call over HTTP, while the
78
+ * stitching adapter merges its typeDefs and resolvers in-process.
173
79
  */
174
- export declare class DocumentPermissionService {
175
- private readonly db;
176
- readonly config: DocumentPermissionConfig;
177
- /**
178
- * Serves the reads authorization decisions make (protection, owner, grant
179
- * level, operation grants). Every write through this service invalidates
180
- * the document it touched.
181
- */
182
- readonly permissionCache: PermissionCache;
183
- constructor(db: Kysely<DocumentPermissionDatabase>, config?: DocumentPermissionConfig, cacheOptions?: PermissionCacheOptions);
80
+ export type SubgraphDefinition = {
81
+ name: string;
82
+ typeDefs: DocumentNode;
83
+ url: string;
184
84
  /**
185
- * Get the permission level for a user on a specific document.
186
- * Returns null if no permission is set.
85
+ * The subgraph's resolver map, in-process form. Optional: federation
86
+ * adapters (Apollo, Mercurius) execute subgraphs over HTTP and ignore this,
87
+ * while stitching-style adapters merge these resolvers directly into the
88
+ * supergraph schema. Subgraph authors never see this field - it is filled
89
+ * in by the gateway manager from the subgraph's own resolvers.
187
90
  */
188
- getUserPermission(documentId: string, userAddress: string): Promise<DocumentPermissionLevel | null>;
91
+ resolvers?: Record<string, unknown>;
92
+ };
93
+ export interface IGatewayAdapter<TContext = unknown> {
94
+ /** One-time startup. */
95
+ start(httpServer: http.Server): Promise<void>;
189
96
  /**
190
- * Get all permissions for a document
97
+ * Returns a Fetch API handler for the given schema.
98
+ * Caller (IHttpAdapter) is responsible for mounting it at a path.
191
99
  */
192
- getDocumentPermissions(documentId: string): Promise<DocumentPermissionEntry[]>;
100
+ createHandler(schema: GraphQLSchema, contextFactory: GatewayContextFactory<TContext>): Promise<FetchHandler>;
193
101
  /**
194
- * Get all documents a user has explicit access to
102
+ * Create a handler that composes all subgraphs into a supergraph (a
103
+ * federation gateway, or a merged in-process schema under the stitching
104
+ * adapter). getSubgraphs is called eagerly (during setup) and again on every
105
+ * updateSupergraph() call.
195
106
  */
196
- getUserDocuments(userAddress: string): Promise<DocumentPermissionEntry[]>;
107
+ createSupergraphHandler(getSubgraphs: () => SubgraphDefinition[], httpServer: http.Server, contextFactory: GatewayContextFactory<TContext>): Promise<FetchHandler>;
197
108
  /**
198
- * Grant or update a user's permission on a document.
109
+ * Recompose the supergraph from the current subgraph list and push the update
110
+ * to the running gateway (a federation gateway, or a merged in-process schema
111
+ * under the stitching adapter). No-op if createSupergraphHandler() has not
112
+ * been called yet, or after stop().
199
113
  */
200
- grantPermission(documentId: string, userAddress: string, permission: DocumentPermissionLevel, grantedBy: string): Promise<DocumentPermissionEntry>;
114
+ updateSupergraph(): Promise<void>;
115
+ stop(): Promise<void>;
116
+ }
117
+ /**
118
+ * Methods a node route may bind. OPTIONS is excluded: the framework's CORS
119
+ * plugin owns preflight, and a duplicate registration conflicts at startup.
120
+ */
121
+ export type HttpMethod = "DELETE" | "GET" | "HEAD" | "PATCH" | "POST" | "PUT";
122
+ export interface NodeRouteOptions {
123
+ /** Serve sub-paths too, not just an exact path match. */
124
+ prefix?: boolean;
201
125
  /**
202
- * Revoke a user's permission on a document
126
+ * Deliver the request body as the client sent it: unparsed and byte-exact.
127
+ * The handler reads `req` itself; the `body` argument stays undefined.
128
+ *
129
+ * Without this, the body has already been parsed by the time the handler
130
+ * runs, so a signature computed over the raw payload cannot be verified —
131
+ * re-encoding loses key order, whitespace and duplicate keys. This is the
132
+ * one capability a webhook endpoint cannot do without, and the reason a
133
+ * route needs to be dispatched ahead of the body parsers rather than behind
134
+ * them.
203
135
  */
204
- revokePermission(documentId: string, userAddress: string): Promise<void>;
205
- /**
206
- * Delete all permissions for a document (used when deleting a document)
207
- */
208
- deleteAllDocumentPermissions(documentId: string): Promise<{
209
- DocumentPermission: number;
210
- OperationUserPermission: number;
211
- }>;
212
- /** Delete a document's protection row, which names its owner. */
213
- deleteDocumentProtection(documentId: string): Promise<number>;
214
- /** Every row that names the address, for a subject access request. */
215
- rowsForAddress(address: string): Promise<{
216
- permissions: DocumentPermissionEntry[];
217
- operationPermissions: OperationUserPermissionEntry[];
218
- ownedDocumentIds: string[];
219
- }>;
220
- /**
221
- * Grant a user permission to execute an operation on a document
222
- */
223
- grantOperationPermission(documentId: string, operationType: string, userAddress: string, grantedBy: string): Promise<OperationUserPermissionEntry>;
224
- /**
225
- * Revoke a user's permission to execute an operation
226
- */
227
- revokeOperationPermission(documentId: string, operationType: string, userAddress: string): Promise<void>;
228
- /**
229
- * Get all users with permission to execute an operation
230
- */
231
- getOperationUserPermissions(documentId: string, operationType: string): Promise<OperationUserPermissionEntry[]>;
232
- /**
233
- * Whether an operation-permission row exists for the user on this operation.
234
- */
235
- hasOperationGrant(documentId: string, operationType: string, userAddress: string): Promise<boolean>;
236
- /**
237
- * Check if an operation has any permissions set (is restricted)
238
- */
239
- isOperationRestricted(documentId: string, operationType: string): Promise<boolean>;
240
- /**
241
- * Check if a specific document has a protection row set to true.
242
- * Falls back to `config.defaultProtection` if no row exists.
243
- */
244
- isDocumentProtected(documentId: string): Promise<boolean>;
245
- /**
246
- * Walk the parent chain: if the document itself or any ancestor is protected, return true.
247
- * Collects all ancestor IDs first (with cycle detection), then batch-checks protection.
248
- */
249
- isProtectedWithAncestors(documentId: string, getParentIds: GetParentIdsFn): Promise<boolean>;
250
- /**
251
- * Reads the permission rows of the given documents from the store, three
252
- * queries for the whole batch. The permission cache's loader.
253
- */
254
- loadPermissionSnapshots(documentIds: string[]): Promise<Map<string, DocumentPermissionSnapshot>>;
255
- /**
256
- * Collect all ancestor IDs (including the document itself) with cycle detection.
257
- */
258
- private collectAncestorIds;
259
- /**
260
- * Upsert protection status for a document.
261
- */
262
- setDocumentProtection(documentId: string, isProtected: boolean): Promise<void>;
263
- /**
264
- * Get the owner address for a document, or null if not set.
265
- */
266
- getDocumentOwner(documentId: string): Promise<string | null>;
136
+ rawBody?: boolean;
137
+ }
138
+ export interface IHttpAdapter {
139
+ /** Set up CORS and body-parser equivalent middleware. */
140
+ setupMiddleware(config: {
141
+ corsOptions?: CorsOptions;
142
+ bodyLimit?: string;
143
+ }): void;
267
144
  /**
268
- * Upsert owner address for a document.
145
+ * Mount a Fetch API handler. Returns a handle whose `dispose()` removes it.
146
+ * - exact = false (default): exact path match.
147
+ * - exact = true: prefix match - handler also receives all sub-paths.
148
+ *
149
+ * Mounting a path that already holds a fetch mount of the same kind
150
+ * replaces the previous one (last write wins).
269
151
  */
270
- setDocumentOwner(documentId: string, ownerAddress: string): Promise<void>;
152
+ mount(path: string, handler: FetchHandler, options?: {
153
+ prefix?: boolean;
154
+ /** @deprecated Misleading name: this always meant *prefix*, not exact. */
155
+ exact?: boolean;
156
+ }): AdapterRouteHandle;
271
157
  /**
272
- * Initialize protection for a newly created document.
273
- * Sets protection status and grants ADMIN to the owner.
158
+ * Register a GET-only route that returns a Fetch Response (for health,
159
+ * explorer, etc.). Returns a handle whose `dispose()` removes it.
274
160
  */
275
- initializeDocumentProtection(documentId: string, ownerAddress: string, defaultProtection?: boolean): Promise<void>;
161
+ getRoute(path: string, handler: (request: Request) => Response | Promise<Response>): AdapterRouteHandle;
276
162
  /**
277
- * Get the full protection info for a document.
163
+ * Start listening on the given port. Returns the underlying http.Server
164
+ * so callers can attach WebSocket servers. Without `host` it binds the
165
+ * wildcard address.
278
166
  */
279
- getDocumentProtection(documentId: string): Promise<{
280
- documentId: string;
281
- protected: boolean;
282
- ownerAddress: string | null;
283
- }>;
284
- }
285
- //#endregion
286
- //#region src/services/authorization.service.d.ts
287
- /**
288
- * A document id that has been resolved to its canonical form, never a slug.
289
- *
290
- * Protection and grant rows are written under the canonical id, while the
291
- * read/operation data paths accept an id-or-slug identifier. The decision layer
292
- * must key on the canonical id, so branding it forces every caller to resolve a
293
- * slug to its id before consulting this service, closing the slug-aliasing
294
- * bypass (S-C1). The only sanctioned cast from string to CanonicalDocumentId
295
- * lives in createCanonicalDocumentIdResolver, immediately after the shared
296
- * resolveIdOrSlug lookup returns.
297
- */
298
- type CanonicalDocumentId = string & {
299
- readonly __canonicalDocumentId: unique symbol;
300
- };
301
- /**
302
- * Result of a passed per-document authorization check. `fetchIdentifier` is
303
- * always safe for the data fetch: the canonical id when resolved, or the raw
304
- * identifier when the check was skipped for a policy-wide caller.
305
- */
306
- export declare class AuthorizedDocumentHandle {
307
- readonly fetchIdentifier: string;
308
- readonly isResolved: boolean;
309
- private constructor();
310
- static resolved(documentId: CanonicalDocumentId): AuthorizedDocumentHandle;
311
- static skipped(identifier: string): AuthorizedDocumentHandle;
312
- /** The verified canonical id; throws when resolution was skipped. */
313
- canonicalId(): CanonicalDocumentId;
314
- }
315
- export declare const AuthorizationPolicy: {
316
- readonly OPEN: "OPEN";
317
- readonly ADMIN_ONLY: "ADMIN_ONLY";
318
- readonly DOCUMENT_PERMISSIONS: "DOCUMENT_PERMISSIONS";
319
- };
320
- export type AuthorizationPolicy = (typeof AuthorizationPolicy)[keyof typeof AuthorizationPolicy];
321
- interface AuthorizationConfig {
322
- admins: string[];
323
- defaultProtection: boolean;
324
- policy: AuthorizationPolicy;
325
- }
326
- /**
327
- * Single source of truth for every permission decision. Always present (never
328
- * null) so callers branch on data, not on the existence of a service.
329
- *
330
- * The policy selects an implementation once at boot:
331
- * - OPEN: authentication disabled — everyone (incl. anonymous) is allowed.
332
- * - ADMIN_ONLY: authentication on, document permissions off — only ADMINS.
333
- * - DOCUMENT_PERMISSIONS: the full per-document protection + grant model.
334
- *
335
- * Permission inheritance walks the parent-document hierarchy through a
336
- * parent resolver injected at construction; callers never supply one.
337
- */
338
- interface IAuthorizationService {
339
- readonly config: AuthorizationConfig;
167
+ listen(port: number, tls?: TlsOptions, host?: string): Promise<http.Server>;
340
168
  /**
341
- * Whether the user has unrestricted, policy-wide access. Under OPEN this is
342
- * true for everyone (including anonymous callers) by design: OPEN means "no
343
- * restrictions", and consumers use this check to skip per-document
344
- * filtering. It does NOT mean the caller is in the ADMINS list.
169
+ * Mount a raw Connect/Express-compatible middleware function (e.g. Vite dev
170
+ * server middleware). The implementation is adapter-specific; for Express this
171
+ * is equivalent to `app.use(middleware)`.
345
172
  */
346
- isSupremeAdmin(userAddress?: string): boolean;
173
+ mountRawMiddleware(middleware: unknown): void;
347
174
  /**
348
- * Whether the user may create new documents under the current policy:
349
- * everyone in OPEN, only admins in ADMIN_ONLY, any authenticated user in
350
- * DOCUMENT_PERMISSIONS.
175
+ * Register a method-specific route handler using Node.js core HTTP types.
176
+ * Use this when a Fetch API FetchHandler is not possible (e.g. streaming
177
+ * protocols that require direct access to IncomingMessage/ServerResponse).
178
+ *
179
+ * The req/res objects are `http.IncomingMessage`/`http.ServerResponse`
180
+ * (Express Request/Response are compatible subtypes). Returns a handle
181
+ * whose `dispose()` removes it.
351
182
  */
352
- canCreate(userAddress?: string): boolean;
353
- canRead(documentId: CanonicalDocumentId, userAddress?: string): Promise<boolean>;
354
- canWrite(documentId: CanonicalDocumentId, userAddress?: string): Promise<boolean>;
183
+ mountNodeRoute(method: HttpMethod, path: string, handler: (req: http.IncomingMessage, res: http.ServerResponse, body?: unknown) => void | Promise<void>, options?: NodeRouteOptions): AdapterRouteHandle;
355
184
  /**
356
- * Whether the user administers the document: supreme admin, document
357
- * owner, or holder of an ADMIN grant.
185
+ * Register framework-specific Sentry error-capturing middleware after all routes
186
+ * are mounted. Each adapter calls the Sentry setup function appropriate for its
187
+ * framework (e.g. setupExpressErrorHandler, setupFastifyErrorHandler).
188
+ * No-op if Sentry is not relevant for the adapter.
358
189
  */
359
- canManage(documentId: CanonicalDocumentId, userAddress?: string): Promise<boolean>;
360
- canMutate(documentId: CanonicalDocumentId, operationType: string, userAddress?: string): Promise<boolean>;
190
+ setupSentryErrorHandler(sentry: object): void;
191
+ /** The raw framework handle (e.g. Express app). Cast as needed at call sites. */
192
+ readonly handle: unknown;
361
193
  }
362
194
  //#endregion
363
195
  //#region src/services/auth.service.d.ts
@@ -495,242 +327,59 @@ export declare class AuthService implements ICredentialInvalidator {
495
327
  private fetchCredentialExists;
496
328
  }
497
329
  //#endregion
498
- //#region src/graphql/request-clients.d.ts
330
+ //#region src/http/webhook-store.d.ts
499
331
  /**
500
- * The reactor client halves a resolver may use, carried on the GraphQL
501
- * context as `ctx.clients`.
332
+ * Where webhook tokens live. Core-owned and relational rather than per-host, so
333
+ * any host in a fleet can serve any endpoint: a provider's registered URL keeps
334
+ * working after a restart, a redeploy or a request landing on another replica.
502
335
  */
503
- interface RequestClients {
504
- /** Answers from read models; always present. */
505
- readonly read: IReactorReadClient;
506
- /**
507
- * Enqueues writes. Present while a mutation executes; reading it in a query
508
- * or a subscription throws {@link WriteClientUnavailableError}.
509
- */
510
- readonly write: IReactorWriteClient;
511
- }
512
- //#endregion
513
- //#region src/graphql/gateway/types.d.ts
514
- export type TlsOptions = {
515
- keyPath: string;
516
- certPath: string;
517
- } | {
518
- cert: Buffer | string;
519
- key: Buffer | string;
520
- } | true;
521
- export type GatewayContextFactory<TContext = unknown> = (request: Request) => Promise<TContext>;
522
- /** Under graphql-ws this is `ctx.extra`, created once per socket. */
523
- export type WsConnection = object;
524
- export type WsContextFactory<TContext = unknown> = (connectionParams: Record<string, unknown>, connection: WsConnection) => Promise<TContext>;
525
- export type WsConnectHandler = (connectionParams: Record<string, unknown>, connection: WsConnection) => Promise<boolean>;
526
- export type WsHandlers<TContext = unknown> = {
527
- onConnect: WsConnectHandler;
528
- context: WsContextFactory<TContext>;
529
- };
530
- /** No authenticated caller resolved, and REQUIRE_AUTHENTICATED_CALLER wants one. */
531
- export declare const WS_CLOSE_REASON_AUTHENTICATION_REQUIRED = "authentication-required";
532
- /** A bearer was sent and could not be verified. */
533
- export declare const WS_CLOSE_REASON_BEARER_REJECTED = "bearer-rejected";
534
- /** An admitted connection's credential was revoked or no longer verifies. */
535
- export declare const WS_CLOSE_REASON_CREDENTIAL_REVOKED = "credential-revoked";
536
- /** Every reason a refusal closes with, for a client matching on the set. */
537
- export declare const WS_AUTH_CLOSE_REASONS: readonly ["authentication-required", "bearer-rejected", "credential-revoked"];
538
- export type WsDisposer = {
539
- dispose: () => void | Promise<void>;
540
- };
541
- export type FetchHandler = (request: Request) => Promise<Response>;
542
- /**
543
- * Handle to a route registered directly on the adapter. Packages hot-reload,
544
- * so every registration is reversible; disposing a route that is already gone
545
- * is a no-op.
546
- *
547
- * The handle *is* the capability to remove that one route: holding it is the
548
- * only way to take the route back, and it cannot name any other. An opaque
549
- * integer would let any holder remove any route by arithmetic, and a caller
550
- * that disposed twice would eventually free somebody else's registration once
551
- * ids were reused.
552
- *
553
- * Distinct from the `ScopedRouteHandle` a package's HTTP scope hands back,
554
- * which also carries the public URL the route answers on — at this layer there
555
- * is no namespace to build one from and no knowledge of the host's origin.
556
- */
557
- export interface AdapterRouteHandle {
558
- dispose(): void;
559
- }
560
- /**
561
- * A framework-agnostic description of one subgraph.
562
- * Used by IGatewayAdapter.createSupergraphHandler() to compose the supergraph:
563
- * federation adapters treat it as a service to call over HTTP, while the
564
- * stitching adapter merges its typeDefs and resolvers in-process.
565
- */
566
- export type SubgraphDefinition = {
567
- name: string;
568
- typeDefs: DocumentNode;
569
- url: string;
570
- /**
571
- * The subgraph's resolver map, in-process form. Optional: federation
572
- * adapters (Apollo, Mercurius) execute subgraphs over HTTP and ignore this,
573
- * while stitching-style adapters merge these resolvers directly into the
574
- * supergraph schema. Subgraph authors never see this field - it is filled
575
- * in by the gateway manager from the subgraph's own resolvers.
576
- */
577
- resolvers?: Record<string, unknown>;
578
- };
579
- export interface IGatewayAdapter<TContext = unknown> {
580
- /** One-time startup. */
581
- start(httpServer: http.Server): Promise<void>;
582
- /**
583
- * Returns a Fetch API handler for the given schema.
584
- * Caller (IHttpAdapter) is responsible for mounting it at a path.
585
- */
586
- createHandler(schema: GraphQLSchema, contextFactory: GatewayContextFactory<TContext>): Promise<FetchHandler>;
587
- /**
588
- * Create a handler that composes all subgraphs into a supergraph (a
589
- * federation gateway, or a merged in-process schema under the stitching
590
- * adapter). getSubgraphs is called eagerly (during setup) and again on every
591
- * updateSupergraph() call.
592
- */
593
- createSupergraphHandler(getSubgraphs: () => SubgraphDefinition[], httpServer: http.Server, contextFactory: GatewayContextFactory<TContext>): Promise<FetchHandler>;
594
- /**
595
- * Recompose the supergraph from the current subgraph list and push the update
596
- * to the running gateway (a federation gateway, or a merged in-process schema
597
- * under the stitching adapter). No-op if createSupergraphHandler() has not
598
- * been called yet, or after stop().
599
- */
600
- updateSupergraph(): Promise<void>;
601
- stop(): Promise<void>;
602
- }
603
- /**
604
- * Methods a node route may bind. OPTIONS is excluded: the framework's CORS
605
- * plugin owns preflight, and a duplicate registration conflicts at startup.
606
- */
607
- export type HttpMethod = "DELETE" | "GET" | "HEAD" | "PATCH" | "POST" | "PUT";
608
- export interface NodeRouteOptions {
609
- /** Serve sub-paths too, not just an exact path match. */
610
- prefix?: boolean;
611
- /**
612
- * Deliver the request body as the client sent it: unparsed and byte-exact.
613
- * The handler reads `req` itself; the `body` argument stays undefined.
614
- *
615
- * Without this, the body has already been parsed by the time the handler
616
- * runs, so a signature computed over the raw payload cannot be verified —
617
- * re-encoding loses key order, whitespace and duplicate keys. This is the
618
- * one capability a webhook endpoint cannot do without, and the reason a
619
- * route needs to be dispatched ahead of the body parsers rather than behind
620
- * them.
621
- */
622
- rawBody?: boolean;
623
- }
624
- export interface IHttpAdapter {
625
- /** Set up CORS and body-parser equivalent middleware. */
626
- setupMiddleware(config: {
627
- corsOptions?: CorsOptions;
628
- bodyLimit?: string;
629
- }): void;
630
- /**
631
- * Mount a Fetch API handler. Returns a handle whose `dispose()` removes it.
632
- * - exact = false (default): exact path match.
633
- * - exact = true: prefix match - handler also receives all sub-paths.
634
- *
635
- * Mounting a path that already holds a fetch mount of the same kind
636
- * replaces the previous one (last write wins).
637
- */
638
- mount(path: string, handler: FetchHandler, options?: {
639
- prefix?: boolean;
640
- /** @deprecated Misleading name: this always meant *prefix*, not exact. */
641
- exact?: boolean;
642
- }): AdapterRouteHandle;
643
- /**
644
- * Register a GET-only route that returns a Fetch Response (for health,
645
- * explorer, etc.). Returns a handle whose `dispose()` removes it.
646
- */
647
- getRoute(path: string, handler: (request: Request) => Response | Promise<Response>): AdapterRouteHandle;
648
- /**
649
- * Start listening on the given port. Returns the underlying http.Server
650
- * so callers can attach WebSocket servers. Without `host` it binds the
651
- * wildcard address.
652
- */
653
- listen(port: number, tls?: TlsOptions, host?: string): Promise<http.Server>;
654
- /**
655
- * Mount a raw Connect/Express-compatible middleware function (e.g. Vite dev
656
- * server middleware). The implementation is adapter-specific; for Express this
657
- * is equivalent to `app.use(middleware)`.
658
- */
659
- mountRawMiddleware(middleware: unknown): void;
660
- /**
661
- * Register a method-specific route handler using Node.js core HTTP types.
662
- * Use this when a Fetch API FetchHandler is not possible (e.g. streaming
663
- * protocols that require direct access to IncomingMessage/ServerResponse).
664
- *
665
- * The req/res objects are `http.IncomingMessage`/`http.ServerResponse`
666
- * (Express Request/Response are compatible subtypes). Returns a handle
667
- * whose `dispose()` removes it.
668
- */
669
- mountNodeRoute(method: HttpMethod, path: string, handler: (req: http.IncomingMessage, res: http.ServerResponse, body?: unknown) => void | Promise<void>, options?: NodeRouteOptions): AdapterRouteHandle;
670
- /**
671
- * Register framework-specific Sentry error-capturing middleware after all routes
672
- * are mounted. Each adapter calls the Sentry setup function appropriate for its
673
- * framework (e.g. setupExpressErrorHandler, setupFastifyErrorHandler).
674
- * No-op if Sentry is not relevant for the adapter.
675
- */
676
- setupSentryErrorHandler(sentry: object): void;
677
- /** The raw framework handle (e.g. Express app). Cast as needed at call sites. */
678
- readonly handle: unknown;
679
- }
680
- //#endregion
681
- //#region src/http/webhook-store.d.ts
682
- /**
683
- * Where webhook tokens live. Core-owned and relational rather than per-host, so
684
- * any host in a fleet can serve any endpoint: a provider's registered URL keeps
685
- * working after a restart, a redeploy or a request landing on another replica.
686
- */
687
- interface WebhookEndpointRow {
688
- token: string;
689
- /** The owning package's npm name. */
690
- namespace: string;
691
- /** The registration within that package. */
692
- endpoint: string;
693
- /** The caller's own key, e.g. a document id. Never appears in the URL. */
694
- ownerKey: string;
695
- createdAt: string;
696
- }
697
- interface IWebhookStore {
698
- init(): Promise<void>;
699
- /** Returns the existing token for this key, or mints one. */
700
- ensure(namespace: string, endpoint: string, ownerKey: string): Promise<WebhookEndpointRow>;
701
- find(token: string): Promise<WebhookEndpointRow | undefined>;
702
- list(namespace: string, endpoint?: string): Promise<WebhookEndpointRow[]>;
703
- revoke(namespace: string, endpoint: string, ownerKey: string): Promise<void>;
704
- /** True when this delivery has been seen before, within the TTL. */
705
- seen(token: string, key: string, ttlSeconds: number): Promise<boolean>;
706
- /** Drops a delivery recorded by seen(), so a retry of it is delivered. */
707
- forget(token: string, key: string): Promise<void>;
708
- }
709
- /** Opaque and unguessable: the URL is a bearer capability held by a third party. */
710
- export declare function newWebhookToken(): string;
711
- /** Relational implementation, over the reactor's own database. */
712
- export declare class RelationalWebhookStore implements IWebhookStore {
713
- #private;
714
- private readonly relationalDb;
715
- constructor(relationalDb: IRelationalDb$1);
716
- init(): Promise<void>;
717
- ensure(namespace: string, endpoint: string, ownerKey: string): Promise<WebhookEndpointRow>;
718
- find(token: string): Promise<WebhookEndpointRow | undefined>;
719
- list(namespace: string, endpoint?: string): Promise<WebhookEndpointRow[]>;
720
- revoke(namespace: string, endpoint: string, ownerKey: string): Promise<void>;
721
- forget(token: string, key: string): Promise<void>;
722
- seen(token: string, key: string, ttlSeconds: number): Promise<boolean>;
723
- }
724
- /** In-memory store, for hosts with no relational database and for tests. */
725
- export declare class MemoryWebhookStore implements IWebhookStore {
726
- #private;
727
- init(): Promise<void>;
728
- ensure(namespace: string, endpoint: string, ownerKey: string): Promise<WebhookEndpointRow>;
729
- find(token: string): Promise<WebhookEndpointRow | undefined>;
730
- forget(token: string, key: string): Promise<void>;
731
- list(namespace: string, endpoint?: string): Promise<WebhookEndpointRow[]>;
732
- revoke(namespace: string, endpoint: string, ownerKey: string): Promise<void>;
733
- seen(token: string, key: string, ttlSeconds: number): Promise<boolean>;
336
+ interface WebhookEndpointRow {
337
+ token: string;
338
+ /** The owning package's npm name. */
339
+ namespace: string;
340
+ /** The registration within that package. */
341
+ endpoint: string;
342
+ /** The caller's own key, e.g. a document id. Never appears in the URL. */
343
+ ownerKey: string;
344
+ createdAt: string;
345
+ }
346
+ interface IWebhookStore {
347
+ init(): Promise<void>;
348
+ /** Returns the existing token for this key, or mints one. */
349
+ ensure(namespace: string, endpoint: string, ownerKey: string): Promise<WebhookEndpointRow>;
350
+ find(token: string): Promise<WebhookEndpointRow | undefined>;
351
+ list(namespace: string, endpoint?: string): Promise<WebhookEndpointRow[]>;
352
+ revoke(namespace: string, endpoint: string, ownerKey: string): Promise<void>;
353
+ /** True when this delivery has been seen before, within the TTL. */
354
+ seen(token: string, key: string, ttlSeconds: number): Promise<boolean>;
355
+ /** Drops a delivery recorded by seen(), so a retry of it is delivered. */
356
+ forget(token: string, key: string): Promise<void>;
357
+ }
358
+ /** Opaque and unguessable: the URL is a bearer capability held by a third party. */
359
+ export declare function newWebhookToken(): string;
360
+ /** Relational implementation, over the reactor's own database. */
361
+ export declare class RelationalWebhookStore implements IWebhookStore {
362
+ #private;
363
+ private readonly relationalDb;
364
+ constructor(relationalDb: IRelationalDb$1);
365
+ init(): Promise<void>;
366
+ ensure(namespace: string, endpoint: string, ownerKey: string): Promise<WebhookEndpointRow>;
367
+ find(token: string): Promise<WebhookEndpointRow | undefined>;
368
+ list(namespace: string, endpoint?: string): Promise<WebhookEndpointRow[]>;
369
+ revoke(namespace: string, endpoint: string, ownerKey: string): Promise<void>;
370
+ forget(token: string, key: string): Promise<void>;
371
+ seen(token: string, key: string, ttlSeconds: number): Promise<boolean>;
372
+ }
373
+ /** In-memory store, for hosts with no relational database and for tests. */
374
+ export declare class MemoryWebhookStore implements IWebhookStore {
375
+ #private;
376
+ init(): Promise<void>;
377
+ ensure(namespace: string, endpoint: string, ownerKey: string): Promise<WebhookEndpointRow>;
378
+ find(token: string): Promise<WebhookEndpointRow | undefined>;
379
+ forget(token: string, key: string): Promise<void>;
380
+ list(namespace: string, endpoint?: string): Promise<WebhookEndpointRow[]>;
381
+ revoke(namespace: string, endpoint: string, ownerKey: string): Promise<void>;
382
+ seen(token: string, key: string, ttlSeconds: number): Promise<boolean>;
734
383
  }
735
384
  //#endregion
736
385
  //#region src/http/webhook-service.d.ts
@@ -867,49 +516,385 @@ export declare function redactHeaders(headers: Record<string, string>, extra?: s
867
516
  * XML or CSV payload is still reachable downstream. */
868
517
  export declare function parseWebhookBody(raw: Buffer, contentType?: string): unknown;
869
518
  //#endregion
870
- //#region src/http/request-load.d.ts
519
+ //#region src/http/request-load.d.ts
520
+ /**
521
+ * Whether a request counts as user load: not the monitor's inspection calls,
522
+ * not a health probe, not a static asset and not a long-lived stream.
523
+ */
524
+ export declare function isCountedRequest(url: string, accept?: string): boolean;
525
+ /** Main-thread event-loop delay, as the recorder reads it once per sample. */
526
+ interface IEventLoopDelaySource {
527
+ /** p99 delay since the last call, in ms. */
528
+ takeP99Ms(): number;
529
+ stop(): void;
530
+ }
531
+ /** `perf_hooks.monitorEventLoopDelay`, reset on every read. */
532
+ export declare class NodeEventLoopDelay implements IEventLoopDelaySource {
533
+ private readonly histogram;
534
+ constructor(resolutionMs?: number);
535
+ takeP99Ms(): number;
536
+ stop(): void;
537
+ }
538
+ type RequestLoadRecorderOptions = {
539
+ windowMs?: number;
540
+ now?: () => number;
541
+ eventLoopDelay?: IEventLoopDelaySource;
542
+ };
543
+ /**
544
+ * Counts completed user requests and their latency over a sliding window, and
545
+ * reads the main thread's event-loop delay, as the catch-up controller's load
546
+ * source. Loop delay over the window is the highest per-sample p99 in it.
547
+ */
548
+ export declare class RequestLoadRecorder implements ICatchUpLoadSource {
549
+ private readonly windowMs;
550
+ private readonly now;
551
+ private readonly eventLoopDelay;
552
+ private readonly completions;
553
+ private readonly loopReadings;
554
+ private lastCompletedAt;
555
+ private readonly detachers;
556
+ constructor(options?: RequestLoadRecorderOptions);
557
+ /** Records every counted request `server` completes, until `stop`. */
558
+ attach(server: http.Server): void;
559
+ record(durationMs: number): void;
560
+ sample(): CatchUpLoadSample;
561
+ stop(): void;
562
+ }
563
+ //#endregion
564
+ //#region src/utils/db.d.ts
565
+ /**
566
+ * Permission levels for documents:
567
+ * - READ: Can fetch and read the document
568
+ * - WRITE: Can push updates and modify the document
569
+ * - ADMIN: Can manage document permissions and settings
570
+ */
571
+ export type DocumentPermissionLevel = "READ" | "WRITE" | "ADMIN";
572
+ /**
573
+ * Database schema for document permissions
574
+ */
575
+ export interface DocumentProtectionTable {
576
+ documentId: string;
577
+ protected: boolean;
578
+ ownerAddress: string | null;
579
+ createdAt: Date;
580
+ updatedAt: Date;
581
+ }
582
+ export interface DocumentPermissionDatabase {
583
+ DocumentPermission: DocumentPermissionTable;
584
+ OperationUserPermission: OperationUserPermissionTable;
585
+ DocumentProtection: DocumentProtectionTable;
586
+ }
587
+ export interface DocumentPermissionTable {
588
+ id: Generated<number>;
589
+ documentId: string;
590
+ userAddress: string;
591
+ permission: DocumentPermissionLevel;
592
+ grantedBy: string;
593
+ createdAt: Date;
594
+ updatedAt: Date;
595
+ }
596
+ export interface OperationUserPermissionTable {
597
+ id: Generated<number>;
598
+ documentId: string;
599
+ operationType: string;
600
+ userAddress: string;
601
+ grantedBy: string;
602
+ createdAt: Date;
603
+ }
604
+ type Db = Kysely<any>;
605
+ export declare function isPostgresConnectionString(connectionString: string): boolean;
606
+ /**
607
+ * Optional factory used by callers (e.g. Switchboard) to inject a
608
+ * version-specific PGLite instance — e.g. `pglite-legacy-02` when an existing
609
+ * data dir was created with an older PG major, or a worker-backed
610
+ * `ThreadedPGlite`. Anything meeting {@link PGliteLike} works.
611
+ */
612
+ export type PgliteFactory = (connectionString: string | undefined) => PGliteLike;
613
+ export interface DbClient {
614
+ db: Db;
615
+ knex: Knex;
616
+ pglite: PGliteLike | undefined;
617
+ }
618
+ export declare function getDbClient(connectionString?: string | undefined, pgliteFactory?: PgliteFactory): DbClient;
619
+ export declare const initAnalyticsStoreSql: string[];
620
+ //#endregion
621
+ //#region src/services/permission-cache.d.ts
622
+ /**
623
+ * Everything an authorization decision reads about one document: its
624
+ * protection flag (the configured default when it has no protection row), its
625
+ * owner, the users' grant levels and the users granted each operation.
626
+ * Addresses are stored lowercase, as the permission service writes them.
627
+ */
628
+ export declare class DocumentPermissionSnapshot {
629
+ readonly documentId: string;
630
+ readonly isProtected: boolean;
631
+ readonly ownerAddress: string | null;
632
+ readonly grants: ReadonlyMap<string, DocumentPermissionLevel>;
633
+ readonly operationGrants: ReadonlyMap<string, ReadonlySet<string>>;
634
+ constructor(documentId: string, isProtected: boolean, ownerAddress: string | null, grants: ReadonlyMap<string, DocumentPermissionLevel>, operationGrants: ReadonlyMap<string, ReadonlySet<string>>);
635
+ grantLevel(userAddress: string): DocumentPermissionLevel | null;
636
+ isOperationRestricted(operationType: string): boolean;
637
+ hasOperationGrant(operationType: string, userAddress: string): boolean;
638
+ }
639
+ /** Loads the snapshots of the given documents; every id gets one. */
640
+ export type PermissionSnapshotLoader = (documentIds: string[]) => Promise<Map<string, DocumentPermissionSnapshot>>;
641
+ export interface PermissionCacheOptions {
642
+ /** How long an entry is served without reloading; 0 disables caching. */
643
+ ttlMs: number;
644
+ /** Entries kept before the least recently used one is dropped. */
645
+ maxEntries: number;
646
+ now: () => number;
647
+ }
648
+ export declare const DEFAULT_PERMISSION_CACHE_TTL_MS = 30000;
649
+ export declare const DEFAULT_PERMISSION_CACHE_OPTIONS: PermissionCacheOptions;
650
+ /**
651
+ * Per-process cache of document permission snapshots, keyed by document id.
652
+ *
653
+ * Filled on miss from the store, invalidated by the permission service after
654
+ * each of its own writes, and expired after `ttlMs` as the safety net for
655
+ * writes made by another process (another switchboard instance on the same
656
+ * database) until cross-instance invalidation exists.
657
+ *
658
+ * A load that overlaps an invalidation still answers its caller but is not
659
+ * stored, so a read that started before a write commits cannot repopulate
660
+ * the cache with the pre-write rows.
661
+ */
662
+ export declare class PermissionCache {
663
+ #private;
664
+ constructor(load: PermissionSnapshotLoader, options?: PermissionCacheOptions);
665
+ get size(): number;
666
+ get(documentId: string): Promise<DocumentPermissionSnapshot>;
667
+ /** Snapshots for every id, loading the missing and expired ones in one batch. */
668
+ getMany(documentIds: string[]): Promise<Map<string, DocumentPermissionSnapshot>>;
669
+ invalidate(documentId: string): void;
670
+ clear(): void;
671
+ }
672
+ //#endregion
673
+ //#region src/services/document-permission.service.d.ts
674
+ export interface DocumentPermissionEntry {
675
+ documentId: string;
676
+ userAddress: string;
677
+ permission: DocumentPermissionLevel;
678
+ grantedBy: string;
679
+ createdAt: Date;
680
+ updatedAt: Date;
681
+ }
682
+ export interface OperationUserPermissionEntry {
683
+ documentId: string;
684
+ operationType: string;
685
+ userAddress: string;
686
+ grantedBy: string;
687
+ createdAt: Date;
688
+ }
689
+ /**
690
+ * Function type for getting parent document IDs
691
+ * This is injected to avoid circular dependencies with the reactor client
692
+ */
693
+ export type GetParentIdsFn = (documentId: string) => Promise<string[]>;
694
+ /**
695
+ * Configuration for the DocumentPermissionService
696
+ */
697
+ export interface DocumentPermissionConfig {
698
+ defaultProtection: boolean;
699
+ }
700
+ /**
701
+ * Service for managing document-level permissions.
702
+ *
703
+ * Permission levels for documents:
704
+ * - READ: Can fetch and read the document
705
+ * - WRITE: Can push updates and modify the document
706
+ * - ADMIN: Can manage document permissions and settings
707
+ *
708
+ * Operation permissions:
709
+ * - Users can be granted permission to execute specific operations
710
+ */
711
+ export declare class DocumentPermissionService {
712
+ private readonly db;
713
+ readonly config: DocumentPermissionConfig;
714
+ /**
715
+ * Serves the reads authorization decisions make (protection, owner, grant
716
+ * level, operation grants). Every write through this service invalidates
717
+ * the document it touched.
718
+ */
719
+ readonly permissionCache: PermissionCache;
720
+ constructor(db: Kysely<DocumentPermissionDatabase>, config?: DocumentPermissionConfig, cacheOptions?: PermissionCacheOptions);
721
+ /**
722
+ * Get the permission level for a user on a specific document.
723
+ * Returns null if no permission is set.
724
+ */
725
+ getUserPermission(documentId: string, userAddress: string): Promise<DocumentPermissionLevel | null>;
726
+ /**
727
+ * Get all permissions for a document
728
+ */
729
+ getDocumentPermissions(documentId: string): Promise<DocumentPermissionEntry[]>;
730
+ /**
731
+ * Get all documents a user has explicit access to
732
+ */
733
+ getUserDocuments(userAddress: string): Promise<DocumentPermissionEntry[]>;
734
+ /**
735
+ * Grant or update a user's permission on a document.
736
+ */
737
+ grantPermission(documentId: string, userAddress: string, permission: DocumentPermissionLevel, grantedBy: string): Promise<DocumentPermissionEntry>;
738
+ /**
739
+ * Revoke a user's permission on a document
740
+ */
741
+ revokePermission(documentId: string, userAddress: string): Promise<void>;
742
+ /**
743
+ * Delete all permissions for a document (used when deleting a document)
744
+ */
745
+ deleteAllDocumentPermissions(documentId: string): Promise<{
746
+ DocumentPermission: number;
747
+ OperationUserPermission: number;
748
+ }>;
749
+ /** Delete a document's protection row, which names its owner. */
750
+ deleteDocumentProtection(documentId: string): Promise<number>;
751
+ /** Every row that names the address, for a subject access request. */
752
+ rowsForAddress(address: string): Promise<{
753
+ permissions: DocumentPermissionEntry[];
754
+ operationPermissions: OperationUserPermissionEntry[];
755
+ ownedDocumentIds: string[];
756
+ }>;
757
+ /**
758
+ * Grant a user permission to execute an operation on a document
759
+ */
760
+ grantOperationPermission(documentId: string, operationType: string, userAddress: string, grantedBy: string): Promise<OperationUserPermissionEntry>;
761
+ /**
762
+ * Revoke a user's permission to execute an operation
763
+ */
764
+ revokeOperationPermission(documentId: string, operationType: string, userAddress: string): Promise<void>;
765
+ /**
766
+ * Get all users with permission to execute an operation
767
+ */
768
+ getOperationUserPermissions(documentId: string, operationType: string): Promise<OperationUserPermissionEntry[]>;
769
+ /**
770
+ * Whether an operation-permission row exists for the user on this operation.
771
+ */
772
+ hasOperationGrant(documentId: string, operationType: string, userAddress: string): Promise<boolean>;
773
+ /**
774
+ * Check if an operation has any permissions set (is restricted)
775
+ */
776
+ isOperationRestricted(documentId: string, operationType: string): Promise<boolean>;
777
+ /**
778
+ * Check if a specific document has a protection row set to true.
779
+ * Falls back to `config.defaultProtection` if no row exists.
780
+ */
781
+ isDocumentProtected(documentId: string): Promise<boolean>;
782
+ /**
783
+ * Walk the parent chain: if the document itself or any ancestor is protected, return true.
784
+ * Collects all ancestor IDs first (with cycle detection), then batch-checks protection.
785
+ */
786
+ isProtectedWithAncestors(documentId: string, getParentIds: GetParentIdsFn): Promise<boolean>;
787
+ /**
788
+ * Reads the permission rows of the given documents from the store, three
789
+ * queries for the whole batch. The permission cache's loader.
790
+ */
791
+ loadPermissionSnapshots(documentIds: string[]): Promise<Map<string, DocumentPermissionSnapshot>>;
792
+ /**
793
+ * Collect all ancestor IDs (including the document itself) with cycle detection.
794
+ */
795
+ private collectAncestorIds;
796
+ /**
797
+ * Upsert protection status for a document.
798
+ */
799
+ setDocumentProtection(documentId: string, isProtected: boolean): Promise<void>;
800
+ /**
801
+ * Get the owner address for a document, or null if not set.
802
+ */
803
+ getDocumentOwner(documentId: string): Promise<string | null>;
804
+ /**
805
+ * Upsert owner address for a document.
806
+ */
807
+ setDocumentOwner(documentId: string, ownerAddress: string): Promise<void>;
808
+ /**
809
+ * Initialize protection for a newly created document.
810
+ * Sets protection status and grants ADMIN to the owner.
811
+ */
812
+ initializeDocumentProtection(documentId: string, ownerAddress: string, defaultProtection?: boolean): Promise<void>;
813
+ /**
814
+ * Get the full protection info for a document.
815
+ */
816
+ getDocumentProtection(documentId: string): Promise<{
817
+ documentId: string;
818
+ protected: boolean;
819
+ ownerAddress: string | null;
820
+ }>;
821
+ }
822
+ //#endregion
823
+ //#region src/services/authorization.service.d.ts
871
824
  /**
872
- * Whether a request counts as user load: not the monitor's inspection calls,
873
- * not a health probe, not a static asset and not a long-lived stream.
825
+ * A document id that has been resolved to its canonical form, never a slug.
826
+ *
827
+ * Protection and grant rows are written under the canonical id, while the
828
+ * read/operation data paths accept an id-or-slug identifier. The decision layer
829
+ * must key on the canonical id, so branding it forces every caller to resolve a
830
+ * slug to its id before consulting this service, closing the slug-aliasing
831
+ * bypass (S-C1). The only sanctioned cast from string to CanonicalDocumentId
832
+ * lives in createCanonicalDocumentIdResolver, immediately after the shared
833
+ * resolveIdOrSlug lookup returns.
874
834
  */
875
- export declare function isCountedRequest(url: string, accept?: string): boolean;
876
- /** Main-thread event-loop delay, as the recorder reads it once per sample. */
877
- interface IEventLoopDelaySource {
878
- /** p99 delay since the last call, in ms. */
879
- takeP99Ms(): number;
880
- stop(): void;
881
- }
882
- /** `perf_hooks.monitorEventLoopDelay`, reset on every read. */
883
- export declare class NodeEventLoopDelay implements IEventLoopDelaySource {
884
- private readonly histogram;
885
- constructor(resolutionMs?: number);
886
- takeP99Ms(): number;
887
- stop(): void;
835
+ type CanonicalDocumentId = string & {
836
+ readonly __canonicalDocumentId: unique symbol;
837
+ };
838
+ /**
839
+ * Result of a passed per-document authorization check. `fetchIdentifier` is
840
+ * always safe for the data fetch: the canonical id when resolved, or the raw
841
+ * identifier when the check was skipped for a policy-wide caller.
842
+ */
843
+ export declare class AuthorizedDocumentHandle {
844
+ readonly fetchIdentifier: string;
845
+ readonly isResolved: boolean;
846
+ private constructor();
847
+ static resolved(documentId: CanonicalDocumentId): AuthorizedDocumentHandle;
848
+ static skipped(identifier: string): AuthorizedDocumentHandle;
849
+ /** The verified canonical id; throws when resolution was skipped. */
850
+ canonicalId(): CanonicalDocumentId;
888
851
  }
889
- type RequestLoadRecorderOptions = {
890
- windowMs?: number;
891
- now?: () => number;
892
- eventLoopDelay?: IEventLoopDelaySource;
852
+ export declare const AuthorizationPolicy: {
853
+ readonly OPEN: "OPEN";
854
+ readonly ADMIN_ONLY: "ADMIN_ONLY";
855
+ readonly DOCUMENT_PERMISSIONS: "DOCUMENT_PERMISSIONS";
893
856
  };
857
+ export type AuthorizationPolicy = (typeof AuthorizationPolicy)[keyof typeof AuthorizationPolicy];
858
+ interface AuthorizationConfig {
859
+ admins: string[];
860
+ defaultProtection: boolean;
861
+ policy: AuthorizationPolicy;
862
+ }
894
863
  /**
895
- * Counts completed user requests and their latency over a sliding window, and
896
- * reads the main thread's event-loop delay, as the catch-up controller's load
897
- * source. Loop delay over the window is the highest per-sample p99 in it.
864
+ * Single source of truth for every permission decision. Always present (never
865
+ * null) so callers branch on data, not on the existence of a service.
866
+ *
867
+ * The policy selects an implementation once at boot:
868
+ * - OPEN: authentication disabled — everyone (incl. anonymous) is allowed.
869
+ * - ADMIN_ONLY: authentication on, document permissions off — only ADMINS.
870
+ * - DOCUMENT_PERMISSIONS: the full per-document protection + grant model.
871
+ *
872
+ * Permission inheritance walks the parent-document hierarchy through a
873
+ * parent resolver injected at construction; callers never supply one.
898
874
  */
899
- export declare class RequestLoadRecorder implements ICatchUpLoadSource {
900
- private readonly windowMs;
901
- private readonly now;
902
- private readonly eventLoopDelay;
903
- private readonly completions;
904
- private readonly loopReadings;
905
- private lastCompletedAt;
906
- private readonly detachers;
907
- constructor(options?: RequestLoadRecorderOptions);
908
- /** Records every counted request `server` completes, until `stop`. */
909
- attach(server: http.Server): void;
910
- record(durationMs: number): void;
911
- sample(): CatchUpLoadSample;
912
- stop(): void;
875
+ interface IAuthorizationService {
876
+ readonly config: AuthorizationConfig;
877
+ /**
878
+ * Whether the user has unrestricted, policy-wide access. Under OPEN this is
879
+ * true for everyone (including anonymous callers) by design: OPEN means "no
880
+ * restrictions", and consumers use this check to skip per-document
881
+ * filtering. It does NOT mean the caller is in the ADMINS list.
882
+ */
883
+ isSupremeAdmin(userAddress?: string): boolean;
884
+ /**
885
+ * Whether the user may create new documents under the current policy:
886
+ * everyone in OPEN, only admins in ADMIN_ONLY, any authenticated user in
887
+ * DOCUMENT_PERMISSIONS.
888
+ */
889
+ canCreate(userAddress?: string): boolean;
890
+ canRead(documentId: CanonicalDocumentId, userAddress?: string): Promise<boolean>;
891
+ canWrite(documentId: CanonicalDocumentId, userAddress?: string): Promise<boolean>;
892
+ /**
893
+ * Whether the user administers the document: supreme admin, document
894
+ * owner, or holder of an ADMIN grant.
895
+ */
896
+ canManage(documentId: CanonicalDocumentId, userAddress?: string): Promise<boolean>;
897
+ canMutate(documentId: CanonicalDocumentId, operationType: string, userAddress?: string): Promise<boolean>;
913
898
  }
914
899
  //#endregion
915
900
  //#region src/services/canonical-document-id.d.ts
@@ -1040,64 +1025,201 @@ export declare class AttachmentAccessService implements IAttachmentAccessService
1040
1025
  private readonly projection;
1041
1026
  private readonly readGate;
1042
1027
  /**
1043
- * Absent below auth enforcement, where there is no policy model to
1044
- * evaluate; the host's permission tables decide alone, exactly as before.
1028
+ * Absent below auth enforcement, where there is no policy model to
1029
+ * evaluate; the host's permission tables decide alone, exactly as before.
1030
+ */
1031
+ private readonly scopeGate?;
1032
+ private readonly options;
1033
+ constructor(resolveCanonicalId: CanonicalDocumentIdResolver, authorization: IAuthorizationService, references: IAttachmentReferenceReader, projection: AttachmentReferenceProjectionCapability, readGate: AttachmentReadGate,
1034
+ /**
1035
+ * Absent below auth enforcement, where there is no policy model to
1036
+ * evaluate; the host's permission tables decide alone, exactly as before.
1037
+ */
1038
+ scopeGate?: IDocumentScopeGate | undefined, options?: AttachmentAccessServiceOptions);
1039
+ admitCaller(request: AttachmentCallerRequest): Promise<AttachmentCallerResult>;
1040
+ canReadAttachment(request: AttachmentAccessRequest): Promise<AttachmentAccessResult>;
1041
+ /**
1042
+ * Whether the caller may read the state the reference lives in.
1043
+ *
1044
+ * A failure here is rethrown rather than turned into a denial. A read side
1045
+ * that is down must not read as a policy: a denial nobody can distinguish
1046
+ * from a refusal is one nobody investigates, and the route answers 500 for a
1047
+ * reason.
1048
+ */
1049
+ private canReadDocument;
1050
+ }
1051
+ //#endregion
1052
+ //#region src/services/authorized-attachment.service.d.ts
1053
+ /** The reference index is not maintained in this composition. */
1054
+ export declare class AttachmentAccessUnavailable extends Error {
1055
+ constructor();
1056
+ }
1057
+ /** The access decision itself failed; the cause is logged, not surfaced. */
1058
+ export declare class AttachmentAccessFailed extends Error {
1059
+ constructor(cause: unknown);
1060
+ }
1061
+ /** An `IAttachmentService` whose reads and writes are decided for one subject. */
1062
+ export declare class AuthorizedAttachmentService implements IAttachmentService {
1063
+ private readonly inner;
1064
+ private readonly access;
1065
+ private readonly subject;
1066
+ private readonly logger;
1067
+ constructor(inner: IAttachmentService, access: IAttachmentAccessService, subject: AuthSubject, logger: ILogger);
1068
+ /** Hash-first only: an upload-first handle can send after it expires. */
1069
+ reserve(options: ReserveAttachmentOptions): Promise<IAttachmentUpload>;
1070
+ stat(ref: AttachmentRef, options?: AttachmentStatOptions): Promise<AttachmentHeader>;
1071
+ get(ref: AttachmentRef, options?: AbortSignal | AttachmentDownloadOptions): Promise<AttachmentResponse>;
1072
+ getDownloadTarget(ref: AttachmentRef, options: AttachmentDownloadTargetOptions): Promise<AttachmentDownloadTarget>;
1073
+ private decideRead;
1074
+ private admit;
1075
+ private accessFailed;
1076
+ }
1077
+ export interface IAttachmentClientProvider {
1078
+ forSubject(subject: AuthSubject): IAttachmentClient;
1079
+ }
1080
+ export declare class AttachmentClientProvider implements IAttachmentClientProvider {
1081
+ private readonly service;
1082
+ private readonly access;
1083
+ private readonly logger;
1084
+ constructor(service: IAttachmentService, access: IAttachmentAccessService, logger: ILogger);
1085
+ forSubject(subject: AuthSubject): IAttachmentClient;
1086
+ }
1087
+ //#endregion
1088
+ //#region src/graphql/request-clients.d.ts
1089
+ /**
1090
+ * The reactor client halves a resolver may use, carried on the GraphQL
1091
+ * context as `ctx.clients`.
1092
+ */
1093
+ interface RequestClients {
1094
+ /** Answers from read models; always present. */
1095
+ readonly read: IReactorReadClient;
1096
+ /**
1097
+ * Enqueues writes. Present while a mutation executes; reading it in a query
1098
+ * or a subscription throws {@link WriteClientUnavailableError}.
1099
+ */
1100
+ readonly write: IReactorWriteClient;
1101
+ }
1102
+ //#endregion
1103
+ //#region src/graphql/base-subgraph.d.ts
1104
+ /**
1105
+ * The subject a request reads as: its address and the app key its token
1106
+ * carries. Anonymous is an empty subject, never the host's signer.
1107
+ */
1108
+ export declare function callerSubject(user: Context["user"]): AuthSubject;
1109
+ export declare class BaseSubgraph implements ISubgraph$1 {
1110
+ #private;
1111
+ name: string;
1112
+ path: string;
1113
+ resolvers: Record<string, any>;
1114
+ typeDefs: DocumentNode;
1115
+ /**
1116
+ * The read half, for setup-time use (schema building, model lookup).
1117
+ * Resolvers read through `ctx.clients.read` instead.
1118
+ */
1119
+ readonly readClient: IReactorReadClient;
1120
+ /**
1121
+ * @deprecated The facade over both halves, for subgraphs that have not
1122
+ * moved. Resolvers use `ctx.clients.read` and, in a mutation,
1123
+ * `ctx.clients.write`; setup-time code uses {@link readClient}.
1124
+ */
1125
+ reactorClient: IReactorClient;
1126
+ /** This package's namespaced slice of the HTTP surface. */
1127
+ readonly http: SubgraphArgs$1["http"];
1128
+ graphqlManager: GraphQLManager$1;
1129
+ relationalDb: IRelationalDb;
1130
+ syncManager: ISyncManager;
1131
+ documentPermissionService?: DocumentPermissionService;
1132
+ authorizationService: IAuthorizationService;
1133
+ syncServingGate?: SyncScopeGate;
1134
+ /**
1135
+ * The host's credential cache, for a package that revokes credentials:
1136
+ * call `this.credentials.invalidateCredential(address, chainId?, appDid?)`
1137
+ * right after the revocation is stored, so this host refuses the credential
1138
+ * on the next request and closes WebSocket connections that rely on it.
1139
+ * A no-op on a host without authentication.
1140
+ */
1141
+ readonly credentials: ICredentialInvalidator;
1142
+ constructor(args: SubgraphArgs$1);
1143
+ /**
1144
+ * An attachment client bound to this request's caller, memoized per request.
1145
+ *
1146
+ * @throws Error when the host provides no attachment client to subgraphs.
1147
+ */
1148
+ attachmentsFor(ctx: Context): IAttachmentClient;
1149
+ /**
1150
+ * The clients this request's operation may use: those the GraphQL layer put
1151
+ * on the context. A context it never saw (a resolver called directly) reads
1152
+ * through {@link readClient} and may not write.
1153
+ */
1154
+ clientsOf(ctx: Context | undefined): RequestClients;
1155
+ onSetup(): Promise<void>;
1156
+ onDisconnect(): Promise<void>;
1157
+ /**
1158
+ * Resolves a caller-supplied identifier (id or slug) to its canonical
1159
+ * document id, memoized per request. Both the decision layer and the data
1160
+ * layer must agree on the subject, so this runs the lookup the data path
1161
+ * uses: `resolveIdOrSlug` on the read half for a query, `describe` on the
1162
+ * write half for a mutation. A resolution failure (not found, ambiguous, or
1163
+ * transient) surfaces as a generic Forbidden, fail-closed, so a bad
1164
+ * identifier cannot be used as a document-existence oracle.
1165
+ */
1166
+ resolveCanonicalDocumentId(identifier: string, requestKey: object): Promise<CanonicalDocumentId>;
1167
+ /**
1168
+ * Resolves the args' `documentId` to canonical form. Unconditional (unlike the
1169
+ * assertCan* helpers, no admin skip): ACL rows are keyed on the canonical id.
1170
+ */
1171
+ withCanonicalDocumentId<T extends {
1172
+ documentId: string;
1173
+ }>(args: T, requestKey: object): Promise<T & {
1174
+ documentId: CanonicalDocumentId;
1175
+ }>;
1176
+ /**
1177
+ * Read filter for an already-canonical document id (one sourced from the data
1178
+ * layer, such as a fetched document's id). Performs no slug resolution.
1045
1179
  */
1046
- private readonly scopeGate?;
1047
- private readonly options;
1048
- constructor(resolveCanonicalId: CanonicalDocumentIdResolver, authorization: IAuthorizationService, references: IAttachmentReferenceReader, projection: AttachmentReferenceProjectionCapability, readGate: AttachmentReadGate,
1180
+ canReadDocument(documentId: CanonicalDocumentId, ctx: Context): Promise<boolean>;
1181
+ /** The ids or slugs in `ids` that {@link assertCanRead} admits, in order; the rest are dropped. */
1182
+ filterReadableDocumentIds(ids: readonly string[], ctx: Context): Promise<string[]>;
1183
+ /** Drops the items the host's own ACL refuses the caller. */
1184
+ readableByHost<T extends {
1185
+ id: string;
1186
+ }>(items: readonly T[], ctx: Context): Promise<T[]>;
1049
1187
  /**
1050
- * Absent below auth enforcement, where there is no policy model to
1051
- * evaluate; the host's permission tables decide alone, exactly as before.
1188
+ * The principal a request decides as: the authenticated caller's address, and
1189
+ * the did:key of the app instance whose token authenticated it.
1190
+ *
1191
+ * Both, because a policy can name either. The key is what a document records
1192
+ * as its creator, so a subject built without one cannot match the creator's
1193
+ * standing permission over the auth scope -- the document's own creator would
1194
+ * be refused an operation the write path accepts, since a signed action
1195
+ * carries the same key. Anonymous callers supply neither.
1052
1196
  */
1053
- scopeGate?: IDocumentScopeGate | undefined, options?: AttachmentAccessServiceOptions);
1054
- admitCaller(request: AttachmentCallerRequest): Promise<AttachmentCallerResult>;
1055
- canReadAttachment(request: AttachmentAccessRequest): Promise<AttachmentAccessResult>;
1197
+ protected viewSubject(ctx: Context): AuthSubject;
1198
+ /** Whether a listing would serve the document to the caller; fails closed. */
1199
+ protected servesDocument(documentId: string, ctx: Context): Promise<boolean>;
1200
+ /** {@link servesDocument}, but a reactor that cannot answer throws. */
1201
+ protected servesDocumentOrThrows(identifier: string, ctx: Context, view?: Pick<ViewFilter, "branch" | "scopes">): Promise<boolean>;
1056
1202
  /**
1057
- * Whether the caller may read the state the reference lives in.
1058
- *
1059
- * A failure here is rethrown rather than turned into a denial. A read side
1060
- * that is down must not read as a policy: a denial nobody can distinguish
1061
- * from a refusal is one nobody investigates, and the route answers 500 for a
1062
- * reason.
1203
+ * Whether a listing would serve the document to the caller: the reactor read
1204
+ * gate, then the host's legacy layer, as `findDocuments` applies them. Absent
1205
+ * or withheld is `false`; a failure to decide throws.
1063
1206
  */
1064
- private canReadDocument;
1065
- }
1066
- //#endregion
1067
- //#region src/services/authorized-attachment.service.d.ts
1068
- /** The reference index is not maintained in this composition. */
1069
- export declare class AttachmentAccessUnavailable extends Error {
1070
- constructor();
1071
- }
1072
- /** The access decision itself failed; the cause is logged, not surfaced. */
1073
- export declare class AttachmentAccessFailed extends Error {
1074
- constructor(cause: unknown);
1075
- }
1076
- /** An `IAttachmentService` whose reads and writes are decided for one subject. */
1077
- export declare class AuthorizedAttachmentService implements IAttachmentService {
1078
- private readonly inner;
1079
- private readonly access;
1080
- private readonly subject;
1081
- private readonly logger;
1082
- constructor(inner: IAttachmentService, access: IAttachmentAccessService, subject: AuthSubject, logger: ILogger);
1083
- /** Hash-first only: an upload-first handle can send after it expires. */
1084
- reserve(options: ReserveAttachmentOptions): Promise<IAttachmentUpload>;
1085
- stat(ref: AttachmentRef, options?: AttachmentStatOptions): Promise<AttachmentHeader>;
1086
- get(ref: AttachmentRef, options?: AbortSignal | AttachmentDownloadOptions): Promise<AttachmentResponse>;
1087
- getDownloadTarget(ref: AttachmentRef, options: AttachmentDownloadTargetOptions): Promise<AttachmentDownloadTarget>;
1088
- private decideRead;
1089
- private admit;
1090
- private accessFailed;
1091
- }
1092
- export interface IAttachmentClientProvider {
1093
- forSubject(subject: AuthSubject): IAttachmentClient;
1094
- }
1095
- export declare class AttachmentClientProvider implements IAttachmentClientProvider {
1096
- private readonly service;
1097
- private readonly access;
1098
- private readonly logger;
1099
- constructor(service: IAttachmentService, access: IAttachmentAccessService, logger: ILogger);
1100
- forSubject(subject: AuthSubject): IAttachmentClient;
1207
+ protected listsDocument(identifier: string, ctx: Context, view?: Pick<ViewFilter, "branch" | "scopes">): Promise<boolean>;
1208
+ /**
1209
+ * Asserts read access, resolving a slug first. Returns a handle whose
1210
+ * `fetchIdentifier` the caller reuses for the data fetch; a denial throws.
1211
+ */
1212
+ assertCanRead(identifier: string, ctx: Context): Promise<AuthorizedDocumentHandle>;
1213
+ assertCanWrite(identifier: string, ctx: Context): Promise<AuthorizedDocumentHandle>;
1214
+ assertCanExecuteOperation(identifier: string, operationType: string, ctx: Context): Promise<AuthorizedDocumentHandle>;
1215
+ /**
1216
+ * Read assertion for an already-canonical document id. No slug resolution;
1217
+ * use only with ids sourced from the data layer or already resolved.
1218
+ */
1219
+ assertCanReadCanonical(documentId: CanonicalDocumentId, ctx: Context): Promise<void>;
1220
+ assertCanWriteCanonical(documentId: CanonicalDocumentId, ctx: Context): Promise<void>;
1221
+ assertCanExecuteOperationCanonical(documentId: CanonicalDocumentId, operationType: string, ctx: Context): Promise<void>;
1222
+ assertCanCreate(ctx: Context): void;
1101
1223
  }
1102
1224
  //#endregion
1103
1225
  //#region src/graphql/inspection/throttle.d.ts
@@ -1298,125 +1420,53 @@ export type GqlDriveDocument = GqlDocument & {
1298
1420
  initialState: DocumentDriveGlobalState;
1299
1421
  };
1300
1422
  //#endregion
1301
- //#region src/graphql/base-subgraph.d.ts
1302
- /**
1303
- * The subject a request reads as: its address and the app key its token
1304
- * carries. Anonymous is an empty subject, never the host's signer.
1305
- */
1306
- export declare function callerSubject(user: Context["user"]): AuthSubject;
1307
- export declare class BaseSubgraph implements ISubgraph$1 {
1308
- #private;
1309
- name: string;
1310
- path: string;
1311
- resolvers: Record<string, any>;
1312
- typeDefs: DocumentNode;
1313
- /**
1314
- * The read half, for setup-time use (schema building, model lookup).
1315
- * Resolvers read through `ctx.clients.read` instead.
1316
- */
1317
- readonly readClient: IReactorReadClient;
1318
- /**
1319
- * @deprecated The facade over both halves, for subgraphs that have not
1320
- * moved. Resolvers use `ctx.clients.read` and, in a mutation,
1321
- * `ctx.clients.write`; setup-time code uses {@link readClient}.
1322
- */
1323
- reactorClient: IReactorClient;
1324
- /** This package's namespaced slice of the HTTP surface. */
1325
- readonly http: SubgraphArgs$1["http"];
1326
- graphqlManager: GraphQLManager$1;
1327
- relationalDb: IRelationalDb;
1328
- syncManager: ISyncManager;
1329
- documentPermissionService?: DocumentPermissionService;
1330
- authorizationService: IAuthorizationService;
1331
- syncServingGate?: SyncScopeGate;
1332
- /**
1333
- * The host's credential cache, for a package that revokes credentials:
1334
- * call `this.credentials.invalidateCredential(address, chainId?, appDid?)`
1335
- * right after the revocation is stored, so this host refuses the credential
1336
- * on the next request and closes WebSocket connections that rely on it.
1337
- * A no-op on a host without authentication.
1338
- */
1339
- readonly credentials: ICredentialInvalidator;
1340
- constructor(args: SubgraphArgs$1);
1341
- /**
1342
- * An attachment client bound to this request's caller, memoized per request.
1343
- *
1344
- * @throws Error when the host provides no attachment client to subgraphs.
1345
- */
1346
- attachmentsFor(ctx: Context): IAttachmentClient;
1347
- /**
1348
- * The clients this request's operation may use: those the GraphQL layer put
1349
- * on the context. A context it never saw (a resolver called directly) reads
1350
- * through {@link readClient} and may not write.
1351
- */
1352
- clientsOf(ctx: Context | undefined): RequestClients;
1353
- onSetup(): Promise<void>;
1354
- onDisconnect(): Promise<void>;
1355
- /**
1356
- * Resolves a caller-supplied identifier (id or slug) to its canonical
1357
- * document id, memoized per request. Both the decision layer and the data
1358
- * layer must agree on the subject, so this runs the lookup the data path
1359
- * uses: `resolveIdOrSlug` on the read half for a query, `describe` on the
1360
- * write half for a mutation. A resolution failure (not found, ambiguous, or
1361
- * transient) surfaces as a generic Forbidden, fail-closed, so a bad
1362
- * identifier cannot be used as a document-existence oracle.
1363
- */
1364
- resolveCanonicalDocumentId(identifier: string, requestKey: object): Promise<CanonicalDocumentId>;
1365
- /**
1366
- * Resolves the args' `documentId` to canonical form. Unconditional (unlike the
1367
- * assertCan* helpers, no admin skip): ACL rows are keyed on the canonical id.
1368
- */
1369
- withCanonicalDocumentId<T extends {
1370
- documentId: string;
1371
- }>(args: T, requestKey: object): Promise<T & {
1372
- documentId: CanonicalDocumentId;
1373
- }>;
1374
- /**
1375
- * Read filter for an already-canonical document id (one sourced from the data
1376
- * layer, such as a fetched document's id). Performs no slug resolution.
1377
- */
1378
- canReadDocument(documentId: CanonicalDocumentId, ctx: Context): Promise<boolean>;
1379
- /** Drops the items the host's own ACL refuses the caller. */
1380
- readableByHost<T extends {
1381
- id: string;
1382
- }>(items: readonly T[], ctx: Context): Promise<T[]>;
1383
- /**
1384
- * The principal a request decides as: the authenticated caller's address, and
1385
- * the did:key of the app instance whose token authenticated it.
1386
- *
1387
- * Both, because a policy can name either. The key is what a document records
1388
- * as its creator, so a subject built without one cannot match the creator's
1389
- * standing permission over the auth scope -- the document's own creator would
1390
- * be refused an operation the write path accepts, since a signed action
1391
- * carries the same key. Anonymous callers supply neither.
1392
- */
1393
- protected viewSubject(ctx: Context): AuthSubject;
1394
- /** Whether a listing would serve the document to the caller; fails closed. */
1395
- protected servesDocument(documentId: string, ctx: Context): Promise<boolean>;
1396
- /** {@link servesDocument}, but a reactor that cannot answer throws. */
1397
- protected servesDocumentOrThrows(identifier: string, ctx: Context, view?: Pick<ViewFilter, "branch" | "scopes">): Promise<boolean>;
1398
- /**
1399
- * Whether a listing would serve the document to the caller: the reactor read
1400
- * gate, then the host's legacy layer, as `findDocuments` applies them. Absent
1401
- * or withheld is `false`; a failure to decide throws.
1402
- */
1403
- protected listsDocument(identifier: string, ctx: Context, view?: Pick<ViewFilter, "branch" | "scopes">): Promise<boolean>;
1404
- /**
1405
- * Asserts read access, resolving a slug first. Returns a handle whose
1406
- * `fetchIdentifier` the caller reuses for the data fetch; a denial throws.
1407
- */
1408
- assertCanRead(identifier: string, ctx: Context): Promise<AuthorizedDocumentHandle>;
1409
- assertCanWrite(identifier: string, ctx: Context): Promise<AuthorizedDocumentHandle>;
1410
- assertCanExecuteOperation(identifier: string, operationType: string, ctx: Context): Promise<AuthorizedDocumentHandle>;
1411
- /**
1412
- * Read assertion for an already-canonical document id. No slug resolution;
1413
- * use only with ids sourced from the data layer or already resolved.
1414
- */
1415
- assertCanReadCanonical(documentId: CanonicalDocumentId, ctx: Context): Promise<void>;
1416
- assertCanWriteCanonical(documentId: CanonicalDocumentId, ctx: Context): Promise<void>;
1417
- assertCanExecuteOperationCanonical(documentId: CanonicalDocumentId, operationType: string, ctx: Context): Promise<void>;
1418
- assertCanCreate(ctx: Context): void;
1419
- }
1423
+ //#region src/graphql/gateway/factory.d.ts
1424
+ export type GatewayAdapterType = "apollo" | "mercurius" | "stitching";
1425
+ export type HttpAdapterType = "express" | "fastify";
1426
+ export declare function createGatewayAdapter(type: GatewayAdapterType, logger: ILogger): Promise<IGatewayAdapter<Context>>;
1427
+ export type HttpAdapterSetup = {
1428
+ adapter: IHttpAdapter;
1429
+ };
1430
+ export declare function createHttpAdapter(type: HttpAdapterType): Promise<HttpAdapterSetup>;
1431
+ //#endregion
1432
+ //#region src/api-config.d.ts
1433
+ type Env = Readonly<Record<string, string | undefined>>;
1434
+ /** reactor-api settings env can supply; an unset key means "not configured here". */
1435
+ export type ReactorApiConfig = {
1436
+ server?: {
1437
+ /** Route prefix for GraphQL, the explorer, package routes and webhooks. */
1438
+ basePath?: string;
1439
+ gatewayAdapter?: GatewayAdapterType;
1440
+ /** Origin advertised in webhook URLs; a bare domain gets `https://`. */
1441
+ publicUrl?: string;
1442
+ };
1443
+ auth?: {
1444
+ enabled?: boolean;
1445
+ admins?: string[];
1446
+ resolveIdentity?: boolean;
1447
+ requireAuthenticatedCaller?: boolean;
1448
+ requireAuthenticatedCallerExemptPaths?: string[];
1449
+ attachmentReadsFollowDocumentPolicy?: boolean;
1450
+ defaultProtection?: boolean;
1451
+ documentPermissions?: {
1452
+ enabled?: boolean;
1453
+ cacheTtlMs?: number;
1454
+ };
1455
+ skipCredentialVerification?: boolean;
1456
+ credentialCacheTtlMs?: number;
1457
+ wsRecheckMs?: number;
1458
+ };
1459
+ inspection?: {
1460
+ admin?: boolean;
1461
+ };
1462
+ attachments?: {
1463
+ storage?: AttachmentStorageConfig;
1464
+ };
1465
+ };
1466
+ /** The reactor-api settings `env` names; keys it does not set stay undefined. */
1467
+ export declare function reactorApiConfigFromEnv(env: Env, logger?: ILogger): ReactorApiConfig;
1468
+ /** `DOCUMENT_PERMISSION_CACHE_TTL_MS` in ms (0 disables); invalid warns and uses the default. */
1469
+ export declare function resolvePermissionCacheTtlMs(raw: string | undefined, logger: ILogger): number;
1420
1470
  //#endregion
1421
1471
  //#region src/graphql/analytics-subgraph.d.ts
1422
1472
  export declare class AnalyticsSubgraph extends BaseSubgraph {
@@ -1646,15 +1696,6 @@ export type AuthFetchMiddleware = (handler: FetchHandler) => FetchHandler;
1646
1696
  export declare function getAuthContext(request: globalThis.Request): AuthContext | undefined;
1647
1697
  export declare function createAuthFetchMiddleware(authService: AuthService): AuthFetchMiddleware;
1648
1698
  //#endregion
1649
- //#region src/graphql/gateway/factory.d.ts
1650
- export type GatewayAdapterType = "apollo" | "mercurius" | "stitching";
1651
- export type HttpAdapterType = "express" | "fastify";
1652
- export declare function createGatewayAdapter(type: GatewayAdapterType, logger: ILogger): Promise<IGatewayAdapter<Context>>;
1653
- export type HttpAdapterSetup = {
1654
- adapter: IHttpAdapter;
1655
- };
1656
- export declare function createHttpAdapter(type: HttpAdapterType): Promise<HttpAdapterSetup>;
1657
- //#endregion
1658
1699
  //#region src/graphql/gateway/drive-ownership-cache.d.ts
1659
1700
  /**
1660
1701
  * Where drives are looked up: the raw reactor, past the read gate. Ownership
@@ -2997,6 +3038,7 @@ export type Query = {
2997
3038
  readonly syncHolds: ReadonlyArray<SyncHold>;
2998
3039
  };
2999
3040
  export type QueryCreateDefaultsArgs = {
3041
+ documentType?: InputMaybe<Scalars["String"]["input"]>;
3000
3042
  parentIdOrSlug?: InputMaybe<Scalars["String"]["input"]>;
3001
3043
  };
3002
3044
  export type QueryDocumentArgs = {
@@ -3587,6 +3629,15 @@ export type GetCreateDefaultsQuery = {
3587
3629
  readonly protocolVersions: NonNullable<unknown>;
3588
3630
  };
3589
3631
  };
3632
+ export type GetCreateProtocolVersionsQueryVariables = Exact<{
3633
+ parentIdOrSlug?: InputMaybe<Scalars["String"]["input"]>;
3634
+ documentType: Scalars["String"]["input"];
3635
+ }>;
3636
+ export type GetCreateProtocolVersionsQuery = {
3637
+ readonly createDefaults: {
3638
+ readonly protocolVersions: NonNullable<unknown>;
3639
+ };
3640
+ };
3590
3641
  type DriveNodeFields_DriveFileNode_Fragment = {
3591
3642
  readonly id: string;
3592
3643
  readonly driveId: string;
@@ -4714,6 +4765,7 @@ export declare const GetDocumentOperationsDocument: DocumentNode;
4714
4765
  export declare const GetJobStatusDocument: DocumentNode;
4715
4766
  export declare const GetDocumentServedDocument: DocumentNode;
4716
4767
  export declare const GetCreateDefaultsDocument: DocumentNode;
4768
+ export declare const GetCreateProtocolVersionsDocument: DocumentNode;
4717
4769
  export declare const GetDriveNodesDocument: DocumentNode;
4718
4770
  export declare const GetDriveNodeDocument: DocumentNode;
4719
4771
  export declare const GetDriveDescendantsDocument: DocumentNode;
@@ -4750,6 +4802,7 @@ export declare function getSdk<C>(requester: Requester<C>): {
4750
4802
  GetJobStatus(variables: GetJobStatusQueryVariables, options?: C): Promise<GetJobStatusQuery>;
4751
4803
  GetDocumentServed(variables: GetDocumentServedQueryVariables, options?: C): Promise<GetDocumentServedQuery>;
4752
4804
  GetCreateDefaults(variables?: GetCreateDefaultsQueryVariables, options?: C): Promise<GetCreateDefaultsQuery>;
4805
+ GetCreateProtocolVersions(variables: GetCreateProtocolVersionsQueryVariables, options?: C): Promise<GetCreateProtocolVersionsQuery>;
4753
4806
  GetDriveNodes(variables: GetDriveNodesQueryVariables, options?: C): Promise<GetDriveNodesQuery>;
4754
4807
  GetDriveNode(variables: GetDriveNodeQueryVariables, options?: C): Promise<GetDriveNodeQuery>;
4755
4808
  GetDriveDescendants(variables: GetDriveDescendantsQueryVariables, options?: C): Promise<GetDriveDescendantsQuery>;
@@ -4837,6 +4890,10 @@ export declare function createReactorGraphQLClient(url: string, fetchImpl?: Fetc
4837
4890
  GetCreateDefaults(variables?: Exact<{
4838
4891
  parentIdOrSlug?: InputMaybe<Scalars["String"]["input"]>;
4839
4892
  }> | undefined, options?: {} | undefined): Promise<GetCreateDefaultsQuery>;
4893
+ GetCreateProtocolVersions(variables: Exact<{
4894
+ parentIdOrSlug?: InputMaybe<Scalars["String"]["input"]>;
4895
+ documentType: Scalars["String"]["input"];
4896
+ }>, options?: {} | undefined): Promise<GetCreateProtocolVersionsQuery>;
4840
4897
  GetDriveNodes(variables: Exact<{
4841
4898
  driveId: Scalars["ID"]["input"];
4842
4899
  parentFolder?: InputMaybe<Scalars["ID"]["input"]>;
@@ -4981,7 +5038,8 @@ export declare class ReactorSubgraph extends BaseSubgraph {
4981
5038
  }
4982
5039
  //#endregion
4983
5040
  //#region src/graphql/system/env/index.d.ts
4984
- export declare const ADMIN_USERS: string[];
5041
+ /** @deprecated Nothing reads it; read `ADMIN_USERS` at your own edge. Reads env on each access. */
5042
+ export declare const ADMIN_USERS: readonly string[];
4985
5043
  //#endregion
4986
5044
  //#region src/graphql/system/subgraph.d.ts
4987
5045
  export declare class SystemSubgraph extends BaseSubgraph {
@@ -5235,32 +5293,42 @@ type Options = {
5235
5293
  pgliteFactory?: PgliteFactory;
5236
5294
  configFile?: string;
5237
5295
  packages?: string[];
5296
+ /** Route prefix, gateway and public origin. Env is not read: map it at the
5297
+ * edge with `reactorApiConfigFromEnv`. */
5298
+ server?: ReactorApiConfig["server"];
5299
+ /** `enabled` and `admins` win over the `configFile`'s. Env is not read. */
5238
5300
  auth?: {
5239
- enabled: boolean;
5240
- admins: string[];
5301
+ enabled?: boolean;
5302
+ admins?: string[];
5241
5303
  /** Read the bearer and populate `ctx.user` independently of `enabled`.
5242
- * Defaults to `enabled`; `RESOLVE_CALLER_IDENTITY` overrides either. */
5304
+ * Defaults to `enabled`. */
5243
5305
  resolveIdentity?: boolean;
5244
5306
  /** Reject anonymous callers with a 401 before any subgraph sees the
5245
- * request. Off by default; `REQUIRE_AUTHENTICATED_CALLER` overrides.
5246
- * Requires identity resolution to be on — refused at boot without it. */
5307
+ * request. Off by default. Requires identity resolution to be on —
5308
+ * refused at boot without it. */
5247
5309
  requireAuthenticatedCaller?: boolean;
5248
5310
  /** Mounted paths that stay reachable anonymously while
5249
5311
  * `requireAuthenticatedCaller` is on, for a flow that runs before
5250
5312
  * sign-in. Matched against the request's pathname in full, never as a
5251
- * prefix. `REQUIRE_AUTHENTICATED_CALLER_EXEMPT_PATHS` overrides, as a
5252
- * comma-separated list. Each entry is a hole in the floor: only ever name
5313
+ * prefix. Each entry is a hole in the floor: only ever name
5253
5314
  * a path serving operations that are safe without a caller. */
5254
5315
  requireAuthenticatedCallerExemptPaths?: string[];
5255
5316
  /** Decide an attachment read with the referencing document's own policy
5256
- * instead of the host permission tables. Off by default;
5257
- * `ATTACHMENT_READS_FOLLOW_DOCUMENT_POLICY` overrides. Requires auth
5317
+ * instead of the host permission tables. Off by default. Requires auth
5258
5318
  * enforcement, which is what supplies the model — refused at boot
5259
5319
  * without it. */
5260
5320
  attachmentReadsFollowDocumentPolicy?: boolean;
5321
+ defaultProtection?: boolean;
5322
+ documentPermissions?: {
5323
+ enabled?: boolean;
5324
+ cacheTtlMs?: number;
5325
+ };
5326
+ skipCredentialVerification?: boolean;
5327
+ credentialCacheTtlMs?: number;
5328
+ wsRecheckMs?: number;
5261
5329
  };
5262
5330
  /** Renown coordinates the host already resolved, used verbatim instead of
5263
- * resolving `auth.renown` and the env again (which would warn twice). */
5331
+ * resolving the config file's `auth.renown` again (which would warn twice). */
5264
5332
  renown?: ResolvedRenownConfig;
5265
5333
  /** Credential check replacing the built-in remote Renown one; required when
5266
5334
  * the resolved source is "self" (see assertCredentialVerifierForSource). */
@@ -5277,8 +5345,7 @@ type Options = {
5277
5345
  * Document permission service instance.
5278
5346
  * When provided, the Auth subgraph is registered and document permission
5279
5347
  * checks are enforced on document operations.
5280
- * If not provided, can be auto-created by setting DOCUMENT_PERMISSIONS_ENABLED=true
5281
- * environment variable.
5348
+ * If not provided, `auth.documentPermissions.enabled` creates one.
5282
5349
  */
5283
5350
  documentPermissionService?: DocumentPermissionService;
5284
5351
  enableDocumentModelSubgraphs?: boolean;
@@ -5291,6 +5358,8 @@ type Options = {
5291
5358
  * or os.tmpdir() for in-memory DB deployments.
5292
5359
  */
5293
5360
  attachmentStoragePath?: string;
5361
+ /** Filesystem when unset. */
5362
+ attachments?: ReactorApiConfig["attachments"];
5294
5363
  /** Storage health and workflow facts for the inspection subgraph; `false`
5295
5364
  * leaves it unmounted and `api.inspection` undefined. On by default. */
5296
5365
  inspection?: ReactorInspectionOptions | false;
@@ -5365,12 +5434,6 @@ export interface ClientInitializerDependencies {
5365
5434
  /** The read-model store, for moving data that used to live there. */
5366
5435
  readModelDb: Kysely<unknown>;
5367
5436
  }
5368
- /**
5369
- * The permission cache TTL from `DOCUMENT_PERMISSION_CACHE_TTL_MS`: a
5370
- * non-negative integer of milliseconds, 0 disabling the cache. Anything else
5371
- * falls back to the default with a warning.
5372
- */
5373
- export declare function resolvePermissionCacheTtlMs(raw: string | undefined, logger: ILogger): number;
5374
5437
  export declare function initializeAndStartAPI(clientInitializer: (documentModels: DocumentModelModule[], dependencies: ClientInitializerDependencies) => Promise<ClientInitializerResult>, options: Options, processorApp: ProcessorApp): Promise<API & {
5375
5438
  /** @deprecated Use `read` and `write`. */
5376
5439
  client: IReactorClient;