clinkx 1.3.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (123) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/README.md +13 -6
  3. package/clinkx-workflows/dist/child-env.d.ts +3 -0
  4. package/clinkx-workflows/dist/child-env.js +11 -0
  5. package/clinkx-workflows/dist/child-env.js.map +1 -1
  6. package/clinkx-workflows/dist/dashboard/api-routes.d.ts +21 -0
  7. package/clinkx-workflows/dist/dashboard/api-routes.js +27 -0
  8. package/clinkx-workflows/dist/dashboard/api-routes.js.map +1 -1
  9. package/clinkx-workflows/dist/dashboard/auth/challenge-store.d.ts +13 -0
  10. package/clinkx-workflows/dist/dashboard/auth/challenge-store.js.map +1 -1
  11. package/clinkx-workflows/dist/dashboard/auth/controller.d.ts +27 -0
  12. package/clinkx-workflows/dist/dashboard/auth/controller.js +262 -23
  13. package/clinkx-workflows/dist/dashboard/auth/controller.js.map +1 -1
  14. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.d.ts +62 -0
  15. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js +70 -0
  16. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js.map +1 -0
  17. package/clinkx-workflows/dist/dashboard/request-admission.d.ts +6 -0
  18. package/clinkx-workflows/dist/dashboard/request-admission.js +9 -0
  19. package/clinkx-workflows/dist/dashboard/request-admission.js.map +1 -1
  20. package/clinkx-workflows/dist/dashboard/server-factory.js +15 -1
  21. package/clinkx-workflows/dist/dashboard/server-factory.js.map +1 -1
  22. package/clinkx-workflows/dist/dashboard/settings-contract.d.ts +1806 -0
  23. package/clinkx-workflows/dist/dashboard/settings-contract.js +630 -0
  24. package/clinkx-workflows/dist/dashboard/settings-contract.js.map +1 -0
  25. package/clinkx-workflows/dist/dashboard/settings-process-reader.d.ts +48 -0
  26. package/clinkx-workflows/dist/dashboard/settings-process-reader.js +195 -0
  27. package/clinkx-workflows/dist/dashboard/settings-process-reader.js.map +1 -0
  28. package/clinkx-workflows/dist/dashboard/settings-routes.d.ts +87 -0
  29. package/clinkx-workflows/dist/dashboard/settings-routes.js +690 -0
  30. package/clinkx-workflows/dist/dashboard/settings-routes.js.map +1 -0
  31. package/clinkx-workflows/dist/dashboard-ui/assets/index-DSOtuS0p.js +122 -0
  32. package/clinkx-workflows/dist/dashboard-ui/assets/style-C5guUjwN.css +1 -0
  33. package/clinkx-workflows/dist/dashboard-ui/index.html +2 -2
  34. package/clinkx-workflows/dist/durable-file-core.d.ts +76 -0
  35. package/clinkx-workflows/dist/durable-file-core.js +146 -0
  36. package/clinkx-workflows/dist/durable-file-core.js.map +1 -0
  37. package/clinkx-workflows/dist/durable-file.d.ts +8 -64
  38. package/clinkx-workflows/dist/durable-file.js +14 -137
  39. package/clinkx-workflows/dist/durable-file.js.map +1 -1
  40. package/clinkx-workflows/dist/index.js +68 -2
  41. package/clinkx-workflows/dist/index.js.map +1 -1
  42. package/clinkx-workflows/dist/settings/audit.d.ts +101 -0
  43. package/clinkx-workflows/dist/settings/audit.js +318 -0
  44. package/clinkx-workflows/dist/settings/audit.js.map +1 -0
  45. package/clinkx-workflows/dist/settings/bootstrap.d.ts +35 -0
  46. package/clinkx-workflows/dist/settings/bootstrap.js +52 -0
  47. package/clinkx-workflows/dist/settings/bootstrap.js.map +1 -0
  48. package/clinkx-workflows/dist/settings/codec.d.ts +51 -0
  49. package/clinkx-workflows/dist/settings/codec.js +410 -0
  50. package/clinkx-workflows/dist/settings/codec.js.map +1 -0
  51. package/clinkx-workflows/dist/settings/durable-write.d.ts +48 -0
  52. package/clinkx-workflows/dist/settings/durable-write.js +31 -0
  53. package/clinkx-workflows/dist/settings/durable-write.js.map +1 -0
  54. package/clinkx-workflows/dist/settings/index.d.ts +20 -0
  55. package/clinkx-workflows/dist/settings/index.js +23 -0
  56. package/clinkx-workflows/dist/settings/index.js.map +1 -0
  57. package/clinkx-workflows/dist/settings/loader.d.ts +80 -0
  58. package/clinkx-workflows/dist/settings/loader.js +577 -0
  59. package/clinkx-workflows/dist/settings/loader.js.map +1 -0
  60. package/clinkx-workflows/dist/settings/lock.d.ts +108 -0
  61. package/clinkx-workflows/dist/settings/lock.js +344 -0
  62. package/clinkx-workflows/dist/settings/lock.js.map +1 -0
  63. package/clinkx-workflows/dist/settings/paths.d.ts +65 -0
  64. package/clinkx-workflows/dist/settings/paths.js +173 -0
  65. package/clinkx-workflows/dist/settings/paths.js.map +1 -0
  66. package/clinkx-workflows/dist/settings/process-heartbeat.d.ts +47 -0
  67. package/clinkx-workflows/dist/settings/process-heartbeat.js +305 -0
  68. package/clinkx-workflows/dist/settings/process-heartbeat.js.map +1 -0
  69. package/clinkx-workflows/dist/settings/registry.d.ts +178 -0
  70. package/clinkx-workflows/dist/settings/registry.js +1285 -0
  71. package/clinkx-workflows/dist/settings/registry.js.map +1 -0
  72. package/clinkx-workflows/dist/settings/schema.d.ts +404 -0
  73. package/clinkx-workflows/dist/settings/schema.js +415 -0
  74. package/clinkx-workflows/dist/settings/schema.js.map +1 -0
  75. package/clinkx-workflows/dist/settings/store.d.ts +157 -0
  76. package/clinkx-workflows/dist/settings/store.js +842 -0
  77. package/clinkx-workflows/dist/settings/store.js.map +1 -0
  78. package/clinkx-workflows/dist/stdio-entry.d.ts +2 -0
  79. package/clinkx-workflows/dist/stdio-entry.js +52 -0
  80. package/clinkx-workflows/dist/stdio-entry.js.map +1 -0
  81. package/dist/dashboard-cli.js +50 -1
  82. package/dist/dashboard-cli.js.map +1 -1
  83. package/dist/dashboard-companion/protocol.js +17 -0
  84. package/dist/dashboard-companion/protocol.js.map +1 -1
  85. package/dist/dashboard-gateway/control-plane/contracts.d.ts +38 -38
  86. package/dist/dashboard-gateway/tunnel-http.js +20 -0
  87. package/dist/dashboard-gateway/tunnel-http.js.map +1 -1
  88. package/dist/elaris/config.d.ts +10 -0
  89. package/dist/elaris/config.js +27 -1
  90. package/dist/elaris/config.js.map +1 -1
  91. package/dist/elaris/tools.js +4 -1
  92. package/dist/elaris/tools.js.map +1 -1
  93. package/dist/index.d.ts +0 -31
  94. package/dist/index.js +41 -404
  95. package/dist/index.js.map +1 -1
  96. package/dist/lib.d.ts +17 -0
  97. package/dist/lib.js +17 -0
  98. package/dist/lib.js.map +1 -0
  99. package/dist/progress-report/lock.d.ts +17 -59
  100. package/dist/progress-report/lock.js +25 -329
  101. package/dist/progress-report/lock.js.map +1 -1
  102. package/dist/server.js +75 -4
  103. package/dist/server.js.map +1 -1
  104. package/dist/settings-cli/clients.d.ts +137 -0
  105. package/dist/settings-cli/clients.js +1124 -0
  106. package/dist/settings-cli/clients.js.map +1 -0
  107. package/dist/settings-cli/commands.d.ts +67 -0
  108. package/dist/settings-cli/commands.js +726 -0
  109. package/dist/settings-cli/commands.js.map +1 -0
  110. package/dist/settings-cli/format.d.ts +34 -0
  111. package/dist/settings-cli/format.js +40 -0
  112. package/dist/settings-cli/format.js.map +1 -0
  113. package/dist/settings-cli/main.d.ts +18 -0
  114. package/dist/settings-cli/main.js +256 -0
  115. package/dist/settings-cli/main.js.map +1 -0
  116. package/dist/stdio-main.d.ts +73 -0
  117. package/dist/stdio-main.js +455 -0
  118. package/dist/stdio-main.js.map +1 -0
  119. package/docs/configuration.md +340 -39
  120. package/docs/security.md +150 -6
  121. package/package.json +2 -2
  122. package/clinkx-workflows/dist/dashboard-ui/assets/index-DRId2DVA.js +0 -119
  123. package/clinkx-workflows/dist/dashboard-ui/assets/style-CHAw57y5.css +0 -1
@@ -0,0 +1,410 @@
1
+ // ---------------------------------------------------------------------------
2
+ // File-value validation
3
+ // ---------------------------------------------------------------------------
4
+ export const MAX_LIST_ENTRIES = 64;
5
+ export const MAX_LIST_ENTRY_CHARS = 4096;
6
+ function invalid(key, message) {
7
+ return { ok: false, error: `${key}: ${message}` };
8
+ }
9
+ export function validateSettingValue(descriptor, value) {
10
+ switch (descriptor.type) {
11
+ case "bool":
12
+ return typeof value === "boolean"
13
+ ? undefined
14
+ : `${descriptor.key}: expected a boolean`;
15
+ case "int":
16
+ return validateIntValue(descriptor, value);
17
+ case "enum":
18
+ return typeof value === "string" && descriptor.choices.includes(value)
19
+ ? undefined
20
+ : `${descriptor.key}: expected one of ${descriptor.choices.join(", ")}`;
21
+ case "string":
22
+ return validateStringValue(descriptor, value);
23
+ case "url":
24
+ return validateUrlValue(descriptor, value);
25
+ case "list":
26
+ return validateListValue(descriptor, value);
27
+ default: {
28
+ // Fail closed (S1): a descriptor this build does not understand must
29
+ // never validate silently. (The cast is needed because the exhaustive
30
+ // switch narrows to `never` here.)
31
+ const unknown = descriptor;
32
+ return `${unknown.key}: unsupported setting type`;
33
+ }
34
+ }
35
+ }
36
+ function validateIntValue(descriptor, value) {
37
+ if (typeof value !== "number" || !Number.isFinite(value)) {
38
+ return `${descriptor.key}: expected a number`;
39
+ }
40
+ if (descriptor.grammar === "idle_timeout_seconds") {
41
+ // Consumer accepts decimal seconds; bound by the setTimeout timer range.
42
+ // Restrict to spellings the consumer's own regex accepts
43
+ // (/^\d+(\.\d+)?$/ in stdio-watchdog): 1e-7 is a finite in-range number
44
+ // but its encoding makes the real server exit 1 at startup (S5).
45
+ if (!/^\d+(?:\.\d+)?$/.test(String(value)) ||
46
+ value < descriptor.min ||
47
+ value * 1000 > 2_147_483_647) {
48
+ return `${descriptor.key}: must be a plain decimal between ${descriptor.min} and 2147483.647 seconds`;
49
+ }
50
+ return undefined;
51
+ }
52
+ if (!Number.isSafeInteger(value)) {
53
+ return `${descriptor.key}: expected an integer`;
54
+ }
55
+ if (value < descriptor.min) {
56
+ return `${descriptor.key}: must be >= ${descriptor.min}`;
57
+ }
58
+ if (descriptor.max != null && value > descriptor.max) {
59
+ return `${descriptor.key}: must be <= ${descriptor.max}`;
60
+ }
61
+ return undefined;
62
+ }
63
+ function validateStringValue(descriptor, value) {
64
+ if (typeof value !== "string") {
65
+ return `${descriptor.key}: expected a string`;
66
+ }
67
+ const trimmed = value.trim();
68
+ if (trimmed === "" && descriptor.default === "") {
69
+ return undefined; // "" is the explicit "unset" spelling for this key
70
+ }
71
+ if (trimmed.length < descriptor.minLength || trimmed.length > descriptor.maxLength) {
72
+ return `${descriptor.key}: length must be between ${descriptor.minLength} and ${descriptor.maxLength} (trimmed)`;
73
+ }
74
+ if (descriptor.pattern != null && !descriptor.pattern.test(trimmed)) {
75
+ return `${descriptor.key}: value does not match the required shape`;
76
+ }
77
+ return undefined;
78
+ }
79
+ function validateUrlValue(descriptor, value) {
80
+ if (typeof value !== "string") {
81
+ return `${descriptor.key}: expected a string`;
82
+ }
83
+ if (value.trim() === "") {
84
+ return undefined; // unset
85
+ }
86
+ const result = validateSettingsBaseUrl(value);
87
+ return result.ok ? undefined : `${descriptor.key}: ${result.error}`;
88
+ }
89
+ function validateListValue(descriptor, value) {
90
+ if (!Array.isArray(value)) {
91
+ return `${descriptor.key}: expected an array of strings`;
92
+ }
93
+ if (value.length > MAX_LIST_ENTRIES) {
94
+ return `${descriptor.key}: at most ${MAX_LIST_ENTRIES} entries`;
95
+ }
96
+ for (const entry of value) {
97
+ if (typeof entry !== "string") {
98
+ return `${descriptor.key}: entries must be strings`;
99
+ }
100
+ if (entry.length < 1 || entry.length > MAX_LIST_ENTRY_CHARS) {
101
+ return `${descriptor.key}: entry length must be between 1 and ${MAX_LIST_ENTRY_CHARS}`;
102
+ }
103
+ if (entry.includes(descriptor.separator)) {
104
+ return `${descriptor.key}: entries must not contain the list separator "${descriptor.separator}"`;
105
+ }
106
+ }
107
+ return undefined;
108
+ }
109
+ // ---------------------------------------------------------------------------
110
+ // Encoding (file value → consumer legacy env spelling)
111
+ // ---------------------------------------------------------------------------
112
+ export function encodeSettingValue(descriptor, value) {
113
+ switch (descriptor.type) {
114
+ case "bool":
115
+ if (typeof value !== "boolean")
116
+ throw new TypeError(`${descriptor.key}: expected boolean`);
117
+ return value ? "true" : "false";
118
+ case "int":
119
+ if (typeof value !== "number" || !Number.isFinite(value)) {
120
+ throw new TypeError(`${descriptor.key}: expected number`);
121
+ }
122
+ return String(value);
123
+ case "enum":
124
+ case "string":
125
+ case "url":
126
+ if (typeof value !== "string")
127
+ throw new TypeError(`${descriptor.key}: expected string`);
128
+ return value;
129
+ case "list":
130
+ if (!Array.isArray(value))
131
+ throw new TypeError(`${descriptor.key}: expected array`);
132
+ return value.join(",");
133
+ default: {
134
+ // Fail closed (S1): never render a value for an unknown descriptor type.
135
+ const unknown = descriptor;
136
+ throw new TypeError(`${unknown.key}: unsupported setting type`);
137
+ }
138
+ }
139
+ }
140
+ /**
141
+ * The env fill the loader applies for a key whose FILE value is invalid
142
+ * (owner decision 7):
143
+ * - undefined → do not fill (onInvalid "default", or a url restrictive value
144
+ * of "" meaning leave-unset; dependents are handled via `requires`).
145
+ * - string → fill with this exact legacy spelling.
146
+ */
147
+ export function encodeInvalidFillValue(descriptor) {
148
+ if (descriptor.onInvalid === "default") {
149
+ return undefined;
150
+ }
151
+ const restrictive = descriptor.onInvalid.restrictive;
152
+ if (restrictive === "") {
153
+ return undefined; // url: leave unset
154
+ }
155
+ return encodeSettingValue(descriptor, restrictive);
156
+ }
157
+ // ---------------------------------------------------------------------------
158
+ // Legacy parsing (consumer env grammar mirrors)
159
+ // ---------------------------------------------------------------------------
160
+ /**
161
+ * undefined/absent is equivalent to "" for every grammar except the string
162
+ * grammars flagged `blankIsVerbatim`, whose consumers (`??` fallback) treat a
163
+ * present empty value differently from an absent one — those receive the raw
164
+ * undefined so they can keep the distinction.
165
+ */
166
+ export function legacyParseSetting(descriptor, raw) {
167
+ const input = raw == null ? "" : raw;
168
+ switch (descriptor.type) {
169
+ case "bool":
170
+ return legacyParseBool(descriptor, input);
171
+ case "int":
172
+ return legacyParseInt(descriptor, input);
173
+ case "enum":
174
+ return legacyParseEnum(descriptor, input);
175
+ case "string":
176
+ return legacyParseString(descriptor, raw);
177
+ case "url":
178
+ return legacyParseUrl(descriptor, input);
179
+ case "list":
180
+ return legacyParseList(descriptor, input);
181
+ }
182
+ }
183
+ function legacyParseBool(descriptor, raw) {
184
+ switch (descriptor.grammar) {
185
+ case "exact_true":
186
+ // src/config.ts appServerEnabled/elarisEnabled, activity-journal, redact,
187
+ // session-log-stream, pipeline strict fidelity: exactly "true" or not.
188
+ return { ok: true, value: raw === "true" };
189
+ case "env_bool": {
190
+ // clinkx-workflows/src/config.ts envBool: trimmed case-insensitive
191
+ // "true"; empty keeps the fallback (false here).
192
+ if (raw.trim() === "")
193
+ return { ok: true, value: descriptor.default };
194
+ return { ok: true, value: raw.trim().toLowerCase() === "true" };
195
+ }
196
+ case "not_false": {
197
+ // src/config.ts directSessionLogsEnabled / server.ts preflight:
198
+ // absent/empty keeps the default; anything except "false" (trimmed,
199
+ // case-insensitive) enables.
200
+ if (raw.trim() === "")
201
+ return { ok: true, value: descriptor.default };
202
+ return { ok: true, value: raw.trim().toLowerCase() !== "false" };
203
+ }
204
+ case "truthy_set": {
205
+ // src/codex/app-server-client.ts isStrictTrue: 1/true/yes/on.
206
+ return {
207
+ ok: true,
208
+ value: ["1", "true", "yes", "on"].includes(String(raw).toLowerCase()),
209
+ };
210
+ }
211
+ case "allow_secrets_tokens": {
212
+ // src/context-builder/secrets.ts: four tokens per polarity; else -32602.
213
+ const value = raw.trim().toLowerCase();
214
+ if (value === "")
215
+ return { ok: true, value: descriptor.default };
216
+ if (value === "false" || value === "0" || value === "no" || value === "off") {
217
+ return { ok: true, value: false };
218
+ }
219
+ if (value === "true" || value === "1" || value === "yes" || value === "on") {
220
+ return { ok: true, value: true };
221
+ }
222
+ return invalid(descriptor.key, "must be one of true/false/1/0/yes/no/on/off (case-insensitive)");
223
+ }
224
+ }
225
+ }
226
+ function legacyParseInt(descriptor, raw) {
227
+ const fallback = descriptor.default;
228
+ switch (descriptor.grammar) {
229
+ case "safe_parse_int": {
230
+ // src/runner.ts / app-server-registry safeParseInt: silent >0 fallback.
231
+ if (raw === "")
232
+ return { ok: true, value: fallback };
233
+ const n = Number(raw);
234
+ return { ok: true, value: Number.isFinite(n) && n > 0 ? n : fallback };
235
+ }
236
+ case "env_int": {
237
+ // clinkx-workflows config envInt: Number-based >0 fallback (fractions
238
+ // pass through the consumer; the file surface stays integer-only).
239
+ if (raw === "")
240
+ return { ok: true, value: fallback };
241
+ const n = Number(raw);
242
+ return { ok: true, value: Number.isFinite(n) && n > 0 ? n : fallback };
243
+ }
244
+ case "env_non_negative_int": {
245
+ if (raw === "")
246
+ return { ok: true, value: fallback };
247
+ const n = Number(raw);
248
+ return {
249
+ ok: true,
250
+ value: Number.isSafeInteger(n) && n >= 0 ? n : fallback,
251
+ };
252
+ }
253
+ case "trimmed_non_negative_int": {
254
+ // src/context-builder/storage.ts parseNonNegativeInteger: the
255
+ // emptiness check TRIMS, so a whitespace-only env value falls back to
256
+ // the default instead of parsing as 0 (A5).
257
+ if (raw.trim() === "")
258
+ return { ok: true, value: fallback };
259
+ const n = Number(raw);
260
+ return {
261
+ ok: true,
262
+ value: Number.isSafeInteger(n) && n >= 0 ? n : fallback,
263
+ };
264
+ }
265
+ case "env_positive_int": {
266
+ if (raw === "")
267
+ return { ok: true, value: fallback };
268
+ const n = Number(raw);
269
+ return { ok: true, value: Number.isSafeInteger(n) && n >= 1 ? n : fallback };
270
+ }
271
+ case "safe_parse_non_neg_int": {
272
+ // app-server-registry: Number-based >=0 (0 disables).
273
+ if (raw === "")
274
+ return { ok: true, value: fallback };
275
+ const n = Number(raw);
276
+ return { ok: true, value: Number.isFinite(n) && n >= 0 ? n : fallback };
277
+ }
278
+ case "positive_seconds_strict": {
279
+ // src/elaris/config.ts readPositiveSeconds: throws on invalid.
280
+ if (raw.trim() === "")
281
+ return { ok: true, value: fallback };
282
+ const n = Number(raw.trim());
283
+ if (!Number.isFinite(n) || n <= 0) {
284
+ return invalid(descriptor.key, "must be a positive number of seconds");
285
+ }
286
+ return { ok: true, value: n };
287
+ }
288
+ case "cb_max_concurrent": {
289
+ // src/context-builder/config.ts parsePositiveInteger: throws, max 32.
290
+ if (raw.trim() === "")
291
+ return { ok: true, value: fallback };
292
+ const trimmed = raw.trim();
293
+ if (!/^[1-9][0-9]*$/.test(trimmed)) {
294
+ return invalid(descriptor.key, "must be a positive decimal integer");
295
+ }
296
+ const n = Number(trimmed);
297
+ if (!Number.isSafeInteger(n) || n > 32) {
298
+ return invalid(descriptor.key, "must be a positive decimal integer at most 32");
299
+ }
300
+ return { ok: true, value: n };
301
+ }
302
+ case "idle_timeout_seconds": {
303
+ // clinkx-workflows/src/stdio-watchdog.ts: empty → 0; decimal seconds;
304
+ // throws on non-numeric or out-of-timer-range values.
305
+ const trimmed = raw.trim();
306
+ if (trimmed === "")
307
+ return { ok: true, value: 0 };
308
+ if (!/^\d+(?:\.\d+)?$/.test(trimmed)) {
309
+ return invalid(descriptor.key, "must be a non-negative number of seconds");
310
+ }
311
+ const n = Number(trimmed);
312
+ if (!Number.isFinite(n) || n * 1000 > 2_147_483_647) {
313
+ return invalid(descriptor.key, "exceeds the timer range");
314
+ }
315
+ return { ok: true, value: n };
316
+ }
317
+ }
318
+ }
319
+ function legacyParseEnum(descriptor, raw) {
320
+ // clinkx-workflows/src/config.ts envWorkflowContextMode: envStr ("" →
321
+ // default), trimmed, throws on a non-choice value.
322
+ if (raw === "")
323
+ return { ok: true, value: descriptor.default };
324
+ const trimmed = raw.trim();
325
+ if (descriptor.choices.includes(trimmed)) {
326
+ return { ok: true, value: trimmed };
327
+ }
328
+ return invalid(descriptor.key, `must be one of ${descriptor.choices.join(", ")}; got ${JSON.stringify(trimmed)}`);
329
+ }
330
+ function legacyParseString(descriptor, raw) {
331
+ if (raw == null) {
332
+ // Absent env: the consumer's fallback (the registry default) applies.
333
+ return { ok: true, value: descriptor.default };
334
+ }
335
+ if (descriptor.blankIsVerbatim === true && raw.trim() === "") {
336
+ // App-server version gates read `process.env[k] ?? default` (A5): a
337
+ // present-but-empty value passes through verbatim (compareSemver reads it
338
+ // as 0.0.0), never the pinned default.
339
+ return { ok: true, value: raw };
340
+ }
341
+ // envStr: "" (or absent) keeps the default; the value is used verbatim
342
+ // (callers trim where they care).
343
+ if (raw === "")
344
+ return { ok: true, value: descriptor.default };
345
+ const trimmed = raw.trim();
346
+ if (trimmed === "") {
347
+ if (descriptor.blankIsUnset === true) {
348
+ return { ok: true, value: descriptor.default };
349
+ }
350
+ // getWorkflowsContextDefaultCurator throws on a non-empty but blank value.
351
+ return invalid(descriptor.key, "must be non-empty");
352
+ }
353
+ return { ok: true, value: trimmed };
354
+ }
355
+ function legacyParseUrl(descriptor, raw) {
356
+ if (raw.trim() === "")
357
+ return { ok: true, value: "" };
358
+ const result = validateSettingsBaseUrl(raw);
359
+ return result.ok
360
+ ? { ok: true, value: result.value }
361
+ : invalid(descriptor.key, result.error);
362
+ }
363
+ function legacyParseList(descriptor, raw) {
364
+ if (raw === "")
365
+ return { ok: true, value: [] };
366
+ const entries = raw.split(descriptor.separator);
367
+ if (entries.some((entry) => entry === "")) {
368
+ return invalid(descriptor.key, "must not contain empty entries");
369
+ }
370
+ return { ok: true, value: entries };
371
+ }
372
+ // ---------------------------------------------------------------------------
373
+ // URL validation (mirrors src/elaris/config.ts validateElarisBaseUrl)
374
+ // ---------------------------------------------------------------------------
375
+ export function validateSettingsBaseUrl(raw) {
376
+ let parsed;
377
+ try {
378
+ parsed = new URL(raw);
379
+ }
380
+ catch {
381
+ return { ok: false, error: "must be an absolute URL" };
382
+ }
383
+ if (parsed.username || parsed.password) {
384
+ return { ok: false, error: "must not include credentials" };
385
+ }
386
+ const hostname = parsed.hostname.toLowerCase();
387
+ const isLoopback = hostname === "localhost" ||
388
+ hostname === "127.0.0.1" ||
389
+ hostname === "[::1]" ||
390
+ hostname === "::1";
391
+ if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && isLoopback)) {
392
+ return {
393
+ ok: false,
394
+ error: "must use https unless it targets localhost or loopback",
395
+ };
396
+ }
397
+ if (parsed.search || parsed.hash) {
398
+ return { ok: false, error: "must not include query parameters or a fragment" };
399
+ }
400
+ const pathname = parsed.pathname.replace(/\/+$/, "");
401
+ if (pathname !== "" && pathname !== "/") {
402
+ return { ok: false, error: "must not include a path" };
403
+ }
404
+ let value = parsed.toString();
405
+ if (value.endsWith("/")) {
406
+ value = value.slice(0, -1);
407
+ }
408
+ return { ok: true, value };
409
+ }
410
+ //# sourceMappingURL=codec.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/settings/codec.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,48 @@
1
+ import { type DurableFsOps as CoreFsOps, type FileWriter } from "../durable-file-core.js";
2
+ /**
3
+ * Crash-durable publication for the dashboard settings documents
4
+ * (`settings.json`, `secrets.json`, audit and process-heartbeat files).
5
+ *
6
+ * The write itself is the shared implementation in `durable-file-core.ts`
7
+ * (O_EXCL|O_NOFOLLOW temporary, fchmod, fsync, rename, parent-directory
8
+ * fsync; a post-rename directory-fsync failure is a `DurablePublishError`
9
+ * with `published: true`). That module imports node built-ins only, so this
10
+ * one stays logger-free for the settings CLI.
11
+ *
12
+ * What this layer adds: a symlinked target is refused before anything is
13
+ * written. `rename(2)` never writes THROUGH a symlink — it would replace the
14
+ * link — so this refusal is a loud policy check for a planted or accidental
15
+ * link, not the security boundary; the check and the rename are still two
16
+ * syscalls, and the worst case between them is a replaced link, never a
17
+ * write through one.
18
+ */
19
+ export type { DurableFileHandle, DurableWriteOptions } from "../durable-file-core.js";
20
+ export { DurablePublishError } from "../durable-file-core.js";
21
+ /** Publishes files crash-durably; every settings writer goes through this. */
22
+ export type DurableWriter = FileWriter;
23
+ /** A symlinked target is never published through or silently clobbered. */
24
+ export declare class DurableSymlinkTargetError extends Error {
25
+ readonly path: string;
26
+ constructor(path: string);
27
+ }
28
+ /** Filesystem operations the writer uses; injectable for order/fault tests. */
29
+ export interface DurableFsOps extends CoreFsOps {
30
+ lstat(path: string): Promise<{
31
+ isSymbolicLink(): boolean;
32
+ }>;
33
+ }
34
+ export interface DurableWriterDeps {
35
+ readonly fs?: DurableFsOps | undefined;
36
+ readonly tempSuffix?: (() => string) | undefined;
37
+ /**
38
+ * Diagnostics sink (tolerated-but-noteworthy conditions). Deliberately NOT
39
+ * the logger: this module must stay importable in contexts that own no
40
+ * logger, and callers (the store, the heartbeat writer) wire their own.
41
+ * Defaults to silence.
42
+ */
43
+ readonly warn?: ((fields: Record<string, unknown>, message: string) => void) | undefined;
44
+ }
45
+ /** The writer factory: the shared durable writer plus symlink-target refusal. */
46
+ export declare function createDurableWriter(deps?: DurableWriterDeps): DurableWriter;
47
+ /** Production writer. Callers wanting diagnostics pass `createDurableWriter`. */
48
+ export declare const durableWriter: DurableWriter;
@@ -0,0 +1,31 @@
1
+ import { lstat } from "node:fs/promises";
2
+ import { createDurableFileWriterCore, } from "../durable-file-core.js";
3
+ export { DurablePublishError } from "../durable-file-core.js";
4
+ /** A symlinked target is never published through or silently clobbered. */
5
+ export class DurableSymlinkTargetError extends Error {
6
+ path;
7
+ constructor(path) {
8
+ super(`refusing to publish ${path}: the target is a symbolic link`);
9
+ this.name = "DurableSymlinkTargetError";
10
+ this.path = path;
11
+ }
12
+ }
13
+ const nodeLstat = async (path) => await lstat(path);
14
+ /** The writer factory: the shared durable writer plus symlink-target refusal. */
15
+ export function createDurableWriter(deps = {}) {
16
+ const core = createDurableFileWriterCore(deps);
17
+ const lstatTarget = deps.fs?.lstat.bind(deps.fs) ?? nodeLstat;
18
+ return {
19
+ ...core,
20
+ async writeFile(path, data, options) {
21
+ const existing = await lstatTarget(path).catch(() => null);
22
+ if (existing !== null && existing.isSymbolicLink()) {
23
+ throw new DurableSymlinkTargetError(path);
24
+ }
25
+ await core.writeFile(path, data, options);
26
+ },
27
+ };
28
+ }
29
+ /** Production writer. Callers wanting diagnostics pass `createDurableWriter`. */
30
+ export const durableWriter = createDurableWriter();
31
+ //# sourceMappingURL=durable-write.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"durable-write.js","sourceRoot":"","sources":["../../src/settings/durable-write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,OAAO,EACL,2BAA2B,GAG5B,MAAM,yBAAyB,CAAC;AAqBjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAK9D,2EAA2E;AAC3E,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IACzC,IAAI,CAAS;IAEtB,YAAY,IAAY;QACtB,KAAK,CAAC,uBAAuB,IAAI,iCAAiC,CAAC,CAAC;QACpE,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAmBD,MAAM,SAAS,GAAG,KAAK,EAAE,IAAY,EAA0C,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;AAEpG,iFAAiF;AACjF,MAAM,UAAU,mBAAmB,CAAC,OAA0B,EAAE;IAC9D,MAAM,IAAI,GAAG,2BAA2B,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,SAAS,CAAC;IAC9D,OAAO;QACL,GAAG,IAAI;QACP,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO;YACjC,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;YAC3D,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,cAAc,EAAE,EAAE,CAAC;gBACnD,MAAM,IAAI,yBAAyB,CAAC,IAAI,CAAC,CAAC;YAC5C,CAAC;YACD,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC5C,CAAC;KACF,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,MAAM,aAAa,GAAkB,mBAAmB,EAAE,CAAC"}
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Settings module barrel — S0-1 freeze point.
3
+ *
4
+ * Public surface: the registry (keys, descriptors, exclusion lists), the
5
+ * disk-document schemas (settings/secrets/heartbeat/audit) and the codec
6
+ * (file-value validation, legacy encode/parse). Durable writes, the loader
7
+ * and the heartbeat writer (S0-2, A1-1, A1-3) live in sibling modules and are
8
+ * re-exported from here as they land.
9
+ *
10
+ * Keep this subtree dependency-light: registry.ts has zero imports, schema.ts
11
+ * and codec.ts import zod + registry only. The startup bootstrap walks this
12
+ * closure before any logger import.
13
+ */
14
+ export * from "./registry.js";
15
+ export * from "./schema.js";
16
+ export * from "./codec.js";
17
+ export * from "./paths.js";
18
+ export * from "./loader.js";
19
+ export * from "./bootstrap.js";
20
+ export * from "./process-heartbeat.js";
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Settings module barrel — S0-1 freeze point.
3
+ *
4
+ * Public surface: the registry (keys, descriptors, exclusion lists), the
5
+ * disk-document schemas (settings/secrets/heartbeat/audit) and the codec
6
+ * (file-value validation, legacy encode/parse). Durable writes, the loader
7
+ * and the heartbeat writer (S0-2, A1-1, A1-3) live in sibling modules and are
8
+ * re-exported from here as they land.
9
+ *
10
+ * Keep this subtree dependency-light: registry.ts has zero imports, schema.ts
11
+ * and codec.ts import zod + registry only. The startup bootstrap walks this
12
+ * closure before any logger import.
13
+ */
14
+ export * from "./registry.js";
15
+ export * from "./schema.js";
16
+ export * from "./codec.js";
17
+ // A1-1 / A1-3 (Track A runtime): locations, startup loader + bootstrap, and
18
+ // the per-process heartbeat writer.
19
+ export * from "./paths.js";
20
+ export * from "./loader.js";
21
+ export * from "./bootstrap.js";
22
+ export * from "./process-heartbeat.js";
23
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/settings/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,4EAA4E;AAC5E,oCAAoC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC"}
@@ -0,0 +1,80 @@
1
+ export type SettingsLoadState = "off" | "absent" | "loaded" | "unreadable";
2
+ export type SettingsProvenanceSource = "env" | "file" | "default" | "invalid_fallback";
3
+ export interface SettingsProvenanceEntry {
4
+ readonly source: SettingsProvenanceSource;
5
+ /**
6
+ * The effective env spelling for this key. OMITTED for secret-class keys
7
+ * (secret values never appear in the application or the heartbeat) and for
8
+ * the credential-indirection target (L7).
9
+ */
10
+ readonly effective?: string;
11
+ /** Set when the file carried a value for an env-present key. */
12
+ readonly envEqualsFile?: boolean;
13
+ /**
14
+ * True when the value is withheld because this key is the target of the
15
+ * CLINKX_ELARIS_API_KEY_ENV indirection (L7): the value IS the Elaris
16
+ * credential even though the key is an ordinary non-secret registry key.
17
+ */
18
+ readonly withheld?: true;
19
+ }
20
+ export interface SettingsApplication {
21
+ readonly state: SettingsLoadState;
22
+ /** Resolved settings directory ("" when off / invalid / unresolvable). */
23
+ readonly settingsDir: string;
24
+ readonly revision?: number;
25
+ /** sha256 over the raw settings.json bytes, when they were read. */
26
+ readonly digest?: string;
27
+ /**
28
+ * Secrets-document revision when one was read and parsed; null otherwise
29
+ * (off / absent / unreadable). Secret-free by construction: only the
30
+ * revision number travels, never a value (T04; the heartbeat writer and
31
+ * the dashboard freshness rule consume it).
32
+ */
33
+ readonly secretsRevision: number | null;
34
+ /**
35
+ * Load state of the SECRETS document, in the SettingsLoadState vocabulary:
36
+ * "off" = settings disabled, "absent" = no document, "loaded" = applied,
37
+ * "unreadable" = a document exists but was refused (mode/JSON/schema).
38
+ * Secret-free.
39
+ */
40
+ readonly secretsState: SettingsLoadState;
41
+ /** One entry per registry key, in registry order. */
42
+ readonly perKey: Readonly<Record<string, SettingsProvenanceEntry>>;
43
+ /** Unclassified CLINKX_* names in the pre-start env (names only, bounded). */
44
+ readonly unknownEnvKeys: readonly string[];
45
+ readonly warnings: readonly string[];
46
+ }
47
+ export interface StartupSettingsLoadOptions {
48
+ /**
49
+ * Pre-overlay env values used for presence and equality checks. Defaults
50
+ * to `env` itself. The bootstrap passes its ORIGINAL first-call snapshot
51
+ * so a replay never relabels file-filled keys as env.
52
+ */
53
+ readonly envSnapshot?: Readonly<Record<string, string | undefined>>;
54
+ /** Injectable reader (default: hardened node reader). */
55
+ readonly reader?: SettingsFileReader;
56
+ }
57
+ /** Hard per-file cap, applied before any byte is read. */
58
+ export declare const MAX_SETTINGS_FILE_BYTES: number;
59
+ export type SettingsFileReadResult = {
60
+ readonly ok: true;
61
+ readonly bytes: Uint8Array;
62
+ readonly mode: number;
63
+ } | {
64
+ readonly ok: false;
65
+ readonly code: "MISSING" | "SYMLINK" | "NOT_REGULAR" | "TOO_LARGE" | "UNREADABLE";
66
+ };
67
+ export type SettingsFileReader = (path: string) => SettingsFileReadResult;
68
+ /**
69
+ * lstat (no follow) → open O_NOFOLLOW|O_NONBLOCK → fstat regular-file check
70
+ * → capped read. O_NONBLOCK makes an open of a swapped-in FIFO harmless
71
+ * (open-for-read returns immediately instead of blocking); regular files
72
+ * ignore it. A symlink is refused by the lstat gate and again by O_NOFOLLOW.
73
+ */
74
+ export declare function createNodeSettingsFileReader(): SettingsFileReader;
75
+ /**
76
+ * Load the settings documents and overlay them onto `env` (mutated). Fills
77
+ * only VALID file values for keys absent from the pre-start env snapshot —
78
+ * never registry defaults (amendment 1). Never throws.
79
+ */
80
+ export declare function runStartupSettingsLoad(env: Record<string, string | undefined>, options?: StartupSettingsLoadOptions): SettingsApplication;