@mnmal-ai/substrate 1.0.0-alpha.0 → 1.0.0-alpha.10
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.
- package/README.md +51 -9
- package/dist/boot-store-BVqfFxh1.js +4060 -0
- package/dist/{runtime-metrics-DwpDJ8vz.d.ts → bridge-Cp4PaIYO.d.ts} +2 -87
- package/dist/cli-hSCBywhE.js +3126 -0
- package/dist/client.d.ts +130 -8
- package/dist/client.js +6 -5
- package/dist/{plugin-t2g2wX0b.d.ts → dataset-CejF-Fr_.d.ts} +1640 -1320
- package/dist/{agent-token-BIboWOU0.js → env-utils-CGNazUNt.js} +31 -2
- package/dist/{errors-D4vKuwz8.d.ts → errors-7mycvNGq.d.ts} +1 -1
- package/dist/{index-D7mSOFlM.d.ts → index-DgSfwx7M.d.ts} +1 -1
- package/dist/node-version-C5FSmwJX.js +26 -0
- package/dist/pack.d.ts +2 -2
- package/dist/pack.js +1 -1
- package/dist/pg-edges-store-Lxsl5ZnK.js +381 -0
- package/dist/{plugin-j1jt1l3n.js → plugin-CtwOINCM.js} +171 -18
- package/dist/proposals-bootstrap.js +6 -4
- package/dist/proposals.config.schema.json +5 -0
- package/dist/proposals.d.ts +15 -4
- package/dist/proposals.default-config.json +2 -1
- package/dist/proposals.js +2 -2
- package/dist/recall-bootstrap.js +13 -4
- package/dist/recall.config.schema.json +12 -0
- package/dist/recall.d.ts +54 -9
- package/dist/recall.js +2 -2
- package/dist/{repl-C52wyfMs.js → repl-DqfHelK7.js} +62 -29
- package/dist/{row-ByLFE2Wx.d.ts → row-BKKCXIG6.d.ts} +5 -3
- package/dist/run-B5dTbZ3g.js +1997 -0
- package/dist/{schema-g4FQLr0V.d.ts → schema-DoSc-4ig.d.ts} +44 -7
- package/dist/script-C6DSa_Na.js +134 -0
- package/dist/sdk.d.ts +90 -12
- package/dist/sdk.js +5 -110
- package/dist/{src-D91yij6C.js → src-5SJ5GEIM.js} +1557 -327
- package/dist/{src-DuopV8u7.js → src-7CUSMK66.js} +148 -19
- package/dist/{src-CrEgiMJQ.js → src-Bi849yhn.js} +39 -15
- package/dist/{src-D88LvCX8.js → src-CqT-QWZ_.js} +697 -57
- package/dist/src-CyvV7dCK.js +4333 -0
- package/dist/{row-DK7lPZVe.js → src-Da0t6si5.js} +11 -11
- package/dist/{src-C4DzaIQZ.js → src-hZb8wfvg.js} +12 -1
- package/dist/substrate-admin.js +17 -781
- package/dist/substrate.js +4 -5471
- package/dist/testing.d.ts +557 -8
- package/dist/testing.js +39 -3
- package/dist/{ws-C72iVS5T.d.ts → ws-ByZyHk7m.d.ts} +3 -3
- package/package.json +21 -20
- package/dist/dataset-BXkus75W.js +0 -1527
- package/dist/env-utils-B7SGmoeJ.js +0 -21
- package/dist/src-CzxvmhFn.js +0 -2327
|
@@ -0,0 +1,4060 @@
|
|
|
1
|
+
import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
|
|
2
|
+
import { D as isReservedAutoCrudField, W as MemoryEdgesStore, a as composeFromManifests, c as MemoryDataset, ft as buildContext, gt as parseAuthConfig, h as AUDIT_EVENT_TYPE, i as PluginLoadError, it as unregisterExtensionOperator, m as buildAuditRow, n as kernelMigrationTracking, nt as listExtensionOperators, o as DEFAULT_NAMESPACE, q as effectiveFilterOperators, r as mountKernelRoute, rt as registerExtensionOperator, s as compose, t as composeKernelPlugins, tt as getExtensionOperator, u as isStoreProfileName, ut as HttpBridgeClient, yt as WS_REASON_SERVER_RESTART } from "./src-5SJ5GEIM.js";
|
|
3
|
+
import { a as adminClaimCapabilities, d as resolveDefaultKidPath, l as resolveAdminCredential, n as trimTrailingSlashes, r as ADMIN_CAPABILITIES, s as makeAuthorizationProvider, t as parsePositiveInt, u as resolveDefaultKeyPath } from "./env-utils-CGNazUNt.js";
|
|
4
|
+
import { D as isActiveAdminKeyRow, E as describeGrant, L as encodeList, M as grantEntryError, T as SYSTEM_NAMESPACE, v as grantEntriesConfer } from "./src-Da0t6si5.js";
|
|
5
|
+
import "./src-hZb8wfvg.js";
|
|
6
|
+
import { C as diagnose, S as DIAGNOSE_CHECKS, _ as SKIPPABLE_STEPS, b as planOnboarding, h as CURRENT_MARK, i as tokenAudience, v as STEP_MARKS, x as requiredOutstanding, y as currentStep } from "./src-7CUSMK66.js";
|
|
7
|
+
import { f as pendingMigrations, g as detectLayout, l as deriveListIndexMigration, m as runMigrations, p as runDerivedMigrations, s as assertNotMigrating, t as PgDataset } from "./src-CyvV7dCK.js";
|
|
8
|
+
import { t as PgEdgesStore } from "./pg-edges-store-Lxsl5ZnK.js";
|
|
9
|
+
import { a as InMemoryLexicalStore, i as PgClusterStore, n as PgLexicalStore, o as InMemoryEmbeddingsStore, r as PgEmbeddingsStore, s as InMemoryClusterStore } from "./src-Bi849yhn.js";
|
|
10
|
+
import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
11
|
+
import { homedir } from "node:os";
|
|
12
|
+
import { basename, dirname, join, resolve } from "node:path";
|
|
13
|
+
import { createHash, createPublicKey, generateKeyPairSync, randomUUID } from "node:crypto";
|
|
14
|
+
import { BlockList, isIP } from "node:net";
|
|
15
|
+
import WebSocket$1 from "ws";
|
|
16
|
+
import { readFile, readdir, stat, statfs } from "node:fs/promises";
|
|
17
|
+
import postgres from "postgres";
|
|
18
|
+
import { pathToFileURL } from "node:url";
|
|
19
|
+
import compressPlugin from "@fastify/compress";
|
|
20
|
+
import corsPlugin from "@fastify/cors";
|
|
21
|
+
import websocketPlugin from "@fastify/websocket";
|
|
22
|
+
import Fastify from "fastify";
|
|
23
|
+
import { Readable } from "node:stream";
|
|
24
|
+
import { setTimeout as setTimeout$1 } from "node:timers/promises";
|
|
25
|
+
|
|
26
|
+
//#region ../../packages/substrate-core/src/memory-bridge-credential-store.ts
|
|
27
|
+
var MemoryBridgeCredentialStore = class {
|
|
28
|
+
#creds = /* @__PURE__ */ new Map();
|
|
29
|
+
constructor(entries = {}) {
|
|
30
|
+
for (const [name, cred] of Object.entries(entries)) this.#creds.set(name, cred);
|
|
31
|
+
}
|
|
32
|
+
get(bridgeName) {
|
|
33
|
+
return this.#creds.get(bridgeName);
|
|
34
|
+
}
|
|
35
|
+
set(bridgeName, cred) {
|
|
36
|
+
this.#creds.set(bridgeName, cred);
|
|
37
|
+
}
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
//#endregion
|
|
41
|
+
//#region ../../packages/substrate-core/src/memory-bridge-registry.ts
|
|
42
|
+
var DuplicateBridgeRegistration = class extends Error {
|
|
43
|
+
name = "DuplicateBridgeRegistration";
|
|
44
|
+
constructor(ns) {
|
|
45
|
+
super(`bridge already registered under namespace alias '${ns}'`);
|
|
46
|
+
}
|
|
47
|
+
};
|
|
48
|
+
var MemoryBridgeRegistry = class {
|
|
49
|
+
#bridges = /* @__PURE__ */ new Map();
|
|
50
|
+
register(ns, client) {
|
|
51
|
+
if (this.#bridges.has(ns)) throw new DuplicateBridgeRegistration(ns);
|
|
52
|
+
this.#bridges.set(ns, client);
|
|
53
|
+
}
|
|
54
|
+
unregister(ns) {
|
|
55
|
+
this.#bridges.delete(ns);
|
|
56
|
+
}
|
|
57
|
+
has(ns) {
|
|
58
|
+
return this.#bridges.has(ns);
|
|
59
|
+
}
|
|
60
|
+
get(ns) {
|
|
61
|
+
return this.#bridges.get(ns);
|
|
62
|
+
}
|
|
63
|
+
isUnreachable(ns) {
|
|
64
|
+
const client = this.#bridges.get(ns);
|
|
65
|
+
if (client === void 0) return false;
|
|
66
|
+
return !client.isReachable();
|
|
67
|
+
}
|
|
68
|
+
entries() {
|
|
69
|
+
return Array.from(this.#bridges.entries());
|
|
70
|
+
}
|
|
71
|
+
/** Dispose every registered bridge and clear the registry. Idempotent. */
|
|
72
|
+
dispose() {
|
|
73
|
+
for (const [, client] of this.#bridges) client.dispose();
|
|
74
|
+
this.#bridges.clear();
|
|
75
|
+
}
|
|
76
|
+
};
|
|
77
|
+
|
|
78
|
+
//#endregion
|
|
79
|
+
//#region ../../packages/substrate-core/src/memory-idempotency-store.ts
|
|
80
|
+
var MemoryIdempotencyStore = class {
|
|
81
|
+
#entries = /* @__PURE__ */ new Map();
|
|
82
|
+
#now;
|
|
83
|
+
constructor(options = {}) {
|
|
84
|
+
this.#now = options.now ?? (() => Date.now());
|
|
85
|
+
}
|
|
86
|
+
async get(key) {
|
|
87
|
+
const entry = this.#entries.get(key);
|
|
88
|
+
if (entry === void 0) return void 0;
|
|
89
|
+
if (entry.expiresAt <= this.#now()) {
|
|
90
|
+
this.#entries.delete(key);
|
|
91
|
+
return;
|
|
92
|
+
}
|
|
93
|
+
return entry.envelope;
|
|
94
|
+
}
|
|
95
|
+
async put(key, envelope, ttlMs) {
|
|
96
|
+
const now = this.#now();
|
|
97
|
+
const expiresAt = now + ttlMs;
|
|
98
|
+
const existing = this.#entries.get(key);
|
|
99
|
+
if (existing !== void 0 && existing.expiresAt > now) {
|
|
100
|
+
existing.expiresAt = Math.max(existing.expiresAt, expiresAt);
|
|
101
|
+
return;
|
|
102
|
+
}
|
|
103
|
+
this.#entries.set(key, {
|
|
104
|
+
envelope,
|
|
105
|
+
expiresAt
|
|
106
|
+
});
|
|
107
|
+
}
|
|
108
|
+
async reapExpired() {
|
|
109
|
+
const now = this.#now();
|
|
110
|
+
let deleted = 0;
|
|
111
|
+
for (const [key, entry] of this.#entries) if (entry.expiresAt <= now) {
|
|
112
|
+
this.#entries.delete(key);
|
|
113
|
+
deleted += 1;
|
|
114
|
+
}
|
|
115
|
+
return { deleted };
|
|
116
|
+
}
|
|
117
|
+
};
|
|
118
|
+
|
|
119
|
+
//#endregion
|
|
120
|
+
//#region ../../packages/substrate-dataset-pg/src/disk-guard.ts
|
|
121
|
+
function makeDiskGuard(opts) {
|
|
122
|
+
const { path, marginBytes } = opts;
|
|
123
|
+
const statfs$2 = opts.statfs ?? ((p) => statfs(p, { bigint: true }));
|
|
124
|
+
return {
|
|
125
|
+
path,
|
|
126
|
+
async check(estimateBytes) {
|
|
127
|
+
if (path === void 0) return { ok: true };
|
|
128
|
+
const s = await statfs$2(path);
|
|
129
|
+
const freeBytes = Number(s.bavail * s.bsize);
|
|
130
|
+
const needBytes = estimateBytes + marginBytes;
|
|
131
|
+
return freeBytes >= needBytes ? { ok: true } : {
|
|
132
|
+
ok: false,
|
|
133
|
+
freeBytes,
|
|
134
|
+
needBytes
|
|
135
|
+
};
|
|
136
|
+
}
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
//#endregion
|
|
141
|
+
//#region ../../packages/substrate-dataset-pg/src/pg-idempotency-store.ts
|
|
142
|
+
var PgIdempotencyStore = class {
|
|
143
|
+
#sql;
|
|
144
|
+
constructor(options) {
|
|
145
|
+
this.#sql = options.sql;
|
|
146
|
+
}
|
|
147
|
+
async get(key) {
|
|
148
|
+
const row = (await this.#sql`
|
|
149
|
+
SELECT envelope
|
|
150
|
+
FROM idempotency
|
|
151
|
+
WHERE key = ${key}
|
|
152
|
+
AND expires_at > now()
|
|
153
|
+
LIMIT 1
|
|
154
|
+
`)[0];
|
|
155
|
+
if (row === void 0) return void 0;
|
|
156
|
+
return row.envelope;
|
|
157
|
+
}
|
|
158
|
+
async put(key, envelope, ttlMs) {
|
|
159
|
+
const sql = this.#sql;
|
|
160
|
+
await sql`
|
|
161
|
+
INSERT INTO idempotency (key, envelope, expires_at)
|
|
162
|
+
VALUES (
|
|
163
|
+
${key},
|
|
164
|
+
${sql.json(envelope)},
|
|
165
|
+
now() + (${ttlMs}::bigint || ' milliseconds')::interval
|
|
166
|
+
)
|
|
167
|
+
ON CONFLICT (key) DO UPDATE SET
|
|
168
|
+
-- The envelope is IMMUTABLE while the entry is live: an idempotency key
|
|
169
|
+
-- must resolve to one stable answer for its whole window, or two
|
|
170
|
+
-- retries of the same request can get different results, which is the
|
|
171
|
+
-- thing the store exists to prevent.
|
|
172
|
+
--
|
|
173
|
+
-- Once it has EXPIRED that rule inverts. The dedupe window closed, the
|
|
174
|
+
-- mutation legitimately re-executed, and the new envelope is the real
|
|
175
|
+
-- result. Keeping the old one would hand back a stale answer wrapped in
|
|
176
|
+
-- a fresh TTL, to a caller who was never deduped at all.
|
|
177
|
+
envelope = CASE
|
|
178
|
+
WHEN idempotency.expires_at <= now() THEN EXCLUDED.envelope
|
|
179
|
+
ELSE idempotency.envelope
|
|
180
|
+
END,
|
|
181
|
+
-- GREATEST rather than a WHERE guard: extends a live window, never
|
|
182
|
+
-- shortens it, and takes the new value outright when the old is past.
|
|
183
|
+
expires_at = GREATEST(idempotency.expires_at, EXCLUDED.expires_at)
|
|
184
|
+
`;
|
|
185
|
+
}
|
|
186
|
+
async reapExpired() {
|
|
187
|
+
return { deleted: (await this.#sql`
|
|
188
|
+
DELETE FROM idempotency
|
|
189
|
+
WHERE expires_at <= now()
|
|
190
|
+
`).count };
|
|
191
|
+
}
|
|
192
|
+
};
|
|
193
|
+
|
|
194
|
+
//#endregion
|
|
195
|
+
//#region src/pg-client.ts
|
|
196
|
+
function formatPgNotice(notice) {
|
|
197
|
+
const candidate = typeof notice === "object" && notice !== null ? notice : null;
|
|
198
|
+
const message = typeof candidate?.message === "string" ? candidate.message : String(notice);
|
|
199
|
+
return `pg ${(typeof candidate?.severity === "string" ? candidate.severity : "NOTICE").toLowerCase()}: ${message}\n`;
|
|
200
|
+
}
|
|
201
|
+
/**
|
|
202
|
+
* The `onnotice` option, with an injectable sink so the routing is testable
|
|
203
|
+
* without opening a connection.
|
|
204
|
+
*/
|
|
205
|
+
function pgNoticeOptions(write = (s) => void process.stderr.write(s)) {
|
|
206
|
+
return { onnotice: (notice) => write(formatPgNotice(notice)) };
|
|
207
|
+
}
|
|
208
|
+
/**
|
|
209
|
+
* Open a pg client with substrate's standard options. Prefer this over calling
|
|
210
|
+
* `postgres()` directly so NOTICE routing stays consistent across `serve`, the
|
|
211
|
+
* admin CLI, `substrate federate`, and the migrate CLI.
|
|
212
|
+
*/
|
|
213
|
+
function openSql(url) {
|
|
214
|
+
return postgres(url, pgNoticeOptions());
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
//#endregion
|
|
218
|
+
//#region src/admin/errors.ts
|
|
219
|
+
/**
|
|
220
|
+
* Shared CLI error carrying a process exit code. Used by `substrate-admin` and by
|
|
221
|
+
* the `substrate federate` verbs that write direct-to-pg.
|
|
222
|
+
*/
|
|
223
|
+
var AdminCliError = class extends Error {
|
|
224
|
+
name = "AdminCliError";
|
|
225
|
+
exitCode;
|
|
226
|
+
constructor(message, exitCode = 1) {
|
|
227
|
+
super(message);
|
|
228
|
+
this.exitCode = exitCode;
|
|
229
|
+
}
|
|
230
|
+
};
|
|
231
|
+
|
|
232
|
+
//#endregion
|
|
233
|
+
//#region src/admin/usage.ts
|
|
234
|
+
/** The `--help` text, kept beside the dispatch that has to stay true to it. */
|
|
235
|
+
const USAGE = [
|
|
236
|
+
"Usage: substrate-admin <subcommand>",
|
|
237
|
+
" substrate-admin --version print the package version (also -v, version)",
|
|
238
|
+
"",
|
|
239
|
+
"Subcommands:",
|
|
240
|
+
" bootstrap [--encrypt] seed the genesis admin Key",
|
|
241
|
+
" doctor [--url <base>] check this deployment end to end and say what is wrong",
|
|
242
|
+
" onboard [--url <base>] [--check] walk a deployment to ready, offering to run each fix",
|
|
243
|
+
" list print active Key rows (DIRECT to pg — does not authenticate)",
|
|
244
|
+
" list --url <base> ask a SERVER over the admin-gated route (authenticates)",
|
|
245
|
+
" revoke <kid> soft-delete a Key by kid",
|
|
246
|
+
" rotate <kid> --out <path> [--encrypt] rotate a Key (new key to <path>)",
|
|
247
|
+
" register <kid> --pubkey <path> --ns <csv> register an existing ed25519 pubkey as an agent Key",
|
|
248
|
+
" update <kid> [--ns <csv>] ... change a live key's namespaces/caps/name in place",
|
|
249
|
+
" migrate-store [options] copy a store into a fresh, empty, partitioned PG 18 store",
|
|
250
|
+
"",
|
|
251
|
+
" register transport: drives POST /substrate/v1/_system/keys (credential + directory row,",
|
|
252
|
+
" one transaction, no restart) using --url or SUBSTRATE_URL and an admin identity",
|
|
253
|
+
" (SUBSTRATE_ADMIN_TOKEN, or SUBSTRATE_ADMIN_KEY_PATH + SUBSTRATE_ADMIN_KEY_ID).",
|
|
254
|
+
" --direct forces the legacy direct-to-postgres write — break-glass only:",
|
|
255
|
+
" it needs the pg superuser password and CANNOT write the directory row.",
|
|
256
|
+
" register directory flags: --no-directory (credential only), --no-broadcast",
|
|
257
|
+
" (directory row with broadcastEligible false), --project <p>.",
|
|
258
|
+
" register flags: --ns <csv> is REQUIRED (use --ns '*' to grant every namespace);",
|
|
259
|
+
" --name <n> --caps <csv> --allow-admin are optional.",
|
|
260
|
+
" update flags: --name <n> --ns <csv> --caps <csv> --widen --allow-admin",
|
|
261
|
+
" omitted flags leave that field unchanged; --widen is required",
|
|
262
|
+
" only when the change grants authority the key does not have.",
|
|
263
|
+
" --ns entries may carry per-namespace capabilities:",
|
|
264
|
+
" --ns inventory:read,notes:read+mutate read inventory, write notes.",
|
|
265
|
+
" A bare entry takes --caps, so --ns notes is unchanged.",
|
|
266
|
+
" --allow-unknown-ns (register + update): confirm a grant naming a namespace",
|
|
267
|
+
" this deployment does not host. Without it such a grant is",
|
|
268
|
+
" refused, because it is accepted by the store and then",
|
|
269
|
+
" refused at every frame — it reads as granted and reaches",
|
|
270
|
+
" nothing. Pass it to register ahead of a plugin install.",
|
|
271
|
+
" TARGET (register / revoke / update): --url <base> goes through a running",
|
|
272
|
+
" server; --direct writes to SUBSTRATE_DATABASE_URL. Say neither and the",
|
|
273
|
+
" target comes from SUBSTRATE_URL, or from SUBSTRATE_DATABASE_URL when no",
|
|
274
|
+
" SUBSTRATE_URL is set. If BOTH are set and you name neither, the",
|
|
275
|
+
" command REFUSES rather than guessing — these are credential",
|
|
276
|
+
" writes and a silent choice can PATCH the wrong store. Every",
|
|
277
|
+
" run prints the target and where it came from before acting.",
|
|
278
|
+
" doctor goes through the running server on purpose: it is the one command that can",
|
|
279
|
+
" answer NO about auth. It checks reachability, whether the server verifies",
|
|
280
|
+
" credentials at all, whether YOUR admin credential resolves, whether the grant it",
|
|
281
|
+
" resolves to confers admin, and how many admin keys the deployment has left.",
|
|
282
|
+
" A check it could not run prints as `skip`, never as a pass.",
|
|
283
|
+
" --encrypt produces a PKCS#8+PBES2 (aes-256-cbc) encrypted private-key PEM.",
|
|
284
|
+
" Passphrase is read from SUBSTRATE_ADMIN_KEY_PASSPHRASE (required when --encrypt is set).",
|
|
285
|
+
" An encrypted admin key is read with SUBSTRATE_ADMIN_KEY_PASSPHRASE for every command that signs.",
|
|
286
|
+
" migrate-store: reads the source and target connection strings from environment variables,",
|
|
287
|
+
" SUBSTRATE_MIGRATE_FROM_URL and SUBSTRATE_MIGRATE_TO_URL unless --from-env / --to-env name",
|
|
288
|
+
" others; a connection string on argv is refused. Stop the service first. The source is",
|
|
289
|
+
" only read. The target must be empty and on PostgreSQL 18; it is prepared with the same",
|
|
290
|
+
" migrations and plugins (SUBSTRATE_PLUGIN_DIR) serve uses, copied, indexed and verified.",
|
|
291
|
+
" SUBSTRATE_INDEX_DISK_PATH must be set (the target volume mount, or off).",
|
|
292
|
+
" --from-schema / --to-schema <s> pin a side to schema <s>",
|
|
293
|
+
" --dry-run preflight only: the plan, every refusal, nothing written",
|
|
294
|
+
" --verify-only build indexes, then verify a finished copy against its source",
|
|
295
|
+
" --skip-index-build leave non-unique index builds to the first serve boot",
|
|
296
|
+
" --full-checksum hash every row rather than a sample per type",
|
|
297
|
+
" --batch-rows <n> rows between progress lines (default 10000)",
|
|
298
|
+
" --skip-table <t> waive a source table nothing declares (repeatable)",
|
|
299
|
+
" --json the final report as one JSON object on stdout; progress is on stderr",
|
|
300
|
+
" Exit: 0 copied and verified; 2 refused or a usage error; 3 verification failed; 1 otherwise."
|
|
301
|
+
].join("\n");
|
|
302
|
+
/** One-line synopsis per subcommand — the shape the operator typed wrong. */
|
|
303
|
+
const SYNOPSIS = {
|
|
304
|
+
bootstrap: "substrate-admin bootstrap [--encrypt]",
|
|
305
|
+
doctor: "substrate-admin doctor [--url <base> | --direct]",
|
|
306
|
+
onboard: "substrate-admin onboard [--url <base>] [--check]",
|
|
307
|
+
list: "substrate-admin list [--url <base>]",
|
|
308
|
+
revoke: "substrate-admin revoke <kid> [--url <base> | --direct]",
|
|
309
|
+
rotate: "substrate-admin rotate <kid> --out <path> [--encrypt]",
|
|
310
|
+
register: "substrate-admin register <kid> --pubkey <path> --ns <csv> [--name <n>] [--caps <csv>] [--allow-admin]",
|
|
311
|
+
update: "substrate-admin update <kid> [--name <n>] [--ns <csv>] [--caps <csv>] [--widen] [--allow-admin]",
|
|
312
|
+
"migrate-store": "substrate-admin migrate-store [--from-env <VAR>] [--to-env <VAR>] [--from-schema <s>] [--to-schema <s>] [--dry-run | --verify-only] [--skip-index-build] [--full-checksum] [--batch-rows <n>] [--skip-table <t>]... [--json]"
|
|
313
|
+
};
|
|
314
|
+
/**
|
|
315
|
+
* An argv-parse failure with the command's usage synopsis attached. Every
|
|
316
|
+
* throw inside a parse*Args function goes through here; run-phase errors keep
|
|
317
|
+
* bare messages because they name the refusing layer instead.
|
|
318
|
+
*/
|
|
319
|
+
function argvError(cmd, message, exitCode = 1) {
|
|
320
|
+
const synopsis = SYNOPSIS[cmd];
|
|
321
|
+
return new AdminCliError(synopsis === void 0 ? message : `${message}\nusage: ${synopsis}`, exitCode);
|
|
322
|
+
}
|
|
323
|
+
/**
|
|
324
|
+
* Printed after every DIRECT-to-postgres credential write. No interceptor
|
|
325
|
+
* fires, so the running server does not see the change until its re-prime
|
|
326
|
+
* interval elapses or it restarts.
|
|
327
|
+
*/
|
|
328
|
+
const RESTART_NOTE = [
|
|
329
|
+
"A RUNNING binary will not see this change until its registry re-primes —",
|
|
330
|
+
"restart it (e.g. `sudo systemctl restart substrate-binary`), or set",
|
|
331
|
+
"SUBSTRATE_KEY_REFRESH_INTERVAL_MS so it converges without one."
|
|
332
|
+
].join("\n");
|
|
333
|
+
|
|
334
|
+
//#endregion
|
|
335
|
+
//#region src/admin/argv.ts
|
|
336
|
+
/**
|
|
337
|
+
* One argv contract for every subcommand, declared once.
|
|
338
|
+
*
|
|
339
|
+
* This owns exactly two questions: is this flag known, and is this positional
|
|
340
|
+
* one too many. Everything semantic stays with each parser — duplicate
|
|
341
|
+
* detection, mutual exclusion (`--direct` vs `--url`), required flags, value
|
|
342
|
+
* SHAPES, and missing required positionals.
|
|
343
|
+
*/
|
|
344
|
+
/**
|
|
345
|
+
* The subcommands, and the whole of what each accepts.
|
|
346
|
+
*
|
|
347
|
+
* This table is also the definition of "known command": `main` refuses anything
|
|
348
|
+
* absent from it BEFORE dispatching, so a subcommand added to the dispatch
|
|
349
|
+
* switch without an entry here does not run at all.
|
|
350
|
+
*
|
|
351
|
+
* Per-command wording (`hint`, `excess`) and `list`'s `--url=` form are
|
|
352
|
+
* deliberate and pinned by tests.
|
|
353
|
+
*/
|
|
354
|
+
const ARGV_SPEC = {
|
|
355
|
+
bootstrap: {
|
|
356
|
+
valueFlags: [],
|
|
357
|
+
boolFlags: ["--encrypt"],
|
|
358
|
+
maxPositionals: 0
|
|
359
|
+
},
|
|
360
|
+
doctor: {
|
|
361
|
+
valueFlags: ["--url"],
|
|
362
|
+
boolFlags: ["--direct"],
|
|
363
|
+
maxPositionals: 0,
|
|
364
|
+
hint: " (accepts --url <base> or --direct)",
|
|
365
|
+
excess: (tok) => `doctor: unexpected argument '${tok}' (accepts --url <base> or --direct)`
|
|
366
|
+
},
|
|
367
|
+
onboard: {
|
|
368
|
+
valueFlags: ["--url"],
|
|
369
|
+
boolFlags: ["--direct", "--check"],
|
|
370
|
+
maxPositionals: 0,
|
|
371
|
+
hint: " (accepts --url <base> and --check)",
|
|
372
|
+
excess: (tok) => `onboard: unexpected argument '${tok}' (accepts --url <base> and --check)`
|
|
373
|
+
},
|
|
374
|
+
list: {
|
|
375
|
+
valueFlags: ["--url"],
|
|
376
|
+
boolFlags: [],
|
|
377
|
+
maxPositionals: 0,
|
|
378
|
+
hint: " (list accepts only --url <base>)",
|
|
379
|
+
excess: (tok) => `list: unexpected argument '${tok}' (list accepts only --url <base>)`,
|
|
380
|
+
equalsForm: true
|
|
381
|
+
},
|
|
382
|
+
revoke: {
|
|
383
|
+
valueFlags: ["--url"],
|
|
384
|
+
boolFlags: ["--direct"],
|
|
385
|
+
maxPositionals: 1,
|
|
386
|
+
excess: (tok) => `revoke: unexpected extra argument '${tok}' — one <kid> at a time`
|
|
387
|
+
},
|
|
388
|
+
rotate: {
|
|
389
|
+
valueFlags: ["--out"],
|
|
390
|
+
boolFlags: ["--encrypt"],
|
|
391
|
+
maxPositionals: 1
|
|
392
|
+
},
|
|
393
|
+
register: {
|
|
394
|
+
valueFlags: [
|
|
395
|
+
"--pubkey",
|
|
396
|
+
"--name",
|
|
397
|
+
"--ns",
|
|
398
|
+
"--caps",
|
|
399
|
+
"--url",
|
|
400
|
+
"--project"
|
|
401
|
+
],
|
|
402
|
+
boolFlags: [
|
|
403
|
+
"--allow-admin",
|
|
404
|
+
"--allow-unknown-ns",
|
|
405
|
+
"--direct",
|
|
406
|
+
"--no-directory",
|
|
407
|
+
"--no-broadcast"
|
|
408
|
+
],
|
|
409
|
+
maxPositionals: 1
|
|
410
|
+
},
|
|
411
|
+
update: {
|
|
412
|
+
valueFlags: [
|
|
413
|
+
"--name",
|
|
414
|
+
"--ns",
|
|
415
|
+
"--caps",
|
|
416
|
+
"--url"
|
|
417
|
+
],
|
|
418
|
+
boolFlags: [
|
|
419
|
+
"--direct",
|
|
420
|
+
"--allow-unknown-ns",
|
|
421
|
+
"--widen",
|
|
422
|
+
"--allow-admin"
|
|
423
|
+
],
|
|
424
|
+
maxPositionals: 1
|
|
425
|
+
},
|
|
426
|
+
"migrate-store": {
|
|
427
|
+
valueFlags: [
|
|
428
|
+
"--from-env",
|
|
429
|
+
"--to-env",
|
|
430
|
+
"--from-schema",
|
|
431
|
+
"--to-schema",
|
|
432
|
+
"--batch-rows",
|
|
433
|
+
"--skip-table"
|
|
434
|
+
],
|
|
435
|
+
boolFlags: [
|
|
436
|
+
"--dry-run",
|
|
437
|
+
"--verify-only",
|
|
438
|
+
"--json",
|
|
439
|
+
"--skip-index-build",
|
|
440
|
+
"--full-checksum"
|
|
441
|
+
],
|
|
442
|
+
maxPositionals: 0,
|
|
443
|
+
hint: " (connection strings never go on argv: name their environment variables with --from-env / --to-env)",
|
|
444
|
+
excess: (tok) => `migrate-store: unexpected argument '${tok}' (connection strings never go on argv: name their environment variables with --from-env / --to-env)`,
|
|
445
|
+
exitCode: 2
|
|
446
|
+
}
|
|
447
|
+
};
|
|
448
|
+
/** A command with no descriptor accepts nothing at all. */
|
|
449
|
+
const FAIL_CLOSED = {
|
|
450
|
+
valueFlags: [],
|
|
451
|
+
boolFlags: [],
|
|
452
|
+
maxPositionals: 0
|
|
453
|
+
};
|
|
454
|
+
/**
|
|
455
|
+
* Refuse unknown flags and surplus positionals for `cmd`, given its tail
|
|
456
|
+
* (argv WITHOUT the subcommand name).
|
|
457
|
+
*
|
|
458
|
+
* Pure and idempotent, which is why it is safe to call from both `main` —
|
|
459
|
+
* once, before dispatch — and from each `parse*Args`. The parsers are exported
|
|
460
|
+
* from `bin/substrate-admin.ts` and called directly, so they cannot delegate their
|
|
461
|
+
* guarantee to a caller they do not have.
|
|
462
|
+
*/
|
|
463
|
+
function validateArgv(cmd, tail) {
|
|
464
|
+
const spec = ARGV_SPEC[cmd] ?? FAIL_CLOSED;
|
|
465
|
+
let positionals = 0;
|
|
466
|
+
for (let i = 0; i < tail.length; i++) {
|
|
467
|
+
const tok = tail[i];
|
|
468
|
+
if (tok === void 0) continue;
|
|
469
|
+
if (tok.startsWith("--")) {
|
|
470
|
+
if (spec.valueFlags.includes(tok)) {
|
|
471
|
+
const next = tail[i + 1];
|
|
472
|
+
const nextIsKnownFlag = next !== void 0 && (spec.valueFlags.includes(next) || spec.boolFlags.includes(next));
|
|
473
|
+
if (next !== void 0 && !nextIsKnownFlag) i += 1;
|
|
474
|
+
continue;
|
|
475
|
+
}
|
|
476
|
+
if (spec.boolFlags.includes(tok)) continue;
|
|
477
|
+
if (spec.equalsForm === true && spec.valueFlags.some((f) => tok.startsWith(`${f}=`))) continue;
|
|
478
|
+
throw argvError(cmd, `${cmd}: unknown flag ${tok}${spec.hint ?? ""}`, spec.exitCode ?? 1);
|
|
479
|
+
}
|
|
480
|
+
positionals += 1;
|
|
481
|
+
if (positionals > spec.maxPositionals) throw argvError(cmd, spec.excess?.(tok) ?? `${cmd}: unexpected positional arg '${tok}'`, spec.exitCode ?? 1);
|
|
482
|
+
}
|
|
483
|
+
}
|
|
484
|
+
|
|
485
|
+
//#endregion
|
|
486
|
+
//#region src/admin/identity.ts
|
|
487
|
+
/**
|
|
488
|
+
* WHICH store a credential write lands in, and WHICH identity signs it —
|
|
489
|
+
* each resolved explicitly and reported with where the choice came from.
|
|
490
|
+
*/
|
|
491
|
+
/**
|
|
492
|
+
* Resolve the target for `update` / `revoke` / `register`.
|
|
493
|
+
*
|
|
494
|
+
* `explicitUrl` is the parser's tri-state: a base URL from `--url`, the empty
|
|
495
|
+
* string from `--direct`, and `null` for "said nothing".
|
|
496
|
+
*
|
|
497
|
+
* When both `SUBSTRATE_URL` and `SUBSTRATE_DATABASE_URL` are set ambiently and no flag
|
|
498
|
+
* chooses, this throws naming both escape hatches rather than picking: they
|
|
499
|
+
* name two different stores, and a credential write to the wrong one can
|
|
500
|
+
* succeed.
|
|
501
|
+
*/
|
|
502
|
+
function resolveAdminTarget(explicitUrl, env) {
|
|
503
|
+
if (explicitUrl !== null) return explicitUrl.length > 0 ? {
|
|
504
|
+
kind: "route",
|
|
505
|
+
baseUrl: explicitUrl,
|
|
506
|
+
source: "flag"
|
|
507
|
+
} : {
|
|
508
|
+
kind: "direct",
|
|
509
|
+
source: "flag"
|
|
510
|
+
};
|
|
511
|
+
const ambientUrl = env.SUBSTRATE_URL !== void 0 && env.SUBSTRATE_URL.length > 0 ? env.SUBSTRATE_URL : null;
|
|
512
|
+
const ambientStore = env.SUBSTRATE_DATABASE_URL !== void 0 && env.SUBSTRATE_DATABASE_URL.length > 0 ? env.SUBSTRATE_DATABASE_URL : null;
|
|
513
|
+
if (ambientUrl !== null && ambientStore !== null) throw new AdminCliError(`two targets given and neither was chosen: SUBSTRATE_URL names a running server (${ambientUrl}) and SUBSTRATE_DATABASE_URL names a postgres store. This is a credential write, so it will not guess. Pass \`--url <base>\` to go through the server, or \`--direct\` to write to SUBSTRATE_DATABASE_URL.`, 1);
|
|
514
|
+
return ambientUrl !== null ? {
|
|
515
|
+
kind: "route",
|
|
516
|
+
baseUrl: ambientUrl,
|
|
517
|
+
source: "env"
|
|
518
|
+
} : {
|
|
519
|
+
kind: "direct",
|
|
520
|
+
source: "fallback"
|
|
521
|
+
};
|
|
522
|
+
}
|
|
523
|
+
/**
|
|
524
|
+
* One line, printed BEFORE the write, naming the destination and its
|
|
525
|
+
* provenance, so a misdirected command is self-diagnosing.
|
|
526
|
+
*/
|
|
527
|
+
function describeAdminTarget(command, target) {
|
|
528
|
+
if (target.kind === "route") {
|
|
529
|
+
const from = target.source === "flag" ? "--url" : "SUBSTRATE_URL";
|
|
530
|
+
return `${command}: targeting ${target.baseUrl} (from ${from})`;
|
|
531
|
+
}
|
|
532
|
+
return `${command}: targeting the postgres store DIRECTLY, bypassing the running server (from ${target.source === "flag" ? "--direct" : "SUBSTRATE_DATABASE_URL"})`;
|
|
533
|
+
}
|
|
534
|
+
/**
|
|
535
|
+
* Build the `Authorization` value for an admin route at `baseUrl`, or explain
|
|
536
|
+
* what to set. A minted token names `baseUrl`'s origin as its `aud`; a
|
|
537
|
+
* `baseUrl` that is plain http to a non-loopback host is refused.
|
|
538
|
+
*
|
|
539
|
+
* Fail-loud: a message naming the missing key is more use than the 401 an
|
|
540
|
+
* unauthenticated admin call would get.
|
|
541
|
+
*/
|
|
542
|
+
function resolveAdminAuth(env, baseUrl) {
|
|
543
|
+
let audience;
|
|
544
|
+
try {
|
|
545
|
+
audience = tokenAudience(baseUrl);
|
|
546
|
+
} catch (err) {
|
|
547
|
+
return { error: err instanceof Error ? err.message : String(err) };
|
|
548
|
+
}
|
|
549
|
+
const cred = resolveAdminCredential(env);
|
|
550
|
+
if (cred.kind === "error") return { error: cred.error };
|
|
551
|
+
if (cred.kind === "token") return { ok: cred.authorization };
|
|
552
|
+
const passphrase = env.SUBSTRATE_ADMIN_KEY_PASSPHRASE !== void 0 && env.SUBSTRATE_ADMIN_KEY_PASSPHRASE.length > 0 ? { passphrase: env.SUBSTRATE_ADMIN_KEY_PASSPHRASE } : {};
|
|
553
|
+
try {
|
|
554
|
+
return { ok: makeAuthorizationProvider({
|
|
555
|
+
keyPath: cred.keyPath,
|
|
556
|
+
kid: cred.kid
|
|
557
|
+
}, {
|
|
558
|
+
capabilities: adminClaimCapabilities(env),
|
|
559
|
+
audience,
|
|
560
|
+
...passphrase
|
|
561
|
+
})() };
|
|
562
|
+
} catch (err) {
|
|
563
|
+
return { error: `could not sign with ${cred.keyPath}: ${err instanceof Error ? err.message : err}` };
|
|
564
|
+
}
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
//#endregion
|
|
568
|
+
//#region src/admin/keys.ts
|
|
569
|
+
/**
|
|
570
|
+
* Key row plumbing shared by every subcommand: reading rows, classifying
|
|
571
|
+
* the admin ones, minting keypairs, and the write-attribution hint.
|
|
572
|
+
*
|
|
573
|
+
* `listActiveAdminKeys` classifies through `isActiveAdminKeyRow` rather than
|
|
574
|
+
* reading the flat `capabilities` column: a key stored
|
|
575
|
+
* `namespaces: '*:read+mutate+admin'` carries no `admin` in `capabilities`
|
|
576
|
+
* and is nonetheless an admin.
|
|
577
|
+
*/
|
|
578
|
+
/** Sentinel `actorKid` stamped on every audit row emitted by this CLI. */
|
|
579
|
+
const CLI_ACTOR_KID = "substrate-admin-cli";
|
|
580
|
+
/**
|
|
581
|
+
* Substrate auto-fill hint for every `_system` write this CLI makes. Without
|
|
582
|
+
* it the row metadata (`createdBy` / `updatedBy`) lands NULL.
|
|
583
|
+
*
|
|
584
|
+
* `kind: 'system'` rather than `'agent'`: this is a component acting, not a
|
|
585
|
+
* registered identity signing.
|
|
586
|
+
*/
|
|
587
|
+
const ACTOR_HINT = { identity: {
|
|
588
|
+
kind: "system",
|
|
589
|
+
id: CLI_ACTOR_KID
|
|
590
|
+
} };
|
|
591
|
+
/**
|
|
592
|
+
* Strip `_metadata` from a row read back for update, so the write's
|
|
593
|
+
* {@link ACTOR_HINT} actually takes effect.
|
|
594
|
+
*
|
|
595
|
+
* A dataset auto-fills metadata from `options.identity` only when the
|
|
596
|
+
* incoming row has NO `_metadata`, so a row built as `{ ...existing.row, ... }`
|
|
597
|
+
* would silently keep the previous `updatedBy`.
|
|
598
|
+
*
|
|
599
|
+
* Stripping is safe and does not lose `createdBy`: the dataset merges per-field
|
|
600
|
+
* against the STORED row (`createdBy: existing.createdBy ?? incoming.createdBy`),
|
|
601
|
+
* so `created*` survive from storage while `updated*` come from the hint.
|
|
602
|
+
*/
|
|
603
|
+
function forUpdate(row) {
|
|
604
|
+
const { _metadata: _dropped, ...rest } = row;
|
|
605
|
+
return rest;
|
|
606
|
+
}
|
|
607
|
+
/**
|
|
608
|
+
* Mint an ed25519 keypair for `bootstrap` / `rotate`. When `wantsEncrypt` is
|
|
609
|
+
* true, the private-key PEM is PKCS#8+PBES2 (aes-256-cbc) encrypted with
|
|
610
|
+
* `SUBSTRATE_ADMIN_KEY_PASSPHRASE` — the env var MUST be set to a non-empty value
|
|
611
|
+
* or this helper hard-errors. When false, the PEM is cleartext PKCS#8.
|
|
612
|
+
*
|
|
613
|
+
* At-rest encryption is purely operator-side: the server only ever reads the
|
|
614
|
+
* public key from pg, so the encrypted-ness of the on-disk private key has no
|
|
615
|
+
* server-side coupling.
|
|
616
|
+
*/
|
|
617
|
+
function generateAdminKeypair(env, wantsEncrypt) {
|
|
618
|
+
if (wantsEncrypt) {
|
|
619
|
+
const passphrase = env.SUBSTRATE_ADMIN_KEY_PASSPHRASE;
|
|
620
|
+
if (passphrase === void 0 || passphrase.length === 0) throw new AdminCliError("--encrypt requires SUBSTRATE_ADMIN_KEY_PASSPHRASE to be set to a non-empty value", 6);
|
|
621
|
+
const { privateKey, publicKey } = generateKeyPairSync("ed25519", {
|
|
622
|
+
publicKeyEncoding: {
|
|
623
|
+
format: "pem",
|
|
624
|
+
type: "spki"
|
|
625
|
+
},
|
|
626
|
+
privateKeyEncoding: {
|
|
627
|
+
format: "pem",
|
|
628
|
+
type: "pkcs8",
|
|
629
|
+
cipher: "aes-256-cbc",
|
|
630
|
+
passphrase
|
|
631
|
+
}
|
|
632
|
+
});
|
|
633
|
+
return {
|
|
634
|
+
publicKeyPem: publicKey.toString(),
|
|
635
|
+
privateKeyPem: privateKey.toString(),
|
|
636
|
+
encrypted: true
|
|
637
|
+
};
|
|
638
|
+
}
|
|
639
|
+
const { privateKey, publicKey } = generateKeyPairSync("ed25519", {
|
|
640
|
+
publicKeyEncoding: {
|
|
641
|
+
format: "pem",
|
|
642
|
+
type: "spki"
|
|
643
|
+
},
|
|
644
|
+
privateKeyEncoding: {
|
|
645
|
+
format: "pem",
|
|
646
|
+
type: "pkcs8"
|
|
647
|
+
}
|
|
648
|
+
});
|
|
649
|
+
return {
|
|
650
|
+
publicKeyPem: publicKey.toString(),
|
|
651
|
+
privateKeyPem: privateKey.toString(),
|
|
652
|
+
encrypted: false
|
|
653
|
+
};
|
|
654
|
+
}
|
|
655
|
+
var BootstrapError = class extends Error {
|
|
656
|
+
name = "BootstrapError";
|
|
657
|
+
exitCode;
|
|
658
|
+
constructor(message, exitCode = 1) {
|
|
659
|
+
super(message);
|
|
660
|
+
this.exitCode = exitCode;
|
|
661
|
+
}
|
|
662
|
+
};
|
|
663
|
+
function base64Url(buf) {
|
|
664
|
+
return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
|
|
665
|
+
}
|
|
666
|
+
function rowAsAdminKey(row) {
|
|
667
|
+
const kid = row.kid;
|
|
668
|
+
if (typeof kid !== "string" || kid.length === 0) return null;
|
|
669
|
+
return {
|
|
670
|
+
kid,
|
|
671
|
+
name: typeof row.name === "string" ? row.name : "",
|
|
672
|
+
namespaces: typeof row.namespaces === "string" ? row.namespaces : "",
|
|
673
|
+
capabilities: typeof row.capabilities === "string" ? row.capabilities : "",
|
|
674
|
+
createdAt: row._metadata?.createdAt ?? null
|
|
675
|
+
};
|
|
676
|
+
}
|
|
677
|
+
/**
|
|
678
|
+
* Read every non-revoked Key row whose grant confers `adminCapability`
|
|
679
|
+
* on `_system` (per `isActiveAdminKeyRow`). Scans the whole table, which is
|
|
680
|
+
* fine at CLI cadence.
|
|
681
|
+
*/
|
|
682
|
+
async function listActiveAdminKeys(dataset, adminCapability) {
|
|
683
|
+
const { rows } = await dataset.read("Key", {});
|
|
684
|
+
const out = [];
|
|
685
|
+
for (const row of rows) {
|
|
686
|
+
if (!isActiveAdminKeyRow(row, adminCapability)) continue;
|
|
687
|
+
const ak = rowAsAdminKey(row);
|
|
688
|
+
if (ak === null) continue;
|
|
689
|
+
out.push(ak);
|
|
690
|
+
}
|
|
691
|
+
return out;
|
|
692
|
+
}
|
|
693
|
+
/**
|
|
694
|
+
* `bootstrap`-specific helper: first matching admin row or `null`. Wraps
|
|
695
|
+
* `listActiveAdminKeys` so the bootstrap contract ("refuse if ANY admin row
|
|
696
|
+
* exists") doesn't leak the array shape out of this module.
|
|
697
|
+
*/
|
|
698
|
+
async function firstAdminKey(dataset, adminCapability) {
|
|
699
|
+
return (await listActiveAdminKeys(dataset, adminCapability))[0] ?? null;
|
|
700
|
+
}
|
|
701
|
+
/** The capability name that means "admin" when `SUBSTRATE_ADMIN_CAPABILITY` is unset. */
|
|
702
|
+
const DEFAULT_ADMIN_CAPABILITY = "admin";
|
|
703
|
+
async function readKeyById(dataset, kid) {
|
|
704
|
+
const { rows } = await dataset.read("Key", { where: { kid: { eq: kid } } });
|
|
705
|
+
const row = rows.find((r) => r.revokedAt == null) ?? rows[0];
|
|
706
|
+
if (row === void 0) return null;
|
|
707
|
+
return {
|
|
708
|
+
row,
|
|
709
|
+
revokedAt: row.revokedAt instanceof Date ? row.revokedAt : typeof row.revokedAt === "string" ? row.revokedAt : null
|
|
710
|
+
};
|
|
711
|
+
}
|
|
712
|
+
/**
|
|
713
|
+
* Read a public-key PEM from disk and assert it is Ed25519. Returns the PEM
|
|
714
|
+
* text verbatim for storage on the Key row. Throws AdminCliError(2) on a
|
|
715
|
+
* missing/unreadable file, a private-key PEM (missing `BEGIN PUBLIC KEY`
|
|
716
|
+
* header — prevents accidental private-key leakage when the operator passes
|
|
717
|
+
* the wrong file to `--pubkey`), an unparseable PEM, or a non-ed25519 key.
|
|
718
|
+
* `register` only mints/accepts Ed25519 agent identities (the one alg the
|
|
719
|
+
* verifier + signer support).
|
|
720
|
+
*/
|
|
721
|
+
function readEd25519PublicKey(path) {
|
|
722
|
+
let pem;
|
|
723
|
+
try {
|
|
724
|
+
pem = readFileSync(path, "utf8");
|
|
725
|
+
} catch (err) {
|
|
726
|
+
const msg = err instanceof Error ? err.message : String(err);
|
|
727
|
+
throw new AdminCliError(`register: cannot read --pubkey '${path}': ${msg}`, 2);
|
|
728
|
+
}
|
|
729
|
+
if (!pem.includes("BEGIN PUBLIC KEY")) throw new AdminCliError(`register: --pubkey '${path}' is not a public-key PEM (missing 'BEGIN PUBLIC KEY' header) — did you pass the private key by mistake?`, 2);
|
|
730
|
+
let keyType;
|
|
731
|
+
try {
|
|
732
|
+
keyType = createPublicKey(pem).asymmetricKeyType;
|
|
733
|
+
} catch (err) {
|
|
734
|
+
const msg = err instanceof Error ? err.message : String(err);
|
|
735
|
+
throw new AdminCliError(`register: --pubkey '${path}' is not a valid public key: ${msg}`, 2);
|
|
736
|
+
}
|
|
737
|
+
if (keyType !== "ed25519") throw new AdminCliError(`register: --pubkey '${path}' is ${keyType ?? "unknown"}, expected ed25519`, 2);
|
|
738
|
+
return pem;
|
|
739
|
+
}
|
|
740
|
+
|
|
741
|
+
//#endregion
|
|
742
|
+
//#region src/admin/route.ts
|
|
743
|
+
/**
|
|
744
|
+
* Drive `PATCH /substrate/v1/_system/keys`. A write through the engine reaches the
|
|
745
|
+
* running server's key registry; a direct write does not.
|
|
746
|
+
*
|
|
747
|
+
* Refusals come back with the same `code` the CLI's own guards produce,
|
|
748
|
+
* because both sides ask `key-guards`. Statuses are mapped back to the
|
|
749
|
+
* same exit codes so scripts do not care which transport ran.
|
|
750
|
+
*/
|
|
751
|
+
async function runKeyPatchViaRoute(body, baseUrl, env, exitCodes, fetchImpl = fetch) {
|
|
752
|
+
const auth = resolveAdminAuth(env, baseUrl);
|
|
753
|
+
if ("error" in auth) throw new AdminCliError(`${body.revoke === true ? "revoke" : "update"}: ${auth.error}`, 1);
|
|
754
|
+
const url = `${trimTrailingSlashes(baseUrl)}/substrate/v1/_system/keys`;
|
|
755
|
+
let res;
|
|
756
|
+
try {
|
|
757
|
+
res = await fetchImpl(url, {
|
|
758
|
+
method: "PATCH",
|
|
759
|
+
headers: {
|
|
760
|
+
"content-type": "application/json",
|
|
761
|
+
authorization: auth.ok
|
|
762
|
+
},
|
|
763
|
+
body: JSON.stringify(body),
|
|
764
|
+
redirect: "error"
|
|
765
|
+
});
|
|
766
|
+
} catch (err) {
|
|
767
|
+
throw new AdminCliError(`could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`, 1);
|
|
768
|
+
}
|
|
769
|
+
const payload = await res.json().catch(() => ({}));
|
|
770
|
+
if (!res.ok) {
|
|
771
|
+
const code = typeof payload.code === "string" ? payload.code : "request_failed";
|
|
772
|
+
const message = failureText(payload, res.status);
|
|
773
|
+
throw new AdminCliError(message, exitCodes[code] ?? 1);
|
|
774
|
+
}
|
|
775
|
+
return payload;
|
|
776
|
+
}
|
|
777
|
+
/**
|
|
778
|
+
* `revoke` refusal code -> CLI exit code. The route maps the same reasons to
|
|
779
|
+
* HTTP statuses. Values are stable: scripts key on them.
|
|
780
|
+
*/
|
|
781
|
+
const REVOKE_EXIT_CODES = {
|
|
782
|
+
unknown_kid: 2,
|
|
783
|
+
already_revoked: 3,
|
|
784
|
+
last_active_admin: 4
|
|
785
|
+
};
|
|
786
|
+
/**
|
|
787
|
+
* `update` refusal code -> CLI exit code. Values are stable: scripts key on
|
|
788
|
+
* them. Guards, in the order they fire:
|
|
789
|
+
* - unknown kid → exit 2; revoked kid → exit 3 (updating a revoked key would
|
|
790
|
+
* be a quiet way to resurrect a retired identity)
|
|
791
|
+
* - dropping admin from the last active admin → exit 4, mirroring `revoke`'s
|
|
792
|
+
* lockout guard. Fires BEFORE the widen gate: it cannot be lifted by a flag,
|
|
793
|
+
* and one request can trip both.
|
|
794
|
+
* - a change that GRANTS authority the key lacks → exit 5 unless `--widen`
|
|
795
|
+
* - granting `admin` → additionally requires `--allow-admin`, mirroring
|
|
796
|
+
* `register`
|
|
797
|
+
*/
|
|
798
|
+
const UPDATE_EXIT_CODES = {
|
|
799
|
+
unknown_kid: 2,
|
|
800
|
+
already_revoked: 3,
|
|
801
|
+
last_active_admin: 4,
|
|
802
|
+
last_admin_deadmin: 4,
|
|
803
|
+
requires_widen: 5,
|
|
804
|
+
requires_allow_admin: 1,
|
|
805
|
+
invalid_grant: 1
|
|
806
|
+
};
|
|
807
|
+
/**
|
|
808
|
+
* Drive `GET /substrate/v1/_system/keys` — the authenticated read behind
|
|
809
|
+
* `list --url`, gated by the server's admin check.
|
|
810
|
+
*
|
|
811
|
+
* Pages to exhaustion rather than returning the first page: a silently
|
|
812
|
+
* truncated answer to "which identities exist" is worse than an error.
|
|
813
|
+
*/
|
|
814
|
+
async function runKeyListViaRoute(baseUrl, env, fetchImpl = fetch) {
|
|
815
|
+
const auth = resolveAdminAuth(env, baseUrl);
|
|
816
|
+
if ("error" in auth) throw new AdminCliError(`list: ${auth.error}`, 1);
|
|
817
|
+
const base = `${trimTrailingSlashes(baseUrl)}/substrate/v1/_system/keys`;
|
|
818
|
+
const keys = [];
|
|
819
|
+
let cursor;
|
|
820
|
+
for (let page = 0; page < 50; page += 1) {
|
|
821
|
+
const url = cursor === void 0 ? base : `${base}?cursor=${encodeURIComponent(cursor)}`;
|
|
822
|
+
let res;
|
|
823
|
+
try {
|
|
824
|
+
res = await fetchImpl(url, {
|
|
825
|
+
method: "GET",
|
|
826
|
+
headers: { authorization: auth.ok },
|
|
827
|
+
redirect: "error"
|
|
828
|
+
});
|
|
829
|
+
} catch (err) {
|
|
830
|
+
throw new AdminCliError(`could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`, 1);
|
|
831
|
+
}
|
|
832
|
+
const payload = await res.json().catch(() => ({}));
|
|
833
|
+
if (!res.ok) {
|
|
834
|
+
const message = failureText(payload, res.status);
|
|
835
|
+
throw new AdminCliError(res.status === 403 ? `list --url: refused by ${baseUrl} — ${message}\n This is the server's verdict on the credential you presented, which is exactly what \`list\` without --url cannot tell you.` : `list --url: ${message}`, res.status === 403 ? 5 : 1);
|
|
836
|
+
}
|
|
837
|
+
const batch = payload.keys;
|
|
838
|
+
if (!Array.isArray(batch)) throw new AdminCliError("list --url: response carried no `keys` array", 1);
|
|
839
|
+
keys.push(...batch);
|
|
840
|
+
if (payload.hasMore !== true) return keys;
|
|
841
|
+
cursor = typeof payload.nextCursor === "string" ? payload.nextCursor : void 0;
|
|
842
|
+
if (cursor === void 0) throw new AdminCliError("list --url: server reported hasMore with no nextCursor — refusing to report a partial list as complete", 1);
|
|
843
|
+
}
|
|
844
|
+
throw new AdminCliError("list --url: pagination did not terminate after 50 pages", 1);
|
|
845
|
+
}
|
|
846
|
+
/** A refusal body as one line: its `message`, else `code (reason): detail`, else the status. */
|
|
847
|
+
function failureText(payload, status) {
|
|
848
|
+
if (typeof payload.message === "string") return payload.message;
|
|
849
|
+
if (typeof payload.code !== "string") return `HTTP ${status}`;
|
|
850
|
+
const reason = typeof payload.reason === "string" ? ` (${payload.reason})` : "";
|
|
851
|
+
const detail = typeof payload.detail === "string" ? `: ${payload.detail}` : "";
|
|
852
|
+
return `${payload.code}${reason}${detail}`;
|
|
853
|
+
}
|
|
854
|
+
|
|
855
|
+
//#endregion
|
|
856
|
+
//#region src/admin/env.ts
|
|
857
|
+
/**
|
|
858
|
+
* Where the admin CLI's key files live, and the env it reads them from.
|
|
859
|
+
*
|
|
860
|
+
* These resolvers live together because they answer one question — *which
|
|
861
|
+
* file is this deployment's admin identity?* — and `bootstrap` (the writer)
|
|
862
|
+
* and `resolveAdminAuth` (the reader) must agree on it.
|
|
863
|
+
*/
|
|
864
|
+
/**
|
|
865
|
+
* Where `bootstrap` writes the kid. Beside the key when one was named
|
|
866
|
+
* explicitly, else the default path.
|
|
867
|
+
*/
|
|
868
|
+
function bootstrapKidPath(env) {
|
|
869
|
+
return env.SUBSTRATE_ADMIN_KEY_PATH !== void 0 && env.SUBSTRATE_ADMIN_KEY_PATH.length > 0 ? `${resolveDefaultKeyPath(env).replace(/\.key$/, "")}.kid` : resolveDefaultKidPath(env);
|
|
870
|
+
}
|
|
871
|
+
|
|
872
|
+
//#endregion
|
|
873
|
+
//#region src/admin/commands/bootstrap.ts
|
|
874
|
+
/**
|
|
875
|
+
* `bootstrap` — seed the genesis admin Key on a fresh `_system` namespace.
|
|
876
|
+
*
|
|
877
|
+
* The one subcommand that CANNOT go through the route: it exists to create the
|
|
878
|
+
* first admin identity, so there is none to present. Direct-to-postgres is not
|
|
879
|
+
* a legacy path here, it is the only possible one.
|
|
880
|
+
*/
|
|
881
|
+
/**
|
|
882
|
+
* What the genesis row grants: the admin capability plus `read` / `mutate`.
|
|
883
|
+
*
|
|
884
|
+
* `resolveAdminAuth` mints with `adminClaimCapabilities`, a superset of this
|
|
885
|
+
* row for any `adminCapability`, and `auth.ts` intersects that claim against
|
|
886
|
+
* the row, so the row is the ceiling. Derived from the same constant so the
|
|
887
|
+
* two cannot drift; `admin` alone does not satisfy the per-frame `read` /
|
|
888
|
+
* `mutate` gates.
|
|
889
|
+
*/
|
|
890
|
+
function seedCapabilities(adminCapability) {
|
|
891
|
+
return [...ADMIN_CAPABILITIES.filter((c) => c !== DEFAULT_ADMIN_CAPABILITY), adminCapability];
|
|
892
|
+
}
|
|
893
|
+
/**
|
|
894
|
+
* Perform the bootstrap.
|
|
895
|
+
*
|
|
896
|
+
* `wantsEncrypt` controls whether the on-disk private-key PEM is
|
|
897
|
+
* PBES2-encrypted with `SUBSTRATE_ADMIN_KEY_PASSPHRASE`. Defaults to false.
|
|
898
|
+
*/
|
|
899
|
+
async function runBootstrap(env, wantsEncrypt = false, openSql = postgres) {
|
|
900
|
+
const storeSpec = env.SUBSTRATE_DATABASE_URL;
|
|
901
|
+
if (storeSpec === void 0 || storeSpec.length === 0) throw new BootstrapError("SUBSTRATE_DATABASE_URL is required (must be a postgres:// URL)");
|
|
902
|
+
if (!storeSpec.startsWith("postgres://") && !storeSpec.startsWith("postgresql://")) throw new BootstrapError(`SUBSTRATE_DATABASE_URL must be a postgres:// URL for bootstrap (got '${redactStore(storeSpec)}'). Memory-backed stores cannot persist the admin key across restarts.`);
|
|
903
|
+
const adminCapability = env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 && env.SUBSTRATE_ADMIN_CAPABILITY.length > 0 ? env.SUBSTRATE_ADMIN_CAPABILITY : DEFAULT_ADMIN_CAPABILITY;
|
|
904
|
+
const seededCapabilities = seedCapabilities(adminCapability);
|
|
905
|
+
const privateKeyPath = resolveDefaultKeyPath(env);
|
|
906
|
+
if (existsSync(privateKeyPath)) throw new BootstrapError(`private key path '${privateKeyPath}' already exists — move it aside and retry`);
|
|
907
|
+
const kidPath = bootstrapKidPath(env);
|
|
908
|
+
if (existsSync(kidPath)) throw new BootstrapError(`kid path '${kidPath}' already exists — move it aside and retry`);
|
|
909
|
+
const { publicKeyPem, privateKeyPem, encrypted } = generateAdminKeypair(env, wantsEncrypt);
|
|
910
|
+
const sql = openSql(storeSpec);
|
|
911
|
+
let dataset;
|
|
912
|
+
try {
|
|
913
|
+
await runMigrations(sql);
|
|
914
|
+
dataset = new PgDataset({
|
|
915
|
+
namespace: SYSTEM_NAMESPACE,
|
|
916
|
+
sql
|
|
917
|
+
});
|
|
918
|
+
await dataset.ensureTypeStorage("Key");
|
|
919
|
+
return await dataset.withAdvisoryLock("substrate:bootstrap", async () => {
|
|
920
|
+
const existing = await firstAdminKey(dataset, adminCapability);
|
|
921
|
+
if (existing !== null) throw new BootstrapError(`admin Key already bootstrapped (kid: ${existing.kid}). Revoke or purge it via the _system namespace before running bootstrap again.`);
|
|
922
|
+
const kid = randomUUID();
|
|
923
|
+
const shaFull = createHash("sha256").update(publicKeyPem).digest();
|
|
924
|
+
const fingerprint = `sha256:${base64Url(shaFull).slice(0, 8)}`;
|
|
925
|
+
const parentDir = dirname(privateKeyPath);
|
|
926
|
+
mkdirSync(parentDir, {
|
|
927
|
+
recursive: true,
|
|
928
|
+
mode: 448
|
|
929
|
+
});
|
|
930
|
+
writeFileSync(privateKeyPath, privateKeyPem, {
|
|
931
|
+
mode: 384,
|
|
932
|
+
flag: "wx"
|
|
933
|
+
});
|
|
934
|
+
writeFileSync(kidPath, `${kid}\n`, {
|
|
935
|
+
mode: 384,
|
|
936
|
+
flag: "wx"
|
|
937
|
+
});
|
|
938
|
+
const now = /* @__PURE__ */ new Date();
|
|
939
|
+
await dataset.write("Key", [{
|
|
940
|
+
id: kid,
|
|
941
|
+
kid,
|
|
942
|
+
name: "bootstrap-admin",
|
|
943
|
+
algorithm: "EdDSA",
|
|
944
|
+
publicKey: publicKeyPem,
|
|
945
|
+
namespaces: "*",
|
|
946
|
+
capabilities: encodeList(seededCapabilities),
|
|
947
|
+
revokedAt: null
|
|
948
|
+
}], {
|
|
949
|
+
identity: {
|
|
950
|
+
kind: "system",
|
|
951
|
+
id: "bootstrap"
|
|
952
|
+
},
|
|
953
|
+
now
|
|
954
|
+
});
|
|
955
|
+
return {
|
|
956
|
+
kid,
|
|
957
|
+
fingerprint,
|
|
958
|
+
privateKeyPath,
|
|
959
|
+
namespaces: "*",
|
|
960
|
+
capabilities: seededCapabilities.join(","),
|
|
961
|
+
encrypted
|
|
962
|
+
};
|
|
963
|
+
});
|
|
964
|
+
} finally {
|
|
965
|
+
try {
|
|
966
|
+
await sql.end();
|
|
967
|
+
} catch {}
|
|
968
|
+
}
|
|
969
|
+
}
|
|
970
|
+
function formatBootstrapOutput(result) {
|
|
971
|
+
const encLabel = result.encrypted ? "encrypted: aes-256-cbc+pbes2" : "unencrypted";
|
|
972
|
+
return [
|
|
973
|
+
"substrate-admin bootstrap complete.",
|
|
974
|
+
`kid: ${result.kid}`,
|
|
975
|
+
`fingerprint: ${result.fingerprint}`,
|
|
976
|
+
`private key: ${result.privateKeyPath} (mode 0600, ${encLabel})`,
|
|
977
|
+
`namespaces: ${result.namespaces}`,
|
|
978
|
+
`capabilities: ${result.capabilities}`,
|
|
979
|
+
"",
|
|
980
|
+
`Use the private key to sign JWTs with kid=${result.kid} to authenticate as admin.`,
|
|
981
|
+
"",
|
|
982
|
+
RESTART_NOTE,
|
|
983
|
+
""
|
|
984
|
+
].join("\n");
|
|
985
|
+
}
|
|
986
|
+
function parseBootstrapArgs(argv) {
|
|
987
|
+
try {
|
|
988
|
+
return parseBootstrapArgsInner(argv);
|
|
989
|
+
} catch (err) {
|
|
990
|
+
if (err instanceof AdminCliError) throw argvError("bootstrap", err.message, err.exitCode);
|
|
991
|
+
throw err;
|
|
992
|
+
}
|
|
993
|
+
}
|
|
994
|
+
function parseBootstrapArgsInner(argv) {
|
|
995
|
+
const rest = argv.slice(1);
|
|
996
|
+
validateArgv("bootstrap", rest);
|
|
997
|
+
let wantsEncrypt = false;
|
|
998
|
+
for (const tok of rest) if (tok === "--encrypt") {
|
|
999
|
+
if (wantsEncrypt) throw new AdminCliError("bootstrap: --encrypt specified more than once", 1);
|
|
1000
|
+
wantsEncrypt = true;
|
|
1001
|
+
}
|
|
1002
|
+
return { wantsEncrypt };
|
|
1003
|
+
}
|
|
1004
|
+
|
|
1005
|
+
//#endregion
|
|
1006
|
+
//#region src/admin/commands/doctor.ts
|
|
1007
|
+
/**
|
|
1008
|
+
* `substrate-admin doctor` — diagnoses an admin deployment through checks that
|
|
1009
|
+
* can each answer NO.
|
|
1010
|
+
*
|
|
1011
|
+
* 1. **Route-only.** Every auth claim is checked through the running server;
|
|
1012
|
+
* a direct postgres read never authenticates, so it cannot test auth.
|
|
1013
|
+
* 2. **A SKIP is not an OK.** A check whose precondition failed renders as
|
|
1014
|
+
* `skip` with the reason — never as a pass, and never omitted.
|
|
1015
|
+
* 3. **Shared classifiers.** Admin checks use `isActiveAdminKeyRow` and
|
|
1016
|
+
* `capabilitiesFor`, the same predicates the server's guards use, so the
|
|
1017
|
+
* doctor cannot agree with a copy that has drifted from the guard.
|
|
1018
|
+
*/
|
|
1019
|
+
/** The NO a non-route target gets: doctor and onboard both refuse to measure through postgres. */
|
|
1020
|
+
const DIRECT_TARGET_REFUSAL = {
|
|
1021
|
+
name: "target",
|
|
1022
|
+
status: "no",
|
|
1023
|
+
detail: "resolved to the postgres store, bypassing the running server. Nothing below can be measured from there: a direct read never authenticates, so it answers a different question from the one you asked (this is what made `substrate-admin list` misleading — it printed the admin row while admin auth was broken).",
|
|
1024
|
+
fix: "Pass `--url <base>`, or set SUBSTRATE_URL, so the checks go through the server that is doing the refusing."
|
|
1025
|
+
};
|
|
1026
|
+
/**
|
|
1027
|
+
* Runs every check against `target`, in dependency order. A failure
|
|
1028
|
+
* short-circuits its dependants into explicit skips.
|
|
1029
|
+
*/
|
|
1030
|
+
async function runDoctor(env, target, fetchImpl = fetch) {
|
|
1031
|
+
if (target.kind !== "route") return {
|
|
1032
|
+
checks: [DIRECT_TARGET_REFUSAL, ...DIAGNOSE_CHECKS.map((name) => ({
|
|
1033
|
+
name,
|
|
1034
|
+
status: "skip",
|
|
1035
|
+
detail: "not asked — target answered no"
|
|
1036
|
+
}))],
|
|
1037
|
+
exitCode: 1
|
|
1038
|
+
};
|
|
1039
|
+
const result = await diagnoseTarget(env, target.baseUrl, fetchImpl);
|
|
1040
|
+
return {
|
|
1041
|
+
checks: [{
|
|
1042
|
+
name: "target",
|
|
1043
|
+
status: "ok",
|
|
1044
|
+
detail: describeAdminTarget("doctor", target).replace(/^doctor: /, "")
|
|
1045
|
+
}, ...result.checks],
|
|
1046
|
+
exitCode: result.exitCode
|
|
1047
|
+
};
|
|
1048
|
+
}
|
|
1049
|
+
/** Diagnose `baseUrl` with the admin credential `env` resolves — shared by doctor and onboard. */
|
|
1050
|
+
async function diagnoseTarget(env, baseUrl, fetchImpl = fetch) {
|
|
1051
|
+
const auth = resolveAdminAuth(env, baseUrl);
|
|
1052
|
+
return diagnose({
|
|
1053
|
+
baseUrl,
|
|
1054
|
+
credential: "error" in auth ? { error: auth.error } : {
|
|
1055
|
+
authorization: () => auth.ok,
|
|
1056
|
+
label: describeCredential(env)
|
|
1057
|
+
},
|
|
1058
|
+
...env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 && env.SUBSTRATE_ADMIN_CAPABILITY.length > 0 ? { adminCapability: env.SUBSTRATE_ADMIN_CAPABILITY } : {},
|
|
1059
|
+
fetch: (input, init) => fetchImpl(input, {
|
|
1060
|
+
...init,
|
|
1061
|
+
redirect: "error"
|
|
1062
|
+
})
|
|
1063
|
+
});
|
|
1064
|
+
}
|
|
1065
|
+
/** Which credential the run used, without printing any of it. */
|
|
1066
|
+
function describeCredential(env) {
|
|
1067
|
+
if (env.SUBSTRATE_ADMIN_TOKEN !== void 0 && env.SUBSTRATE_ADMIN_TOKEN.length > 0) return "SUBSTRATE_ADMIN_TOKEN";
|
|
1068
|
+
return `${env.SUBSTRATE_ADMIN_KEY_PATH !== void 0 && env.SUBSTRATE_ADMIN_KEY_PATH.length > 0 ? env.SUBSTRATE_ADMIN_KEY_PATH : "the default admin key path"} (the file path only — no key material is read out here)`;
|
|
1069
|
+
}
|
|
1070
|
+
const GLYPH = {
|
|
1071
|
+
ok: "ok ",
|
|
1072
|
+
no: "NO ",
|
|
1073
|
+
skip: "skip"
|
|
1074
|
+
};
|
|
1075
|
+
/**
|
|
1076
|
+
* Renders the report. The trailer counts skips separately from passes so a
|
|
1077
|
+
* reader cannot sum unasked checks into a verdict.
|
|
1078
|
+
*/
|
|
1079
|
+
function formatDoctorReport(report) {
|
|
1080
|
+
const width = Math.max(...report.checks.map((c) => c.name.length));
|
|
1081
|
+
const lines = ["substrate-admin doctor", ""];
|
|
1082
|
+
for (const check of report.checks) {
|
|
1083
|
+
lines.push(` ${GLYPH[check.status]} ${check.name.padEnd(width)} ${check.detail}`);
|
|
1084
|
+
if (check.fix !== void 0) lines.push(` ${" ".repeat(width)} fix: ${check.fix}`);
|
|
1085
|
+
}
|
|
1086
|
+
const ok = report.checks.filter((c) => c.status === "ok").length;
|
|
1087
|
+
const no = report.checks.filter((c) => c.status === "no").length;
|
|
1088
|
+
const skipped = report.checks.filter((c) => c.status === "skip").length;
|
|
1089
|
+
lines.push("", skipped > 0 ? `${ok} ok, ${no} failed, ${skipped} NOT ASKED (a skipped check is not a passing one).` : `${ok} ok, ${no} failed.`);
|
|
1090
|
+
return `${lines.join("\n")}\n`;
|
|
1091
|
+
}
|
|
1092
|
+
/** Resolve the target and run — the shape `main` dispatches to. */
|
|
1093
|
+
async function doctorCommand(argv, env, fetchImpl = fetch) {
|
|
1094
|
+
validateArgv("doctor", argv);
|
|
1095
|
+
let url;
|
|
1096
|
+
let direct = false;
|
|
1097
|
+
for (let i = 0; i < argv.length; i++) {
|
|
1098
|
+
const tok = argv[i];
|
|
1099
|
+
if (tok === void 0) continue;
|
|
1100
|
+
if (tok === "--url") {
|
|
1101
|
+
if (url !== void 0) throw argvError("doctor", "doctor: --url specified more than once", 1);
|
|
1102
|
+
url = argv[i + 1] ?? "";
|
|
1103
|
+
i += 1;
|
|
1104
|
+
continue;
|
|
1105
|
+
}
|
|
1106
|
+
if (tok === "--direct") direct = true;
|
|
1107
|
+
}
|
|
1108
|
+
return runDoctor(env, resolveAdminTarget(direct ? "" : url ?? null, env), fetchImpl);
|
|
1109
|
+
}
|
|
1110
|
+
|
|
1111
|
+
//#endregion
|
|
1112
|
+
//#region src/admin/commands/onboard-keys.ts
|
|
1113
|
+
/**
|
|
1114
|
+
* Key-file helpers for onboarding: generating a keypair for the register steps, and
|
|
1115
|
+
* knowing in advance when `bootstrap` would refuse. Both refuse to overwrite, like
|
|
1116
|
+
* `bootstrap`: clobbering key material destroys an identity silently.
|
|
1117
|
+
*/
|
|
1118
|
+
/** `~` and `~/…` against HOME; a shell would have done this, a prompt does not. */
|
|
1119
|
+
function expandHome(env, path) {
|
|
1120
|
+
if (path !== "~" && !path.startsWith("~/")) return path;
|
|
1121
|
+
return join(env.HOME ?? homedir(), path.slice(1));
|
|
1122
|
+
}
|
|
1123
|
+
/**
|
|
1124
|
+
* Writes `<path>` (0600) and `<path>.pub`, plus `<path minus .key>.kid` when a kid is
|
|
1125
|
+
* given — the file the credential resolver reads beside a named key. Creates missing
|
|
1126
|
+
* parent directories 0700. On a failed write, removes whatever this call already wrote.
|
|
1127
|
+
*/
|
|
1128
|
+
function writeKeypair(env, path, kid) {
|
|
1129
|
+
const privateKeyPath = expandHome(env, path);
|
|
1130
|
+
const publicKeyPath = `${privateKeyPath}.pub`;
|
|
1131
|
+
const kidPath = kid === void 0 ? void 0 : `${privateKeyPath.replace(/\.key$/, "")}.kid`;
|
|
1132
|
+
const targets = [
|
|
1133
|
+
privateKeyPath,
|
|
1134
|
+
publicKeyPath,
|
|
1135
|
+
...kidPath === void 0 ? [] : [kidPath]
|
|
1136
|
+
];
|
|
1137
|
+
for (const p of targets) if (existsSync(p)) throw new AdminCliError(`'${p}' already exists — choose another path`, 1);
|
|
1138
|
+
const { publicKeyPem, privateKeyPem } = generateAdminKeypair(env, false);
|
|
1139
|
+
mkdirSync(dirname(privateKeyPath), {
|
|
1140
|
+
recursive: true,
|
|
1141
|
+
mode: 448
|
|
1142
|
+
});
|
|
1143
|
+
const written = [];
|
|
1144
|
+
try {
|
|
1145
|
+
writeFileSync(privateKeyPath, privateKeyPem, {
|
|
1146
|
+
mode: 384,
|
|
1147
|
+
flag: "wx"
|
|
1148
|
+
});
|
|
1149
|
+
written.push(privateKeyPath);
|
|
1150
|
+
writeFileSync(publicKeyPath, publicKeyPem, {
|
|
1151
|
+
mode: 420,
|
|
1152
|
+
flag: "wx"
|
|
1153
|
+
});
|
|
1154
|
+
written.push(publicKeyPath);
|
|
1155
|
+
if (kidPath !== void 0 && kid !== void 0) writeFileSync(kidPath, `${kid}\n`, {
|
|
1156
|
+
mode: 384,
|
|
1157
|
+
flag: "wx"
|
|
1158
|
+
});
|
|
1159
|
+
} catch (err) {
|
|
1160
|
+
for (const p of written) rmSync(p, { force: true });
|
|
1161
|
+
throw err;
|
|
1162
|
+
}
|
|
1163
|
+
return {
|
|
1164
|
+
privateKeyPath,
|
|
1165
|
+
publicKeyPath,
|
|
1166
|
+
...kidPath === void 0 ? {} : { kidPath }
|
|
1167
|
+
};
|
|
1168
|
+
}
|
|
1169
|
+
/**
|
|
1170
|
+
* The files whose presence makes `bootstrap` refuse — its own guards, checked without
|
|
1171
|
+
* opening postgres, so onboard offers bootstrap only when it can succeed.
|
|
1172
|
+
*/
|
|
1173
|
+
function bootstrapBlockers(env) {
|
|
1174
|
+
return [resolveDefaultKeyPath(env), bootstrapKidPath(env)].filter((p) => existsSync(p));
|
|
1175
|
+
}
|
|
1176
|
+
|
|
1177
|
+
//#endregion
|
|
1178
|
+
//#region src/admin/grant-display.ts
|
|
1179
|
+
/**
|
|
1180
|
+
* Rendering a stored grant as the AUTHORITY it confers, rather than as the two
|
|
1181
|
+
* columns it happens to be stored in.
|
|
1182
|
+
*
|
|
1183
|
+
* The two columns only mean anything jointly: `capabilities` is the default
|
|
1184
|
+
* for BARE `--ns` entries only, so `--ns 'notes:read'` with default
|
|
1185
|
+
* capabilities `read,mutate` is a read-only grant, not a write grant.
|
|
1186
|
+
*/
|
|
1187
|
+
/**
|
|
1188
|
+
* `describeGrant` laid out under a label, continuation lines aligned.
|
|
1189
|
+
*
|
|
1190
|
+
* The label is passed in rather than fixed so `register` and `update` can align
|
|
1191
|
+
* the grant block with their own existing columns.
|
|
1192
|
+
*/
|
|
1193
|
+
function grantLines(label, namespaces, capabilities) {
|
|
1194
|
+
const entries = describeGrant(namespaces, capabilities);
|
|
1195
|
+
const pad = " ".repeat(label.length);
|
|
1196
|
+
return entries.map((e, i) => `${i === 0 ? label : pad}${e}`);
|
|
1197
|
+
}
|
|
1198
|
+
|
|
1199
|
+
//#endregion
|
|
1200
|
+
//#region src/admin/commands/register.ts
|
|
1201
|
+
/**
|
|
1202
|
+
* `register` — add an existing ed25519 public key as an agent Key.
|
|
1203
|
+
*
|
|
1204
|
+
* `--ns` is REQUIRED and has no default, because a default here is an unbounded
|
|
1205
|
+
* grant nobody chose. The route path also writes the directory row in the same
|
|
1206
|
+
* transaction: a credential with no directory row keeps authenticating while
|
|
1207
|
+
* mail routing and agent listing quietly break.
|
|
1208
|
+
*/
|
|
1209
|
+
/**
|
|
1210
|
+
* Parse `register <kid> --pubkey <path> --ns <csv> [--name <n>] [--caps <csv>]
|
|
1211
|
+
* [--allow-admin]`. Positional <kid> exactly once, single-valued flags.
|
|
1212
|
+
* Defaults (kid as name, caps read,mutate) are resolved here; `--ns` has no
|
|
1213
|
+
* default and its absence throws `AdminCliError`.
|
|
1214
|
+
*/
|
|
1215
|
+
function parseRegisterArgs(argv) {
|
|
1216
|
+
try {
|
|
1217
|
+
return parseRegisterArgsInner(argv);
|
|
1218
|
+
} catch (err) {
|
|
1219
|
+
if (err instanceof AdminCliError) throw argvError("register", err.message, err.exitCode);
|
|
1220
|
+
throw err;
|
|
1221
|
+
}
|
|
1222
|
+
}
|
|
1223
|
+
function parseRegisterArgsInner(argv) {
|
|
1224
|
+
const rest = argv.slice(1);
|
|
1225
|
+
validateArgv("register", rest);
|
|
1226
|
+
let kid;
|
|
1227
|
+
let pubkeyPath;
|
|
1228
|
+
let name;
|
|
1229
|
+
let nsCsv;
|
|
1230
|
+
let capsCsv;
|
|
1231
|
+
let allowAdmin = false;
|
|
1232
|
+
let allowUnknownNs = false;
|
|
1233
|
+
let url;
|
|
1234
|
+
let direct = false;
|
|
1235
|
+
let noDirectory = false;
|
|
1236
|
+
let noBroadcast = false;
|
|
1237
|
+
let project;
|
|
1238
|
+
const takeValue = (flag, i) => {
|
|
1239
|
+
const val = rest[i + 1];
|
|
1240
|
+
if (val === void 0 || val.length === 0 || val.startsWith("--")) throw new AdminCliError(`register: ${flag} requires a value`, 1);
|
|
1241
|
+
return val;
|
|
1242
|
+
};
|
|
1243
|
+
for (let i = 0; i < rest.length; i++) {
|
|
1244
|
+
const tok = rest[i];
|
|
1245
|
+
if (tok === void 0) continue;
|
|
1246
|
+
if (tok === "--pubkey") {
|
|
1247
|
+
if (pubkeyPath !== void 0) throw new AdminCliError("register: --pubkey specified more than once", 1);
|
|
1248
|
+
pubkeyPath = takeValue("--pubkey", i);
|
|
1249
|
+
i += 1;
|
|
1250
|
+
} else if (tok === "--name") {
|
|
1251
|
+
if (name !== void 0) throw new AdminCliError("register: --name specified more than once", 1);
|
|
1252
|
+
name = takeValue("--name", i);
|
|
1253
|
+
i += 1;
|
|
1254
|
+
} else if (tok === "--ns") {
|
|
1255
|
+
if (nsCsv !== void 0) throw new AdminCliError("register: --ns specified more than once", 1);
|
|
1256
|
+
nsCsv = takeValue("--ns", i);
|
|
1257
|
+
i += 1;
|
|
1258
|
+
} else if (tok === "--caps") {
|
|
1259
|
+
if (capsCsv !== void 0) throw new AdminCliError("register: --caps specified more than once", 1);
|
|
1260
|
+
capsCsv = takeValue("--caps", i);
|
|
1261
|
+
i += 1;
|
|
1262
|
+
} else if (tok === "--allow-admin") {
|
|
1263
|
+
if (allowAdmin) throw new AdminCliError("register: --allow-admin specified more than once", 1);
|
|
1264
|
+
allowAdmin = true;
|
|
1265
|
+
} else if (tok === "--allow-unknown-ns") allowUnknownNs = true;
|
|
1266
|
+
else if (tok === "--url") {
|
|
1267
|
+
if (direct) throw new AdminCliError("register: --direct and --url are mutually exclusive", 1);
|
|
1268
|
+
if (url !== void 0) throw new AdminCliError("register: --url specified more than once", 1);
|
|
1269
|
+
url = takeValue("--url", i);
|
|
1270
|
+
i += 1;
|
|
1271
|
+
} else if (tok === "--direct") {
|
|
1272
|
+
if (url !== void 0) throw new AdminCliError("register: --direct and --url are mutually exclusive", 1);
|
|
1273
|
+
direct = true;
|
|
1274
|
+
url = "";
|
|
1275
|
+
} else if (tok === "--no-directory") noDirectory = true;
|
|
1276
|
+
else if (tok === "--no-broadcast") noBroadcast = true;
|
|
1277
|
+
else if (tok === "--project") {
|
|
1278
|
+
if (project !== void 0) throw new AdminCliError("register: --project specified more than once", 1);
|
|
1279
|
+
project = takeValue("--project", i);
|
|
1280
|
+
i += 1;
|
|
1281
|
+
} else kid = tok;
|
|
1282
|
+
}
|
|
1283
|
+
if (kid === void 0 || kid.length === 0) throw new AdminCliError("register requires a <kid> positional arg", 1);
|
|
1284
|
+
if (pubkeyPath === void 0 || pubkeyPath.length === 0) throw new AdminCliError("register requires --pubkey <path>", 1);
|
|
1285
|
+
const splitCsv = (csv) => csv.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
|
|
1286
|
+
if (nsCsv === void 0) throw new AdminCliError("register requires --ns <csv> — namespaces are granted explicitly, never by default. Pass the namespaces this identity needs (e.g. --ns notes,recall), or --ns '*' to deliberately grant every namespace.", 1);
|
|
1287
|
+
const namespaces = splitCsv(nsCsv);
|
|
1288
|
+
if (namespaces.length === 0) throw new AdminCliError(`register: --ns '${nsCsv}' resolves to an empty namespace list — an identity that can reach nothing is almost certainly a mistake. Pass real namespaces, or --ns '*'.`, 1);
|
|
1289
|
+
const nsError = grantEntryError(namespaces, ["read", "mutate"]);
|
|
1290
|
+
if (nsError !== null) throw new AdminCliError(`register: ${nsError} — e.g. --ns inventory:read,notes:read+mutate`, 1);
|
|
1291
|
+
const capabilities = capsCsv === void 0 ? ["read", "mutate"] : splitCsv(capsCsv);
|
|
1292
|
+
return {
|
|
1293
|
+
kid,
|
|
1294
|
+
pubkeyPath,
|
|
1295
|
+
name: name ?? kid,
|
|
1296
|
+
namespaces,
|
|
1297
|
+
capabilities,
|
|
1298
|
+
allowAdmin,
|
|
1299
|
+
allowUnknownNs,
|
|
1300
|
+
url: url ?? null,
|
|
1301
|
+
noDirectory,
|
|
1302
|
+
noBroadcast,
|
|
1303
|
+
project: project ?? null
|
|
1304
|
+
};
|
|
1305
|
+
}
|
|
1306
|
+
/**
|
|
1307
|
+
* Register an existing Ed25519 public key as an agent Key row directly
|
|
1308
|
+
* in postgres, with one `key_registered` audit row written in the SAME tx.
|
|
1309
|
+
*
|
|
1310
|
+
* Unlike `bootstrap`/`rotate`, the kid is operator-chosen. The row id is a
|
|
1311
|
+
* freshly-minted UUID; the kid is the principal field stored separately. A
|
|
1312
|
+
* previously-revoked same-kid row is re-registered (same UUID id, clears
|
|
1313
|
+
* revokedAt). A LIVE same-kid row is refused — rotate/revoke is the path.
|
|
1314
|
+
*/
|
|
1315
|
+
async function runRegister(args, env, openDataset = openPgDataset) {
|
|
1316
|
+
if (grantEntriesConfer(args.namespaces, args.capabilities, "admin") && !args.allowAdmin) throw new AdminCliError("register: 'admin' capability requires --allow-admin (bootstrap is the deliberate admin path)", 1);
|
|
1317
|
+
const publicKeyPem = readEd25519PublicKey(args.pubkeyPath);
|
|
1318
|
+
const shaFull = createHash("sha256").update(publicKeyPem).digest();
|
|
1319
|
+
const fingerprint = `sha256:${base64Url(shaFull).slice(0, 8)}`;
|
|
1320
|
+
const namespaces = encodeList(args.namespaces);
|
|
1321
|
+
const capabilities = encodeList(args.capabilities);
|
|
1322
|
+
const { dataset, close } = await openDataset(env);
|
|
1323
|
+
try {
|
|
1324
|
+
const replacedRevoked = await dataset.withTransaction(async (tx) => {
|
|
1325
|
+
const { rows: existingRows } = await tx.read("Key", { where: { kid: { eq: args.kid } } });
|
|
1326
|
+
const existing = existingRows.find((r) => r.revokedAt == null) ?? existingRows[0];
|
|
1327
|
+
let wasRevoked = false;
|
|
1328
|
+
let rowId;
|
|
1329
|
+
if (existing !== void 0) {
|
|
1330
|
+
if ((existing.revokedAt instanceof Date ? existing.revokedAt : typeof existing.revokedAt === "string" ? existing.revokedAt : null) == null) throw new AdminCliError(`kid '${args.kid}' is already registered and live — rotate or revoke it instead`, 3);
|
|
1331
|
+
wasRevoked = true;
|
|
1332
|
+
rowId = existing.id;
|
|
1333
|
+
}
|
|
1334
|
+
const now = /* @__PURE__ */ new Date();
|
|
1335
|
+
await tx.write("Key", [{
|
|
1336
|
+
...rowId !== void 0 && { id: rowId },
|
|
1337
|
+
kid: args.kid,
|
|
1338
|
+
name: args.name,
|
|
1339
|
+
algorithm: "EdDSA",
|
|
1340
|
+
publicKey: publicKeyPem,
|
|
1341
|
+
namespaces,
|
|
1342
|
+
capabilities,
|
|
1343
|
+
revokedAt: null
|
|
1344
|
+
}], ACTOR_HINT);
|
|
1345
|
+
await tx.write(AUDIT_EVENT_TYPE, [buildAuditRow({
|
|
1346
|
+
actorKid: CLI_ACTOR_KID,
|
|
1347
|
+
kind: "key_registered",
|
|
1348
|
+
targetKid: args.kid,
|
|
1349
|
+
details: {
|
|
1350
|
+
kid: args.kid,
|
|
1351
|
+
name: args.name,
|
|
1352
|
+
namespaces,
|
|
1353
|
+
capabilities,
|
|
1354
|
+
fingerprint,
|
|
1355
|
+
replacedRevoked: wasRevoked
|
|
1356
|
+
},
|
|
1357
|
+
now
|
|
1358
|
+
})], ACTOR_HINT);
|
|
1359
|
+
return wasRevoked;
|
|
1360
|
+
});
|
|
1361
|
+
return {
|
|
1362
|
+
kid: args.kid,
|
|
1363
|
+
name: args.name,
|
|
1364
|
+
fingerprint,
|
|
1365
|
+
namespaces,
|
|
1366
|
+
capabilities,
|
|
1367
|
+
replacedRevoked,
|
|
1368
|
+
via: "direct",
|
|
1369
|
+
directoryCreated: false,
|
|
1370
|
+
directoryDetail: "direct-to-postgres cannot reach a plugin namespace"
|
|
1371
|
+
};
|
|
1372
|
+
} finally {
|
|
1373
|
+
await close();
|
|
1374
|
+
}
|
|
1375
|
+
}
|
|
1376
|
+
/**
|
|
1377
|
+
* Register a key through the admin-gated `POST /substrate/v1/_system/keys` route,
|
|
1378
|
+
* which needs an `admin` identity rather than postgres write access, and
|
|
1379
|
+
* writes the directory row in the same transaction. Throws `AdminCliError`
|
|
1380
|
+
* on a non-2xx response.
|
|
1381
|
+
*/
|
|
1382
|
+
async function runRegisterViaRoute(args, baseUrl, env, fetchImpl = fetch) {
|
|
1383
|
+
if (grantEntriesConfer(args.namespaces, args.capabilities, "admin") && !args.allowAdmin) throw new AdminCliError("register: 'admin' capability requires --allow-admin (bootstrap is the deliberate admin path)", 1);
|
|
1384
|
+
const publicKeyPem = readEd25519PublicKey(args.pubkeyPath);
|
|
1385
|
+
const fingerprint = `sha256:${base64Url(createHash("sha256").update(publicKeyPem).digest()).slice(0, 8)}`;
|
|
1386
|
+
const auth = resolveAdminAuth(env, baseUrl);
|
|
1387
|
+
if ("error" in auth) throw new AdminCliError(`register: ${auth.error}`, 1);
|
|
1388
|
+
const directoryParams = {};
|
|
1389
|
+
if (args.noBroadcast) directoryParams.broadcastEligible = false;
|
|
1390
|
+
if (args.project !== null) directoryParams.project = args.project;
|
|
1391
|
+
const body = {
|
|
1392
|
+
kid: args.kid,
|
|
1393
|
+
publicKey: publicKeyPem,
|
|
1394
|
+
name: args.name,
|
|
1395
|
+
algorithm: "EdDSA",
|
|
1396
|
+
namespaces: args.namespaces,
|
|
1397
|
+
capabilities: args.capabilities,
|
|
1398
|
+
allowAdmin: args.allowAdmin,
|
|
1399
|
+
allowUnknownNs: args.allowUnknownNs,
|
|
1400
|
+
directory: {
|
|
1401
|
+
create: !args.noDirectory,
|
|
1402
|
+
...Object.keys(directoryParams).length > 0 ? { params: directoryParams } : {}
|
|
1403
|
+
}
|
|
1404
|
+
};
|
|
1405
|
+
const url = `${trimTrailingSlashes(baseUrl)}/substrate/v1/_system/keys`;
|
|
1406
|
+
let res;
|
|
1407
|
+
try {
|
|
1408
|
+
res = await fetchImpl(url, {
|
|
1409
|
+
method: "POST",
|
|
1410
|
+
headers: {
|
|
1411
|
+
"content-type": "application/json",
|
|
1412
|
+
authorization: auth.ok
|
|
1413
|
+
},
|
|
1414
|
+
body: JSON.stringify(body),
|
|
1415
|
+
redirect: "error"
|
|
1416
|
+
});
|
|
1417
|
+
} catch (err) {
|
|
1418
|
+
const msg = err instanceof Error ? err.message : String(err);
|
|
1419
|
+
throw new AdminCliError(`register: could not reach ${url}: ${msg}. Pass --direct to write to postgres instead (break-glass; leaves no directory row).`, 2);
|
|
1420
|
+
}
|
|
1421
|
+
const text = await res.text();
|
|
1422
|
+
let parsed = null;
|
|
1423
|
+
try {
|
|
1424
|
+
parsed = JSON.parse(text);
|
|
1425
|
+
} catch {}
|
|
1426
|
+
if (!res.ok) {
|
|
1427
|
+
const code = typeof parsed?.code === "string" ? parsed.code : `http_${res.status}`;
|
|
1428
|
+
const message = typeof parsed?.message === "string" ? parsed.message : text.slice(0, 500);
|
|
1429
|
+
if (res.status === 404) throw new AdminCliError(`register: ${url} returned 404 — this server predates the keys route. Upgrade it, or pass --direct.`, 2);
|
|
1430
|
+
throw new AdminCliError(`register: ${code}: ${message}`, 3);
|
|
1431
|
+
}
|
|
1432
|
+
const dir = parsed?.directory ?? {};
|
|
1433
|
+
return {
|
|
1434
|
+
kid: typeof parsed?.kid === "string" ? parsed.kid : args.kid,
|
|
1435
|
+
name: args.name,
|
|
1436
|
+
fingerprint: typeof parsed?.fingerprint === "string" ? parsed.fingerprint : fingerprint,
|
|
1437
|
+
namespaces: encodeList(args.namespaces),
|
|
1438
|
+
capabilities: encodeList(args.capabilities),
|
|
1439
|
+
replacedRevoked: parsed?.replacedRevoked === true,
|
|
1440
|
+
via: "route",
|
|
1441
|
+
directoryCreated: dir.created === true,
|
|
1442
|
+
directoryDetail: dir.created === true ? typeof dir.frame === "string" ? dir.frame : "created" : typeof dir.reason === "string" ? dir.reason : "not created"
|
|
1443
|
+
};
|
|
1444
|
+
}
|
|
1445
|
+
function formatRegisterOutput(result, opts = {}) {
|
|
1446
|
+
const lines = [
|
|
1447
|
+
"substrate-admin register complete.",
|
|
1448
|
+
`kid: ${result.kid}`,
|
|
1449
|
+
`name: ${result.name}`,
|
|
1450
|
+
`fingerprint: ${result.fingerprint}`,
|
|
1451
|
+
...grantLines("grant: ", result.namespaces, result.capabilities),
|
|
1452
|
+
` (stored as: namespaces='${result.namespaces}' capabilities='${result.capabilities}')`,
|
|
1453
|
+
`transport: ${result.via === "route" ? "POST /substrate/v1/_system/keys" : "direct-to-postgres (--direct)"}`,
|
|
1454
|
+
`directory row: ${result.directoryCreated ? `created in ${result.directoryDetail}` : `NOT created — ${result.directoryDetail}`}`
|
|
1455
|
+
];
|
|
1456
|
+
if (result.replacedRevoked) lines.push("re-registered over a previously-revoked kid.");
|
|
1457
|
+
lines.push("");
|
|
1458
|
+
if (result.via === "route") {
|
|
1459
|
+
lines.push("This build refreshes the key registry post-commit, so no restart should be needed.");
|
|
1460
|
+
lines.push("Verify before relying on it: mint a token with this kid's private key and call /substrate/v1/whoami.");
|
|
1461
|
+
} else lines.push("A RUNNING binary will not see this key until its registry re-primes —", "restart it (e.g. `sudo systemctl restart substrate-binary`) for the key to verify.");
|
|
1462
|
+
if (!result.directoryCreated && opts.adminRoot === true) lines.push("", "No directory row, by design: admin roots are exempt by capability, like the bootstrap key.");
|
|
1463
|
+
else if (!result.directoryCreated) lines.push("", "WARNING: this identity has a credential but NO directory row. It will", "authenticate normally and be invisible to fleet listing and mail routing.", result.via === "direct" ? "Re-run without --direct (or with --url) to write both rows in one transaction." : result.directoryDetail === "not_configured" ? "This deployment has no identity directory configured, so there is nowhere to write one. Expected for a substrate with no mailbox; alarming for a fleet member. Configure SUBSTRATE_AGENT_DIRECTORY_TYPE if it should have one." : "Create the directory row by hand, or re-run without --no-directory.");
|
|
1464
|
+
lines.push("");
|
|
1465
|
+
return lines.join("\n");
|
|
1466
|
+
}
|
|
1467
|
+
|
|
1468
|
+
//#endregion
|
|
1469
|
+
//#region src/admin/commands/onboard.ts
|
|
1470
|
+
/**
|
|
1471
|
+
* `substrate-admin onboard` — guided onboarding. Runs diagnose, plans the steps,
|
|
1472
|
+
* stops at the first one still to do, and offers to run its fix when a client
|
|
1473
|
+
* can. Every action is confirmed; nothing runs unattended.
|
|
1474
|
+
*/
|
|
1475
|
+
function formatChecklist(steps) {
|
|
1476
|
+
const current = currentStep(steps);
|
|
1477
|
+
const width = Math.max(...steps.map((s) => s.name.length));
|
|
1478
|
+
return `${steps.map((s) => {
|
|
1479
|
+
const mark = s === current ? "▶" : STEP_MARKS[s.status];
|
|
1480
|
+
const tag = s.optional ? " (optional)" : "";
|
|
1481
|
+
return ` ${mark} ${s.name.padEnd(width)} ${s.detail}${tag}`;
|
|
1482
|
+
}).join("\n")}\n`;
|
|
1483
|
+
}
|
|
1484
|
+
function describeAction(action, store, adminCapability) {
|
|
1485
|
+
switch (action.kind) {
|
|
1486
|
+
case "bootstrap": return `substrate-admin bootstrap — writes straight to SUBSTRATE_DATABASE_URL=${store ?? "(unset)"}. It must be the same database the server you named serves; nothing here can check that.`;
|
|
1487
|
+
case "register-admin": return `substrate-admin register <kid> --pubkey <path> --ns '*' --caps ${seedCapabilities(adminCapability).join(",")} --allow-admin --no-directory`;
|
|
1488
|
+
case "register-agent": return "substrate-admin register <kid> --pubkey <path> --ns <namespace,…>";
|
|
1489
|
+
case "revoke": return action.kids.map((k) => `substrate-admin revoke ${k}`).join(" && ");
|
|
1490
|
+
}
|
|
1491
|
+
}
|
|
1492
|
+
/** Thrown when input ends mid-action; the loop turns it into a quit. */
|
|
1493
|
+
var EndOfInput = class extends Error {};
|
|
1494
|
+
async function need(io, prompt) {
|
|
1495
|
+
const line = await io.ask(prompt);
|
|
1496
|
+
if (line === null) throw new EndOfInput();
|
|
1497
|
+
return line.trim();
|
|
1498
|
+
}
|
|
1499
|
+
/** Asks for a public key, offering to generate a keypair when the operator has none. */
|
|
1500
|
+
async function publicKeyPath(io, actions, kid) {
|
|
1501
|
+
const given = await need(io, "public key path (Enter to generate a keypair here): ");
|
|
1502
|
+
if (given.length > 0) return given;
|
|
1503
|
+
io.out("A private key must live with whoever will use it, and never travel. Generate it on the machine that will sign with it.\n");
|
|
1504
|
+
const target = await need(io, "write the new private key to (Enter to cancel): ");
|
|
1505
|
+
if (target.length === 0) return null;
|
|
1506
|
+
const written = actions.generateKeypair(target, kid);
|
|
1507
|
+
io.out(`wrote ${written.privateKeyPath} (0600) and ${written.publicKeyPath}\n`);
|
|
1508
|
+
if (written.kidPath !== void 0) io.out(`wrote ${written.kidPath} — point the signing-key variable at the private key and the kid is read from beside it.
|
|
1509
|
+
`);
|
|
1510
|
+
return written.publicKeyPath;
|
|
1511
|
+
}
|
|
1512
|
+
/** Runs one action. Returns the output to show, or null when the operator cancelled. */
|
|
1513
|
+
async function perform(action, io, actions) {
|
|
1514
|
+
switch (action.kind) {
|
|
1515
|
+
case "bootstrap": return actions.bootstrap();
|
|
1516
|
+
case "register-admin": {
|
|
1517
|
+
const kid = await need(io, "kid for the second admin: ");
|
|
1518
|
+
if (kid.length === 0) return null;
|
|
1519
|
+
const pub = await publicKeyPath(io, actions, kid);
|
|
1520
|
+
return pub === null ? null : actions.registerAdmin(kid, pub);
|
|
1521
|
+
}
|
|
1522
|
+
case "register-agent": {
|
|
1523
|
+
const kid = await need(io, "kid for the agent (e.g. myrepo-claude@host): ");
|
|
1524
|
+
if (kid.length === 0) return null;
|
|
1525
|
+
const pub = await publicKeyPath(io, actions, kid);
|
|
1526
|
+
if (pub === null) return null;
|
|
1527
|
+
const ns = await need(io, "grant namespaces (comma-separated): ");
|
|
1528
|
+
const namespaces = ns.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
|
|
1529
|
+
if (namespaces.length === 0) {
|
|
1530
|
+
io.out("a namespace is required\n");
|
|
1531
|
+
return null;
|
|
1532
|
+
}
|
|
1533
|
+
const grantError = grantEntryError(namespaces, ["read", "mutate"]);
|
|
1534
|
+
if (grantError !== null) {
|
|
1535
|
+
io.out(`grant '${ns}' refused: ${grantError}\n`);
|
|
1536
|
+
return null;
|
|
1537
|
+
}
|
|
1538
|
+
return actions.registerAgent(kid, pub, namespaces);
|
|
1539
|
+
}
|
|
1540
|
+
case "revoke": {
|
|
1541
|
+
const done = [];
|
|
1542
|
+
for (const kid of action.kids) {
|
|
1543
|
+
const typed = await need(io, `type '${kid}' to revoke it: `);
|
|
1544
|
+
if (typed !== kid) {
|
|
1545
|
+
io.out(`'${typed}' did not match — ${kid} left alone\n`);
|
|
1546
|
+
continue;
|
|
1547
|
+
}
|
|
1548
|
+
try {
|
|
1549
|
+
done.push(await actions.revoke(kid));
|
|
1550
|
+
} catch (err) {
|
|
1551
|
+
done.push(`failed: ${kid}: ${err instanceof Error ? err.message : String(err)}`);
|
|
1552
|
+
}
|
|
1553
|
+
}
|
|
1554
|
+
return done.length > 0 ? done.join("\n") : null;
|
|
1555
|
+
}
|
|
1556
|
+
}
|
|
1557
|
+
}
|
|
1558
|
+
function summary(steps, stopped) {
|
|
1559
|
+
const skipped = steps.filter((s) => s.status === "skipped").map((s) => s.name);
|
|
1560
|
+
const blocked = steps.filter((s) => s.status === "blocked").map((s) => s.name);
|
|
1561
|
+
const lines = [stopped ? "onboarding stopped before it finished." : requiredOutstanding(steps) ? "onboarding has required steps outstanding." : "onboarding complete."];
|
|
1562
|
+
if (skipped.length > 0) lines.push(`skipped: ${skipped.join(", ")}`);
|
|
1563
|
+
if (blocked.length > 0) lines.push(`not checked: ${blocked.join(", ")}`);
|
|
1564
|
+
return `\n${lines.join("\n")}\n`;
|
|
1565
|
+
}
|
|
1566
|
+
async function runOnboard(opts) {
|
|
1567
|
+
const { io, actions } = opts;
|
|
1568
|
+
const adminCapability = opts.adminCapability ?? "admin";
|
|
1569
|
+
const skipped = /* @__PURE__ */ new Set();
|
|
1570
|
+
let declined = null;
|
|
1571
|
+
for (;;) {
|
|
1572
|
+
let result;
|
|
1573
|
+
try {
|
|
1574
|
+
result = await opts.diagnose();
|
|
1575
|
+
} catch (err) {
|
|
1576
|
+
io.out(`diagnose failed: ${err instanceof Error ? err.message : String(err)}\n`);
|
|
1577
|
+
return 2;
|
|
1578
|
+
}
|
|
1579
|
+
const steps = planOnboarding(result, {
|
|
1580
|
+
canBootstrap: opts.canBootstrap,
|
|
1581
|
+
skipped
|
|
1582
|
+
});
|
|
1583
|
+
io.out(`\n${formatChecklist(steps)}`);
|
|
1584
|
+
const step = currentStep(steps);
|
|
1585
|
+
const exitCode = requiredOutstanding(steps) ? 1 : 0;
|
|
1586
|
+
if (step === void 0 || !opts.interactive) {
|
|
1587
|
+
io.out(summary(steps, false));
|
|
1588
|
+
return exitCode;
|
|
1589
|
+
}
|
|
1590
|
+
if (declined !== step.name) declined = null;
|
|
1591
|
+
io.out(`\n${step.name}: ${step.detail}\n`);
|
|
1592
|
+
try {
|
|
1593
|
+
if (step.action !== void 0 && declined === null) {
|
|
1594
|
+
io.out(` would run: ${describeAction(step.action, opts.bootstrapStore, adminCapability)}\n`);
|
|
1595
|
+
if ((await need(io, "Run it? [y/N] ")).toLowerCase() === "y") {
|
|
1596
|
+
try {
|
|
1597
|
+
const output = await perform(step.action, io, actions);
|
|
1598
|
+
if (output !== null) io.out(`${output}\n`);
|
|
1599
|
+
} catch (err) {
|
|
1600
|
+
if (err instanceof EndOfInput) throw err;
|
|
1601
|
+
io.out(`failed: ${err instanceof Error ? err.message : String(err)}\n`);
|
|
1602
|
+
}
|
|
1603
|
+
continue;
|
|
1604
|
+
}
|
|
1605
|
+
declined = step.name;
|
|
1606
|
+
}
|
|
1607
|
+
if (step.fix !== void 0) io.out(` fix: ${step.fix}\n`);
|
|
1608
|
+
const offerRun = step.action !== void 0 && declined === step.name;
|
|
1609
|
+
const choice = (await need(io, `Enter re-checks${offerRun ? ", r runs the fix" : ""}${step.skippable ? ", s skips" : ""}, q quits: `)).toLowerCase();
|
|
1610
|
+
if (choice === "q") {
|
|
1611
|
+
io.out(summary(steps, true));
|
|
1612
|
+
return exitCode;
|
|
1613
|
+
}
|
|
1614
|
+
if (choice === "r" && offerRun) declined = null;
|
|
1615
|
+
if (choice === "s") {
|
|
1616
|
+
if (SKIPPABLE_STEPS.has(step.name)) skipped.add(step.name);
|
|
1617
|
+
else io.out(`${step.name} cannot be skipped\n`);
|
|
1618
|
+
}
|
|
1619
|
+
} catch (err) {
|
|
1620
|
+
if (!(err instanceof EndOfInput)) throw err;
|
|
1621
|
+
io.out(summary(steps, true));
|
|
1622
|
+
return exitCode;
|
|
1623
|
+
}
|
|
1624
|
+
}
|
|
1625
|
+
}
|
|
1626
|
+
/** A postgres URL fit to print: the password is never echoed. */
|
|
1627
|
+
function redactStore(url) {
|
|
1628
|
+
let u;
|
|
1629
|
+
try {
|
|
1630
|
+
u = new URL(url);
|
|
1631
|
+
} catch {
|
|
1632
|
+
return "(an unparseable postgres URL)";
|
|
1633
|
+
}
|
|
1634
|
+
const auth = u.username.length > 0 ? `${u.username}${u.password.length > 0 ? ":***" : ""}@` : "";
|
|
1635
|
+
return `${u.protocol}//${auth}${u.host}${u.pathname}`;
|
|
1636
|
+
}
|
|
1637
|
+
function registerArgs(kid, pubkeyPath, over) {
|
|
1638
|
+
return {
|
|
1639
|
+
kid,
|
|
1640
|
+
pubkeyPath,
|
|
1641
|
+
name: kid,
|
|
1642
|
+
namespaces: [],
|
|
1643
|
+
capabilities: ["read", "mutate"],
|
|
1644
|
+
allowAdmin: false,
|
|
1645
|
+
allowUnknownNs: false,
|
|
1646
|
+
url: null,
|
|
1647
|
+
noDirectory: false,
|
|
1648
|
+
noBroadcast: false,
|
|
1649
|
+
project: null,
|
|
1650
|
+
...over
|
|
1651
|
+
};
|
|
1652
|
+
}
|
|
1653
|
+
/** The production action runners: the same functions the standalone subcommands call. */
|
|
1654
|
+
function realOnboardActions(env, baseUrl, fetchImpl = fetch) {
|
|
1655
|
+
const cap = env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 && env.SUBSTRATE_ADMIN_CAPABILITY.length > 0 ? env.SUBSTRATE_ADMIN_CAPABILITY : DEFAULT_ADMIN_CAPABILITY;
|
|
1656
|
+
return {
|
|
1657
|
+
bootstrap: async () => formatBootstrapOutput(await runBootstrap(env)),
|
|
1658
|
+
registerAdmin: async (kid, pub) => formatRegisterOutput(await runRegisterViaRoute(registerArgs(kid, pub, {
|
|
1659
|
+
namespaces: ["*"],
|
|
1660
|
+
capabilities: seedCapabilities(cap),
|
|
1661
|
+
allowAdmin: true,
|
|
1662
|
+
noDirectory: true
|
|
1663
|
+
}), baseUrl, env, fetchImpl), { adminRoot: true }),
|
|
1664
|
+
registerAgent: async (kid, pub, namespaces) => formatRegisterOutput(await runRegisterViaRoute(registerArgs(kid, pub, { namespaces: [...namespaces] }), baseUrl, env, fetchImpl)),
|
|
1665
|
+
revoke: async (kid) => {
|
|
1666
|
+
await runKeyPatchViaRoute({
|
|
1667
|
+
kid,
|
|
1668
|
+
revoke: true
|
|
1669
|
+
}, baseUrl, env, REVOKE_EXIT_CODES, fetchImpl);
|
|
1670
|
+
return `revoked ${kid}`;
|
|
1671
|
+
},
|
|
1672
|
+
generateKeypair: (path, kid) => writeKeypair(env, path, kid)
|
|
1673
|
+
};
|
|
1674
|
+
}
|
|
1675
|
+
/** Parse argv, resolve the target, and run — the shape `main` dispatches to. */
|
|
1676
|
+
async function onboardCommand(argv, env, io, interactive, fetchImpl = fetch) {
|
|
1677
|
+
validateArgv("onboard", argv);
|
|
1678
|
+
let url;
|
|
1679
|
+
let direct = false;
|
|
1680
|
+
let check = false;
|
|
1681
|
+
for (let i = 0; i < argv.length; i++) {
|
|
1682
|
+
const tok = argv[i];
|
|
1683
|
+
if (tok === "--url") {
|
|
1684
|
+
if (url !== void 0) throw argvError("onboard", "onboard: --url specified more than once", 1);
|
|
1685
|
+
url = argv[i + 1] ?? "";
|
|
1686
|
+
i += 1;
|
|
1687
|
+
} else if (tok === "--direct") direct = true;
|
|
1688
|
+
else if (tok === "--check") check = true;
|
|
1689
|
+
}
|
|
1690
|
+
const target = resolveAdminTarget(direct ? "" : url ?? null, env);
|
|
1691
|
+
if (target.kind !== "route") {
|
|
1692
|
+
io.out(formatDoctorReport({
|
|
1693
|
+
checks: [DIRECT_TARGET_REFUSAL],
|
|
1694
|
+
exitCode: 1
|
|
1695
|
+
}));
|
|
1696
|
+
return 1;
|
|
1697
|
+
}
|
|
1698
|
+
const store = env.SUBSTRATE_DATABASE_URL ?? "";
|
|
1699
|
+
const canBootstrap = (store.startsWith("postgres://") || store.startsWith("postgresql://")) && bootstrapBlockers(env).length === 0;
|
|
1700
|
+
return runOnboard({
|
|
1701
|
+
diagnose: () => diagnoseTarget(env, target.baseUrl, fetchImpl),
|
|
1702
|
+
canBootstrap,
|
|
1703
|
+
...canBootstrap ? { bootstrapStore: redactStore(store) } : {},
|
|
1704
|
+
...env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 && env.SUBSTRATE_ADMIN_CAPABILITY.length > 0 ? { adminCapability: env.SUBSTRATE_ADMIN_CAPABILITY } : {},
|
|
1705
|
+
interactive: interactive && !check,
|
|
1706
|
+
io,
|
|
1707
|
+
actions: realOnboardActions(env, target.baseUrl, fetchImpl)
|
|
1708
|
+
});
|
|
1709
|
+
}
|
|
1710
|
+
|
|
1711
|
+
//#endregion
|
|
1712
|
+
//#region src/admin/dataset.ts
|
|
1713
|
+
/**
|
|
1714
|
+
* Direct-to-pg dataset opener shared by every CLI path that writes `_system`
|
|
1715
|
+
* rows without going through the running binary, including
|
|
1716
|
+
* `substrate federate enroll`.
|
|
1717
|
+
*
|
|
1718
|
+
* It never migrates: only `bootstrap` and the server change the schema. A
|
|
1719
|
+
* store missing a migration this CLI knows is refused.
|
|
1720
|
+
*/
|
|
1721
|
+
async function openPgDataset(env, openSql$1 = openSql) {
|
|
1722
|
+
const storeSpec = env.SUBSTRATE_DATABASE_URL;
|
|
1723
|
+
if (storeSpec === void 0 || storeSpec.length === 0) throw new AdminCliError("SUBSTRATE_DATABASE_URL is required (must be a postgres:// URL)");
|
|
1724
|
+
if (!storeSpec.startsWith("postgres://") && !storeSpec.startsWith("postgresql://")) throw new AdminCliError(`SUBSTRATE_DATABASE_URL must be a postgres:// URL (got '${redactStore(storeSpec)}'). Memory-backed stores cannot persist admin state across restarts.`);
|
|
1725
|
+
const sql = openSql$1(storeSpec);
|
|
1726
|
+
let pending;
|
|
1727
|
+
try {
|
|
1728
|
+
pending = await pendingMigrations(sql);
|
|
1729
|
+
} catch (err) {
|
|
1730
|
+
await closeQuietly(sql);
|
|
1731
|
+
throw err;
|
|
1732
|
+
}
|
|
1733
|
+
if (pending.length > 0) {
|
|
1734
|
+
await closeQuietly(sql);
|
|
1735
|
+
throw new AdminCliError(`the store at SUBSTRATE_DATABASE_URL is missing migration(s) ${pending.join(", ")}. This command does not migrate: start the server (or run bootstrap) against it, or use a substrate-admin matching the server version.`);
|
|
1736
|
+
}
|
|
1737
|
+
return {
|
|
1738
|
+
dataset: new PgDataset({
|
|
1739
|
+
namespace: SYSTEM_NAMESPACE,
|
|
1740
|
+
sql
|
|
1741
|
+
}),
|
|
1742
|
+
close: () => closeQuietly(sql)
|
|
1743
|
+
};
|
|
1744
|
+
}
|
|
1745
|
+
async function closeQuietly(sql) {
|
|
1746
|
+
try {
|
|
1747
|
+
await sql.end();
|
|
1748
|
+
} catch {}
|
|
1749
|
+
}
|
|
1750
|
+
|
|
1751
|
+
//#endregion
|
|
1752
|
+
//#region package.json
|
|
1753
|
+
var version = "1.0.0-alpha.10";
|
|
1754
|
+
|
|
1755
|
+
//#endregion
|
|
1756
|
+
//#region src/plugin-manifest.ts
|
|
1757
|
+
var PluginManifestError = class extends Error {
|
|
1758
|
+
packageName;
|
|
1759
|
+
constructor(packageName, message) {
|
|
1760
|
+
const prefix = packageName !== void 0 ? `[${packageName}] ` : "";
|
|
1761
|
+
super(`${prefix}${message}`);
|
|
1762
|
+
this.name = "PluginManifestError";
|
|
1763
|
+
this.packageName = packageName;
|
|
1764
|
+
}
|
|
1765
|
+
};
|
|
1766
|
+
async function listPluginManifests(pluginDir) {
|
|
1767
|
+
const declared = await declaredDependencies(pluginDir);
|
|
1768
|
+
if (declared.size === 0) return [];
|
|
1769
|
+
const nodeModulesDir = resolve(pluginDir, "node_modules");
|
|
1770
|
+
if (!await isDirectory(nodeModulesDir)) throw new PluginManifestError(void 0, `${pluginDir}/package.json lists ${[...declared].join(", ")} but there is no node_modules: run \`pnpm install\` in ${pluginDir}`);
|
|
1771
|
+
const packageDirs = await listPackageDirs(nodeModulesDir, declared);
|
|
1772
|
+
const manifests = [];
|
|
1773
|
+
for (const packageDir of packageDirs) manifests.push(...await readManifestsIfPresent(packageDir));
|
|
1774
|
+
if (manifests.length === 0) process.stderr.write(`substrate: SUBSTRATE_PLUGIN_DIR=${pluginDir} lists ${[...declared].join(", ")}, none of which is an installed substrate plugin; booting without plugins\n`);
|
|
1775
|
+
return manifests;
|
|
1776
|
+
}
|
|
1777
|
+
/**
|
|
1778
|
+
* The names `<pluginDir>/package.json` lists under `dependencies`. Only these
|
|
1779
|
+
* are plugin candidates: a transitive package hoisted into `node_modules` is
|
|
1780
|
+
* not something the operator chose to run. A missing package.json refuses
|
|
1781
|
+
* boot, since a plugin dir that can name no plugin is a misconfiguration.
|
|
1782
|
+
*/
|
|
1783
|
+
async function declaredDependencies(pluginDir) {
|
|
1784
|
+
let raw;
|
|
1785
|
+
try {
|
|
1786
|
+
raw = await readFile(resolve(pluginDir, "package.json"), "utf8");
|
|
1787
|
+
} catch (err) {
|
|
1788
|
+
if (err.code !== "ENOENT") throw err;
|
|
1789
|
+
throw new PluginManifestError(void 0, `SUBSTRATE_PLUGIN_DIR=${pluginDir} has no package.json, so no plugin can load. List each plugin under "dependencies" there (\`substrate init\` writes one) and run \`pnpm install\`, or unset SUBSTRATE_PLUGIN_DIR to boot without plugins`);
|
|
1790
|
+
}
|
|
1791
|
+
let parsed;
|
|
1792
|
+
try {
|
|
1793
|
+
parsed = JSON.parse(raw);
|
|
1794
|
+
} catch (err) {
|
|
1795
|
+
const msg = err instanceof Error ? err.message : String(err);
|
|
1796
|
+
throw new PluginManifestError(void 0, `${pluginDir}/package.json is not valid JSON: ${msg}`);
|
|
1797
|
+
}
|
|
1798
|
+
const deps = parsed?.dependencies;
|
|
1799
|
+
return new Set(deps !== null && typeof deps === "object" ? Object.keys(deps) : []);
|
|
1800
|
+
}
|
|
1801
|
+
async function listPackageDirs(nodeModulesDir, declared) {
|
|
1802
|
+
const entries = await readdir(nodeModulesDir, { withFileTypes: true });
|
|
1803
|
+
const result = [];
|
|
1804
|
+
for (const entry of entries) {
|
|
1805
|
+
if (entry.name.startsWith(".")) continue;
|
|
1806
|
+
if (!await isDirectoryEntry(nodeModulesDir, entry)) continue;
|
|
1807
|
+
if (entry.name.startsWith("@")) {
|
|
1808
|
+
const scopeDir = resolve(nodeModulesDir, entry.name);
|
|
1809
|
+
const scopedEntries = await readdir(scopeDir, { withFileTypes: true });
|
|
1810
|
+
for (const scoped of scopedEntries) {
|
|
1811
|
+
if (scoped.name.startsWith(".")) continue;
|
|
1812
|
+
if (!declared.has(`${entry.name}/${scoped.name}`)) continue;
|
|
1813
|
+
if (!await isDirectoryEntry(scopeDir, scoped)) continue;
|
|
1814
|
+
result.push(resolve(scopeDir, scoped.name));
|
|
1815
|
+
}
|
|
1816
|
+
} else if (declared.has(entry.name)) result.push(resolve(nodeModulesDir, entry.name));
|
|
1817
|
+
}
|
|
1818
|
+
return result;
|
|
1819
|
+
}
|
|
1820
|
+
/**
|
|
1821
|
+
* Treat both real directories AND symlinks-to-directories as plugin
|
|
1822
|
+
* candidates. `Dirent.isDirectory()` is false for symlinks (it returns
|
|
1823
|
+
* true for `isSymbolicLink()` instead) — without the follow-through,
|
|
1824
|
+
* operators using a symlinked node_modules layout (the typical pattern
|
|
1825
|
+
* when wiring the workspace's plugin dirs into a runtime plugin dir
|
|
1826
|
+
* via `ln -s`) would see their plugins silently skipped.
|
|
1827
|
+
*/
|
|
1828
|
+
async function isDirectoryEntry(parentDir, entry) {
|
|
1829
|
+
if (entry.isDirectory()) return true;
|
|
1830
|
+
if (!entry.isSymbolicLink()) return false;
|
|
1831
|
+
try {
|
|
1832
|
+
return (await stat(resolve(parentDir, entry.name))).isDirectory();
|
|
1833
|
+
} catch {
|
|
1834
|
+
return false;
|
|
1835
|
+
}
|
|
1836
|
+
}
|
|
1837
|
+
async function readManifestsIfPresent(packageDir) {
|
|
1838
|
+
const pkgPath = resolve(packageDir, "package.json");
|
|
1839
|
+
let raw;
|
|
1840
|
+
try {
|
|
1841
|
+
raw = await readFile(pkgPath, "utf8");
|
|
1842
|
+
} catch {
|
|
1843
|
+
return [];
|
|
1844
|
+
}
|
|
1845
|
+
let pkg;
|
|
1846
|
+
try {
|
|
1847
|
+
pkg = JSON.parse(raw);
|
|
1848
|
+
} catch (err) {
|
|
1849
|
+
throw new PluginManifestError(void 0, `package.json at '${pkgPath}' is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
|
|
1850
|
+
}
|
|
1851
|
+
if (pkg.substrate === void 0) return [];
|
|
1852
|
+
return parseManifests(pkg, packageDir);
|
|
1853
|
+
}
|
|
1854
|
+
const PLUGIN_NAME = /^[a-z0-9][a-z0-9-]*$/;
|
|
1855
|
+
function parseManifests(pkg, packageDir) {
|
|
1856
|
+
const packageName = typeof pkg.name === "string" ? pkg.name : void 0;
|
|
1857
|
+
if (packageName === void 0 || packageName.length === 0) throw new PluginManifestError(void 0, `package.json at '${packageDir}' is missing a name`);
|
|
1858
|
+
if (!isPlainObject(pkg.substrate)) throw new PluginManifestError(packageName, "`substrate` manifest must be an object");
|
|
1859
|
+
const block = pkg.substrate;
|
|
1860
|
+
if (block.plugins === void 0) return [parseEntry(block, packageName, packageDir, void 0, "`substrate")];
|
|
1861
|
+
const strays = Object.keys(block).filter((key) => key !== "plugins");
|
|
1862
|
+
if (strays.length > 0) throw new PluginManifestError(packageName, `\`substrate.plugins\` cannot sit beside single-plugin keys (${strays.join(", ")}); move them into the entries`);
|
|
1863
|
+
if (!Array.isArray(block.plugins) || block.plugins.length === 0) throw new PluginManifestError(packageName, "`substrate.plugins` must be a non-empty array");
|
|
1864
|
+
const names = /* @__PURE__ */ new Set();
|
|
1865
|
+
return block.plugins.map((raw, i) => {
|
|
1866
|
+
const at = `\`substrate.plugins[${i}]`;
|
|
1867
|
+
if (!isPlainObject(raw)) throw new PluginManifestError(packageName, `${at}\` must be an object`);
|
|
1868
|
+
const entry = raw;
|
|
1869
|
+
if (typeof entry.name !== "string" || !PLUGIN_NAME.test(entry.name)) throw new PluginManifestError(packageName, `${at}.name\` must be lowercase letters, digits and hyphens (got ${JSON.stringify(entry.name)})`);
|
|
1870
|
+
if (names.has(entry.name)) throw new PluginManifestError(packageName, `${at}.name\` '${entry.name}' is declared twice`);
|
|
1871
|
+
names.add(entry.name);
|
|
1872
|
+
if (entry.plugins !== void 0) throw new PluginManifestError(packageName, `${at}\` cannot nest \`plugins\``);
|
|
1873
|
+
return parseEntry(entry, packageName, packageDir, entry.name, at);
|
|
1874
|
+
});
|
|
1875
|
+
}
|
|
1876
|
+
function parseEntry(block, packageName, packageDir, name, at) {
|
|
1877
|
+
if (name === void 0 && block.name !== void 0) throw new PluginManifestError(packageName, "`substrate.name` is only meaningful inside a `substrate.plugins` entry");
|
|
1878
|
+
if (block.tier !== "kernel" && block.tier !== "coordinator") throw new PluginManifestError(packageName, `${at}.tier\` must be 'kernel' or 'coordinator' (got ${JSON.stringify(block.tier)})`);
|
|
1879
|
+
if (typeof block.entry !== "string" || block.entry.length === 0) throw new PluginManifestError(packageName, `${at}.entry\` must be a non-empty string`);
|
|
1880
|
+
if (block.configSchema !== void 0 && (typeof block.configSchema !== "string" || block.configSchema.length === 0)) throw new PluginManifestError(packageName, `${at}.configSchema\` must be a non-empty string when present`);
|
|
1881
|
+
if (block.defaultConfig !== void 0 && (typeof block.defaultConfig !== "string" || block.defaultConfig.length === 0)) throw new PluginManifestError(packageName, `${at}.defaultConfig\` must be a non-empty string when present`);
|
|
1882
|
+
if (block.configBasename !== void 0 && (typeof block.configBasename !== "string" || block.configBasename.length === 0)) throw new PluginManifestError(packageName, `${at}.configBasename\` must be a non-empty string when present`);
|
|
1883
|
+
const defaultConfigPath = typeof block.defaultConfig === "string" ? resolve(packageDir, block.defaultConfig) : void 0;
|
|
1884
|
+
const configSchemaPath = typeof block.configSchema === "string" ? resolve(packageDir, block.configSchema) : void 0;
|
|
1885
|
+
const bareName = basename(packageName);
|
|
1886
|
+
const configBasename = typeof block.configBasename === "string" ? block.configBasename : name === void 0 ? bareName : `${bareName}-${name}`;
|
|
1887
|
+
return {
|
|
1888
|
+
packageName,
|
|
1889
|
+
pluginId: name === void 0 ? packageName : `${packageName}/${name}`,
|
|
1890
|
+
packageDir,
|
|
1891
|
+
tier: block.tier,
|
|
1892
|
+
entry: block.entry,
|
|
1893
|
+
defaultConfigPath,
|
|
1894
|
+
configSchemaPath,
|
|
1895
|
+
configBasename
|
|
1896
|
+
};
|
|
1897
|
+
}
|
|
1898
|
+
function isPlainObject(value) {
|
|
1899
|
+
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
1900
|
+
}
|
|
1901
|
+
async function isDirectory(path) {
|
|
1902
|
+
try {
|
|
1903
|
+
return (await stat(path)).isDirectory();
|
|
1904
|
+
} catch {
|
|
1905
|
+
return false;
|
|
1906
|
+
}
|
|
1907
|
+
}
|
|
1908
|
+
|
|
1909
|
+
//#endregion
|
|
1910
|
+
//#region src/plugin-dir-loader.ts
|
|
1911
|
+
/**
|
|
1912
|
+
* Plugin discovery + loader for the `SUBSTRATE_PLUGIN_DIR` boot path.
|
|
1913
|
+
*
|
|
1914
|
+
* Scans `<dir>/node_modules/{*,@*\/*}/package.json` for the dependencies
|
|
1915
|
+
* `<dir>/package.json` lists that declare a
|
|
1916
|
+
* `substrate` manifest, reads each plugin's defaults + the operator's colocated
|
|
1917
|
+
* `<basename>.config.json` overrides, and invokes each plugin's structured
|
|
1918
|
+
* `bootstrap(rawConfig[, hostDeps])` from `@mnmal-ai/substrate-bootstrap`.
|
|
1919
|
+
*
|
|
1920
|
+
* This module owns the fs-specific parts — directory scan, config-file reads,
|
|
1921
|
+
* dynamic `import()` of the bootstrap entry. The tier ordering (substrate
|
|
1922
|
+
* before coordinator, alphabetical within tier) + bootstrap invocation +
|
|
1923
|
+
* `BootstrapConfigError` wrapping live in `composeFromManifests`
|
|
1924
|
+
* (`@mnmal-ai/substrate-compose`), shared with downstream consumers that load from
|
|
1925
|
+
* a statically-bundled manifest list rather than an fs scan.
|
|
1926
|
+
*
|
|
1927
|
+
* Failure mode: refuse boot. Manifest parse errors,
|
|
1928
|
+
* `BootstrapConfigError` from a plugin's zod schema, and import errors all
|
|
1929
|
+
* surface as `PluginLoadError` with the offending package name attached so
|
|
1930
|
+
* the operator sees `<plugin>: <issue>` rather than a bare zod dump.
|
|
1931
|
+
*
|
|
1932
|
+
* Coordinator plugins receive operator config only — no code-shaped extras.
|
|
1933
|
+
* The substrate-driven postWrite registry (substrate-recall's `contributePostWrites`)
|
|
1934
|
+
* is the correct path for cross-plugin wiring; the binary does not post-attach
|
|
1935
|
+
* anything to specific coordinators.
|
|
1936
|
+
*/
|
|
1937
|
+
const defaultImportResolver = async (entryPath) => {
|
|
1938
|
+
return import(pathToFileURL(entryPath).href);
|
|
1939
|
+
};
|
|
1940
|
+
async function loadPluginsFromDir(opts) {
|
|
1941
|
+
const importResolver = opts.importResolver ?? defaultImportResolver;
|
|
1942
|
+
const manifests = await listPluginManifests(opts.pluginDir);
|
|
1943
|
+
const { kernel, coordinators, configs } = await composeFromManifests({
|
|
1944
|
+
manifests,
|
|
1945
|
+
kernelHostDeps: opts.kernelHostDeps,
|
|
1946
|
+
...opts.contractCheck !== void 0 ? { contractCheck: opts.contractCheck } : {},
|
|
1947
|
+
resolveConfig: (manifest) => readMergedConfig(manifest, opts.pluginDir),
|
|
1948
|
+
resolveBootstrap: async (manifest) => {
|
|
1949
|
+
return (await importBootstrapModule(manifest, importResolver)).default;
|
|
1950
|
+
}
|
|
1951
|
+
});
|
|
1952
|
+
const manifestMap = /* @__PURE__ */ new Map();
|
|
1953
|
+
for (const m of manifests) manifestMap.set(m.pluginId, m);
|
|
1954
|
+
return {
|
|
1955
|
+
kernel,
|
|
1956
|
+
coordinators,
|
|
1957
|
+
manifests: manifestMap,
|
|
1958
|
+
configs
|
|
1959
|
+
};
|
|
1960
|
+
}
|
|
1961
|
+
async function importBootstrapModule(manifest, importResolver) {
|
|
1962
|
+
const entryAbs = resolve(manifest.packageDir, manifest.entry);
|
|
1963
|
+
let mod;
|
|
1964
|
+
try {
|
|
1965
|
+
mod = await importResolver(entryAbs);
|
|
1966
|
+
} catch (err) {
|
|
1967
|
+
throw new PluginLoadError(manifest.pluginId, `failed to import bootstrap entry '${manifest.entry}': ${describeError(err)}`, err);
|
|
1968
|
+
}
|
|
1969
|
+
if (typeof mod.default !== "function") throw new PluginLoadError(manifest.pluginId, `bootstrap entry '${manifest.entry}' must default-export a function (got ${typeof mod.default})`, void 0);
|
|
1970
|
+
return mod;
|
|
1971
|
+
}
|
|
1972
|
+
async function readMergedConfig(manifest, pluginDir) {
|
|
1973
|
+
const defaults = await readJsonIfPresent(manifest.defaultConfigPath, manifest.pluginId);
|
|
1974
|
+
const overrides = await readJsonIfPresent(resolve(pluginDir, `${manifest.configBasename}.config.json`), manifest.pluginId);
|
|
1975
|
+
return {
|
|
1976
|
+
...defaults,
|
|
1977
|
+
...overrides
|
|
1978
|
+
};
|
|
1979
|
+
}
|
|
1980
|
+
async function readJsonIfPresent(path, pluginId) {
|
|
1981
|
+
if (path === void 0) return {};
|
|
1982
|
+
let content;
|
|
1983
|
+
try {
|
|
1984
|
+
content = await readFile(path, "utf8");
|
|
1985
|
+
} catch (err) {
|
|
1986
|
+
if (isENOENT(err)) return {};
|
|
1987
|
+
throw new PluginLoadError(pluginId, `failed to read config at '${path}'`, err);
|
|
1988
|
+
}
|
|
1989
|
+
try {
|
|
1990
|
+
const parsed = JSON.parse(content);
|
|
1991
|
+
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new PluginLoadError(pluginId, `config at '${path}' must be a JSON object (got ${Array.isArray(parsed) ? "array" : typeof parsed})`, void 0);
|
|
1992
|
+
return parsed;
|
|
1993
|
+
} catch (err) {
|
|
1994
|
+
if (err instanceof PluginLoadError) throw err;
|
|
1995
|
+
throw new PluginLoadError(pluginId, `config at '${path}' is not valid JSON`, err);
|
|
1996
|
+
}
|
|
1997
|
+
}
|
|
1998
|
+
function isENOENT(err) {
|
|
1999
|
+
return err !== null && typeof err === "object" && "code" in err && err.code === "ENOENT";
|
|
2000
|
+
}
|
|
2001
|
+
function describeError(err) {
|
|
2002
|
+
if (err instanceof Error) return err.message;
|
|
2003
|
+
return String(err);
|
|
2004
|
+
}
|
|
2005
|
+
|
|
2006
|
+
//#endregion
|
|
2007
|
+
//#region ../../packages/substrate-server-fastify/src/translate.ts
|
|
2008
|
+
/**
|
|
2009
|
+
* Fastify <-> Substrate translators. The only file (along with
|
|
2010
|
+
* fastify-substrate-server.ts) that may import from `fastify`. Nothing from
|
|
2011
|
+
* `fastify` leaks out of this module.
|
|
2012
|
+
*
|
|
2013
|
+
* Body rule:
|
|
2014
|
+
* - No Content-Length AND no buffered body -> `null`
|
|
2015
|
+
* - Content-Length: 0 or empty buffered body -> `Buffer.alloc(0)`
|
|
2016
|
+
* - Otherwise -> Buffer with the bytes the parser produced
|
|
2017
|
+
*
|
|
2018
|
+
* Header rule:
|
|
2019
|
+
* - Fastify normalizes header names to lowercase; we preserve that.
|
|
2020
|
+
* - Array-valued headers (e.g. set-cookie on inbound, rare) are joined with
|
|
2021
|
+
* ", " which matches the RFC 7230 field-value folding rule the rest of the
|
|
2022
|
+
* ecosystem assumes. `set-cookie` on responses is a known exception, but
|
|
2023
|
+
* inbound requests never carry multiple set-cookie headers so the join is
|
|
2024
|
+
* safe for the SubstrateRequest direction.
|
|
2025
|
+
*/
|
|
2026
|
+
const HTTP_METHODS = /* @__PURE__ */ new Set([
|
|
2027
|
+
"GET",
|
|
2028
|
+
"POST",
|
|
2029
|
+
"PUT",
|
|
2030
|
+
"DELETE",
|
|
2031
|
+
"PATCH",
|
|
2032
|
+
"HEAD",
|
|
2033
|
+
"OPTIONS"
|
|
2034
|
+
]);
|
|
2035
|
+
function coerceMethod(raw) {
|
|
2036
|
+
const upper = raw.toUpperCase();
|
|
2037
|
+
if (!HTTP_METHODS.has(upper)) throw new Error(`Unsupported HTTP method: ${raw}`);
|
|
2038
|
+
return upper;
|
|
2039
|
+
}
|
|
2040
|
+
function stripQuery(url) {
|
|
2041
|
+
const q = url.indexOf("?");
|
|
2042
|
+
return q === -1 ? url : url.slice(0, q);
|
|
2043
|
+
}
|
|
2044
|
+
function flattenHeaders(raw) {
|
|
2045
|
+
const out = {};
|
|
2046
|
+
for (const [k, v] of Object.entries(raw)) {
|
|
2047
|
+
if (v === void 0) continue;
|
|
2048
|
+
if (Array.isArray(v)) out[k] = v.join(", ");
|
|
2049
|
+
else if (typeof v === "number") out[k] = String(v);
|
|
2050
|
+
else out[k] = v;
|
|
2051
|
+
}
|
|
2052
|
+
return out;
|
|
2053
|
+
}
|
|
2054
|
+
function flattenQuery(raw) {
|
|
2055
|
+
if (raw === null || typeof raw !== "object") return {};
|
|
2056
|
+
const out = {};
|
|
2057
|
+
for (const [k, v] of Object.entries(raw)) {
|
|
2058
|
+
if (v === void 0 || v === null) continue;
|
|
2059
|
+
if (Array.isArray(v)) {
|
|
2060
|
+
const first = v[0];
|
|
2061
|
+
if (first === void 0 || first === null) continue;
|
|
2062
|
+
out[k] = String(first);
|
|
2063
|
+
} else out[k] = String(v);
|
|
2064
|
+
}
|
|
2065
|
+
return out;
|
|
2066
|
+
}
|
|
2067
|
+
function flattenParams(raw) {
|
|
2068
|
+
if (raw === null || typeof raw !== "object") return {};
|
|
2069
|
+
const out = {};
|
|
2070
|
+
for (const [k, v] of Object.entries(raw)) {
|
|
2071
|
+
if (v === void 0 || v === null) continue;
|
|
2072
|
+
out[k] = String(v);
|
|
2073
|
+
}
|
|
2074
|
+
return out;
|
|
2075
|
+
}
|
|
2076
|
+
function coerceBody(req) {
|
|
2077
|
+
const body = req.body;
|
|
2078
|
+
const cl = req.headers["content-length"];
|
|
2079
|
+
const hasContentLength = typeof cl === "string" && cl.length > 0;
|
|
2080
|
+
if (body === void 0 || body === null) return hasContentLength ? Buffer.alloc(0) : null;
|
|
2081
|
+
if (Buffer.isBuffer(body)) return body;
|
|
2082
|
+
if (body instanceof Uint8Array) return Buffer.from(body);
|
|
2083
|
+
if (typeof body === "string") return Buffer.from(body, "utf8");
|
|
2084
|
+
return Buffer.from(JSON.stringify(body), "utf8");
|
|
2085
|
+
}
|
|
2086
|
+
function toSubstrateRequest(req, signal) {
|
|
2087
|
+
return {
|
|
2088
|
+
method: coerceMethod(req.method),
|
|
2089
|
+
path: stripQuery(req.url),
|
|
2090
|
+
headers: flattenHeaders(req.headers),
|
|
2091
|
+
query: flattenQuery(req.query),
|
|
2092
|
+
params: flattenParams(req.params),
|
|
2093
|
+
body: coerceBody(req),
|
|
2094
|
+
...typeof req.ip === "string" && req.ip.length > 0 ? { peerIp: req.ip } : {},
|
|
2095
|
+
...signal !== void 0 ? { signal } : {}
|
|
2096
|
+
};
|
|
2097
|
+
}
|
|
2098
|
+
async function applySubstrateResponse(reply, res) {
|
|
2099
|
+
reply.status(res.status);
|
|
2100
|
+
if (res.headers) for (const [k, v] of Object.entries(res.headers)) reply.header(k, v);
|
|
2101
|
+
const body = res.body;
|
|
2102
|
+
if (body === void 0) {
|
|
2103
|
+
await reply.send();
|
|
2104
|
+
return;
|
|
2105
|
+
}
|
|
2106
|
+
if (typeof body === "string") {
|
|
2107
|
+
await reply.send(body);
|
|
2108
|
+
return;
|
|
2109
|
+
}
|
|
2110
|
+
if (Buffer.isBuffer(body)) {
|
|
2111
|
+
await reply.send(body);
|
|
2112
|
+
return;
|
|
2113
|
+
}
|
|
2114
|
+
if (body instanceof Uint8Array) {
|
|
2115
|
+
await reply.send(Buffer.from(body));
|
|
2116
|
+
return;
|
|
2117
|
+
}
|
|
2118
|
+
await reply.send(Readable.fromWeb(body));
|
|
2119
|
+
}
|
|
2120
|
+
|
|
2121
|
+
//#endregion
|
|
2122
|
+
//#region ../../packages/substrate-server-fastify/src/fastify-server.ts
|
|
2123
|
+
/**
|
|
2124
|
+
* Reference SubstrateServer backed by Fastify 5.x.
|
|
2125
|
+
*
|
|
2126
|
+
* TLS design call: Fastify requires the https options at construction time, so
|
|
2127
|
+
* `tls` must be passed to the constructor. Passing `tls` on `start()` when the
|
|
2128
|
+
* instance was built without it is a programming error and throws — we do not
|
|
2129
|
+
* silently re-construct.
|
|
2130
|
+
*
|
|
2131
|
+
* onError design call: we register BOTH `setErrorHandler` and the `onError`
|
|
2132
|
+
* hook. The `onError` hook fires for errors that surface inside the request
|
|
2133
|
+
* lifecycle (including those thrown by handlers before the reply is sent); the
|
|
2134
|
+
* `setErrorHandler` override preserves Fastify's default 500 response shape
|
|
2135
|
+
* while still invoking the user hook. A per-request WeakSet guard stops the
|
|
2136
|
+
* hook from firing twice for the same error.
|
|
2137
|
+
*
|
|
2138
|
+
* createPluginRouter design call: plugin routes are mounted under
|
|
2139
|
+
* `/substrate/v1/plugins/<name>` so they can never shadow `/substrate/v1/*` and two plugins
|
|
2140
|
+
* declaring the same subpath (e.g. `/ping`) stay isolated. The facade
|
|
2141
|
+
* prefixes every path before handing it to `registerRoute` / `registerWsRoute`
|
|
2142
|
+
* — the main Fastify instance still sees one flat routing table.
|
|
2143
|
+
*
|
|
2144
|
+
* start() twice: Fastify's listen() rejects on a second call. We surface that
|
|
2145
|
+
* error as-is rather than caching and returning the prior address — the
|
|
2146
|
+
* caller's intent is ambiguous, fail loudly.
|
|
2147
|
+
*/
|
|
2148
|
+
const DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
|
|
2149
|
+
const DEFAULT_WS_MAX_PAYLOAD = 1 << 20;
|
|
2150
|
+
const DEFAULT_WS_MAX_BUFFERED = 16 << 20;
|
|
2151
|
+
/** How long a buffer-full socket gets to finish its close handshake before it is dropped. */
|
|
2152
|
+
const WS_CLOSE_GRACE_MS = 1e3;
|
|
2153
|
+
const HANDLED_ERRORS = /* @__PURE__ */ new WeakSet();
|
|
2154
|
+
var FastifySubstrateServer = class {
|
|
2155
|
+
fastify;
|
|
2156
|
+
hasTls;
|
|
2157
|
+
errorHook;
|
|
2158
|
+
#observer;
|
|
2159
|
+
#inFlightObserver;
|
|
2160
|
+
inFlight = /* @__PURE__ */ new Set();
|
|
2161
|
+
inFlightWs = /* @__PURE__ */ new Map();
|
|
2162
|
+
#shutdownHooks = /* @__PURE__ */ new Set();
|
|
2163
|
+
#streamedResponses = /* @__PURE__ */ new Set();
|
|
2164
|
+
#wsMaxBuffered;
|
|
2165
|
+
#onWarn;
|
|
2166
|
+
constructor(options = {}) {
|
|
2167
|
+
const { logger = false, bodyLimit, tls, cors, compression = true, requestTimeout = DEFAULT_REQUEST_TIMEOUT_MS, wsMaxPayload = DEFAULT_WS_MAX_PAYLOAD, wsMaxBuffered = DEFAULT_WS_MAX_BUFFERED, onWarn } = options;
|
|
2168
|
+
this.#wsMaxBuffered = wsMaxBuffered;
|
|
2169
|
+
this.#onWarn = onWarn;
|
|
2170
|
+
this.hasTls = tls !== void 0;
|
|
2171
|
+
const common = {
|
|
2172
|
+
logger,
|
|
2173
|
+
requestTimeout,
|
|
2174
|
+
...bodyLimit !== void 0 ? { bodyLimit } : {}
|
|
2175
|
+
};
|
|
2176
|
+
if (tls) {
|
|
2177
|
+
const httpsOptions = {
|
|
2178
|
+
cert: tls.cert,
|
|
2179
|
+
key: tls.key,
|
|
2180
|
+
...tls.ca !== void 0 ? { ca: tls.ca } : {}
|
|
2181
|
+
};
|
|
2182
|
+
this.fastify = Fastify({
|
|
2183
|
+
...common,
|
|
2184
|
+
https: httpsOptions
|
|
2185
|
+
});
|
|
2186
|
+
} else this.fastify = Fastify(common);
|
|
2187
|
+
this.fastify.addContentTypeParser("application/octet-stream", { parseAs: "buffer" }, (_req, body, done) => done(null, body));
|
|
2188
|
+
this.fastify.addContentTypeParser("application/vnd.substrate.pack", { parseAs: "buffer" }, (_req, body, done) => done(null, body));
|
|
2189
|
+
this.fastify.setErrorHandler((err, req, reply) => {
|
|
2190
|
+
this.invokeErrorHook(err, req);
|
|
2191
|
+
const statusCode = err.statusCode ?? 500;
|
|
2192
|
+
const internal = statusCode >= 500;
|
|
2193
|
+
reply.status(statusCode).header("content-type", "application/json; charset=utf-8").send({
|
|
2194
|
+
schemaVersion: "",
|
|
2195
|
+
data: {},
|
|
2196
|
+
shapes: {},
|
|
2197
|
+
errors: [internal ? {
|
|
2198
|
+
message: "internal server error",
|
|
2199
|
+
code: "internal_error"
|
|
2200
|
+
} : {
|
|
2201
|
+
message: err.message,
|
|
2202
|
+
code: typeof err.code === "string" && err.code.length > 0 ? err.code : "request_error"
|
|
2203
|
+
}]
|
|
2204
|
+
});
|
|
2205
|
+
});
|
|
2206
|
+
this.fastify.addHook("onError", async (req, _reply, err) => {
|
|
2207
|
+
this.invokeErrorHook(err, req);
|
|
2208
|
+
});
|
|
2209
|
+
if (compression) this.fastify.register(compressPlugin, { threshold: 1024 });
|
|
2210
|
+
if (cors !== void 0) this.fastify.register(corsPlugin, {
|
|
2211
|
+
origin: cors.origins === "*" ? "*" : cors.origins,
|
|
2212
|
+
credentials: cors.credentials ?? cors.origins !== "*",
|
|
2213
|
+
methods: [
|
|
2214
|
+
"GET",
|
|
2215
|
+
"POST",
|
|
2216
|
+
"PUT",
|
|
2217
|
+
"PATCH",
|
|
2218
|
+
"DELETE",
|
|
2219
|
+
"OPTIONS"
|
|
2220
|
+
],
|
|
2221
|
+
allowedHeaders: [
|
|
2222
|
+
"Authorization",
|
|
2223
|
+
"Content-Type",
|
|
2224
|
+
"Accept"
|
|
2225
|
+
]
|
|
2226
|
+
});
|
|
2227
|
+
this.fastify.register(websocketPlugin, { options: { maxPayload: wsMaxPayload } });
|
|
2228
|
+
}
|
|
2229
|
+
invokeErrorHook(err, req) {
|
|
2230
|
+
if (!this.errorHook) return;
|
|
2231
|
+
if (HANDLED_ERRORS.has(err)) return;
|
|
2232
|
+
HANDLED_ERRORS.add(err);
|
|
2233
|
+
try {
|
|
2234
|
+
this.errorHook(err, req ? toSubstrateRequest(req) : void 0);
|
|
2235
|
+
} catch {}
|
|
2236
|
+
}
|
|
2237
|
+
async start(opts) {
|
|
2238
|
+
if (opts?.tls && !this.hasTls) throw new Error("FastifySubstrateServer: tls must be supplied at construction time, not to start()");
|
|
2239
|
+
const host = opts?.host ?? "0.0.0.0";
|
|
2240
|
+
const port = opts?.port ?? 0;
|
|
2241
|
+
await this.fastify.ready();
|
|
2242
|
+
const address = await this.fastify.listen({
|
|
2243
|
+
host,
|
|
2244
|
+
port
|
|
2245
|
+
});
|
|
2246
|
+
const info = this.fastify.addresses()[0];
|
|
2247
|
+
if (!info) {
|
|
2248
|
+
const match = /:(\d+)$/.exec(address);
|
|
2249
|
+
return {
|
|
2250
|
+
address: host,
|
|
2251
|
+
port: match?.[1] ? Number.parseInt(match[1], 10) : port
|
|
2252
|
+
};
|
|
2253
|
+
}
|
|
2254
|
+
return {
|
|
2255
|
+
address: info.address,
|
|
2256
|
+
port: info.port
|
|
2257
|
+
};
|
|
2258
|
+
}
|
|
2259
|
+
async stop(opts) {
|
|
2260
|
+
this.notifyWsShutdown(WS_REASON_SERVER_RESTART);
|
|
2261
|
+
this.#notifyShutdown(WS_REASON_SERVER_RESTART);
|
|
2262
|
+
if (opts?.abortInFlight === true) this.abortAllRequests("server_shutdown");
|
|
2263
|
+
const grace = opts?.grace;
|
|
2264
|
+
if (grace === void 0) {
|
|
2265
|
+
await this.#drainThenClose();
|
|
2266
|
+
return;
|
|
2267
|
+
}
|
|
2268
|
+
await Promise.race([this.#drainThenClose(), new Promise((resolve) => {
|
|
2269
|
+
setTimeout(resolve, grace).unref();
|
|
2270
|
+
})]);
|
|
2271
|
+
}
|
|
2272
|
+
/**
|
|
2273
|
+
* Let streamed responses finish before handing off to `fastify.close()`.
|
|
2274
|
+
*
|
|
2275
|
+
* `close()` takes exactly ONE pass at reaping idle keep-alive connections. A
|
|
2276
|
+
* socket still flushing its final bytes at that instant survives the pass,
|
|
2277
|
+
* and nothing revisits it — so `close()` waits on a connection that will
|
|
2278
|
+
* never be reaped, and a bare `stop()` never returns.
|
|
2279
|
+
*
|
|
2280
|
+
* Unbounded on purpose: `fastify.close()` already waits on in-flight
|
|
2281
|
+
* requests, so a route that ignores the shutdown notice blocks `stop()`
|
|
2282
|
+
* anyway. Callers who need a ceiling pass `grace`, which races this whole
|
|
2283
|
+
* sequence.
|
|
2284
|
+
*/
|
|
2285
|
+
async #drainThenClose() {
|
|
2286
|
+
await Promise.all([...this.#streamedResponses]);
|
|
2287
|
+
await new Promise((resolve) => {
|
|
2288
|
+
setImmediate(resolve);
|
|
2289
|
+
});
|
|
2290
|
+
await this.fastify.close();
|
|
2291
|
+
}
|
|
2292
|
+
abortAllRequests(reason) {
|
|
2293
|
+
const controllers = [...this.inFlight];
|
|
2294
|
+
for (const controller of controllers) if (!controller.signal.aborted) controller.abort(reason ?? "aborted");
|
|
2295
|
+
}
|
|
2296
|
+
onShutdown(cb) {
|
|
2297
|
+
this.#shutdownHooks.add(cb);
|
|
2298
|
+
}
|
|
2299
|
+
/**
|
|
2300
|
+
* Fan the shutdown notice out to every registered route hook. Synchronous so
|
|
2301
|
+
* a hook's final writes are queued before `fastify.close()` starts draining.
|
|
2302
|
+
*/
|
|
2303
|
+
#notifyShutdown(reason) {
|
|
2304
|
+
for (const hook of [...this.#shutdownHooks]) try {
|
|
2305
|
+
hook(reason);
|
|
2306
|
+
} catch {}
|
|
2307
|
+
}
|
|
2308
|
+
/**
|
|
2309
|
+
* Walk every live WS connection and invoke its registered shutdown emitter,
|
|
2310
|
+
* then close the socket with code 1012 (Service Restart). Synchronous so
|
|
2311
|
+
* frames flush before the @fastify/websocket plugin's close pass runs.
|
|
2312
|
+
*/
|
|
2313
|
+
notifyWsShutdown(reason) {
|
|
2314
|
+
const entries = [...this.inFlightWs.entries()];
|
|
2315
|
+
for (const [conn, emit] of entries) {
|
|
2316
|
+
try {
|
|
2317
|
+
emit?.(reason);
|
|
2318
|
+
} catch {}
|
|
2319
|
+
try {
|
|
2320
|
+
conn.close(1012, reason);
|
|
2321
|
+
} catch {}
|
|
2322
|
+
}
|
|
2323
|
+
}
|
|
2324
|
+
/**
|
|
2325
|
+
* Wrap an HTTP-method route in a child plugin so it lands in the plugin
|
|
2326
|
+
* queue *after* compress / cors / websocket have finished loading.
|
|
2327
|
+
* @fastify/compress installs an `onRoute` hook that decorates each route
|
|
2328
|
+
* with compression metadata; routes added directly to the parent scope
|
|
2329
|
+
* before ready() runs miss that hook and are never compressed.
|
|
2330
|
+
*
|
|
2331
|
+
* Done-callback form (not `async`) because registerRoute is synchronous —
|
|
2332
|
+
* no extra Promise to discard.
|
|
2333
|
+
*/
|
|
2334
|
+
#registerWrapped(method, path, handler, inFlight = this.inFlight) {
|
|
2335
|
+
this.fastify.register((scope, _opts, done) => {
|
|
2336
|
+
registerRoute(scope, method, path, handler, inFlight, this.#streamedResponses);
|
|
2337
|
+
done();
|
|
2338
|
+
});
|
|
2339
|
+
}
|
|
2340
|
+
/** Same ordering guarantee as #registerWrapped but for WebSocket routes. */
|
|
2341
|
+
#registerWsWrapped(path, handler) {
|
|
2342
|
+
this.fastify.register((scope, _opts, done) => {
|
|
2343
|
+
registerWsRoute(scope, path, handler, this.inFlightWs, (err) => this.invokeErrorHook(err), this.#wsMaxBuffered, this.#onWarn ?? ((message) => scope.log.warn(message)));
|
|
2344
|
+
done();
|
|
2345
|
+
});
|
|
2346
|
+
}
|
|
2347
|
+
route(method, path, handler) {
|
|
2348
|
+
this.#registerWrapped(method, path, this.#instrument(method, path, handler));
|
|
2349
|
+
}
|
|
2350
|
+
#instrument(method, path, handler) {
|
|
2351
|
+
const op = method === "POST" && path === "/substrate/v1/query" ? "query" : method === "POST" && path === "/substrate/v1/mutate" ? "mutate" : null;
|
|
2352
|
+
if (op === null) return handler;
|
|
2353
|
+
return async (req) => {
|
|
2354
|
+
const inflight = this.#inFlightObserver;
|
|
2355
|
+
this.#notifyInFlight(inflight, op, 1);
|
|
2356
|
+
try {
|
|
2357
|
+
const startedAt = Date.now();
|
|
2358
|
+
const res = await handler(req);
|
|
2359
|
+
const obs = this.#observer;
|
|
2360
|
+
if (obs !== void 0) try {
|
|
2361
|
+
obs({
|
|
2362
|
+
op,
|
|
2363
|
+
ok: res.status < 400,
|
|
2364
|
+
durationMs: Date.now() - startedAt
|
|
2365
|
+
});
|
|
2366
|
+
} catch {}
|
|
2367
|
+
return res;
|
|
2368
|
+
} finally {
|
|
2369
|
+
this.#notifyInFlight(inflight, op, -1);
|
|
2370
|
+
}
|
|
2371
|
+
};
|
|
2372
|
+
}
|
|
2373
|
+
#notifyInFlight(fn, op, delta) {
|
|
2374
|
+
if (fn === void 0) return;
|
|
2375
|
+
try {
|
|
2376
|
+
fn(op, delta);
|
|
2377
|
+
} catch {}
|
|
2378
|
+
}
|
|
2379
|
+
observeInFlight(fn) {
|
|
2380
|
+
this.#inFlightObserver = fn;
|
|
2381
|
+
}
|
|
2382
|
+
observeRequests(observer) {
|
|
2383
|
+
this.#observer = observer;
|
|
2384
|
+
}
|
|
2385
|
+
websocket(path, handler) {
|
|
2386
|
+
this.#registerWsWrapped(path, handler);
|
|
2387
|
+
}
|
|
2388
|
+
onError(hook) {
|
|
2389
|
+
this.errorHook = hook;
|
|
2390
|
+
}
|
|
2391
|
+
createPluginRouter(plugin) {
|
|
2392
|
+
const prefix = `/substrate/v1/plugins/${plugin.name}`;
|
|
2393
|
+
const prefixed = (path) => `${prefix}${path.length === 0 ? "/" : path.startsWith("/") ? path : `/${path}`}`;
|
|
2394
|
+
const verbEntries = [
|
|
2395
|
+
"GET",
|
|
2396
|
+
"POST",
|
|
2397
|
+
"PUT",
|
|
2398
|
+
"DELETE",
|
|
2399
|
+
"PATCH"
|
|
2400
|
+
].map((method) => [method.toLowerCase(), (path, handler) => this.#registerWrapped(method, prefixed(path), handler, this.inFlight)]);
|
|
2401
|
+
return {
|
|
2402
|
+
...Object.fromEntries(verbEntries),
|
|
2403
|
+
websocket: (path, handler) => this.#registerWsWrapped(prefixed(path), handler)
|
|
2404
|
+
};
|
|
2405
|
+
}
|
|
2406
|
+
async inject(req) {
|
|
2407
|
+
await this.fastify.ready();
|
|
2408
|
+
const method = req.method ?? "GET";
|
|
2409
|
+
const url = buildInjectUrl(req.path ?? "/", req.query ?? {});
|
|
2410
|
+
const headers = { ...req.headers ?? {} };
|
|
2411
|
+
const payload = req.body ?? void 0;
|
|
2412
|
+
const injectOpts = {
|
|
2413
|
+
method,
|
|
2414
|
+
url,
|
|
2415
|
+
headers,
|
|
2416
|
+
...payload !== void 0 ? { payload } : {}
|
|
2417
|
+
};
|
|
2418
|
+
const result = await this.fastify.inject(injectOpts);
|
|
2419
|
+
const rawHeaders = result.headers;
|
|
2420
|
+
const outHeaders = {};
|
|
2421
|
+
for (const [k, v] of Object.entries(rawHeaders)) {
|
|
2422
|
+
if (v === void 0) continue;
|
|
2423
|
+
outHeaders[k] = Array.isArray(v) ? v.join(", ") : String(v);
|
|
2424
|
+
}
|
|
2425
|
+
return {
|
|
2426
|
+
status: result.statusCode,
|
|
2427
|
+
headers: outHeaders,
|
|
2428
|
+
body: result.rawPayload
|
|
2429
|
+
};
|
|
2430
|
+
}
|
|
2431
|
+
};
|
|
2432
|
+
function buildInjectUrl(path, query) {
|
|
2433
|
+
const keys = Object.keys(query);
|
|
2434
|
+
if (keys.length === 0) return path;
|
|
2435
|
+
const qs = new URLSearchParams();
|
|
2436
|
+
for (const k of keys) {
|
|
2437
|
+
const v = query[k];
|
|
2438
|
+
if (v !== void 0) qs.set(k, v);
|
|
2439
|
+
}
|
|
2440
|
+
return `${path}${path.includes("?") ? "&" : "?"}${qs.toString()}`;
|
|
2441
|
+
}
|
|
2442
|
+
/**
|
|
2443
|
+
* Register a response that streams its body, resolving when the underlying
|
|
2444
|
+
* socket finishes (`close` covers both a completed response and a torn-down
|
|
2445
|
+
* connection). `stop()` awaits these so it never calls `fastify.close()` while
|
|
2446
|
+
* a socket is mid-flush.
|
|
2447
|
+
*/
|
|
2448
|
+
function trackStreamedResponse(reply, streamed) {
|
|
2449
|
+
let settle;
|
|
2450
|
+
const finished = new Promise((resolve) => {
|
|
2451
|
+
settle = resolve;
|
|
2452
|
+
});
|
|
2453
|
+
streamed.add(finished);
|
|
2454
|
+
reply.raw.once("close", () => {
|
|
2455
|
+
streamed.delete(finished);
|
|
2456
|
+
settle();
|
|
2457
|
+
});
|
|
2458
|
+
}
|
|
2459
|
+
function registerRoute(fastify, method, path, handler, inFlight, streamed) {
|
|
2460
|
+
fastify.route({
|
|
2461
|
+
method,
|
|
2462
|
+
url: path,
|
|
2463
|
+
handler: async (req, reply) => {
|
|
2464
|
+
const controller = new AbortController();
|
|
2465
|
+
inFlight.add(controller);
|
|
2466
|
+
const onResponseClose = () => {
|
|
2467
|
+
if (!reply.raw.writableFinished && !controller.signal.aborted) controller.abort("client_disconnect");
|
|
2468
|
+
};
|
|
2469
|
+
reply.raw.once("close", onResponseClose);
|
|
2470
|
+
try {
|
|
2471
|
+
const hRes = await handler(toSubstrateRequest(req, controller.signal));
|
|
2472
|
+
if (hRes.body instanceof ReadableStream) trackStreamedResponse(reply, streamed);
|
|
2473
|
+
await applySubstrateResponse(reply, hRes);
|
|
2474
|
+
} finally {
|
|
2475
|
+
reply.raw.off("close", onResponseClose);
|
|
2476
|
+
inFlight.delete(controller);
|
|
2477
|
+
}
|
|
2478
|
+
}
|
|
2479
|
+
});
|
|
2480
|
+
}
|
|
2481
|
+
function registerWsRoute(fastify, path, handler, inFlightWs, onHandlerError, maxBuffered, warn) {
|
|
2482
|
+
const wsHandler = (socket, req) => {
|
|
2483
|
+
const substrateReq = {
|
|
2484
|
+
...toSubstrateRequest(req),
|
|
2485
|
+
body: null
|
|
2486
|
+
};
|
|
2487
|
+
let shutdownEmitter = null;
|
|
2488
|
+
let bufferFull = false;
|
|
2489
|
+
const conn = {
|
|
2490
|
+
id: randomUUID(),
|
|
2491
|
+
send(frame) {
|
|
2492
|
+
if (bufferFull) return;
|
|
2493
|
+
if (socket.bufferedAmount > maxBuffered) {
|
|
2494
|
+
bufferFull = true;
|
|
2495
|
+
warn(`websocket ${path} conn ${conn.id}: send buffer full (${socket.bufferedAmount} > ${maxBuffered} bytes); closing 1013`);
|
|
2496
|
+
socket.close(1013, "send_buffer_full");
|
|
2497
|
+
setTimeout(() => socket.terminate(), WS_CLOSE_GRACE_MS).unref?.();
|
|
2498
|
+
return;
|
|
2499
|
+
}
|
|
2500
|
+
if (typeof frame === "string") socket.send(frame);
|
|
2501
|
+
else if (Buffer.isBuffer(frame)) socket.send(frame);
|
|
2502
|
+
else socket.send(Buffer.from(frame));
|
|
2503
|
+
},
|
|
2504
|
+
drain() {
|
|
2505
|
+
const HIGH_WATER = 1 << 20;
|
|
2506
|
+
if (socket.bufferedAmount <= HIGH_WATER || socket.readyState !== 1) return Promise.resolve();
|
|
2507
|
+
return new Promise((resolve) => {
|
|
2508
|
+
const check = () => {
|
|
2509
|
+
if (socket.readyState !== 1 || socket.bufferedAmount <= HIGH_WATER) {
|
|
2510
|
+
resolve();
|
|
2511
|
+
return;
|
|
2512
|
+
}
|
|
2513
|
+
setTimeout(check, 10).unref?.();
|
|
2514
|
+
};
|
|
2515
|
+
setTimeout(check, 10).unref?.();
|
|
2516
|
+
});
|
|
2517
|
+
},
|
|
2518
|
+
onMessage(cb) {
|
|
2519
|
+
socket.on("message", (buf) => {
|
|
2520
|
+
cb(Buffer.isBuffer(buf) ? buf : Buffer.from(buf));
|
|
2521
|
+
});
|
|
2522
|
+
},
|
|
2523
|
+
onClose(cb) {
|
|
2524
|
+
socket.on("close", (code) => {
|
|
2525
|
+
cb(code);
|
|
2526
|
+
});
|
|
2527
|
+
},
|
|
2528
|
+
close(code, reason) {
|
|
2529
|
+
socket.close(code, reason);
|
|
2530
|
+
},
|
|
2531
|
+
onShutdown(cb) {
|
|
2532
|
+
shutdownEmitter = cb;
|
|
2533
|
+
inFlightWs.set(conn, shutdownEmitter);
|
|
2534
|
+
}
|
|
2535
|
+
};
|
|
2536
|
+
inFlightWs.set(conn, null);
|
|
2537
|
+
socket.on("close", () => {
|
|
2538
|
+
inFlightWs.delete(conn);
|
|
2539
|
+
});
|
|
2540
|
+
const fail = (err) => {
|
|
2541
|
+
onHandlerError(err instanceof Error ? err : new Error(String(err)));
|
|
2542
|
+
socket.close(1011, "internal error");
|
|
2543
|
+
};
|
|
2544
|
+
try {
|
|
2545
|
+
Promise.resolve(handler(substrateReq, conn)).catch(fail);
|
|
2546
|
+
} catch (err) {
|
|
2547
|
+
fail(err);
|
|
2548
|
+
}
|
|
2549
|
+
};
|
|
2550
|
+
fastify.route({
|
|
2551
|
+
method: "GET",
|
|
2552
|
+
url: path,
|
|
2553
|
+
handler: (_req, reply) => {
|
|
2554
|
+
reply.status(426).send({ error: "Upgrade Required" });
|
|
2555
|
+
},
|
|
2556
|
+
wsHandler
|
|
2557
|
+
});
|
|
2558
|
+
}
|
|
2559
|
+
|
|
2560
|
+
//#endregion
|
|
2561
|
+
//#region ../../packages/substrate-sentinel-client/src/client.ts
|
|
2562
|
+
/**
|
|
2563
|
+
* substrate-sentinel-client — watches a sentinel instance's WS topology stream and
|
|
2564
|
+
* mutates a caller-owned BridgeRegistry on online/offline events.
|
|
2565
|
+
*
|
|
2566
|
+
* - connect to sentinel WS, send {type:'watch'}
|
|
2567
|
+
* - on {event:'online'}: create HttpBridgeClient, register in bridges,
|
|
2568
|
+
* call engine.refreshBridgeSchemas()
|
|
2569
|
+
* - on {event:'offline'}: unregister bridge + dispose client
|
|
2570
|
+
* - on error/close: reconnect with exponential backoff
|
|
2571
|
+
* - stop(): closes WS + disposes all active bridges
|
|
2572
|
+
*/
|
|
2573
|
+
const NO_OP_METRIC = () => {};
|
|
2574
|
+
function startSentinelClient(opts) {
|
|
2575
|
+
const metric = opts.metric ?? NO_OP_METRIC;
|
|
2576
|
+
const upgradeAuth = opts.auth;
|
|
2577
|
+
const wsFactory = opts.wsFactory ?? ((url) => upgradeAuth === void 0 ? new WebSocket$1(url) : new WebSocket$1(url, { headers: { authorization: upgradeAuth() } }));
|
|
2578
|
+
const baseMs = opts.reconnectBaseMs ?? 500;
|
|
2579
|
+
const maxMs = opts.reconnectMaxMs ?? 3e4;
|
|
2580
|
+
const ownedBridges = /* @__PURE__ */ new Map();
|
|
2581
|
+
let ws = null;
|
|
2582
|
+
let stopped = false;
|
|
2583
|
+
let connected = false;
|
|
2584
|
+
let currentBackoff = baseMs;
|
|
2585
|
+
let reconnectTimer = null;
|
|
2586
|
+
function scheduleReconnect() {
|
|
2587
|
+
if (stopped) return;
|
|
2588
|
+
const delay = currentBackoff;
|
|
2589
|
+
metric("sentinel_client_reconnecting", { delayMs: delay });
|
|
2590
|
+
const timer = setTimeout(() => {
|
|
2591
|
+
reconnectTimer = null;
|
|
2592
|
+
if (stopped) return;
|
|
2593
|
+
currentBackoff = Math.min(currentBackoff * 2, maxMs);
|
|
2594
|
+
connect();
|
|
2595
|
+
}, delay);
|
|
2596
|
+
timer.unref();
|
|
2597
|
+
reconnectTimer = timer;
|
|
2598
|
+
}
|
|
2599
|
+
function connect() {
|
|
2600
|
+
if (stopped) return;
|
|
2601
|
+
const socket = wsFactory(opts.sentinelUrl);
|
|
2602
|
+
ws = socket;
|
|
2603
|
+
socket.once("open", () => {
|
|
2604
|
+
connected = true;
|
|
2605
|
+
currentBackoff = baseMs;
|
|
2606
|
+
metric("sentinel_client_connected");
|
|
2607
|
+
socket.send(JSON.stringify({ type: "watch" }));
|
|
2608
|
+
});
|
|
2609
|
+
socket.on("message", (buf) => {
|
|
2610
|
+
let frame;
|
|
2611
|
+
try {
|
|
2612
|
+
frame = JSON.parse(buf.toString("utf8"));
|
|
2613
|
+
} catch {
|
|
2614
|
+
return;
|
|
2615
|
+
}
|
|
2616
|
+
if (frame.event === "online") handleOnline(frame);
|
|
2617
|
+
else if (frame.event === "offline") handleOffline(frame);
|
|
2618
|
+
else if (typeof frame.error === "string") metric("sentinel_client_error", { error: frame.error });
|
|
2619
|
+
});
|
|
2620
|
+
socket.once("close", () => {
|
|
2621
|
+
connected = false;
|
|
2622
|
+
metric("sentinel_client_disconnected");
|
|
2623
|
+
scheduleReconnect();
|
|
2624
|
+
});
|
|
2625
|
+
socket.once("error", () => {});
|
|
2626
|
+
}
|
|
2627
|
+
async function handleOnline(frame) {
|
|
2628
|
+
const name = typeof frame.name === "string" ? frame.name : void 0;
|
|
2629
|
+
const url = typeof frame.url === "string" ? frame.url : void 0;
|
|
2630
|
+
const namespaces = Array.isArray(frame.namespaces) ? frame.namespaces : [];
|
|
2631
|
+
if (name === void 0 || url === void 0) return;
|
|
2632
|
+
const cred = opts.creds.get(name);
|
|
2633
|
+
if (cred === void 0) {
|
|
2634
|
+
metric("bridge_discovery_rejected", {
|
|
2635
|
+
name,
|
|
2636
|
+
url
|
|
2637
|
+
});
|
|
2638
|
+
return;
|
|
2639
|
+
}
|
|
2640
|
+
let advertisedOrigin;
|
|
2641
|
+
try {
|
|
2642
|
+
advertisedOrigin = new URL(url).origin;
|
|
2643
|
+
} catch {
|
|
2644
|
+
metric("bridge_discovery_origin_mismatch", {
|
|
2645
|
+
name,
|
|
2646
|
+
url,
|
|
2647
|
+
expected: cred.origin
|
|
2648
|
+
});
|
|
2649
|
+
return;
|
|
2650
|
+
}
|
|
2651
|
+
if (advertisedOrigin !== cred.origin) {
|
|
2652
|
+
metric("bridge_discovery_origin_mismatch", {
|
|
2653
|
+
name,
|
|
2654
|
+
url,
|
|
2655
|
+
expected: cred.origin
|
|
2656
|
+
});
|
|
2657
|
+
return;
|
|
2658
|
+
}
|
|
2659
|
+
const auth = makeAuthorizationProvider(cred, {
|
|
2660
|
+
lazyKey: true,
|
|
2661
|
+
audience: cred.origin
|
|
2662
|
+
});
|
|
2663
|
+
for (const nsValue of namespaces) {
|
|
2664
|
+
if (stopped) return;
|
|
2665
|
+
if (typeof nsValue !== "string" || nsValue.length === 0) continue;
|
|
2666
|
+
const ns = nsValue;
|
|
2667
|
+
if (opts.bridges.has(ns)) continue;
|
|
2668
|
+
if (opts.engine.registryFor(ns) !== void 0) {
|
|
2669
|
+
metric("bridge_discovery_local_namespace", {
|
|
2670
|
+
name,
|
|
2671
|
+
ns
|
|
2672
|
+
});
|
|
2673
|
+
continue;
|
|
2674
|
+
}
|
|
2675
|
+
const client = new HttpBridgeClient({
|
|
2676
|
+
name,
|
|
2677
|
+
baseUrl: url,
|
|
2678
|
+
auth
|
|
2679
|
+
});
|
|
2680
|
+
opts.bridges.register(ns, client);
|
|
2681
|
+
ownedBridges.set(ns, client);
|
|
2682
|
+
metric("sentinel_client_online", {
|
|
2683
|
+
ns,
|
|
2684
|
+
url
|
|
2685
|
+
});
|
|
2686
|
+
try {
|
|
2687
|
+
await opts.engine.refreshBridgeSchemas();
|
|
2688
|
+
} catch {
|
|
2689
|
+
metric("sentinel_client_refresh_failed", { ns });
|
|
2690
|
+
}
|
|
2691
|
+
if (stopped) {
|
|
2692
|
+
try {
|
|
2693
|
+
opts.bridges.unregister(ns);
|
|
2694
|
+
} catch {}
|
|
2695
|
+
client.dispose();
|
|
2696
|
+
ownedBridges.delete(ns);
|
|
2697
|
+
return;
|
|
2698
|
+
}
|
|
2699
|
+
}
|
|
2700
|
+
}
|
|
2701
|
+
function handleOffline(frame) {
|
|
2702
|
+
const name = typeof frame.name === "string" ? frame.name : void 0;
|
|
2703
|
+
const raw = typeof frame.url === "string" ? frame.url : void 0;
|
|
2704
|
+
if (name === void 0 || raw === void 0) return;
|
|
2705
|
+
const url = raw.endsWith("/") ? raw.slice(0, -1) : raw;
|
|
2706
|
+
for (const [ns, client] of [...ownedBridges]) {
|
|
2707
|
+
if (client.baseUrl !== url || client.name !== name) continue;
|
|
2708
|
+
try {
|
|
2709
|
+
opts.bridges.unregister(ns);
|
|
2710
|
+
} catch {}
|
|
2711
|
+
client.dispose();
|
|
2712
|
+
ownedBridges.delete(ns);
|
|
2713
|
+
metric("sentinel_client_offline", { ns });
|
|
2714
|
+
}
|
|
2715
|
+
}
|
|
2716
|
+
connect();
|
|
2717
|
+
return {
|
|
2718
|
+
isConnected: () => connected,
|
|
2719
|
+
stop: async () => {
|
|
2720
|
+
if (stopped) return;
|
|
2721
|
+
stopped = true;
|
|
2722
|
+
if (reconnectTimer !== null) {
|
|
2723
|
+
clearTimeout(reconnectTimer);
|
|
2724
|
+
reconnectTimer = null;
|
|
2725
|
+
}
|
|
2726
|
+
for (const [ns, client] of ownedBridges) {
|
|
2727
|
+
try {
|
|
2728
|
+
opts.bridges.unregister(ns);
|
|
2729
|
+
} catch {}
|
|
2730
|
+
client.dispose();
|
|
2731
|
+
}
|
|
2732
|
+
ownedBridges.clear();
|
|
2733
|
+
if (ws !== null && ws.readyState !== WebSocket$1.CLOSED) await new Promise((resolve) => {
|
|
2734
|
+
ws?.once("close", () => resolve());
|
|
2735
|
+
ws?.close();
|
|
2736
|
+
});
|
|
2737
|
+
}
|
|
2738
|
+
};
|
|
2739
|
+
}
|
|
2740
|
+
|
|
2741
|
+
//#endregion
|
|
2742
|
+
//#region ../../packages/substrate-sentinel-client/src/config.ts
|
|
2743
|
+
function parseCred(raw) {
|
|
2744
|
+
if (raw === void 0 || raw.trim() === "") throw new Error("SUBSTRATE_SENTINEL_URL is set but SUBSTRATE_SENTINEL_CREDENTIAL is not — sentinel requires an authenticated client");
|
|
2745
|
+
let parsed;
|
|
2746
|
+
try {
|
|
2747
|
+
parsed = JSON.parse(raw);
|
|
2748
|
+
} catch (err) {
|
|
2749
|
+
throw new Error(`SUBSTRATE_SENTINEL_CREDENTIAL: invalid JSON — ${err instanceof Error ? err.message : String(err)}`);
|
|
2750
|
+
}
|
|
2751
|
+
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("SUBSTRATE_SENTINEL_CREDENTIAL: must be a JSON object of { keyPath, kid }");
|
|
2752
|
+
const e = parsed;
|
|
2753
|
+
if (typeof e.keyPath !== "string" || e.keyPath.length === 0) throw new Error("SUBSTRATE_SENTINEL_CREDENTIAL: missing string 'keyPath'");
|
|
2754
|
+
if (typeof e.kid !== "string" || e.kid.length === 0) throw new Error("SUBSTRATE_SENTINEL_CREDENTIAL: missing string 'kid'");
|
|
2755
|
+
return {
|
|
2756
|
+
keyPath: e.keyPath,
|
|
2757
|
+
kid: e.kid
|
|
2758
|
+
};
|
|
2759
|
+
}
|
|
2760
|
+
const DEFAULT_RECONNECT_BASE_MS = 500;
|
|
2761
|
+
const DEFAULT_RECONNECT_MAX_MS = 3e4;
|
|
2762
|
+
function loadConfig(env = process.env) {
|
|
2763
|
+
const rawUrl = env.SUBSTRATE_SENTINEL_URL;
|
|
2764
|
+
if (rawUrl === void 0 || rawUrl.length === 0) return null;
|
|
2765
|
+
if (!rawUrl.startsWith("ws://") && !rawUrl.startsWith("wss://")) throw new Error("SUBSTRATE_SENTINEL_URL must be a ws:// or wss:// URL");
|
|
2766
|
+
return {
|
|
2767
|
+
url: rawUrl,
|
|
2768
|
+
cred: parseCred(env.SUBSTRATE_SENTINEL_CREDENTIAL),
|
|
2769
|
+
reconnectBaseMs: parsePositiveInt(env.SUBSTRATE_SENTINEL_RECONNECT_BASE_MS, "SUBSTRATE_SENTINEL_RECONNECT_BASE_MS", DEFAULT_RECONNECT_BASE_MS),
|
|
2770
|
+
reconnectMaxMs: parsePositiveInt(env.SUBSTRATE_SENTINEL_RECONNECT_MAX_MS, "SUBSTRATE_SENTINEL_RECONNECT_MAX_MS", DEFAULT_RECONNECT_MAX_MS)
|
|
2771
|
+
};
|
|
2772
|
+
}
|
|
2773
|
+
|
|
2774
|
+
//#endregion
|
|
2775
|
+
//#region src/serve/knobs.ts
|
|
2776
|
+
/** Treat explicitly-empty string env values as unset. */
|
|
2777
|
+
function nonEmpty(v) {
|
|
2778
|
+
return v !== void 0 && v !== "" ? v : void 0;
|
|
2779
|
+
}
|
|
2780
|
+
function createKnobRecorder() {
|
|
2781
|
+
const entries = /* @__PURE__ */ new Map();
|
|
2782
|
+
const sourceOf = (raw) => nonEmpty(raw) === void 0 ? "default" : "explicit";
|
|
2783
|
+
return {
|
|
2784
|
+
record(key, env, raw, value) {
|
|
2785
|
+
entries.set(key, {
|
|
2786
|
+
env,
|
|
2787
|
+
value,
|
|
2788
|
+
source: sourceOf(raw)
|
|
2789
|
+
});
|
|
2790
|
+
return value;
|
|
2791
|
+
},
|
|
2792
|
+
recordSecret(key, env, raw) {
|
|
2793
|
+
const present = nonEmpty(raw?.trim()) !== void 0;
|
|
2794
|
+
entries.set(key, {
|
|
2795
|
+
env,
|
|
2796
|
+
value: present ? "<set>" : null,
|
|
2797
|
+
source: sourceOf(raw),
|
|
2798
|
+
redacted: true
|
|
2799
|
+
});
|
|
2800
|
+
},
|
|
2801
|
+
report() {
|
|
2802
|
+
return Object.fromEntries(entries);
|
|
2803
|
+
}
|
|
2804
|
+
};
|
|
2805
|
+
}
|
|
2806
|
+
|
|
2807
|
+
//#endregion
|
|
2808
|
+
//#region src/serve/wiring.ts
|
|
2809
|
+
/**
|
|
2810
|
+
* serve/wiring.ts — substrate + bridge + dataset wiring.
|
|
2811
|
+
*
|
|
2812
|
+
* Everything `runServe()` needs between `parseEnv()` and `compose()`:
|
|
2813
|
+
* store construction, bridge registry, per-namespace datasets, migration
|
|
2814
|
+
* tracking, and the two substrate-composition singletons (filter-operator
|
|
2815
|
+
* registry, pending MCP tools).
|
|
2816
|
+
*/
|
|
2817
|
+
const filterRegistry = { register(name, op) {
|
|
2818
|
+
if (getExtensionOperator(name) !== void 0) throw new EnvConfigError(`Filter operator '${name}' already registered`);
|
|
2819
|
+
registerExtensionOperator(name, op);
|
|
2820
|
+
} };
|
|
2821
|
+
const pendingMcpTools = [];
|
|
2822
|
+
/** Seconds `close` waits for in-flight queries before it drops their connections. */
|
|
2823
|
+
const STORE_END_TIMEOUT_S = 2;
|
|
2824
|
+
async function wireStore(storeSpec, fieldDefLookupFor, typeDefLookupFor, diskGuard, layout) {
|
|
2825
|
+
if (storeSpec === "memory") return {
|
|
2826
|
+
dataset: new MemoryDataset({
|
|
2827
|
+
namespace: DEFAULT_NAMESPACE,
|
|
2828
|
+
fieldDefLookup: fieldDefLookupFor(DEFAULT_NAMESPACE),
|
|
2829
|
+
...typeDefLookupFor ? { typeDefLookup: typeDefLookupFor(DEFAULT_NAMESPACE) } : {}
|
|
2830
|
+
}),
|
|
2831
|
+
edges: new MemoryEdgesStore({ now: () => /* @__PURE__ */ new Date() }),
|
|
2832
|
+
substrateNamespaceDataset: null,
|
|
2833
|
+
sql: null,
|
|
2834
|
+
close: null
|
|
2835
|
+
};
|
|
2836
|
+
if (storeSpec.startsWith("postgres://") || storeSpec.startsWith("postgresql://")) {
|
|
2837
|
+
const sql = openSql(storeSpec);
|
|
2838
|
+
try {
|
|
2839
|
+
await runMigrations(sql, layout !== void 0 ? { layout } : {});
|
|
2840
|
+
} catch (err) {
|
|
2841
|
+
await sql.end({ timeout: 2 }).catch(() => void 0);
|
|
2842
|
+
throw err;
|
|
2843
|
+
}
|
|
2844
|
+
const edges = new PgEdgesStore({ sql });
|
|
2845
|
+
return {
|
|
2846
|
+
dataset: new PgDataset({
|
|
2847
|
+
namespace: DEFAULT_NAMESPACE,
|
|
2848
|
+
sql,
|
|
2849
|
+
edgesStore: edges,
|
|
2850
|
+
fieldDefLookup: fieldDefLookupFor(DEFAULT_NAMESPACE),
|
|
2851
|
+
...typeDefLookupFor ? { typeDefLookup: typeDefLookupFor(DEFAULT_NAMESPACE) } : {},
|
|
2852
|
+
...diskGuard !== void 0 ? { diskGuard } : {}
|
|
2853
|
+
}),
|
|
2854
|
+
edges,
|
|
2855
|
+
substrateNamespaceDataset: new PgDataset({
|
|
2856
|
+
namespace: SYSTEM_NAMESPACE,
|
|
2857
|
+
sql,
|
|
2858
|
+
edgesStore: edges,
|
|
2859
|
+
fieldDefLookup: fieldDefLookupFor(SYSTEM_NAMESPACE),
|
|
2860
|
+
...typeDefLookupFor ? { typeDefLookup: typeDefLookupFor(SYSTEM_NAMESPACE) } : {},
|
|
2861
|
+
...diskGuard !== void 0 ? { diskGuard } : {}
|
|
2862
|
+
}),
|
|
2863
|
+
sql,
|
|
2864
|
+
close: () => sql.end({ timeout: 2 })
|
|
2865
|
+
};
|
|
2866
|
+
}
|
|
2867
|
+
throw new EnvConfigError(`SUBSTRATE_DATABASE_URL: invalid value '${storeSpec}' — expected 'memory' or a postgres:// URL`);
|
|
2868
|
+
}
|
|
2869
|
+
/**
|
|
2870
|
+
* Builds a bridge registry from `specs`, returning it with a `dispose` that
|
|
2871
|
+
* releases every client. Throws if a spec has no credential, a malformed
|
|
2872
|
+
* url, or a url whose origin differs from its credential's.
|
|
2873
|
+
*/
|
|
2874
|
+
function buildBridgeRegistry(specs, creds) {
|
|
2875
|
+
const registry = new MemoryBridgeRegistry();
|
|
2876
|
+
const clients = [];
|
|
2877
|
+
for (const spec of specs) {
|
|
2878
|
+
const cred = creds.get(spec.name);
|
|
2879
|
+
if (cred === void 0) throw new Error(`bridge '${spec.name}' has no credential`);
|
|
2880
|
+
let specOrigin;
|
|
2881
|
+
try {
|
|
2882
|
+
specOrigin = new URL(spec.url).origin;
|
|
2883
|
+
} catch {
|
|
2884
|
+
throw new Error(`bridge '${spec.name}' has a malformed url '${spec.url}'`);
|
|
2885
|
+
}
|
|
2886
|
+
if (specOrigin !== cred.origin) throw new Error(`bridge '${spec.name}' url origin '${specOrigin}' does not match its credential origin '${cred.origin}'`);
|
|
2887
|
+
const auth = makeAuthorizationProvider(cred, { audience: cred.origin });
|
|
2888
|
+
const client = new HttpBridgeClient({
|
|
2889
|
+
name: spec.name,
|
|
2890
|
+
baseUrl: spec.url,
|
|
2891
|
+
auth
|
|
2892
|
+
});
|
|
2893
|
+
clients.push(client);
|
|
2894
|
+
registry.register(spec.ns, client);
|
|
2895
|
+
}
|
|
2896
|
+
return {
|
|
2897
|
+
registry,
|
|
2898
|
+
dispose: () => {
|
|
2899
|
+
for (const c of clients) c.dispose();
|
|
2900
|
+
}
|
|
2901
|
+
};
|
|
2902
|
+
}
|
|
2903
|
+
/**
|
|
2904
|
+
* Build a per-namespace {@link FieldDefLookup} factory backed by a mutable
|
|
2905
|
+
* registry of loaded namespace definitions. The default + `_system` datasets are
|
|
2906
|
+
* constructed (in `wireStore`) BEFORE plugins load, so the returned closures
|
|
2907
|
+
* resolve lazily — the same late-binding contract as `datasetRegistryRef` /
|
|
2908
|
+
* `engineRef`. `runServe` populates `nsDefs` once plugins are loaded and well
|
|
2909
|
+
* before the server listens, so every query resolves against a populated map.
|
|
2910
|
+
*
|
|
2911
|
+
* A miss (namespace absent, or a hand-crafted `NamespaceDefinition` whose
|
|
2912
|
+
* `types` is undefined because it bypassed `defineNamespace`) returns
|
|
2913
|
+
* `undefined`, and the dataset falls back to lexicographic text compare.
|
|
2914
|
+
*/
|
|
2915
|
+
function makeFieldDefLookupFactory(nsDefs) {
|
|
2916
|
+
return (namespace) => (type, field) => nsDefs.get(namespace)?.types?.[type]?.fields?.[field];
|
|
2917
|
+
}
|
|
2918
|
+
/**
|
|
2919
|
+
* Build a {@link TypeDefLookup} factory over the same late-bound `nsDefs`
|
|
2920
|
+
* registry as {@link makeFieldDefLookupFactory}: a type's fields and declared
|
|
2921
|
+
* indexes, which `PgDataset.ensureTypeStorage` builds indexes from. Once
|
|
2922
|
+
* `registryFor` resolves, the live registry's fields, which include proposed
|
|
2923
|
+
* ones, are merged over the declared fields, and the declared `indexes` are
|
|
2924
|
+
* kept; a type no definition declares (proposed at runtime, or registered at
|
|
2925
|
+
* install) has the registry's fields alone. The engine's reserved fields are
|
|
2926
|
+
* left out where autoCRUD registered them, since they are not body fields.
|
|
2927
|
+
* The lookup answers for the namespace it is asked about, so clones made by
|
|
2928
|
+
* `forNamespace` resolve their own types.
|
|
2929
|
+
*/
|
|
2930
|
+
function makeTypeDefLookupFactory(nsDefs, registryFor = () => void 0) {
|
|
2931
|
+
const lookup = (type, namespace) => {
|
|
2932
|
+
const declared = nsDefs.get(namespace)?.types?.[type];
|
|
2933
|
+
const entry = registryFor(namespace)?.get(type);
|
|
2934
|
+
const registered = entry?.kind === "type" ? entry : void 0;
|
|
2935
|
+
const orderedBy = registered !== void 0 ? registered.orderedBy : declared?.autoCrud === false ? void 0 : declared?.orderedBy;
|
|
2936
|
+
if (registered === void 0 && (declared === void 0 || orderedBy === declared.orderedBy)) return declared;
|
|
2937
|
+
const { orderedBy: _ignored, ...rest } = declared ?? { fields: {} };
|
|
2938
|
+
const live = registered === void 0 ? {} : Object.fromEntries(Object.entries(registered.fields).filter(([, def]) => !isReservedAutoCrudField(def)));
|
|
2939
|
+
const indexes = rest.indexes ?? registered?.indexes;
|
|
2940
|
+
const expectedSize = rest.expectedSize ?? registered?.expectedSize;
|
|
2941
|
+
return {
|
|
2942
|
+
...rest,
|
|
2943
|
+
fields: {
|
|
2944
|
+
...rest.fields,
|
|
2945
|
+
...live
|
|
2946
|
+
},
|
|
2947
|
+
...orderedBy !== void 0 ? { orderedBy } : {},
|
|
2948
|
+
...indexes !== void 0 ? { indexes } : {},
|
|
2949
|
+
...expectedSize !== void 0 ? { expectedSize } : {}
|
|
2950
|
+
};
|
|
2951
|
+
};
|
|
2952
|
+
return () => lookup;
|
|
2953
|
+
}
|
|
2954
|
+
/**
|
|
2955
|
+
* Prepares storage for every type the namespace definitions declare: its
|
|
2956
|
+
* partition and its unique indexes, through `Dataset.ensureTypeStorage`. Runs
|
|
2957
|
+
* before any kernel migration, so a migration can rely on a declared unique
|
|
2958
|
+
* index. Non-unique indexes are left to {@link buildDeferredIndexes}. Errors
|
|
2959
|
+
* propagate and fail the boot, among them `UniqueIndexDuplicatesError` and
|
|
2960
|
+
* `IndexDefinitionConflictError`, which name the index, and a declared
|
|
2961
|
+
* namespace with no dataset. Index builds run CONCURRENTLY, so the process
|
|
2962
|
+
* must hold no open transaction meanwhile.
|
|
2963
|
+
*/
|
|
2964
|
+
async function reconcileDeclaredStorage(datasetFor, nsDefs) {
|
|
2965
|
+
for (const [ns, def] of nsDefs) {
|
|
2966
|
+
const dataset = datasetFor(ns);
|
|
2967
|
+
if (dataset === void 0) throw new Error(`namespace '${ns}' is declared but has no dataset; its storage cannot be prepared`);
|
|
2968
|
+
for (const type of Object.keys(def.types ?? {})) await dataset.ensureTypeStorage?.(type, { indexes: "unique" });
|
|
2969
|
+
}
|
|
2970
|
+
}
|
|
2971
|
+
/** Every type registered in a namespace with a local dataset, with that dataset. */
|
|
2972
|
+
function* registeredTypes(engine, datasets) {
|
|
2973
|
+
for (const ns of Object.keys(engine.federatedSchema())) {
|
|
2974
|
+
if (!datasets.has(ns)) continue;
|
|
2975
|
+
const dataset = datasets.get(ns);
|
|
2976
|
+
for (const [type, entry] of engine.registryFor(ns)?.all() ?? []) if (entry.kind === "type") yield {
|
|
2977
|
+
ns,
|
|
2978
|
+
type,
|
|
2979
|
+
dataset
|
|
2980
|
+
};
|
|
2981
|
+
}
|
|
2982
|
+
}
|
|
2983
|
+
const message = (err) => err instanceof Error ? err.message : String(err);
|
|
2984
|
+
/**
|
|
2985
|
+
* Prepares storage, partition and unique indexes, for every type registered in
|
|
2986
|
+
* every local namespace once compose has run: `_system`, install-time types
|
|
2987
|
+
* such as the proposals plugin's, and proposed types replayed at start.
|
|
2988
|
+
* Namespaces without a local dataset (bridged, virtual) are skipped. A type the
|
|
2989
|
+
* operator's `nsDefs` declares fails the boot on error, since its unique
|
|
2990
|
+
* indexes must exist. A type only the registry knows (proposed by a principal
|
|
2991
|
+
* who can merely propose) logs the error naming it and the boot continues.
|
|
2992
|
+
*/
|
|
2993
|
+
async function reconcileRegisteredStorage(engine, datasets, nsDefs) {
|
|
2994
|
+
for (const { ns, type, dataset } of registeredTypes(engine, datasets)) try {
|
|
2995
|
+
await dataset?.ensureTypeStorage?.(type, { indexes: "unique" });
|
|
2996
|
+
} catch (err) {
|
|
2997
|
+
if (nsDefs.get(ns)?.types?.[type] !== void 0) throw err;
|
|
2998
|
+
process.stderr.write(`storage for registered type ${ns}/${type} was not prepared: ${message(err)}\n`);
|
|
2999
|
+
}
|
|
3000
|
+
}
|
|
3001
|
+
/**
|
|
3002
|
+
* When `SUBSTRATE_INDEX_DISK_PATH` is unset, logs how many non-unique index
|
|
3003
|
+
* builds the boot pass faces and their estimated size, since none of them
|
|
3004
|
+
* will be checked against free disk. Logs nothing when none is pending.
|
|
3005
|
+
*/
|
|
3006
|
+
async function reportUnguardedIndexBuilds(engine, datasets, write = (line) => void process.stderr.write(line)) {
|
|
3007
|
+
let count = 0;
|
|
3008
|
+
let bytes = 0;
|
|
3009
|
+
for (const { type, dataset } of registeredTypes(engine, datasets)) {
|
|
3010
|
+
if (!(dataset instanceof PgDataset)) continue;
|
|
3011
|
+
for (const p of await dataset.pendingIndexBuilds(type)) {
|
|
3012
|
+
count++;
|
|
3013
|
+
bytes += p.estimateBytes;
|
|
3014
|
+
}
|
|
3015
|
+
}
|
|
3016
|
+
if (count === 0) return;
|
|
3017
|
+
write(`${count} index build${count === 1 ? "" : "s"} pending, estimated ${(bytes / 2 ** 30).toFixed(1)} GiB in total, and SUBSTRATE_INDEX_DISK_PATH is unset, so free disk is not checked before them; set it to the database volume's mount (or 'off')
|
|
3018
|
+
`);
|
|
3019
|
+
}
|
|
3020
|
+
/**
|
|
3021
|
+
* Builds the non-unique indexes of every registered type, one type at a time.
|
|
3022
|
+
* Started after the server listens: until an index is valid, filters it would
|
|
3023
|
+
* serve scan. Never rejects: a type whose build fails is logged, and reported
|
|
3024
|
+
* `failed`, until the next build pass (periodic, or the next boot) retries it. `signal` cancels the build in
|
|
3025
|
+
* flight, whose INVALID leftover the next reconcile drops, and skips the rest.
|
|
3026
|
+
* Resolves to the logged failures, one line per type, for a caller that must
|
|
3027
|
+
* not pass over them.
|
|
3028
|
+
*/
|
|
3029
|
+
async function buildDeferredIndexes(engine, datasets, signal, opts = {}) {
|
|
3030
|
+
const failures = [];
|
|
3031
|
+
for (const { ns, type, dataset } of registeredTypes(engine, datasets)) {
|
|
3032
|
+
if (signal?.aborted === true) break;
|
|
3033
|
+
try {
|
|
3034
|
+
if (opts.onlyUnsettled === true && !await unsettled(dataset, type)) continue;
|
|
3035
|
+
await dataset?.ensureTypeStorage?.(type, {
|
|
3036
|
+
indexes: "nonUnique",
|
|
3037
|
+
...signal !== void 0 ? { signal } : {}
|
|
3038
|
+
});
|
|
3039
|
+
} catch (err) {
|
|
3040
|
+
const line = `indexes of ${ns}/${type} were not built and will be retried by the next build pass: ${message(err)}`;
|
|
3041
|
+
failures.push(line);
|
|
3042
|
+
process.stderr.write(`${line}\n`);
|
|
3043
|
+
}
|
|
3044
|
+
}
|
|
3045
|
+
return failures;
|
|
3046
|
+
}
|
|
3047
|
+
/** Whether `type` has a non-unique index still pending, failed or invalid. */
|
|
3048
|
+
async function unsettled(dataset, type) {
|
|
3049
|
+
return ((await dataset?.describeStorage?.(type))?.indexes ?? []).some((i) => !i.unique && (i.state === "pending" || i.state === "failed" || i.state === "invalid"));
|
|
3050
|
+
}
|
|
3051
|
+
/**
|
|
3052
|
+
* The boot pass of {@link buildDeferredIndexes}, then every `intervalMs` a
|
|
3053
|
+
* pass over only the types with a non-unique index still pending, failed or invalid,
|
|
3054
|
+
* such as one the disk guard refused. 0 runs the boot pass alone. Passes run
|
|
3055
|
+
* one after another, so never overlap. Resolves once `signal` aborts.
|
|
3056
|
+
*/
|
|
3057
|
+
async function runDeferredIndexBuilds(engine, datasets, intervalMs, signal) {
|
|
3058
|
+
await buildDeferredIndexes(engine, datasets, signal);
|
|
3059
|
+
while (intervalMs > 0 && !signal.aborted) {
|
|
3060
|
+
try {
|
|
3061
|
+
await setTimeout$1(intervalMs, void 0, {
|
|
3062
|
+
signal,
|
|
3063
|
+
ref: false
|
|
3064
|
+
});
|
|
3065
|
+
} catch {
|
|
3066
|
+
return;
|
|
3067
|
+
}
|
|
3068
|
+
await buildDeferredIndexes(engine, datasets, signal, { onlyUnsettled: true });
|
|
3069
|
+
}
|
|
3070
|
+
}
|
|
3071
|
+
/**
|
|
3072
|
+
* Walk loaded namespace definitions for `field.list({ indexed: true })` and
|
|
3073
|
+
* `field.json({ indexed: true })` fields. Each becomes an auto-derived GIN
|
|
3074
|
+
* migration so the `indexed` flag — the physical-index contract —
|
|
3075
|
+
* can't drift from the physical index.
|
|
3076
|
+
*/
|
|
3077
|
+
function extractIndexedListFields(nsDefs) {
|
|
3078
|
+
const out = [];
|
|
3079
|
+
for (const [namespace, def] of nsDefs) {
|
|
3080
|
+
const types = def.types;
|
|
3081
|
+
if (types === void 0) continue;
|
|
3082
|
+
for (const [type, typeDef] of Object.entries(types)) for (const [field, fieldDef] of Object.entries(typeDef.fields)) {
|
|
3083
|
+
const indexedJson = fieldDef.kind === "scalar" && fieldDef.type === "json" && fieldDef.indexed === true;
|
|
3084
|
+
if (fieldDef.kind === "list" && fieldDef.indexed === true || indexedJson) out.push({
|
|
3085
|
+
namespace,
|
|
3086
|
+
type,
|
|
3087
|
+
field
|
|
3088
|
+
});
|
|
3089
|
+
}
|
|
3090
|
+
}
|
|
3091
|
+
return out;
|
|
3092
|
+
}
|
|
3093
|
+
/**
|
|
3094
|
+
* Pick per-namespace datasets for plugin-contributed namespaces.
|
|
3095
|
+
*
|
|
3096
|
+
* When the store is pg (`sharedSql` is non-null) every plugin namespace is
|
|
3097
|
+
* backed by a `PgDataset` pointing at the same connection pool — they
|
|
3098
|
+
* coexist in one `rows` table keyed by the `namespace` column, which
|
|
3099
|
+
* is the core multi-namespace model. Multi-pg (namespace → distinct DB)
|
|
3100
|
+
* deployments should override `datasets` on the `compose()` call site
|
|
3101
|
+
* directly; this helper only covers the common single-pg-many-namespaces
|
|
3102
|
+
* shape.
|
|
3103
|
+
*
|
|
3104
|
+
* When the store is memory, every plugin namespace gets a fresh
|
|
3105
|
+
* `MemoryDataset` so the contribution boots cleanly without reaching
|
|
3106
|
+
* across to the default substrate.
|
|
3107
|
+
*
|
|
3108
|
+
* `fieldDefLookupFor` yields the namespace-scoped lookup that lets pg datasets
|
|
3109
|
+
* cast numeric/date/boolean body fields in orderBy + range + cursor compares.
|
|
3110
|
+
* Memory datasets ignore it.
|
|
3111
|
+
*/
|
|
3112
|
+
function buildPluginDatasetMap(plugins, defaultDataset, sharedSql, sharedEdges, fieldDefLookupFor, typeDefLookup, diskGuard) {
|
|
3113
|
+
const datasets = {};
|
|
3114
|
+
for (const plugin of plugins) for (const nsDef of plugin.namespaces) {
|
|
3115
|
+
const ns = nsDef.namespace;
|
|
3116
|
+
if (ns === "default") {
|
|
3117
|
+
datasets[ns] = defaultDataset;
|
|
3118
|
+
continue;
|
|
3119
|
+
}
|
|
3120
|
+
if (datasets[ns] !== void 0) continue;
|
|
3121
|
+
datasets[ns] = sharedSql !== null ? new PgDataset({
|
|
3122
|
+
namespace: ns,
|
|
3123
|
+
sql: sharedSql,
|
|
3124
|
+
fieldDefLookup: fieldDefLookupFor(ns),
|
|
3125
|
+
typeDefLookup: typeDefLookup ?? ((type) => nsDef.types?.[type]),
|
|
3126
|
+
...nsDef.promotedColumns !== void 0 ? { promotedColumns: nsDef.promotedColumns } : {},
|
|
3127
|
+
...sharedEdges !== null ? { edgesStore: sharedEdges } : {},
|
|
3128
|
+
...diskGuard !== void 0 ? { diskGuard } : {}
|
|
3129
|
+
}) : new MemoryDataset({
|
|
3130
|
+
namespace: ns,
|
|
3131
|
+
fieldDefLookup: fieldDefLookupFor(ns),
|
|
3132
|
+
typeDefLookup: typeDefLookup ?? ((type) => nsDef.types?.[type])
|
|
3133
|
+
});
|
|
3134
|
+
}
|
|
3135
|
+
return datasets;
|
|
3136
|
+
}
|
|
3137
|
+
/**
|
|
3138
|
+
* Redact the password component of a `SUBSTRATE_DATABASE_URL` value so it can be safely
|
|
3139
|
+
* written to stdout / journald at boot. Operates on postgres URLs; passes
|
|
3140
|
+
* `memory` (and any other non-URL value) through unchanged.
|
|
3141
|
+
*/
|
|
3142
|
+
function redactStoreSpec(spec) {
|
|
3143
|
+
if (!spec.startsWith("postgres://") && !spec.startsWith("postgresql://")) return spec;
|
|
3144
|
+
return spec.replace(/^(postgres(?:ql)?:\/\/[^:@/]+):[^@]*@/, "$1:<redacted>@");
|
|
3145
|
+
}
|
|
3146
|
+
/**
|
|
3147
|
+
* Ensure the `kernel_migrations` tracking table exists. Distinct
|
|
3148
|
+
* from `migrations` (which the dataset-pg framework owns for its own
|
|
3149
|
+
* `version`/`checksum`-keyed migrations) — this table tracks
|
|
3150
|
+
* KernelPlugin-contributed migrations by `(plugin_name, migration_id)`.
|
|
3151
|
+
* Idempotent CREATE-IF-NOT-EXISTS. No-op on memory-backed deployments.
|
|
3152
|
+
*/
|
|
3153
|
+
async function ensureMigrationsTable(sql) {
|
|
3154
|
+
await kernelMigrationTracking(sql).ensure();
|
|
3155
|
+
}
|
|
3156
|
+
/**
|
|
3157
|
+
* Return the set of migration IDs already recorded as applied for the given
|
|
3158
|
+
* plugin. Returns an empty Set on memory-backed deployments (sql null).
|
|
3159
|
+
*/
|
|
3160
|
+
async function getAppliedMigrationIds(sql, pluginName) {
|
|
3161
|
+
return kernelMigrationTracking(sql).getAppliedMigrationIds(pluginName);
|
|
3162
|
+
}
|
|
3163
|
+
/**
|
|
3164
|
+
* Record a migration as applied. ON CONFLICT DO NOTHING makes this safe to
|
|
3165
|
+
* call even if the row already exists (concurrent boot, retry after a partial
|
|
3166
|
+
* failure). No-op on memory-backed deployments.
|
|
3167
|
+
*/
|
|
3168
|
+
async function recordMigrationApplied(sql, pluginName, migrationId) {
|
|
3169
|
+
await kernelMigrationTracking(sql).recordMigrationApplied(pluginName, migrationId);
|
|
3170
|
+
}
|
|
3171
|
+
|
|
3172
|
+
//#endregion
|
|
3173
|
+
//#region src/serve/config.ts
|
|
3174
|
+
/**
|
|
3175
|
+
* serve/config.ts — env-var configuration parsing for `substrate serve`.
|
|
3176
|
+
*/
|
|
3177
|
+
const DEFAULT_SWEEP_INTERVAL_MS = 3e5;
|
|
3178
|
+
const DEFAULT_INVITE_SWEEP_INTERVAL_MS = 36e5;
|
|
3179
|
+
const DEFAULT_TOMBSTONE_RETENTION_DAYS = 30;
|
|
3180
|
+
const DEFAULT_SHUTDOWN_GRACE_MS = 5e3;
|
|
3181
|
+
const DEFAULT_PARTITION_BUDGET = 500;
|
|
3182
|
+
const DEFAULT_INDEX_DISK_MARGIN_MB = 2048;
|
|
3183
|
+
const DEFAULT_INDEX_RETRY_INTERVAL_MS = 6e5;
|
|
3184
|
+
const DEFAULT_ADVISOR_INTERVAL_MS = 6e5;
|
|
3185
|
+
const MS_PER_DAY = 864e5;
|
|
3186
|
+
const DEFAULT_PORT = 3100;
|
|
3187
|
+
var EnvConfigError = class extends Error {
|
|
3188
|
+
name = "EnvConfigError";
|
|
3189
|
+
};
|
|
3190
|
+
/**
|
|
3191
|
+
* Parses the serve env into a fully resolved `ParsedConfig`. The only I/O is
|
|
3192
|
+
* reading the auth and TLS PEM / JSON files. Throws `EnvConfigError` on any
|
|
3193
|
+
* malformed input.
|
|
3194
|
+
*/
|
|
3195
|
+
function parseEnv(env) {
|
|
3196
|
+
const knobs = createKnobRecorder();
|
|
3197
|
+
const storeSpec = env.SUBSTRATE_DATABASE_URL ?? "memory";
|
|
3198
|
+
knobs.record("storeSpec", "SUBSTRATE_DATABASE_URL", env.SUBSTRATE_DATABASE_URL, redactStoreSpec(storeSpec));
|
|
3199
|
+
const memoryByDefault = env.SUBSTRATE_DATABASE_URL === void 0;
|
|
3200
|
+
const bridges = parseBridges(env.SUBSTRATE_BRIDGES);
|
|
3201
|
+
const bridgeCreds = parseBridgeCreds(env.SUBSTRATE_BRIDGE_CREDENTIALS);
|
|
3202
|
+
for (const spec of bridges) {
|
|
3203
|
+
const cred = bridgeCreds.get(spec.name);
|
|
3204
|
+
if (cred === void 0) throw new EnvConfigError(`SUBSTRATE_BRIDGES: bridge '${spec.name}' has no entry in SUBSTRATE_BRIDGE_CREDENTIALS — every configured bridge must carry a credential`);
|
|
3205
|
+
let specOrigin;
|
|
3206
|
+
try {
|
|
3207
|
+
specOrigin = new URL(spec.url).origin;
|
|
3208
|
+
} catch {
|
|
3209
|
+
throw new EnvConfigError(`SUBSTRATE_BRIDGES: bridge '${spec.name}' has a malformed url '${spec.url}'`);
|
|
3210
|
+
}
|
|
3211
|
+
if (specOrigin !== cred.origin) throw new EnvConfigError(`SUBSTRATE_BRIDGES: bridge '${spec.name}' url origin '${specOrigin}' does not match its SUBSTRATE_BRIDGE_CREDENTIALS origin '${cred.origin}'`);
|
|
3212
|
+
}
|
|
3213
|
+
const auth = parseAuthConfig(env);
|
|
3214
|
+
const tls = parseTlsConfig(env);
|
|
3215
|
+
knobs.record("authMode", "SUBSTRATE_AUTH_MODE", env.SUBSTRATE_AUTH_MODE, auth?.mode ?? "off");
|
|
3216
|
+
const publicOrigins = parsePublicOrigins(env.SUBSTRATE_PUBLIC_ORIGIN);
|
|
3217
|
+
const sweepIntervalMs = parseSweepIntervalMs(env, knobs);
|
|
3218
|
+
const inviteSweepIntervalMs = parseInviteSweepIntervalMs(env, knobs);
|
|
3219
|
+
const tombstoneRetentionDays = parseTombstoneRetentionDays(env, knobs);
|
|
3220
|
+
const shutdownGraceMs = parseShutdownGraceMs(env, knobs);
|
|
3221
|
+
const partitionBudget = parsePositiveIntEnv(env, knobs, "partitionBudget", "SUBSTRATE_PARTITION_BUDGET", DEFAULT_PARTITION_BUDGET, "partitions");
|
|
3222
|
+
const indexDiskPath = knobs.record("indexDiskPath", "SUBSTRATE_INDEX_DISK_PATH", env.SUBSTRATE_INDEX_DISK_PATH, diskPathOf(nonEmpty(env.SUBSTRATE_INDEX_DISK_PATH?.trim())));
|
|
3223
|
+
const indexDiskMarginMb = parseNonNegativeIntEnv(env, knobs, "indexDiskMarginMb", "SUBSTRATE_INDEX_DISK_MARGIN_MB", DEFAULT_INDEX_DISK_MARGIN_MB, "megabytes");
|
|
3224
|
+
const indexRetryIntervalMs = parseNonNegativeIntEnv(env, knobs, "indexRetryIntervalMs", "SUBSTRATE_INDEX_RETRY_INTERVAL_MS", DEFAULT_INDEX_RETRY_INTERVAL_MS, "milliseconds, 0 to disable");
|
|
3225
|
+
const advisorIntervalMs = parseNonNegativeIntEnv(env, knobs, "advisorIntervalMs", "SUBSTRATE_ADVISOR_INTERVAL_MS", DEFAULT_ADVISOR_INTERVAL_MS, "milliseconds, 0 to disable");
|
|
3226
|
+
const profileRaw = nonEmpty(env.SUBSTRATE_STORE_PROFILE?.trim());
|
|
3227
|
+
if (profileRaw !== void 0 && !isStoreProfileName(profileRaw)) throw new EnvConfigError(`SUBSTRATE_STORE_PROFILE must be personal, growth or scale, got '${profileRaw}'`);
|
|
3228
|
+
const storeProfile = knobs.record("storeProfile", "SUBSTRATE_STORE_PROFILE", env.SUBSTRATE_STORE_PROFILE, profileRaw ?? null);
|
|
3229
|
+
const writeHeavyRaw = env.SUBSTRATE_STORE_WRITE_HEAVY;
|
|
3230
|
+
const writeHeavyWord = (writeHeavyRaw ?? "").trim().toLowerCase();
|
|
3231
|
+
if (![
|
|
3232
|
+
"",
|
|
3233
|
+
"0",
|
|
3234
|
+
"false",
|
|
3235
|
+
"1",
|
|
3236
|
+
"true"
|
|
3237
|
+
].includes(writeHeavyWord)) throw new EnvConfigError(`SUBSTRATE_STORE_WRITE_HEAVY must be 1, true, 0 or false, got '${writeHeavyRaw}'`);
|
|
3238
|
+
const storeWriteHeavy = knobs.record("storeWriteHeavy", "SUBSTRATE_STORE_WRITE_HEAVY", writeHeavyRaw, writeHeavyWord === "1" || writeHeavyWord === "true");
|
|
3239
|
+
const idempotency = parseIdempotencyConfig(env, knobs);
|
|
3240
|
+
const trustedProxies = parseTrustedProxies(env, knobs);
|
|
3241
|
+
const port = parsePort(env, knobs);
|
|
3242
|
+
const host = knobs.record("host", "HOST", env.HOST, env.HOST ?? (auth === null ? "127.0.0.1" : "0.0.0.0"));
|
|
3243
|
+
const openRaw = env.SUBSTRATE_ALLOW_UNAUTHENTICATED_HOST;
|
|
3244
|
+
const allowOpenHost = knobs.record("allowUnauthenticatedHost", "SUBSTRATE_ALLOW_UNAUTHENTICATED_HOST", openRaw, openRaw !== void 0 && (openRaw === "1" || openRaw.toLowerCase() === "true"));
|
|
3245
|
+
if (auth === null && !isLoopbackHost(host) && !allowOpenHost) throw new EnvConfigError(`HOST '${host}' is not loopback and auth is off, so every caller would act as the system actor (admin routes included). Enable auth, bind to loopback, or set SUBSTRATE_ALLOW_UNAUTHENTICATED_HOST=1. Inside a container, a port published only on the host's 127.0.0.1 still needs the opt-in: the server binds a non-loopback interface there.`);
|
|
3246
|
+
if (auth !== null && publicOrigins === null && !isLoopbackHost(host)) throw new EnvConfigError(`SUBSTRATE_PUBLIC_ORIGIN is required when auth is on and HOST '${host}' is not loopback: set it to the origins callers reach this server by (e.g. https://host:3100), so a token minted for another origin is refused.`);
|
|
3247
|
+
let audiences = publicOrigins;
|
|
3248
|
+
if (auth !== null && audiences === null) {
|
|
3249
|
+
const bound = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
|
|
3250
|
+
const scheme = tls !== null ? "https" : "http";
|
|
3251
|
+
audiences = [...new Set([
|
|
3252
|
+
"127.0.0.1",
|
|
3253
|
+
"localhost",
|
|
3254
|
+
"[::1]",
|
|
3255
|
+
bound
|
|
3256
|
+
].map((h) => new URL(`${scheme}://${h}:${port}`).origin))];
|
|
3257
|
+
}
|
|
3258
|
+
if (auth !== null && audiences !== null) auth.audiences = audiences;
|
|
3259
|
+
knobs.record("publicOrigin", "SUBSTRATE_PUBLIC_ORIGIN", env.SUBSTRATE_PUBLIC_ORIGIN, audiences?.join(",") ?? null);
|
|
3260
|
+
const cors = parseCorsConfig(env, knobs);
|
|
3261
|
+
const bodyLimit = parseBodyLimit(env, knobs);
|
|
3262
|
+
const pageLimits = parsePageLimits(env, knobs);
|
|
3263
|
+
const snapshotLimit = parseSnapshotLimit(env, knobs, pageLimits.maxLimit);
|
|
3264
|
+
const keyReprimeIntervalMs = parseKeyReprimeIntervalMs(env, knobs);
|
|
3265
|
+
knobs.recordSecret("streamTicketSecret", "SUBSTRATE_STREAM_TICKET_SECRET", env.SUBSTRATE_STREAM_TICKET_SECRET);
|
|
3266
|
+
knobs.record("systemActor", "SUBSTRATE_SYSTEM_ACTOR", env.SUBSTRATE_SYSTEM_ACTOR, nonEmpty(env.SUBSTRATE_SYSTEM_ACTOR?.trim()) ?? null);
|
|
3267
|
+
const streamTicketSecret = nonEmpty(env.SUBSTRATE_STREAM_TICKET_SECRET?.trim()) ?? null;
|
|
3268
|
+
return {
|
|
3269
|
+
storeSpec,
|
|
3270
|
+
memoryByDefault,
|
|
3271
|
+
bridges,
|
|
3272
|
+
bridgeCreds,
|
|
3273
|
+
auth,
|
|
3274
|
+
tls,
|
|
3275
|
+
sweepIntervalMs,
|
|
3276
|
+
inviteSweepIntervalMs,
|
|
3277
|
+
tombstoneRetentionDays,
|
|
3278
|
+
shutdownGraceMs,
|
|
3279
|
+
partitionBudget,
|
|
3280
|
+
indexDiskPath,
|
|
3281
|
+
indexDiskMarginMb,
|
|
3282
|
+
indexRetryIntervalMs,
|
|
3283
|
+
advisorIntervalMs,
|
|
3284
|
+
storeProfile,
|
|
3285
|
+
storeWriteHeavy,
|
|
3286
|
+
idempotency,
|
|
3287
|
+
trustedProxies,
|
|
3288
|
+
port,
|
|
3289
|
+
host,
|
|
3290
|
+
cors,
|
|
3291
|
+
bodyLimit,
|
|
3292
|
+
pageLimits,
|
|
3293
|
+
snapshotLimit,
|
|
3294
|
+
keyReprimeIntervalMs,
|
|
3295
|
+
knobs: knobs.report(),
|
|
3296
|
+
streamTicketSecret,
|
|
3297
|
+
systemActor: nonEmpty(env.SUBSTRATE_SYSTEM_ACTOR?.trim()) ?? null
|
|
3298
|
+
};
|
|
3299
|
+
}
|
|
3300
|
+
/**
|
|
3301
|
+
* Parse `SUBSTRATE_KEY_REFRESH_INTERVAL_MS` — periodic public-key-cache re-prime
|
|
3302
|
+
* interval in ms. Unset or empty → {@link DEFAULT_KEY_REPRIME_INTERVAL_MS}.
|
|
3303
|
+
* The literal `off` disables it. A set value must otherwise be a positive
|
|
3304
|
+
* integer; anything else is a config bug and throws rather than silently
|
|
3305
|
+
* disabling the safety net.
|
|
3306
|
+
*
|
|
3307
|
+
* On by default: single-instance deployments are exactly where nothing else
|
|
3308
|
+
* repairs a stale cache entry.
|
|
3309
|
+
*/
|
|
3310
|
+
const DEFAULT_KEY_REPRIME_INTERVAL_MS = 3e4;
|
|
3311
|
+
function parseKeyReprimeIntervalMs(env, knobs) {
|
|
3312
|
+
const note = (v) => knobs.record("keyReprimeIntervalMs", "SUBSTRATE_KEY_REFRESH_INTERVAL_MS", env.SUBSTRATE_KEY_REFRESH_INTERVAL_MS, v);
|
|
3313
|
+
const raw = nonEmpty(env.SUBSTRATE_KEY_REFRESH_INTERVAL_MS);
|
|
3314
|
+
if (raw === void 0) return note(DEFAULT_KEY_REPRIME_INTERVAL_MS);
|
|
3315
|
+
if (raw.trim().toLowerCase() === "off") return note(null);
|
|
3316
|
+
try {
|
|
3317
|
+
return note(parsePositiveInt(raw, "SUBSTRATE_KEY_REFRESH_INTERVAL_MS", 0));
|
|
3318
|
+
} catch (err) {
|
|
3319
|
+
throw new EnvConfigError(`${err instanceof Error ? err.message : String(err)} — expected a positive integer (milliseconds)`);
|
|
3320
|
+
}
|
|
3321
|
+
}
|
|
3322
|
+
/**
|
|
3323
|
+
* Parse `SUBSTRATE_BODY_LIMIT_BYTES` — max Fastify request body size in bytes. Unset or
|
|
3324
|
+
* empty (docker `${VAR:-}` substitution) → `null`, leaving Fastify's 1 MiB
|
|
3325
|
+
* default in place. A set value must be a positive integer; anything else is a
|
|
3326
|
+
* config bug and throws rather than silently falling back.
|
|
3327
|
+
*/
|
|
3328
|
+
function parseBodyLimit(env, knobs) {
|
|
3329
|
+
const note = (v) => knobs.record("bodyLimit", "SUBSTRATE_BODY_LIMIT_BYTES", env.SUBSTRATE_BODY_LIMIT_BYTES, v);
|
|
3330
|
+
const raw = nonEmpty(env.SUBSTRATE_BODY_LIMIT_BYTES);
|
|
3331
|
+
if (raw === void 0) return note(null);
|
|
3332
|
+
try {
|
|
3333
|
+
return note(parsePositiveInt(raw, "SUBSTRATE_BODY_LIMIT_BYTES", 0));
|
|
3334
|
+
} catch (err) {
|
|
3335
|
+
throw new EnvConfigError(`${err instanceof Error ? err.message : String(err)} — expected a positive integer (bytes)`);
|
|
3336
|
+
}
|
|
3337
|
+
}
|
|
3338
|
+
/** Parse `SUBSTRATE_PAGE_LIMIT_DEFAULT` (100) and `SUBSTRATE_PAGE_LIMIT_MAX` (1000). */
|
|
3339
|
+
function parsePageLimits(env, knobs) {
|
|
3340
|
+
const read = (name, fallback) => {
|
|
3341
|
+
const raw = nonEmpty(env[name]);
|
|
3342
|
+
const v = raw === void 0 ? fallback : Number(raw);
|
|
3343
|
+
if (!Number.isInteger(v) || v <= 0) throw new EnvConfigError(`${name}: invalid value '${raw}' — expected a positive integer`);
|
|
3344
|
+
return knobs.record(name === "SUBSTRATE_PAGE_LIMIT_MAX" ? "pageLimitMax" : "pageLimitDefault", name, env[name], v);
|
|
3345
|
+
};
|
|
3346
|
+
const defaultLimit = read("SUBSTRATE_PAGE_LIMIT_DEFAULT", 100);
|
|
3347
|
+
const maxLimit = read("SUBSTRATE_PAGE_LIMIT_MAX", 1e3);
|
|
3348
|
+
if (defaultLimit > maxLimit) throw new EnvConfigError(`SUBSTRATE_PAGE_LIMIT_DEFAULT (${defaultLimit}) exceeds SUBSTRATE_PAGE_LIMIT_MAX (${maxLimit})`);
|
|
3349
|
+
return {
|
|
3350
|
+
defaultLimit,
|
|
3351
|
+
maxLimit
|
|
3352
|
+
};
|
|
3353
|
+
}
|
|
3354
|
+
/** Parse `SUBSTRATE_SNAPSHOT_LIMIT`, defaulting to the max page size. */
|
|
3355
|
+
function parseSnapshotLimit(env, knobs, fallback) {
|
|
3356
|
+
const raw = nonEmpty(env.SUBSTRATE_SNAPSHOT_LIMIT);
|
|
3357
|
+
const v = raw === void 0 ? fallback : Number(raw);
|
|
3358
|
+
if (!Number.isInteger(v) || v <= 0) throw new EnvConfigError(`SUBSTRATE_SNAPSHOT_LIMIT: invalid value '${raw}' — expected a positive integer`);
|
|
3359
|
+
return knobs.record("snapshotLimit", "SUBSTRATE_SNAPSHOT_LIMIT", env.SUBSTRATE_SNAPSHOT_LIMIT, v);
|
|
3360
|
+
}
|
|
3361
|
+
/**
|
|
3362
|
+
* Parse `SUBSTRATE_TRUSTED_PROXIES` — CSV of exact peer-IP strings. Entries are
|
|
3363
|
+
* trimmed; empty entries are dropped. A non-empty value that devolves to an
|
|
3364
|
+
* empty set after trimming (e.g. `",,,"`) is a config bug and throws —
|
|
3365
|
+
* silently treating it as "no trust" would mask a deployment typo.
|
|
3366
|
+
*/
|
|
3367
|
+
function parseTrustedProxies(env, knobs) {
|
|
3368
|
+
const raw = env.SUBSTRATE_TRUSTED_PROXIES;
|
|
3369
|
+
const note = (ips) => {
|
|
3370
|
+
knobs.record("trustedProxies", "SUBSTRATE_TRUSTED_PROXIES", raw, [...ips].join(",") || null);
|
|
3371
|
+
return ips;
|
|
3372
|
+
};
|
|
3373
|
+
if (raw === void 0 || raw.trim() === "") return note(/* @__PURE__ */ new Set());
|
|
3374
|
+
const parts = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
|
|
3375
|
+
if (parts.length === 0) throw new EnvConfigError(`SUBSTRATE_TRUSTED_PROXIES: value '${raw}' contains no usable IP entries — supply a CSV of exact peer-IP strings or unset the var`);
|
|
3376
|
+
return note(new Set(parts));
|
|
3377
|
+
}
|
|
3378
|
+
/**
|
|
3379
|
+
* Parse `SUBSTRATE_CORS_ORIGINS` — optional CORS origin allowlist for browser clients.
|
|
3380
|
+
*
|
|
3381
|
+
* Returns `null` when the env var is unset or empty — the CORS plugin is not
|
|
3382
|
+
* registered and the server behaves as it does today (agent-only deployments).
|
|
3383
|
+
*
|
|
3384
|
+
* `'*'` allows any origin. Credentials are automatically disabled for wildcard
|
|
3385
|
+
* origins because browsers reject `Access-Control-Allow-Credentials: true` when
|
|
3386
|
+
* the origin is `*`. An explicit comma-separated list enables credentialed
|
|
3387
|
+
* cross-origin requests (Authorization header) from those origins.
|
|
3388
|
+
*/
|
|
3389
|
+
function parseCorsConfig(env, knobs) {
|
|
3390
|
+
const raw = env.SUBSTRATE_CORS_ORIGINS;
|
|
3391
|
+
const note = (c) => {
|
|
3392
|
+
const value = c === null ? null : c.origins === "*" ? "*" : c.origins.join(",");
|
|
3393
|
+
knobs.record("cors", "SUBSTRATE_CORS_ORIGINS", raw, value);
|
|
3394
|
+
return c;
|
|
3395
|
+
};
|
|
3396
|
+
if (raw === void 0 || raw.trim() === "") return note(null);
|
|
3397
|
+
const trimmed = raw.trim();
|
|
3398
|
+
if (trimmed === "*") return note({
|
|
3399
|
+
origins: "*",
|
|
3400
|
+
credentials: false
|
|
3401
|
+
});
|
|
3402
|
+
const origins = trimmed.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
|
|
3403
|
+
if (origins.length === 0) throw new EnvConfigError(`SUBSTRATE_CORS_ORIGINS: value '${raw}' contains no usable origin entries — supply a CSV of origins, '*', or unset the var`);
|
|
3404
|
+
return note({
|
|
3405
|
+
origins,
|
|
3406
|
+
credentials: true
|
|
3407
|
+
});
|
|
3408
|
+
}
|
|
3409
|
+
const diskPathOf = (raw) => raw === void 0 ? null : raw.toLowerCase() === "off" ? "off" : raw;
|
|
3410
|
+
/** As {@link parsePositiveIntEnv}, but 0 is allowed. */
|
|
3411
|
+
function parseNonNegativeIntEnv(env, knobs, key, varName, defaultValue, units) {
|
|
3412
|
+
const raw = nonEmpty(env[varName]);
|
|
3413
|
+
const n = raw === void 0 ? defaultValue : Number(raw);
|
|
3414
|
+
if (!Number.isInteger(n) || n < 0) throw new EnvConfigError(`${varName}: got '${raw}' — expected a non-negative integer (${units})`);
|
|
3415
|
+
return knobs.record(key, varName, env[varName], n);
|
|
3416
|
+
}
|
|
3417
|
+
/**
|
|
3418
|
+
* Parses positive-integer env var `varName`, falling back to `defaultValue`
|
|
3419
|
+
* when unset or empty, and records it under `key`. Throws `EnvConfigError`
|
|
3420
|
+
* naming the var and `units` on a malformed value.
|
|
3421
|
+
*
|
|
3422
|
+
* Empty must mean unset: docker-compose `${VAR:-}` passes `""`, and NaN
|
|
3423
|
+
* flowing into `setInterval` fires the callback every 1 ms.
|
|
3424
|
+
*/
|
|
3425
|
+
function parsePositiveIntEnv(env, knobs, key, varName, defaultValue, units) {
|
|
3426
|
+
const raw = env[varName];
|
|
3427
|
+
try {
|
|
3428
|
+
return knobs.record(key, varName, raw, parsePositiveInt(nonEmpty(raw), varName, defaultValue));
|
|
3429
|
+
} catch (err) {
|
|
3430
|
+
throw new EnvConfigError(`${varName}: ${err instanceof Error ? err.message : String(err)} — expected a positive integer (${units})`);
|
|
3431
|
+
}
|
|
3432
|
+
}
|
|
3433
|
+
/** Parse `SUBSTRATE_SWEEP_INTERVAL_MS` — main edge-sweep cadence (§6.4 reaper). Default 5min. */
|
|
3434
|
+
function parseSweepIntervalMs(env, knobs) {
|
|
3435
|
+
return parsePositiveIntEnv(env, knobs, "sweepIntervalMs", "SUBSTRATE_SWEEP_INTERVAL_MS", DEFAULT_SWEEP_INTERVAL_MS, "milliseconds");
|
|
3436
|
+
}
|
|
3437
|
+
/** Parse `SUBSTRATE_INVITE_SWEEP_INTERVAL_MS` — reaper cadence for expired `Invite` rows. Default 1h. */
|
|
3438
|
+
function parseInviteSweepIntervalMs(env, knobs) {
|
|
3439
|
+
return parsePositiveIntEnv(env, knobs, "inviteSweepIntervalMs", "SUBSTRATE_INVITE_SWEEP_INTERVAL_MS", DEFAULT_INVITE_SWEEP_INTERVAL_MS, "milliseconds");
|
|
3440
|
+
}
|
|
3441
|
+
/**
|
|
3442
|
+
* Parse `SUBSTRATE_TOMBSTONE_RETENTION_DAYS` — retention window before tombstoned
|
|
3443
|
+
* `rows` / `edges` are hard-deleted by the sweep loop. Default 30.
|
|
3444
|
+
*/
|
|
3445
|
+
function parseTombstoneRetentionDays(env, knobs) {
|
|
3446
|
+
return parsePositiveIntEnv(env, knobs, "tombstoneRetentionDays", "SUBSTRATE_TOMBSTONE_RETENTION_DAYS", DEFAULT_TOMBSTONE_RETENTION_DAYS, "days");
|
|
3447
|
+
}
|
|
3448
|
+
/** Parse `SUBSTRATE_SHUTDOWN_GRACE_MS` — graceful drain deadline. Default 5s. */
|
|
3449
|
+
function parseShutdownGraceMs(env, knobs) {
|
|
3450
|
+
return parsePositiveIntEnv(env, knobs, "shutdownGraceMs", "SUBSTRATE_SHUTDOWN_GRACE_MS", DEFAULT_SHUTDOWN_GRACE_MS, "milliseconds");
|
|
3451
|
+
}
|
|
3452
|
+
/**
|
|
3453
|
+
* Parse `PORT` — Fastify HTTP listen port. Defaults to 3100. Empty string
|
|
3454
|
+
* and unset both fall back to the default; malformed values throw at boot.
|
|
3455
|
+
*/
|
|
3456
|
+
function parsePort(env, knobs) {
|
|
3457
|
+
const raw = env.PORT;
|
|
3458
|
+
const note = (v) => knobs.record("port", "PORT", raw, v);
|
|
3459
|
+
if (raw === void 0 || raw === "") return note(DEFAULT_PORT);
|
|
3460
|
+
const parsed = Number(raw);
|
|
3461
|
+
if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) throw new EnvConfigError(`PORT: invalid value '${raw}' — expected an integer in 1..65535`);
|
|
3462
|
+
return note(parsed);
|
|
3463
|
+
}
|
|
3464
|
+
/**
|
|
3465
|
+
* `SUBSTRATE_PUBLIC_ORIGIN`: comma-separated origins (`https://a:3100,https://b`)
|
|
3466
|
+
* a token's `aud` may name. Null when unset; anything not a bare http(s)
|
|
3467
|
+
* origin throws.
|
|
3468
|
+
*/
|
|
3469
|
+
function parsePublicOrigins(raw) {
|
|
3470
|
+
if (raw === void 0 || raw.trim() === "") return null;
|
|
3471
|
+
return raw.split(",").map((part) => {
|
|
3472
|
+
const entry = part.trim();
|
|
3473
|
+
let origin;
|
|
3474
|
+
try {
|
|
3475
|
+
const url = new URL(entry);
|
|
3476
|
+
if (url.protocol === "https:" || url.protocol === "http:") origin = url.origin;
|
|
3477
|
+
} catch {}
|
|
3478
|
+
if (origin === void 0 || origin !== entry.replace(/\/$/, "")) throw new EnvConfigError(`SUBSTRATE_PUBLIC_ORIGIN: '${entry}' is not an origin like 'https://host:3100'`);
|
|
3479
|
+
return origin;
|
|
3480
|
+
});
|
|
3481
|
+
}
|
|
3482
|
+
const LOOPBACK = new BlockList();
|
|
3483
|
+
LOOPBACK.addSubnet("127.0.0.0", 8, "ipv4");
|
|
3484
|
+
LOOPBACK.addAddress("::1", "ipv6");
|
|
3485
|
+
function isLoopbackHost(host) {
|
|
3486
|
+
const h = host.replace(/^\[(.*)\]$/, "$1");
|
|
3487
|
+
if (h.toLowerCase() === "localhost") return true;
|
|
3488
|
+
const family = isIP(h);
|
|
3489
|
+
return family !== 0 && LOOPBACK.check(h, family === 4 ? "ipv4" : "ipv6");
|
|
3490
|
+
}
|
|
3491
|
+
/**
|
|
3492
|
+
* Parses the §5.13 idempotency knobs. Dedup is on by default;
|
|
3493
|
+
* `SUBSTRATE_IDEMPOTENCY_DISABLED` honours `1` / `true` (case-insensitive). A
|
|
3494
|
+
* malformed TTL (non-integer, negative) throws `EnvConfigError`.
|
|
3495
|
+
*/
|
|
3496
|
+
function parseIdempotencyConfig(env, knobs) {
|
|
3497
|
+
const disabledRaw = env.SUBSTRATE_IDEMPOTENCY_DISABLED;
|
|
3498
|
+
const disabled = disabledRaw !== void 0 && (disabledRaw === "1" || disabledRaw.toLowerCase() === "true");
|
|
3499
|
+
knobs.record("idempotencyDisabled", "SUBSTRATE_IDEMPOTENCY_DISABLED", disabledRaw, disabled);
|
|
3500
|
+
const ttlRaw = env.SUBSTRATE_IDEMPOTENCY_TTL_MS;
|
|
3501
|
+
const noteTtl = (v) => knobs.record("idempotencyTtlMs", "SUBSTRATE_IDEMPOTENCY_TTL_MS", ttlRaw, v);
|
|
3502
|
+
if (disabled) {
|
|
3503
|
+
noteTtl(null);
|
|
3504
|
+
return {
|
|
3505
|
+
defaultTtlMs: null,
|
|
3506
|
+
disabled: true
|
|
3507
|
+
};
|
|
3508
|
+
}
|
|
3509
|
+
if (ttlRaw === void 0 || ttlRaw === "") return {
|
|
3510
|
+
defaultTtlMs: noteTtl(null),
|
|
3511
|
+
disabled: false
|
|
3512
|
+
};
|
|
3513
|
+
const parsed = Number(ttlRaw);
|
|
3514
|
+
if (!Number.isInteger(parsed) || parsed < 0) throw new EnvConfigError(`SUBSTRATE_IDEMPOTENCY_TTL_MS: invalid value '${ttlRaw}' — expected a non-negative integer (milliseconds)`);
|
|
3515
|
+
return {
|
|
3516
|
+
defaultTtlMs: noteTtl(parsed),
|
|
3517
|
+
disabled: false
|
|
3518
|
+
};
|
|
3519
|
+
}
|
|
3520
|
+
/**
|
|
3521
|
+
* Read TLS material off disk at parse time. Partial key/cert pairs are a
|
|
3522
|
+
* config bug — silently downgrading to plaintext would mask a deployment
|
|
3523
|
+
* mistake, so we throw. CA is optional (many deployments use the server cert
|
|
3524
|
+
* alone or a `fullchain.pem` with the chain inlined).
|
|
3525
|
+
*/
|
|
3526
|
+
function parseTlsConfig(env) {
|
|
3527
|
+
const keyPath = env.SUBSTRATE_TLS_KEY_PATH;
|
|
3528
|
+
const certPath = env.SUBSTRATE_TLS_CERT_PATH;
|
|
3529
|
+
const caPath = env.SUBSTRATE_TLS_CA_PATH;
|
|
3530
|
+
const hasKey = typeof keyPath === "string" && keyPath.length > 0;
|
|
3531
|
+
const hasCert = typeof certPath === "string" && certPath.length > 0;
|
|
3532
|
+
if (!hasKey && !hasCert) {
|
|
3533
|
+
if (typeof caPath === "string" && caPath.length > 0) throw new EnvConfigError("SUBSTRATE_TLS_CA_PATH set but SUBSTRATE_TLS_KEY_PATH and SUBSTRATE_TLS_CERT_PATH are not");
|
|
3534
|
+
return null;
|
|
3535
|
+
}
|
|
3536
|
+
if (!hasKey) throw new EnvConfigError("SUBSTRATE_TLS_CERT_PATH set but SUBSTRATE_TLS_KEY_PATH is not");
|
|
3537
|
+
if (!hasCert) throw new EnvConfigError("SUBSTRATE_TLS_KEY_PATH set but SUBSTRATE_TLS_CERT_PATH is not");
|
|
3538
|
+
const tls = {
|
|
3539
|
+
key: readTlsFile("SUBSTRATE_TLS_KEY_PATH", keyPath),
|
|
3540
|
+
cert: readTlsFile("SUBSTRATE_TLS_CERT_PATH", certPath)
|
|
3541
|
+
};
|
|
3542
|
+
if (typeof caPath === "string" && caPath.length > 0) tls.ca = readTlsFile("SUBSTRATE_TLS_CA_PATH", caPath);
|
|
3543
|
+
return tls;
|
|
3544
|
+
}
|
|
3545
|
+
function readTlsFile(envVar, path) {
|
|
3546
|
+
try {
|
|
3547
|
+
return readFileSync(path);
|
|
3548
|
+
} catch (err) {
|
|
3549
|
+
throw new EnvConfigError(`${envVar}: cannot read '${path}': ${err instanceof Error ? err.message : String(err)}`);
|
|
3550
|
+
}
|
|
3551
|
+
}
|
|
3552
|
+
function readPackageVersion() {
|
|
3553
|
+
if (typeof version === "string" && version.length > 0) return version;
|
|
3554
|
+
process.stderr.write("warning: apps/substrate package.json has no string 'version' field — onboard will report '0.0.0'\n");
|
|
3555
|
+
return "0.0.0";
|
|
3556
|
+
}
|
|
3557
|
+
/**
|
|
3558
|
+
* The binary's substrate-types contract version. Lifted from package.json at
|
|
3559
|
+
* build time; vite inlines the import so the bundled binary carries the
|
|
3560
|
+
* literal value. Plugin contractVersion ranges are checked against this.
|
|
3561
|
+
*/
|
|
3562
|
+
const BINARY_CONTRACT_VERSION = readPackageVersion();
|
|
3563
|
+
/**
|
|
3564
|
+
* Throws `EnvConfigError` for a plugin whose `contractVersion` does not admit
|
|
3565
|
+
* this binary. Fatal by design: a plugin built against an unsatisfied
|
|
3566
|
+
* contract fails silently rather than loudly.
|
|
3567
|
+
*/
|
|
3568
|
+
function refuseContractViolation(v) {
|
|
3569
|
+
const detail = v.reason === "invalid-range" ? `declares contractVersion '${v.declared}', which is not a valid semver range` : `declares contractVersion '${v.declared}', which does not admit this binary (${v.hostVersion})`;
|
|
3570
|
+
throw new EnvConfigError(`[${v.packageName}] ${v.tier} plugin ${detail}. Refusing to load it: a plugin built against a contract this binary does not satisfy fails silently rather than loudly, which is why this is fatal. Fix by widening that plugin's contractVersion to admit ${v.hostVersion} — a range's ceiling tracks actual compatibility, so it moves only when a major genuinely breaks the plugin interface, not at every major boundary.`);
|
|
3571
|
+
}
|
|
3572
|
+
function parseBridges(raw) {
|
|
3573
|
+
if (raw === void 0 || raw.trim() === "") return [];
|
|
3574
|
+
let parsed;
|
|
3575
|
+
try {
|
|
3576
|
+
parsed = JSON.parse(raw);
|
|
3577
|
+
} catch (err) {
|
|
3578
|
+
throw new EnvConfigError(`SUBSTRATE_BRIDGES: invalid JSON — ${err instanceof Error ? err.message : String(err)}`);
|
|
3579
|
+
}
|
|
3580
|
+
if (!Array.isArray(parsed)) throw new EnvConfigError("SUBSTRATE_BRIDGES: must be a JSON array of { ns, name, url } entries");
|
|
3581
|
+
const out = [];
|
|
3582
|
+
for (const [i, entry] of parsed.entries()) {
|
|
3583
|
+
if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw new EnvConfigError(`SUBSTRATE_BRIDGES: entry ${i} must be an object`);
|
|
3584
|
+
const e = entry;
|
|
3585
|
+
const ns = e.ns;
|
|
3586
|
+
const name = e.name;
|
|
3587
|
+
const url = e.url;
|
|
3588
|
+
if (typeof ns !== "string" || ns.length === 0) throw new EnvConfigError(`SUBSTRATE_BRIDGES: entry ${i} missing string 'ns'`);
|
|
3589
|
+
if (typeof name !== "string" || name.length === 0) throw new EnvConfigError(`SUBSTRATE_BRIDGES: entry ${i} missing string 'name'`);
|
|
3590
|
+
if (typeof url !== "string" || url.length === 0) throw new EnvConfigError(`SUBSTRATE_BRIDGES: entry ${i} missing string 'url'`);
|
|
3591
|
+
out.push({
|
|
3592
|
+
ns,
|
|
3593
|
+
name,
|
|
3594
|
+
url
|
|
3595
|
+
});
|
|
3596
|
+
}
|
|
3597
|
+
return out;
|
|
3598
|
+
}
|
|
3599
|
+
function parseBridgeCreds(raw) {
|
|
3600
|
+
const store = new MemoryBridgeCredentialStore();
|
|
3601
|
+
if (raw === void 0 || raw.trim() === "") return store;
|
|
3602
|
+
let parsed;
|
|
3603
|
+
try {
|
|
3604
|
+
parsed = JSON.parse(raw);
|
|
3605
|
+
} catch (err) {
|
|
3606
|
+
throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: invalid JSON — ${err instanceof Error ? err.message : String(err)}`);
|
|
3607
|
+
}
|
|
3608
|
+
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new EnvConfigError("SUBSTRATE_BRIDGE_CREDENTIALS: must be a JSON object mapping bridge name → { keyPath, kid }");
|
|
3609
|
+
for (const [name, entry] of Object.entries(parsed)) {
|
|
3610
|
+
if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: entry '${name}' must be an object`);
|
|
3611
|
+
const e = entry;
|
|
3612
|
+
if (typeof e.keyPath !== "string" || e.keyPath.length === 0) throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: entry '${name}' missing string 'keyPath'`);
|
|
3613
|
+
if (typeof e.kid !== "string" || e.kid.length === 0) throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: entry '${name}' missing string 'kid'`);
|
|
3614
|
+
if (typeof e.origin !== "string" || e.origin.length === 0) throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: entry '${name}' missing string 'origin'`);
|
|
3615
|
+
let origin;
|
|
3616
|
+
try {
|
|
3617
|
+
const parsed = new URL(e.origin);
|
|
3618
|
+
if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: entry '${name}' has a non-http(s) 'origin' — expected http:// or https://, got '${e.origin}'`);
|
|
3619
|
+
origin = parsed.origin;
|
|
3620
|
+
} catch (err) {
|
|
3621
|
+
if (err instanceof EnvConfigError) throw err;
|
|
3622
|
+
throw new EnvConfigError(`SUBSTRATE_BRIDGE_CREDENTIALS: entry '${name}' has a malformed 'origin' — expected scheme://host[:port], got '${e.origin}'`);
|
|
3623
|
+
}
|
|
3624
|
+
store.set(name, {
|
|
3625
|
+
keyPath: e.keyPath,
|
|
3626
|
+
kid: e.kid,
|
|
3627
|
+
origin
|
|
3628
|
+
});
|
|
3629
|
+
}
|
|
3630
|
+
return store;
|
|
3631
|
+
}
|
|
3632
|
+
|
|
3633
|
+
//#endregion
|
|
3634
|
+
//#region src/serve/compose-opts.ts
|
|
3635
|
+
/**
|
|
3636
|
+
* serve/compose-opts.ts — `compose()` options assembly.
|
|
3637
|
+
*
|
|
3638
|
+
* Pure assembly over already-built pieces: datasets, bridges, auth, ticket
|
|
3639
|
+
* secret, idempotency. No I/O except the sentinel-client env read; the
|
|
3640
|
+
* substrate-migrations table ensure runs here too so it lands before any
|
|
3641
|
+
* substrate plugin migration.
|
|
3642
|
+
*/
|
|
3643
|
+
/**
|
|
3644
|
+
* The free-disk check every pg dataset runs before a background index build,
|
|
3645
|
+
* or none when `SUBSTRATE_INDEX_DISK_PATH=off`. A configured path is statted
|
|
3646
|
+
* once here, so a typo fails the boot rather than every build.
|
|
3647
|
+
*/
|
|
3648
|
+
async function indexDiskGuard(config, statfs$1 = (p) => statfs(p)) {
|
|
3649
|
+
const path = config.indexDiskPath;
|
|
3650
|
+
if (path === "off") return void 0;
|
|
3651
|
+
if (path !== null) try {
|
|
3652
|
+
await statfs$1(path);
|
|
3653
|
+
} catch (err) {
|
|
3654
|
+
throw new EnvConfigError(`SUBSTRATE_INDEX_DISK_PATH: ${path} is not readable: ${err instanceof Error ? err.message : String(err)}`);
|
|
3655
|
+
}
|
|
3656
|
+
return makeDiskGuard({
|
|
3657
|
+
...path !== null ? { path } : {},
|
|
3658
|
+
marginBytes: config.indexDiskMarginMb * 1024 * 1024
|
|
3659
|
+
});
|
|
3660
|
+
}
|
|
3661
|
+
async function buildComposeOpts(args) {
|
|
3662
|
+
const { config, server, dataset, edges, coordinators, storeSql, substrateNamespaceDataset, fieldDefLookupFor, typeDefLookup, kernel, diskGuard } = args;
|
|
3663
|
+
const composeOpts = {
|
|
3664
|
+
server,
|
|
3665
|
+
dataset,
|
|
3666
|
+
edges,
|
|
3667
|
+
trustedProxies: config.trustedProxies,
|
|
3668
|
+
pageLimits: config.pageLimits,
|
|
3669
|
+
subscriptions: { snapshotLimit: config.snapshotLimit },
|
|
3670
|
+
configReport: config.knobs,
|
|
3671
|
+
advisor: {
|
|
3672
|
+
intervalMs: config.advisorIntervalMs,
|
|
3673
|
+
...config.storeProfile !== null ? { storeProfile: config.storeProfile } : {},
|
|
3674
|
+
writeHeavy: config.storeWriteHeavy
|
|
3675
|
+
}
|
|
3676
|
+
};
|
|
3677
|
+
if (dataset.storageReport !== void 0) {
|
|
3678
|
+
const report = dataset.storageReport.bind(dataset);
|
|
3679
|
+
composeOpts.storageReport = () => report({ partitionBudget: config.partitionBudget });
|
|
3680
|
+
}
|
|
3681
|
+
if (coordinators.length > 0) {
|
|
3682
|
+
composeOpts.coordinators = coordinators;
|
|
3683
|
+
composeOpts.datasets = buildPluginDatasetMap(coordinators, dataset, storeSql, storeSql !== null ? edges : null, fieldDefLookupFor, typeDefLookup, diskGuard);
|
|
3684
|
+
}
|
|
3685
|
+
if (substrateNamespaceDataset !== null) {
|
|
3686
|
+
if (composeOpts.datasets === void 0) composeOpts.datasets = {};
|
|
3687
|
+
if (composeOpts.datasets["_system"] !== void 0) process.stdout.write(`warning: coordinator-contributed '${SYSTEM_NAMESPACE}' dataset overridden by main.ts pg wiring\n`);
|
|
3688
|
+
composeOpts.datasets[SYSTEM_NAMESPACE] = substrateNamespaceDataset;
|
|
3689
|
+
}
|
|
3690
|
+
const { registry: bridgeRegistry, dispose: disposeBridges } = buildBridgeRegistry(config.bridges, config.bridgeCreds);
|
|
3691
|
+
try {
|
|
3692
|
+
const sentinelClientConfig = loadConfig(process.env);
|
|
3693
|
+
if (config.bridges.length > 0 || sentinelClientConfig !== null) composeOpts.bridges = bridgeRegistry;
|
|
3694
|
+
if (config.auth !== null) composeOpts.auth = config.auth;
|
|
3695
|
+
if (config.keyReprimeIntervalMs !== null) composeOpts.keyReprimeIntervalMs = config.keyReprimeIntervalMs;
|
|
3696
|
+
if (config.systemActor !== null) composeOpts.systemActor = config.systemActor;
|
|
3697
|
+
if (config.streamTicketSecret !== null) composeOpts.streamTicketSecret = config.streamTicketSecret;
|
|
3698
|
+
let idempotencyStore = null;
|
|
3699
|
+
if (!config.idempotency.disabled) {
|
|
3700
|
+
idempotencyStore = storeSql !== null ? new PgIdempotencyStore({ sql: storeSql }) : new MemoryIdempotencyStore();
|
|
3701
|
+
const idempotencyOpt = { store: idempotencyStore };
|
|
3702
|
+
if (config.idempotency.defaultTtlMs !== null) idempotencyOpt.defaultTtlMs = config.idempotency.defaultTtlMs;
|
|
3703
|
+
composeOpts.idempotency = idempotencyOpt;
|
|
3704
|
+
}
|
|
3705
|
+
composeOpts.version = readPackageVersion();
|
|
3706
|
+
if (kernel.length > 0) composeOpts.kernelPlugins = kernel;
|
|
3707
|
+
await ensureMigrationsTable(storeSql);
|
|
3708
|
+
return {
|
|
3709
|
+
composeOpts,
|
|
3710
|
+
idempotencyStore,
|
|
3711
|
+
sentinelClientConfig,
|
|
3712
|
+
bridgeRegistry,
|
|
3713
|
+
disposeBridges
|
|
3714
|
+
};
|
|
3715
|
+
} catch (err) {
|
|
3716
|
+
disposeBridges();
|
|
3717
|
+
throw err;
|
|
3718
|
+
}
|
|
3719
|
+
}
|
|
3720
|
+
|
|
3721
|
+
//#endregion
|
|
3722
|
+
//#region src/serve/late-refs.ts
|
|
3723
|
+
function createLateRefs(auth) {
|
|
3724
|
+
const datasetRegistryRef = { current: null };
|
|
3725
|
+
const resolveDataset = (namespace) => datasetRegistryRef.current?.get(namespace) ?? null;
|
|
3726
|
+
const engineRef = { current: null };
|
|
3727
|
+
const checkReadPolicy = (ns, type, identity, probe) => engineRef.current?.evaluateReadPolicy(ns, type, identity, probe) ?? {
|
|
3728
|
+
allow: false,
|
|
3729
|
+
reason: "engine not ready"
|
|
3730
|
+
};
|
|
3731
|
+
const checkWritePolicy = (ns, type, identity, probe) => engineRef.current?.evaluateWritePolicy(ns, type, identity, probe) ?? {
|
|
3732
|
+
allow: false,
|
|
3733
|
+
reason: "engine not ready"
|
|
3734
|
+
};
|
|
3735
|
+
return {
|
|
3736
|
+
datasetRegistryRef,
|
|
3737
|
+
resolveDataset,
|
|
3738
|
+
engineRef,
|
|
3739
|
+
checkReadPolicy,
|
|
3740
|
+
checkWritePolicy,
|
|
3741
|
+
kernelAuth: auth === null ? null : { ...auth }
|
|
3742
|
+
};
|
|
3743
|
+
}
|
|
3744
|
+
/**
|
|
3745
|
+
* Populate the late-bound holders after `compose()`, including handing
|
|
3746
|
+
* kernel routes the key registry compose primed.
|
|
3747
|
+
*
|
|
3748
|
+
* Throws when auth is enabled and `keyRegistry` is absent: that is always a
|
|
3749
|
+
* mismatched install (`@mnmal-ai/substrate-compose` is an external runtime
|
|
3750
|
+
* dependency), and serving on would 401 every signed agent silently.
|
|
3751
|
+
*/
|
|
3752
|
+
function populateLateRefs(refs, composedDatasets, engine, keyRegistry) {
|
|
3753
|
+
const kernelAuth = refs.kernelAuth;
|
|
3754
|
+
if (kernelAuth !== null) {
|
|
3755
|
+
if (keyRegistry === null || keyRegistry === void 0) throw new Error("substrate: auth is enabled but compose returned no keyRegistry. This is a MISMATCHED INSTALL, not a config problem — @mnmal-ai/substrate-compose is older than @mnmal-ai/substrate and predates ComposeResult.keyRegistry. Every signed agent request to a kernel route would 401 while unsigned ones succeed. Reinstall the substrate line together rather than swapping one dist.");
|
|
3756
|
+
kernelAuth.keyRegistry = keyRegistry;
|
|
3757
|
+
}
|
|
3758
|
+
refs.datasetRegistryRef.current = composedDatasets;
|
|
3759
|
+
refs.engineRef.current = engine;
|
|
3760
|
+
}
|
|
3761
|
+
|
|
3762
|
+
//#endregion
|
|
3763
|
+
//#region src/serve/nl-engine.ts
|
|
3764
|
+
/**
|
|
3765
|
+
* serve/nl-engine.ts — the engine access substrate-nl is handed.
|
|
3766
|
+
*
|
|
3767
|
+
* Fail-closed: the plugin only calls these from inside a request, after
|
|
3768
|
+
* compose() populated the ref, so a null engine means a fault. Queries run
|
|
3769
|
+
* under the caller's request context and the remote page bounds, since an NL
|
|
3770
|
+
* request is a remote read.
|
|
3771
|
+
*/
|
|
3772
|
+
function nlEngineAccess(engineRef, trustedProxies, pageLimits) {
|
|
3773
|
+
const ready = () => {
|
|
3774
|
+
const engine = engineRef.current;
|
|
3775
|
+
if (engine === null) throw new Error("substrate-nl: engine not ready");
|
|
3776
|
+
return engine;
|
|
3777
|
+
};
|
|
3778
|
+
return {
|
|
3779
|
+
federatedSchema: () => ready().federatedSchema(),
|
|
3780
|
+
operators: (ns) => {
|
|
3781
|
+
const dataset = ready().datasetFor(ns);
|
|
3782
|
+
return dataset === void 0 ? void 0 : effectiveFilterOperators(dataset.capabilities);
|
|
3783
|
+
},
|
|
3784
|
+
query: async (frame, req) => ready().query({
|
|
3785
|
+
frame,
|
|
3786
|
+
ctx: buildContext(req, trustedProxies),
|
|
3787
|
+
pageLimits,
|
|
3788
|
+
...req.signal !== void 0 ? { signal: req.signal } : {}
|
|
3789
|
+
})
|
|
3790
|
+
};
|
|
3791
|
+
}
|
|
3792
|
+
|
|
3793
|
+
//#endregion
|
|
3794
|
+
//#region src/serve/plugins.ts
|
|
3795
|
+
function resolvePluginDir(env = process.env) {
|
|
3796
|
+
const pluginDirRaw = env.SUBSTRATE_PLUGIN_DIR?.trim();
|
|
3797
|
+
return pluginDirRaw !== void 0 && pluginDirRaw.length > 0 ? pluginDirRaw : null;
|
|
3798
|
+
}
|
|
3799
|
+
async function loadServePlugins(opts) {
|
|
3800
|
+
let kernel = [];
|
|
3801
|
+
let coordinators = [];
|
|
3802
|
+
if (opts.pluginDir !== null) {
|
|
3803
|
+
const result = await loadPluginsFromDir({
|
|
3804
|
+
pluginDir: opts.pluginDir,
|
|
3805
|
+
kernelHostDeps: opts.kernelHostDeps,
|
|
3806
|
+
contractCheck: opts.contractCheck
|
|
3807
|
+
});
|
|
3808
|
+
kernel = result.kernel;
|
|
3809
|
+
coordinators = [...result.coordinators];
|
|
3810
|
+
}
|
|
3811
|
+
for (const plugin of coordinators) for (const nsDef of plugin.namespaces) if (!opts.nsDefs.has(nsDef.namespace)) opts.nsDefs.set(nsDef.namespace, nsDef);
|
|
3812
|
+
if (opts.storeSql !== null) {
|
|
3813
|
+
const indexedListFields = extractIndexedListFields(opts.nsDefs);
|
|
3814
|
+
if (indexedListFields.length > 0) await runDerivedMigrations(opts.storeSql, indexedListFields.map(deriveListIndexMigration));
|
|
3815
|
+
}
|
|
3816
|
+
return {
|
|
3817
|
+
kernel,
|
|
3818
|
+
coordinators
|
|
3819
|
+
};
|
|
3820
|
+
}
|
|
3821
|
+
/**
|
|
3822
|
+
* Compose substrate-tier plugins BEFORE coordinator compose, wiring each
|
|
3823
|
+
* KernelPlugin slot (filterOperators, kernelRoutes, mcpTools, migrations,
|
|
3824
|
+
* onKernelReady) into the host's registries. Declared storage is reconciled
|
|
3825
|
+
* first, so kernel migrations run against it.
|
|
3826
|
+
*/
|
|
3827
|
+
async function composeKernelPhase(args) {
|
|
3828
|
+
const { kernel, server, storeSql, coordinators, kernelAuth, trustedProxies } = args;
|
|
3829
|
+
await reconcileDeclaredStorage(args.datasetFor, args.nsDefs);
|
|
3830
|
+
let layout = null;
|
|
3831
|
+
if (storeSql !== null) {
|
|
3832
|
+
const detected = await detectLayout(storeSql);
|
|
3833
|
+
if (detected === "absent") throw new Error("kernel migrations need `rows`, but it is absent");
|
|
3834
|
+
layout = detected;
|
|
3835
|
+
}
|
|
3836
|
+
await composeKernelPlugins(kernel, {
|
|
3837
|
+
sql: storeSql,
|
|
3838
|
+
layout,
|
|
3839
|
+
background: args.background ?? true,
|
|
3840
|
+
coordinatorNamespaces: coordinators.flatMap((p) => p.namespaces.map((n) => n.namespace)),
|
|
3841
|
+
coordinatorNamespacesByPlugin: coordinators.flatMap((p) => p.namespaces.map((n) => ({
|
|
3842
|
+
plugin: p.name,
|
|
3843
|
+
namespace: n.namespace
|
|
3844
|
+
}))),
|
|
3845
|
+
metric: (name, payload) => {
|
|
3846
|
+
process.stdout.write(`[substrate/metric] ${name} ${payload === void 0 ? "" : JSON.stringify(payload)}\n`);
|
|
3847
|
+
},
|
|
3848
|
+
registerKernelRoute: (claim) => {
|
|
3849
|
+
mountKernelRoute(server, claim, kernelAuth, trustedProxies);
|
|
3850
|
+
},
|
|
3851
|
+
registerMcpTool: (tool) => {
|
|
3852
|
+
pendingMcpTools.push(tool);
|
|
3853
|
+
},
|
|
3854
|
+
registerFilterOperator: (name, op) => {
|
|
3855
|
+
filterRegistry.register(name, op);
|
|
3856
|
+
},
|
|
3857
|
+
getAppliedMigrationIds: (pluginName) => getAppliedMigrationIds(storeSql, pluginName),
|
|
3858
|
+
applyMigration: async (pluginName, migrationId) => {
|
|
3859
|
+
await recordMigrationApplied(storeSql, pluginName, migrationId);
|
|
3860
|
+
process.stdout.write(`[substrate] kernel migration applied: ${pluginName}:${migrationId}\n`);
|
|
3861
|
+
}
|
|
3862
|
+
});
|
|
3863
|
+
}
|
|
3864
|
+
|
|
3865
|
+
//#endregion
|
|
3866
|
+
//#region src/rows-missing-probe.ts
|
|
3867
|
+
/** `substrate-recall`'s `memberKey` — kept in step with it by the shared string form. */
|
|
3868
|
+
function memberKey(ref) {
|
|
3869
|
+
return `${ref.namespace}/${ref.type}/${ref.id}`;
|
|
3870
|
+
}
|
|
3871
|
+
function createRowsMissingProbe(opts) {
|
|
3872
|
+
return async (refs) => {
|
|
3873
|
+
const groups = /* @__PURE__ */ new Map();
|
|
3874
|
+
for (const ref of refs) {
|
|
3875
|
+
const key = `${ref.namespace}/${ref.type}`;
|
|
3876
|
+
const group = groups.get(key);
|
|
3877
|
+
if (group === void 0) groups.set(key, {
|
|
3878
|
+
namespace: ref.namespace,
|
|
3879
|
+
type: ref.type,
|
|
3880
|
+
ids: /* @__PURE__ */ new Set([ref.id])
|
|
3881
|
+
});
|
|
3882
|
+
else group.ids.add(ref.id);
|
|
3883
|
+
}
|
|
3884
|
+
const missing = /* @__PURE__ */ new Set();
|
|
3885
|
+
for (const { namespace, type, ids } of groups.values()) {
|
|
3886
|
+
const dataset = opts.resolveDataset(namespace);
|
|
3887
|
+
if (dataset === null) continue;
|
|
3888
|
+
const asked = [...ids];
|
|
3889
|
+
const result = await dataset.read(type, {
|
|
3890
|
+
ids: asked,
|
|
3891
|
+
fields: {}
|
|
3892
|
+
});
|
|
3893
|
+
const found = new Set(result.rows.map((row) => String(row.id)));
|
|
3894
|
+
for (const id of asked) if (!found.has(id)) missing.add(memberKey({
|
|
3895
|
+
namespace,
|
|
3896
|
+
type,
|
|
3897
|
+
id
|
|
3898
|
+
}));
|
|
3899
|
+
}
|
|
3900
|
+
return missing;
|
|
3901
|
+
};
|
|
3902
|
+
}
|
|
3903
|
+
|
|
3904
|
+
//#endregion
|
|
3905
|
+
//#region src/serve/stores.ts
|
|
3906
|
+
/**
|
|
3907
|
+
* serve/stores.ts — recall/cluster store construction.
|
|
3908
|
+
*
|
|
3909
|
+
* The binary owns the pg pool and constructs the EmbeddingsStore, handing it
|
|
3910
|
+
* to recall via kernelHostDeps. Same pg-vs-memory split for all three
|
|
3911
|
+
* stores; memory variants close over the late-bound dataset registry so
|
|
3912
|
+
* content joins resolve after `compose()` populates it.
|
|
3913
|
+
*/
|
|
3914
|
+
function buildRecallStores(storeSql, datasetRegistryRef, resolveDataset) {
|
|
3915
|
+
return {
|
|
3916
|
+
recallStore: storeSql !== null ? new PgEmbeddingsStore({ sql: storeSql }) : new InMemoryEmbeddingsStore({ datasetFor: (ns) => datasetRegistryRef.current?.get(ns) }),
|
|
3917
|
+
lexicalStore: storeSql !== null ? new PgLexicalStore(storeSql) : new InMemoryLexicalStore({ datasetFor: (ns) => datasetRegistryRef.current?.get(ns) }),
|
|
3918
|
+
clusterStore: storeSql !== null ? new PgClusterStore({ sql: storeSql }) : new InMemoryClusterStore(),
|
|
3919
|
+
rowsMissing: createRowsMissingProbe({ resolveDataset })
|
|
3920
|
+
};
|
|
3921
|
+
}
|
|
3922
|
+
|
|
3923
|
+
//#endregion
|
|
3924
|
+
//#region src/serve/boot-store.ts
|
|
3925
|
+
/**
|
|
3926
|
+
* serve/boot-store.ts — every step of `substrate serve`'s boot before the
|
|
3927
|
+
* server listens: open and migrate the store, load plugins, compose the kernel
|
|
3928
|
+
* and coordinators, and reconcile registered storage. `runServe` listens on
|
|
3929
|
+
* the result; `substrate-admin migrate-store` prepares a target with it.
|
|
3930
|
+
*/
|
|
3931
|
+
async function bootStore(opts) {
|
|
3932
|
+
const { pluginDir } = opts;
|
|
3933
|
+
const background = opts.background ?? true;
|
|
3934
|
+
const config = background ? opts.config : {
|
|
3935
|
+
...opts.config,
|
|
3936
|
+
advisorIntervalMs: 0
|
|
3937
|
+
};
|
|
3938
|
+
const nsDefs = /* @__PURE__ */ new Map();
|
|
3939
|
+
const fieldDefLookupFor = makeFieldDefLookupFactory(nsDefs);
|
|
3940
|
+
const diskGuard = await indexDiskGuard(config);
|
|
3941
|
+
const refs = createLateRefs(config.auth);
|
|
3942
|
+
const typeDefLookupFor = makeTypeDefLookupFactory(nsDefs, (ns) => refs.engineRef.current?.registryFor(ns));
|
|
3943
|
+
const { dataset, edges, substrateNamespaceDataset, sql: storeSql, close: closeStore } = await wireStore(config.storeSpec, fieldDefLookupFor, typeDefLookupFor, diskGuard, opts.layout);
|
|
3944
|
+
const opened = [];
|
|
3945
|
+
if (closeStore !== null) opened.push(closeStore);
|
|
3946
|
+
try {
|
|
3947
|
+
if (storeSql !== null && opts.allowMigrating !== true) await assertNotMigrating(storeSql);
|
|
3948
|
+
const { datasetRegistryRef, resolveDataset, engineRef, checkReadPolicy, checkWritePolicy } = refs;
|
|
3949
|
+
const { recallStore, lexicalStore, clusterStore, rowsMissing } = buildRecallStores(storeSql, datasetRegistryRef, resolveDataset);
|
|
3950
|
+
const { kernel, coordinators } = await loadServePlugins({
|
|
3951
|
+
pluginDir,
|
|
3952
|
+
kernelHostDeps: {
|
|
3953
|
+
store: recallStore,
|
|
3954
|
+
lexicalStore,
|
|
3955
|
+
resolveDataset,
|
|
3956
|
+
edges,
|
|
3957
|
+
checkReadPolicy,
|
|
3958
|
+
checkWritePolicy,
|
|
3959
|
+
clusters: clusterStore,
|
|
3960
|
+
rowsMissing,
|
|
3961
|
+
nlEngine: nlEngineAccess(engineRef, config.trustedProxies, config.pageLimits)
|
|
3962
|
+
},
|
|
3963
|
+
contractCheck: {
|
|
3964
|
+
hostVersion: BINARY_CONTRACT_VERSION,
|
|
3965
|
+
onViolation: refuseContractViolation
|
|
3966
|
+
},
|
|
3967
|
+
nsDefs,
|
|
3968
|
+
storeSql
|
|
3969
|
+
});
|
|
3970
|
+
const stopKernel = async () => {
|
|
3971
|
+
for (const plugin of kernel) await plugin.onKernelStop?.();
|
|
3972
|
+
};
|
|
3973
|
+
opened.push(stopKernel);
|
|
3974
|
+
const server = new FastifySubstrateServer({
|
|
3975
|
+
logger: false,
|
|
3976
|
+
onWarn: (message) => process.stderr.write(`${message}\n`),
|
|
3977
|
+
...config.tls !== null ? { tls: config.tls } : {},
|
|
3978
|
+
...config.cors !== null ? { cors: config.cors } : {},
|
|
3979
|
+
...config.bodyLimit !== null ? { bodyLimit: config.bodyLimit } : {}
|
|
3980
|
+
});
|
|
3981
|
+
const { composeOpts, idempotencyStore, sentinelClientConfig, bridgeRegistry, disposeBridges } = await buildComposeOpts({
|
|
3982
|
+
config,
|
|
3983
|
+
server,
|
|
3984
|
+
dataset,
|
|
3985
|
+
edges,
|
|
3986
|
+
coordinators,
|
|
3987
|
+
storeSql,
|
|
3988
|
+
substrateNamespaceDataset,
|
|
3989
|
+
fieldDefLookupFor,
|
|
3990
|
+
typeDefLookup: typeDefLookupFor(DEFAULT_NAMESPACE),
|
|
3991
|
+
kernel,
|
|
3992
|
+
diskGuard
|
|
3993
|
+
});
|
|
3994
|
+
opened.push(disposeBridges);
|
|
3995
|
+
const operatorsBefore = new Set(listExtensionOperators());
|
|
3996
|
+
opened.push(() => {
|
|
3997
|
+
for (const name of listExtensionOperators()) if (!operatorsBefore.has(name)) unregisterExtensionOperator(name);
|
|
3998
|
+
});
|
|
3999
|
+
await composeKernelPhase({
|
|
4000
|
+
kernel,
|
|
4001
|
+
server,
|
|
4002
|
+
storeSql,
|
|
4003
|
+
coordinators,
|
|
4004
|
+
kernelAuth: refs.kernelAuth,
|
|
4005
|
+
trustedProxies: config.trustedProxies,
|
|
4006
|
+
datasetFor: (ns) => composeOpts.datasets?.[ns],
|
|
4007
|
+
nsDefs,
|
|
4008
|
+
background
|
|
4009
|
+
});
|
|
4010
|
+
const { engine, keyRegistry, sweepDeps, scheduler, datasets: composedDatasets, stop } = await compose(composeOpts);
|
|
4011
|
+
opened.push(() => stop());
|
|
4012
|
+
populateLateRefs(refs, composedDatasets, engine, keyRegistry);
|
|
4013
|
+
await reconcileRegisteredStorage(engine, composedDatasets, nsDefs);
|
|
4014
|
+
return {
|
|
4015
|
+
engine,
|
|
4016
|
+
datasets: composedDatasets,
|
|
4017
|
+
nsDefs,
|
|
4018
|
+
sql: storeSql,
|
|
4019
|
+
server,
|
|
4020
|
+
close: () => release(opened),
|
|
4021
|
+
dataset,
|
|
4022
|
+
edges,
|
|
4023
|
+
substrateNamespaceDataset,
|
|
4024
|
+
closeStore: closeStore === null ? null : async () => {
|
|
4025
|
+
try {
|
|
4026
|
+
await stopKernel();
|
|
4027
|
+
} finally {
|
|
4028
|
+
await closeStore();
|
|
4029
|
+
}
|
|
4030
|
+
},
|
|
4031
|
+
kernel,
|
|
4032
|
+
coordinators,
|
|
4033
|
+
recallStore,
|
|
4034
|
+
lexicalStore,
|
|
4035
|
+
idempotencyStore,
|
|
4036
|
+
sentinelClientConfig,
|
|
4037
|
+
bridgeRegistry,
|
|
4038
|
+
disposeBridges,
|
|
4039
|
+
sweepDeps,
|
|
4040
|
+
scheduler,
|
|
4041
|
+
stop
|
|
4042
|
+
};
|
|
4043
|
+
} catch (err) {
|
|
4044
|
+
await release(opened).catch(() => void 0);
|
|
4045
|
+
throw err;
|
|
4046
|
+
}
|
|
4047
|
+
}
|
|
4048
|
+
/** Runs each release step, last opened first, then throws the first failure. */
|
|
4049
|
+
async function release(opened) {
|
|
4050
|
+
let failure;
|
|
4051
|
+
for (const step of [...opened].reverse()) try {
|
|
4052
|
+
await step();
|
|
4053
|
+
} catch (err) {
|
|
4054
|
+
failure ??= err;
|
|
4055
|
+
}
|
|
4056
|
+
if (failure !== void 0) throw failure;
|
|
4057
|
+
}
|
|
4058
|
+
|
|
4059
|
+
//#endregion
|
|
4060
|
+
export { runKeyListViaRoute as A, describeAdminTarget as B, doctorCommand as C, runBootstrap as D, parseBootstrapArgs as E, base64Url as F, USAGE as G, ARGV_SPEC as H, forUpdate as I, pgNoticeOptions as J, argvError as K, generateAdminKeypair as L, ACTOR_HINT as M, BootstrapError as N, REVOKE_EXIT_CODES as O, CLI_ACTOR_KID as P, listActiveAdminKeys as R, grantLines as S, formatBootstrapOutput as T, validateArgv as U, resolveAdminTarget as V, RESTART_NOTE as W, onboardCommand as _, parseBridgeCreds as a, runRegister as b, refuseContractViolation as c, reportUnguardedIndexBuilds as d, runDeferredIndexBuilds as f, openPgDataset as g, version as h, MS_PER_DAY as i, runKeyPatchViaRoute as j, UPDATE_EXIT_CODES as k, buildDeferredIndexes as l, loadPluginsFromDir as m, resolvePluginDir as n, parseBridges as o, startSentinelClient as p, AdminCliError as q, BINARY_CONTRACT_VERSION as r, parseEnv as s, bootStore as t, redactStoreSpec as u, formatRegisterOutput as v, formatDoctorReport as w, runRegisterViaRoute as x, parseRegisterArgs as y, readKeyById as z };
|