@intentrax/sdk 1.7.0 → 1.8.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 (43) hide show
  1. package/README.md +17 -2
  2. package/cli/intentrax.mjs +45 -1
  3. package/mcp/README.md +138 -0
  4. package/mcp/canonical.d.ts +12 -0
  5. package/mcp/canonical.mjs +70 -0
  6. package/mcp/cli.d.ts +16 -0
  7. package/mcp/cli.mjs +214 -0
  8. package/mcp/client.d.ts +131 -0
  9. package/mcp/client.mjs +955 -0
  10. package/mcp/commands.d.ts +113 -0
  11. package/mcp/commands.mjs +575 -0
  12. package/mcp/index.d.ts +12 -0
  13. package/mcp/index.mjs +12 -0
  14. package/mcp/proxy.d.ts +47 -0
  15. package/mcp/proxy.mjs +434 -0
  16. package/mcp/receipt-meta.d.ts +59 -0
  17. package/mcp/receipt-meta.mjs +178 -0
  18. package/mcp/tool-manifest.d.ts +74 -0
  19. package/mcp/tool-manifest.mjs +154 -0
  20. package/package.json +16 -1
  21. package/readback/README.md +352 -0
  22. package/readback/bridge.mjs +71 -0
  23. package/readback/cli.mjs +150 -0
  24. package/readback/confirm.mjs +404 -0
  25. package/readback/index.mjs +12 -0
  26. package/readback/recipe-worker.mjs +33 -0
  27. package/readback/recipes/_shared.mjs +126 -0
  28. package/readback/recipes/email-delivery.mjs +136 -0
  29. package/readback/recipes/github-issue.mjs +88 -0
  30. package/readback/recipes/http-json.mjs +109 -0
  31. package/readback/recipes/sql-row.mjs +96 -0
  32. package/readback/recipes/stripe-refund.mjs +73 -0
  33. package/readback/redact.mjs +68 -0
  34. package/scan/README.md +211 -0
  35. package/scan/classify.mjs +276 -0
  36. package/scan/cli.mjs +102 -0
  37. package/scan/configs.mjs +261 -0
  38. package/scan/credentials.mjs +121 -0
  39. package/scan/extract.mjs +323 -0
  40. package/scan/gates.mjs +94 -0
  41. package/scan/report.mjs +58 -0
  42. package/scan/scan.mjs +571 -0
  43. package/scan/text.mjs +186 -0
@@ -0,0 +1,404 @@
1
+ // confirmThenReport: read the outcome back BEFORE reporting success.
2
+ //
3
+ // An agent or executor says it did something ("refund processed", "email
4
+ // sent"). confirmThenReport reads the system of record with a read-only
5
+ // check and compares the fields that matter:
6
+ //
7
+ // CONFIRMED the read matches firstLine "CONFIRMED …"
8
+ // CONTRADICTED the read differs firstLine "CAUGHT …"
9
+ // PENDING still in a not-final state after the retries
10
+ // (eventually-consistent systems) firstLine "PENDING …"
11
+ // UNKNOWN the check threw, timed out, returned something that is not
12
+ // an object, or a field is missing firstLine "UNKNOWN …"
13
+ //
14
+ // Contract: nothing but CONFIRMED is ever worded as success. A field the read
15
+ // did not return is MISSING (UNKNOWN), never treated as null — the same rule
16
+ // as `intentrax sandbox --check`. A null the system did return is a value,
17
+ // compared like any other.
18
+ //
19
+ // Isolation (same approach as the sandbox's check-runner.mjs): a check runs in
20
+ // a worker thread that is terminated when it answers or when `timeoutMs`
21
+ // passes, so a hung socket cannot keep your process alive. That needs the
22
+ // check to be rebuildable on another thread:
23
+ // - a recipe built from plain-data options (a credential string, ids)
24
+ // runs in a worker automatically;
25
+ // - `{ module: "./my-check.mjs" }` runs that module's default export in a
26
+ // worker, as `intentrax sandbox --check` does;
27
+ // - any other function (a closure over your client, an injected fetch) runs
28
+ // in-process, bounded by the same timeout and given an AbortSignal, and
29
+ // `detail.isolation` says "in-process".
30
+ //
31
+ // Provenance: the check is code YOU configured, so every result is labelled
32
+ // SELF_REPORTED. It is evidence for your own pipeline, not an Intentrax
33
+ // attestation, and carries no trust on its own.
34
+ //
35
+ // Redaction: every string is redacted WHOLE (declared secrets, then
36
+ // credential-shaped patterns) before any display cut, so a secret can never be
37
+ // split by a cut and leave an unredactable prefix behind.
38
+
39
+ import { Worker } from "node:worker_threads";
40
+ import { isAbsolute, resolve } from "node:path";
41
+ import { pathToFileURL } from "node:url";
42
+ import { redact } from "./redact.mjs";
43
+ import { RECIPE_META } from "./recipes/_shared.mjs";
44
+
45
+ export const STATUS = Object.freeze({
46
+ CONFIRMED: "CONFIRMED",
47
+ CONTRADICTED: "CONTRADICTED",
48
+ PENDING: "PENDING",
49
+ UNKNOWN: "UNKNOWN",
50
+ });
51
+
52
+ /** The first word of `firstLine` for each status. */
53
+ export const CATCH_WORDS = Object.freeze({
54
+ CONFIRMED: "CONFIRMED",
55
+ CONTRADICTED: "CAUGHT",
56
+ PENDING: "PENDING",
57
+ UNKNOWN: "UNKNOWN",
58
+ });
59
+
60
+ export const PROVENANCE = "SELF_REPORTED";
61
+ export const PROVENANCE_NOTE =
62
+ "Read back by a check you configured (SELF_REPORTED). Not an Intentrax attestation; carries no trust on its own.";
63
+
64
+ const ISOLATION_MODES = new Set(["auto", "worker", "in-process"]);
65
+
66
+ // ---------------------------------------------------------------------------
67
+ // Worker plumbing
68
+
69
+ /** Run a recipe in a worker; same lifecycle as the sandbox's runCheckWorker. */
70
+ export function runRecipeWorker({ href, exportName, options, signal = null }) {
71
+ return runReadbackWorker({ kind: "recipe", href, exportName, options }, signal);
72
+ }
73
+
74
+ /** Run a { module } check's default export in a worker, with the probe. */
75
+ function runModuleWorker({ href, probe, signal = null }) {
76
+ return runReadbackWorker({ kind: "module", href, probe }, signal);
77
+ }
78
+
79
+ function runReadbackWorker(workerData, signal) {
80
+ return new Promise((resolvePromise, reject) => {
81
+ if (signal && signal.aborted) {
82
+ reject(signal.reason);
83
+ return;
84
+ }
85
+ const worker = new Worker(new URL("./recipe-worker.mjs", import.meta.url), { workerData });
86
+ let settled = false;
87
+ const onAbort = () => finish(() => reject(signal.reason));
88
+ function finish(settle) {
89
+ if (settled) return;
90
+ settled = true;
91
+ if (signal) signal.removeEventListener("abort", onAbort);
92
+ // Terminate unconditionally: the read may have left handles open.
93
+ worker.terminate().catch(() => {});
94
+ settle();
95
+ }
96
+ worker.once("message", (m) => finish(() => (m && m.ok ? resolvePromise(m.value) : reject(new Error(m && m.error ? m.error : "check failed")))));
97
+ worker.once("error", (err) => finish(() => reject(err)));
98
+ worker.once("exit", (code) => finish(() => reject(new Error("check worker exited with code " + code))));
99
+ if (signal) signal.addEventListener("abort", onAbort, { once: true });
100
+ });
101
+ }
102
+
103
+ function moduleHref(mod) {
104
+ if (mod instanceof URL) return mod.href;
105
+ if (typeof mod !== "string" || mod.length === 0) throw new TypeError("check.module must be a path or URL");
106
+ if (/^file:/i.test(mod)) return mod;
107
+ return pathToFileURL(isAbsolute(mod) ? mod : resolve(process.cwd(), mod)).href;
108
+ }
109
+
110
+ function makeRunner(check, isolation, probe) {
111
+ if (!ISOLATION_MODES.has(isolation)) throw new TypeError('isolation must be "auto", "worker" or "in-process"');
112
+ if (check && typeof check === "object" && !Array.isArray(check) && check.module !== undefined) {
113
+ if (isolation === "in-process") throw new TypeError("a { module } check always runs in a worker");
114
+ const href = moduleHref(check.module);
115
+ const p = check.probe === undefined ? probe : check.probe;
116
+ try {
117
+ structuredClone(p);
118
+ } catch {
119
+ throw new TypeError("check.probe must be plain data");
120
+ }
121
+ return {
122
+ isolation: "worker",
123
+ meta: { resource: check.resource, source: check.source, pending: check.pending, secrets: [] },
124
+ run: (signal) => runModuleWorker({ href, probe: p, signal }),
125
+ };
126
+ }
127
+ if (typeof check !== "function") throw new TypeError("check must be an async function, a read-back recipe, or { module }");
128
+ const recipe = check[RECIPE_META] || null;
129
+ const spec = recipe && recipe.worker;
130
+ const meta = { resource: check.resource, source: check.source, pending: check.pending, secrets: recipe ? recipe.secrets : [] };
131
+ if (isolation === "worker" && !spec) {
132
+ throw new TypeError("this check cannot move to a worker thread (it closes over a client or an injected function); " +
133
+ 'use isolation: "in-process", or pass { module } instead');
134
+ }
135
+ if (spec && isolation !== "in-process") {
136
+ return { isolation: "worker", meta, run: (signal) => runRecipeWorker({ ...spec, signal }) };
137
+ }
138
+ return { isolation: "in-process", meta, run: (signal) => Promise.resolve().then(() => check({ signal, ...structuredClone(probe) })) };
139
+ }
140
+
141
+ // ---------------------------------------------------------------------------
142
+ // Comparison
143
+
144
+ const hasOwn = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
145
+
146
+ function isPlainObject(v) {
147
+ if (v === null || typeof v !== "object" || Array.isArray(v)) return false;
148
+ const proto = Object.getPrototypeOf(v);
149
+ return proto === Object.prototype || proto === null;
150
+ }
151
+
152
+ /** Structural equality for JSON-like data. */
153
+ export function sameValue(a, b) {
154
+ if (a === b) return true;
155
+ if (typeof a === "number" && typeof b === "number") return Number.isNaN(a) && Number.isNaN(b);
156
+ if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
157
+ if (Array.isArray(a) !== Array.isArray(b)) return false;
158
+ if (Array.isArray(a)) return a.length === b.length && a.every((x, i) => sameValue(x, b[i]));
159
+ if (!isPlainObject(a) || !isPlainObject(b)) return false;
160
+ const ka = Object.keys(a).filter((k) => a[k] !== undefined);
161
+ const kb = Object.keys(b).filter((k) => b[k] !== undefined);
162
+ return ka.length === kb.length && ka.every((k) => hasOwn(b, k) && sameValue(a[k], b[k]));
163
+ }
164
+
165
+ function normalizeTargets(expected, claimed) {
166
+ const claimedObj = claimed === undefined || claimed === null ? null : claimed;
167
+ if (claimedObj !== null && !isPlainObject(claimedObj)) throw new TypeError("claimed must be a plain object of the fields the agent reported");
168
+ const has = (f) => claimedObj !== null && hasOwn(claimedObj, f) && claimedObj[f] !== undefined;
169
+ if (Array.isArray(expected)) {
170
+ if (expected.length === 0) throw new TypeError("expected must list at least one field");
171
+ if (new Set(expected).size !== expected.length) throw new TypeError("expected lists a field twice");
172
+ return expected.map((field) => {
173
+ if (typeof field !== "string" || field.length === 0) throw new TypeError("expected field names must be non-empty strings");
174
+ if (!has(field)) throw new TypeError("claimed has no value for expected field " + JSON.stringify(field));
175
+ return { field, want: claimedObj[field], claimed: claimedObj[field], hasClaimed: true };
176
+ });
177
+ }
178
+ if (isPlainObject(expected)) {
179
+ const fields = Object.keys(expected);
180
+ if (fields.length === 0) throw new TypeError("expected must name at least one field");
181
+ return fields.map((field) => {
182
+ if (expected[field] === undefined) throw new TypeError("expected value for " + JSON.stringify(field) + " is undefined");
183
+ return { field, want: expected[field], claimed: has(field) ? claimedObj[field] : undefined, hasClaimed: has(field) };
184
+ });
185
+ }
186
+ throw new TypeError("expected must be an array of field names (compared with claimed) or an object of { field: value }");
187
+ }
188
+
189
+ function normalizePending(pending) {
190
+ if (pending === undefined || pending === null) return {};
191
+ if (!isPlainObject(pending)) throw new TypeError("pending must be an object of { field: [values that mean not-settled-yet] }");
192
+ for (const [k, v] of Object.entries(pending)) {
193
+ if (!Array.isArray(v)) throw new TypeError("pending." + k + " must be an array of values");
194
+ }
195
+ return pending;
196
+ }
197
+
198
+ function typeName(v) {
199
+ if (v === null) return "null";
200
+ if (Array.isArray(v)) return "an array";
201
+ return "a " + typeof v;
202
+ }
203
+
204
+ function classify(read, targets, pending, src, timeoutMs) {
205
+ if (!read.ok) {
206
+ return read.timedOut
207
+ ? { outcome: STATUS.UNKNOWN, reason: "check timed out after " + timeoutMs + " ms" }
208
+ : { outcome: STATUS.UNKNOWN, reason: "check failed: " + read.error };
209
+ }
210
+ const obs = read.value;
211
+ if (obs === null || typeof obs !== "object" || Array.isArray(obs)) {
212
+ return { outcome: STATUS.UNKNOWN, reason: src + " read returned " + typeName(obs) + ", not an object of fields" };
213
+ }
214
+ const missing = targets.filter((t) => !hasOwn(obs, t.field) || obs[t.field] === undefined).map((t) => t.field);
215
+ if (missing.length > 0) {
216
+ const shown = missing.slice(0, 3).map((f) => JSON.stringify(f)).join(", ") + (missing.length > 3 ? " and " + (missing.length - 3) + " more" : "");
217
+ return { outcome: STATUS.UNKNOWN, observed: obs, missing, reason: src + " read has no " + shown + " field" + (missing.length > 1 ? "s" : "") + " (missing is not null)" };
218
+ }
219
+ const mismatched = targets.filter((t) => !sameValue(obs[t.field], t.want));
220
+ if (mismatched.length === 0) return { outcome: STATUS.CONFIRMED, observed: obs };
221
+ const isPending = (t) => Array.isArray(pending[t.field]) && pending[t.field].some((v) => sameValue(v, obs[t.field]));
222
+ const terminal = mismatched.filter((t) => !isPending(t));
223
+ if (terminal.length === 0) return { outcome: STATUS.PENDING, observed: obs, mismatched };
224
+ return { outcome: STATUS.CONTRADICTED, observed: obs, mismatched: terminal };
225
+ }
226
+
227
+ // ---------------------------------------------------------------------------
228
+ // Messages
229
+
230
+ /** Longest error text kept in a message, cut AFTER redaction. */
231
+ const ERROR_DISPLAY_MAX = 300;
232
+ /** Longest value shown in firstLine, cut AFTER redaction. */
233
+ const VALUE_DISPLAY_MAX = 80;
234
+
235
+ function fmtValue(v, secrets) {
236
+ let s;
237
+ try {
238
+ s = typeof v === "bigint" ? String(v) : JSON.stringify(v);
239
+ } catch {
240
+ s = String(v);
241
+ }
242
+ if (s === undefined) s = String(v);
243
+ s = redact(s, secrets);
244
+ return s.length > VALUE_DISPLAY_MAX ? s.slice(0, VALUE_DISPLAY_MAX - 1) + "…" : s;
245
+ }
246
+
247
+ function deepRedact(value, secrets) {
248
+ if (typeof value === "string") return redact(value, secrets);
249
+ if (Array.isArray(value)) return value.map((v) => deepRedact(v, secrets));
250
+ if (value !== null && typeof value === "object") {
251
+ const out = {};
252
+ for (const [k, v] of Object.entries(value)) out[k] = deepRedact(v, secrets);
253
+ return out;
254
+ }
255
+ return value;
256
+ }
257
+
258
+ function firstLineFor(last, { label, src, actor, targets, attempts, secrets }) {
259
+ const multi = targets.length > 1;
260
+ const fmt = (v) => fmtValue(v, secrets);
261
+ const named = (t) => (multi ? t.field + " " : "");
262
+ switch (last.outcome) {
263
+ case STATUS.CONFIRMED: {
264
+ const what = multi ? "all " + targets.length + " expected fields" : fmt(last.observed[targets[0].field]);
265
+ const vs = targets.every((t) => t.hasClaimed) ? "matching the " + actor + "'s report" : "matching the expected state";
266
+ return "CONFIRMED " + label + ": " + src + " shows " + what + ", " + vs + (attempts > 1 ? " (read " + attempts + " times)" : "");
267
+ }
268
+ case STATUS.CONTRADICTED: {
269
+ const t = last.mismatched[0];
270
+ const said = t.hasClaimed ? actor + " reported " + named(t) + fmt(t.claimed) : "expected " + named(t) + fmt(t.want);
271
+ const more = last.mismatched.length > 1 ? " (+" + (last.mismatched.length - 1) + " more field" + (last.mismatched.length > 2 ? "s" : "") + " differ)" : "";
272
+ return "CAUGHT " + label + ": " + said + ", " + src + " shows " + fmt(last.observed[t.field]) + more;
273
+ }
274
+ case STATUS.PENDING: {
275
+ const t = last.mismatched[0];
276
+ return "PENDING " + label + ": " + src + " still shows " + named(t) + fmt(last.observed[t.field]) +
277
+ " after " + attempts + " read" + (attempts > 1 ? "s" : "") + "; not confirmed yet";
278
+ }
279
+ default:
280
+ return "UNKNOWN " + label + ": " + last.reason + "; not confirmed";
281
+ }
282
+ }
283
+
284
+ // ---------------------------------------------------------------------------
285
+
286
+ function intIn(name, v, lo, hi) {
287
+ if (!Number.isSafeInteger(v) || v < lo || v > hi) throw new TypeError(name + " must be an integer from " + lo + " to " + hi);
288
+ return v;
289
+ }
290
+
291
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
292
+
293
+ async function readOnce(runner, timeoutMs) {
294
+ const controller = new AbortController();
295
+ let timer;
296
+ try {
297
+ const value = await Promise.race([
298
+ runner.run(controller.signal),
299
+ new Promise((_, reject) => {
300
+ timer = setTimeout(() => {
301
+ const timeout = Object.assign(new Error("timeout"), { readbackTimeout: true });
302
+ controller.abort(timeout);
303
+ reject(timeout);
304
+ }, timeoutMs);
305
+ }),
306
+ ]);
307
+ return { ok: true, value };
308
+ } catch (err) {
309
+ if (err && err.readbackTimeout) return { ok: false, timedOut: true };
310
+ // Whole message: the caller redacts it before cutting it to display length.
311
+ return { ok: false, timedOut: false, error: String(err && err.message ? err.message : err) };
312
+ } finally {
313
+ clearTimeout(timer);
314
+ }
315
+ }
316
+
317
+ /**
318
+ * Read the outcome back and say what it shows, before anyone reports success.
319
+ *
320
+ * @param {object} input
321
+ * @param {object} [input.claimed] what the agent/executor reported, e.g. { status: "processed" }
322
+ * @param {Function|{module: string|URL, probe?: object}} input.check read-only check or recipe
323
+ * @param {string[]|object} input.expected field names to compare with `claimed`, or { field: value }
324
+ * @param {number} [input.retries=2] extra reads while PENDING or UNKNOWN (0–20)
325
+ * @param {number} [input.intervalMs=1000] wait between reads (0–600000)
326
+ * @param {number} [input.timeoutMs=10000] limit per read (1–600000)
327
+ * @param {object} [input.pending] { field: [values meaning not-final] }; default: the recipe's
328
+ * @param {boolean} [input.retryOnMismatch=false] also re-read on a terminal mismatch
329
+ * @param {string} [input.resource] label, e.g. "refund rf_2291" (default: the recipe's)
330
+ * @param {string} [input.source] who was read, e.g. "Stripe" (default: the recipe's)
331
+ * @param {string} [input.actor="agent"] who made the claim
332
+ * @param {string[]} [input.secrets] extra strings to redact from messages
333
+ * @param {"auto"|"worker"|"in-process"} [input.isolation="auto"]
334
+ * @returns {Promise<{status: string, firstLine: string, detail: object}>}
335
+ * @throws {TypeError} for caller mistakes, before any read
336
+ */
337
+ export async function confirmThenReport(input = {}) {
338
+ const {
339
+ claimed, check, expected, retries = 2, intervalMs = 1000, timeoutMs = 10000, pending, retryOnMismatch = false,
340
+ resource, source, actor = "agent", secrets = [], isolation = "auto",
341
+ } = input;
342
+ intIn("retries", retries, 0, 20);
343
+ intIn("intervalMs", intervalMs, 0, 600000);
344
+ intIn("timeoutMs", timeoutMs, 1, 600000);
345
+ if (!Array.isArray(secrets)) throw new TypeError("secrets must be an array of strings");
346
+ if (typeof actor !== "string" || actor.length === 0) throw new TypeError("actor must be a non-empty string");
347
+ const targets = normalizeTargets(expected, claimed);
348
+ const label0 = resource !== undefined ? resource : check && check.resource;
349
+ const probe = { resource: typeof label0 === "string" ? label0 : null, fields: targets.map((t) => t.field).sort() };
350
+ const runner = makeRunner(check, isolation, probe);
351
+ const label = typeof resource === "string" && resource ? resource : typeof runner.meta.resource === "string" && runner.meta.resource ? runner.meta.resource : "read-back";
352
+ const src = typeof source === "string" && source ? source : typeof runner.meta.source === "string" && runner.meta.source ? runner.meta.source : "the system of record";
353
+ const pend = normalizePending(pending !== undefined ? pending : runner.meta.pending);
354
+ const allSecrets = [...secrets, ...(runner.meta.secrets || [])];
355
+
356
+ const attempts = [];
357
+ let last;
358
+ for (let i = 0; i <= retries; i++) {
359
+ if (i > 0 && intervalMs > 0) await sleep(intervalMs);
360
+ const started = Date.now();
361
+ const read = await readOnce(runner, timeoutMs);
362
+ if (!read.ok && read.error) read.error = redact(read.error, allSecrets).slice(0, ERROR_DISPLAY_MAX);
363
+ last = classify(read, targets, pend, src, timeoutMs);
364
+ const rec = { attempt: i + 1, outcome: last.outcome, elapsed_ms: Date.now() - started };
365
+ if (last.reason) rec.reason = last.reason;
366
+ if (last.mismatched) rec.differing_fields = last.mismatched.map((t) => t.field);
367
+ if (last.missing) rec.missing_fields = last.missing;
368
+ attempts.push(rec);
369
+ if (last.outcome === STATUS.CONFIRMED) break;
370
+ if (last.outcome === STATUS.CONTRADICTED && !retryOnMismatch) break;
371
+ }
372
+
373
+ const fields = {};
374
+ for (const t of targets) {
375
+ const f = { expected: t.want };
376
+ if (t.hasClaimed) f.claimed = t.claimed;
377
+ if (last.observed && hasOwn(last.observed, t.field) && last.observed[t.field] !== undefined) {
378
+ f.observed = last.observed[t.field];
379
+ f.matches = sameValue(f.observed, t.want);
380
+ } else {
381
+ f.observed_missing = true;
382
+ f.matches = null;
383
+ }
384
+ fields[t.field] = f;
385
+ }
386
+
387
+ const status = last.outcome;
388
+ const firstLine = redact(firstLineFor(last, { label, src, actor, targets, attempts: attempts.length, secrets: allSecrets }), allSecrets);
389
+ const detail = deepRedact({
390
+ status,
391
+ provenance: PROVENANCE,
392
+ trust_bearing: false,
393
+ note: PROVENANCE_NOTE,
394
+ resource: label,
395
+ source: src,
396
+ isolation: runner.isolation,
397
+ compared_fields: targets.map((t) => t.field),
398
+ fields,
399
+ attempts,
400
+ reason: last.reason || null,
401
+ checked_at: new Date().toISOString(),
402
+ }, allSecrets);
403
+ return { status, firstLine, detail };
404
+ }
@@ -0,0 +1,12 @@
1
+ // Read-back (R1a): confirm an agent's claimed outcome against the system of
2
+ // record before reporting success. Local, no account, no network except the
3
+ // read you configure. See README.md.
4
+
5
+ export { confirmThenReport, STATUS, CATCH_WORDS, PROVENANCE, PROVENANCE_NOTE, sameValue } from "./confirm.mjs";
6
+ export { toSandboxCheck, SANDBOX_BRIDGE_LABEL } from "./bridge.mjs";
7
+ export { redact, REDACTED } from "./redact.mjs";
8
+ export { httpJson, selectPath } from "./recipes/http-json.mjs";
9
+ export { stripeRefund, STRIPE_REFUND_FIELDS, STRIPE_REFUND_PENDING } from "./recipes/stripe-refund.mjs";
10
+ export { emailDelivery, EMAIL_ADAPTERS, EMAIL_DELIVERY_PENDING } from "./recipes/email-delivery.mjs";
11
+ export { githubIssue } from "./recipes/github-issue.mjs";
12
+ export { sqlRow, assertReadOnlySql } from "./recipes/sql-row.mjs";
@@ -0,0 +1,33 @@
1
+ // Worker side of confirm.mjs's read-back workers. Two kinds:
2
+ // - "recipe": rebuilds a read-back recipe from plain-data options and calls
3
+ // its check once (a recipe is a factory, not a module's default export);
4
+ // - "module": imports a { module } check and calls its default export (or
5
+ // `check`) with the probe, as the sandbox's check-worker.mjs does.
6
+ // The parent terminates this worker as soon as it posts (or on timeout), so
7
+ // sockets or timers the read leaves open cannot outlive the answer.
8
+ //
9
+ // Errors are posted WHOLE. The parent redacts them with every secret it knows
10
+ // (the recipe's and the caller's) and only then cuts them to display length.
11
+ // Cutting here first could split a secret and leave a prefix that exact-match
12
+ // redaction can no longer find. (This is why { module } checks do not use the
13
+ // sandbox's check-worker.mjs, which cuts errors at 200 characters.)
14
+
15
+ import { parentPort, workerData } from "node:worker_threads";
16
+
17
+ const { kind = "recipe", href, exportName, options, probe } = workerData;
18
+
19
+ try {
20
+ const mod = await import(href);
21
+ let value;
22
+ if (kind === "module") {
23
+ const check = typeof mod.default === "function" ? mod.default : typeof mod.check === "function" ? mod.check : null;
24
+ if (check === null) throw new Error("module exports no check function");
25
+ value = await check(probe);
26
+ } else {
27
+ if (typeof mod[exportName] !== "function") throw new Error("recipe module has no export " + exportName);
28
+ value = await mod[exportName](options)({});
29
+ }
30
+ parentPort.postMessage({ ok: true, value: value === undefined ? null : value });
31
+ } catch (err) {
32
+ parentPort.postMessage({ ok: false, error: String(err && err.message ? err.message : err) });
33
+ }
@@ -0,0 +1,126 @@
1
+ // Shared plumbing for read-back recipes.
2
+ //
3
+ // A recipe is a factory: it takes a read-only credential (or a client the
4
+ // caller already built) and returns a `check` function that READS one thing
5
+ // and returns a flat object of observed fields.
6
+ //
7
+ // Rules every recipe follows:
8
+ // - it never writes: HTTP recipes only issue GET with no body and refuse
9
+ // redirects; client recipes only call a read method;
10
+ // - it never logs, and never puts a credential in a thrown message (errors
11
+ // are built from status codes; declared secrets are redacted as a backstop);
12
+ // - a field the system did not return is left OUT of the result, never set
13
+ // to null, so confirmThenReport reports it as missing (UNKNOWN).
14
+
15
+ import { redact, displayUrl } from "../redact.mjs";
16
+
17
+ /** Internal: where confirmThenReport finds a recipe's worker spec and secrets. */
18
+ export const RECIPE_META = Symbol.for("intentrax.readback.recipe");
19
+
20
+ const DEFAULT_MAX_BYTES = 2 * 1024 * 1024;
21
+
22
+ function isCloneable(value) {
23
+ try {
24
+ structuredClone(value);
25
+ return true;
26
+ } catch {
27
+ return false;
28
+ }
29
+ }
30
+
31
+ /**
32
+ * Wrap a recipe's read in a `check` function and attach its metadata.
33
+ *
34
+ * When `options` is plain data (a credential string, ids, a base URL, no
35
+ * injected fetch or client), confirmThenReport can rebuild the same check
36
+ * inside a worker thread from `{ href, exportName, options }`. A check built
37
+ * around a caller's client or fetch function runs in-process instead.
38
+ */
39
+ export function defineRecipe({ href, exportName, options, secrets, resource, source, pending, read }) {
40
+ const declared = Object.freeze((secrets || []).filter((s) => typeof s === "string" && s.length > 0));
41
+ const check = async function readbackCheck(ctx = {}) {
42
+ try {
43
+ return await read(ctx && typeof ctx === "object" ? ctx : {});
44
+ } catch (err) {
45
+ // Re-throw with a scrubbed message only; drop the original object,
46
+ // whose cause chain may carry request details.
47
+ throw new Error(redact(err && err.message ? err.message : String(err), declared));
48
+ }
49
+ };
50
+ Object.defineProperty(check, "resource", { value: resource, enumerable: true });
51
+ Object.defineProperty(check, "source", { value: source, enumerable: true });
52
+ Object.defineProperty(check, "pending", { value: pending ? Object.freeze(pending) : null, enumerable: true });
53
+ Object.defineProperty(check, RECIPE_META, {
54
+ value: Object.freeze({
55
+ secrets: declared,
56
+ worker: isCloneable(options) ? Object.freeze({ href, exportName, options }) : null,
57
+ }),
58
+ enumerable: false,
59
+ });
60
+ return check;
61
+ }
62
+
63
+ /** Validate a caller's `notFoundAs` observation (plain JSON object or undefined). */
64
+ export function checkNotFoundAs(value) {
65
+ if (value === undefined) return undefined;
66
+ if (value === null || typeof value !== "object" || Array.isArray(value) || !isCloneable(value)) {
67
+ throw new TypeError("notFoundAs must be a plain object, e.g. { exists: false }");
68
+ }
69
+ return value;
70
+ }
71
+
72
+ /** Copy only the listed fields the object actually has (missing stays missing). */
73
+ export function pick(obj, fields) {
74
+ const out = {};
75
+ if (!obj || typeof obj !== "object") return out;
76
+ for (const f of fields) {
77
+ if (Object.prototype.hasOwnProperty.call(obj, f) && obj[f] !== undefined) out[f] = obj[f];
78
+ }
79
+ return out;
80
+ }
81
+
82
+ export function requireString(name, value, { pattern, max = 500 } = {}) {
83
+ if (typeof value !== "string" || value.length === 0 || value.length > max) {
84
+ throw new TypeError(name + " must be a non-empty string");
85
+ }
86
+ if (pattern && !pattern.test(value)) throw new TypeError(name + " has unexpected characters");
87
+ return value;
88
+ }
89
+
90
+ export function resolveFetch(fetchImpl) {
91
+ if (fetchImpl !== undefined && typeof fetchImpl !== "function") throw new TypeError("fetch must be a function");
92
+ const f = fetchImpl || globalThis.fetch;
93
+ if (typeof f !== "function") throw new TypeError("no fetch implementation available (Node >= 20 has one built in)");
94
+ return f;
95
+ }
96
+
97
+ /**
98
+ * GET a JSON document. Read-only by construction: method GET, no body,
99
+ * redirects refused (so credentials are never replayed to another URL).
100
+ *
101
+ * Returns `{ notFound: true, body: null }` on HTTP 404 when `allowNotFound`,
102
+ * else `{ notFound: false, body }`. Throws an Error whose message names the
103
+ * source and status only.
104
+ */
105
+ export async function getJson({ fetchImpl, url, headers, signal, source, allowNotFound = false, maxBytes = DEFAULT_MAX_BYTES }) {
106
+ const where = source + " (" + displayUrl(url) + ")";
107
+ let res;
108
+ try {
109
+ res = await fetchImpl(url, { method: "GET", headers, signal, redirect: "error" });
110
+ } catch (err) {
111
+ if (signal && signal.aborted) throw new Error("read of " + where + " was aborted");
112
+ const code = err && err.cause && err.cause.code ? " [" + err.cause.code + "]" : "";
113
+ throw new Error("could not read " + where + ": " + (err && err.message ? err.message : String(err)) + code);
114
+ }
115
+ if (res.status === 404 && allowNotFound) return { notFound: true, body: null };
116
+ if (!res.ok) {
117
+ throw new Error(where + " answered HTTP " + res.status + (res.status === 401 || res.status === 403 ? " (check the read-only credential and its scope)" : ""));
118
+ }
119
+ const text = await res.text();
120
+ if (text.length > maxBytes) throw new Error(where + " returned more than " + maxBytes + " bytes");
121
+ try {
122
+ return { notFound: false, body: JSON.parse(text) };
123
+ } catch {
124
+ throw new Error(where + " did not return JSON");
125
+ }
126
+ }