@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.
- package/README.md +17 -2
- package/cli/intentrax.mjs +45 -1
- package/mcp/README.md +138 -0
- package/mcp/canonical.d.ts +12 -0
- package/mcp/canonical.mjs +70 -0
- package/mcp/cli.d.ts +16 -0
- package/mcp/cli.mjs +214 -0
- package/mcp/client.d.ts +131 -0
- package/mcp/client.mjs +955 -0
- package/mcp/commands.d.ts +113 -0
- package/mcp/commands.mjs +575 -0
- package/mcp/index.d.ts +12 -0
- package/mcp/index.mjs +12 -0
- package/mcp/proxy.d.ts +47 -0
- package/mcp/proxy.mjs +434 -0
- package/mcp/receipt-meta.d.ts +59 -0
- package/mcp/receipt-meta.mjs +178 -0
- package/mcp/tool-manifest.d.ts +74 -0
- package/mcp/tool-manifest.mjs +154 -0
- package/package.json +16 -1
- package/readback/README.md +352 -0
- package/readback/bridge.mjs +71 -0
- package/readback/cli.mjs +150 -0
- package/readback/confirm.mjs +404 -0
- package/readback/index.mjs +12 -0
- package/readback/recipe-worker.mjs +33 -0
- package/readback/recipes/_shared.mjs +126 -0
- package/readback/recipes/email-delivery.mjs +136 -0
- package/readback/recipes/github-issue.mjs +88 -0
- package/readback/recipes/http-json.mjs +109 -0
- package/readback/recipes/sql-row.mjs +96 -0
- package/readback/recipes/stripe-refund.mjs +73 -0
- package/readback/redact.mjs +68 -0
- package/scan/README.md +211 -0
- package/scan/classify.mjs +276 -0
- package/scan/cli.mjs +102 -0
- package/scan/configs.mjs +261 -0
- package/scan/credentials.mjs +121 -0
- package/scan/extract.mjs +323 -0
- package/scan/gates.mjs +94 -0
- package/scan/report.mjs +58 -0
- package/scan/scan.mjs +571 -0
- 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
|
+
}
|