@intentrax/sdk 1.6.0 → 1.7.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.
@@ -0,0 +1,242 @@
1
+ // Local effect verifier: the sandbox's independent, read-only outcome check.
2
+ //
3
+ // Adapted from examples/effect-assurance-demo/src/effect-verifier.mjs (PRs
4
+ // #449, #477). As in the demo, the check reads the system with its OWN key and
5
+ // principal (never the executor's), compares the observed state with the
6
+ // state the signed decision authorised, and signs an
7
+ // `intentrax.effect_evidence/0.1` object. `assessEffect` is a pure function
8
+ // shared with the offline verifier, which recomputes every conclusion from the
9
+ // bundled observation and refuses evidence whose signed fields disagree.
10
+ //
11
+ // What differs from the demo, and is labelled in every bundle:
12
+ // - There is no source-signed receipt or authenticated channel. The read is
13
+ // either the sandbox's synthetic store (source_authentication
14
+ // LOCAL_EFFECT_VERIFIER_READ, provenance THIRD_PARTY_ATTESTED: attested by
15
+ // the local effect-verifier key, distinct from the executor key) or a
16
+ // check module the developer wrote (USER_SUPPLIED_CHECK, provenance
17
+ // SELF_REPORTED: the party whose action is checked also wrote the check).
18
+ // Neither is an Intentrax-pulled authoritative read.
19
+ // - The sandbox never calls a developer's write path. A user check is
20
+ // read-only by contract only; the sandbox cannot enforce that.
21
+
22
+ import { digest, canonicalJson, isCanonicalizable } from "./canonical.mjs";
23
+ import { signEnvelope, envelopeDigest, PAYLOAD_TYPES } from "./envelope.mjs";
24
+ import { effectFor, claimedOutcome, expectedStateDigest, OUTCOMES } from "./effects.mjs";
25
+ import { isoMs } from "./time.mjs";
26
+
27
+ export const RETRIEVAL_METHOD = "LOCAL_SANDBOX_PULL";
28
+
29
+ export const READ_KINDS = Object.freeze({
30
+ SANDBOX_SYNTHETIC_STORE: "SANDBOX_SYNTHETIC_STORE",
31
+ USER_SUPPLIED_CHECK: "USER_SUPPLIED_CHECK",
32
+ });
33
+
34
+ const SOURCE_AUTHENTICATION = Object.freeze({
35
+ SANDBOX_SYNTHETIC_STORE: "LOCAL_EFFECT_VERIFIER_READ",
36
+ USER_SUPPLIED_CHECK: "USER_SUPPLIED_CHECK",
37
+ });
38
+
39
+ const READ_LIMITATIONS = Object.freeze({
40
+ SANDBOX_SYNTHETIC_STORE: ["SOURCE_RESPONSE_NOT_THIRD_PARTY_SIGNED", "SYNTHETIC_SOURCE"],
41
+ USER_SUPPLIED_CHECK: ["USER_SUPPLIED_CHECK_NOT_INDEPENDENT", "USER_CHECK_READ_ONLY_BY_CONTRACT_ONLY"],
42
+ });
43
+
44
+ export function sourceAuthenticationFor(readKind) {
45
+ return Object.prototype.hasOwnProperty.call(SOURCE_AUTHENTICATION, readKind) ? SOURCE_AUTHENTICATION[readKind] : "NONE";
46
+ }
47
+
48
+
49
+ export function assessEffect({
50
+ request,
51
+ report,
52
+ retrievalMethod,
53
+ retrievalPrincipal,
54
+ expectedRetrievalPrincipal = null,
55
+ observation,
56
+ observedAt,
57
+ }) {
58
+ const eff = effectFor(request.operation);
59
+ const outcome = claimedOutcome(report.status);
60
+ const reasons = [];
61
+ const limitations = [];
62
+ let expected = null;
63
+ try {
64
+ expected = outcome && outcome !== OUTCOMES.PENDING ? expectedStateDigest(request, outcome) : null;
65
+ } catch {
66
+ expected = null;
67
+ }
68
+ const out = {
69
+ claimed_outcome: outcome,
70
+ expected_state_digest: expected,
71
+ observed_state_digest: null,
72
+ evidence_digest: null,
73
+ source_authentication: "NONE",
74
+ finality: "UNKNOWN",
75
+ max_age_seconds: eff.max_age_seconds,
76
+ };
77
+
78
+ if (retrievalMethod !== RETRIEVAL_METHOD) reasons.push("READ_NOT_PERFORMED_BY_SANDBOX_EFFECT_VERIFIER");
79
+ if (retrievalPrincipal === report.executor_principal) reasons.push("RETRIEVAL_NOT_INDEPENDENT_OF_EXECUTOR");
80
+ if (expectedRetrievalPrincipal !== null && retrievalPrincipal !== expectedRetrievalPrincipal) {
81
+ reasons.push("RETRIEVAL_PRINCIPAL_IS_NOT_THE_EFFECT_VERIFIER");
82
+ }
83
+
84
+ if (!observation) {
85
+ reasons.push("OBSERVATION_MISSING");
86
+ } else {
87
+ out.evidence_digest = isCanonicalizable(observation.body) ? digest(observation.body) : null;
88
+ if (canonicalJson(observation.request) !== canonicalJson(eff.probe(request))) {
89
+ reasons.push("PROBE_DOES_NOT_TARGET_CLAIMED_EFFECT");
90
+ }
91
+ out.source_authentication = sourceAuthenticationFor(observation.read_kind);
92
+ if (out.source_authentication === "NONE") reasons.push("READ_KIND_UNKNOWN");
93
+ else limitations.push(...READ_LIMITATIONS[observation.read_kind]);
94
+ if (observation.status !== "OK") reasons.push("SOURCE_READ_FAILED:" + observation.status);
95
+ const bound = observation.status === "OK" && eff.bound(request, observation.body);
96
+ if (observation.status === "OK" && !bound) reasons.push("OBSERVATION_NOT_BOUND_TO_DECISION");
97
+ if (bound) {
98
+ const problems = eff.observationProblems(request, observation.body);
99
+ if (problems.length) {
100
+ reasons.push(...problems);
101
+ } else {
102
+ out.observed_state_digest = digest(eff.observed(request, observation.body));
103
+ out.finality = eff.finality(observation.body);
104
+ }
105
+ }
106
+ }
107
+
108
+ // Strict timestamps (explicit offset; #491 parity): a timezone-less or
109
+ // unparseable time fails closed.
110
+ const reportedMs = isoMs(report.reported_at);
111
+ const observedMs = isoMs(observedAt);
112
+ const age = reportedMs === null || observedMs === null ? null : (observedMs - reportedMs) / 1000;
113
+ if (age === null) reasons.push("OBSERVATION_TIME_INVALID");
114
+ else if (age < 0) reasons.push("OBSERVATION_PREDATES_EXECUTION_REPORT");
115
+ else if (age > eff.max_age_seconds) reasons.push("OBSERVATION_STALE");
116
+
117
+ out.observed_result = reasons.length ? "INSUFFICIENT_EVIDENCE" : "OBSERVED";
118
+ if (reasons.length) {
119
+ out.result = "INSUFFICIENT_EVIDENCE";
120
+ } else if (outcome === null) {
121
+ reasons.push("REPORT_STATUS_UNRECOGNISED");
122
+ out.result = "INSUFFICIENT_EVIDENCE";
123
+ } else if (outcome === OUTCOMES.PENDING || out.finality !== "FINAL") {
124
+ out.result = "PENDING";
125
+ } else if (expected === null) {
126
+ reasons.push("EXPECTATION_NOT_DERIVABLE_FROM_DECISION");
127
+ out.result = "INSUFFICIENT_EVIDENCE";
128
+ } else {
129
+ out.result = expected === out.observed_state_digest ? "CONFIRMED" : "CONTRADICTED";
130
+ }
131
+ if (out.result === "CONTRADICTED") reasons.push("OBSERVED_STATE_DIFFERS_FROM_AUTHORISED_EFFECT");
132
+ if (out.result === "PENDING") reasons.push(outcome === OUTCOMES.PENDING ? "EXECUTION_NOT_FINAL" : "SOURCE_STATE_NOT_FINAL");
133
+ if (out.result === "CONFIRMED") limitations.push("EFFECT_NOT_ATTRIBUTED_TO_THIS_EXECUTION");
134
+ out.reasons = reasons;
135
+ out.limitations = limitations;
136
+ return out;
137
+ }
138
+
139
+ // Run a read with a timeout. Never throws: failures become an observation
140
+ // status, so a broken check yields INSUFFICIENT_EVIDENCE, not CONFIRMED.
141
+ // On timeout the read's AbortSignal fires; a user check (run in a worker
142
+ // thread, see check-runner.mjs) is then terminated, so its outstanding
143
+ // sockets or timers cannot keep the CLI alive.
144
+ async function performRead(read, probe, timeoutMs) {
145
+ const controller = new AbortController();
146
+ let timer;
147
+ try {
148
+ const value = await Promise.race([
149
+ // A copy, so a check that mutates its argument cannot alter the recorded probe.
150
+ Promise.resolve().then(() => read(structuredClone(probe), { signal: controller.signal })),
151
+ new Promise((_, reject) => {
152
+ timer = setTimeout(() => {
153
+ const timeout = Object.assign(new Error("timeout"), { sandboxTimeout: true });
154
+ controller.abort(timeout);
155
+ reject(timeout);
156
+ }, timeoutMs);
157
+ }),
158
+ ]);
159
+ if (!isCanonicalizable(value)) {
160
+ return { status: "CHECK_RESULT_NOT_CANONICAL_JSON", state: null, error: "result must be plain JSON data with integer numbers" };
161
+ }
162
+ return { status: "OK", state: value, error: null };
163
+ } catch (err) {
164
+ if (err && err.sandboxTimeout) return { status: "CHECK_TIMED_OUT", state: null, error: "no result within " + timeoutMs + " ms" };
165
+ return { status: "CHECK_THREW", state: null, error: String(err && err.message ? err.message : err).slice(0, 200) };
166
+ } finally {
167
+ clearTimeout(timer);
168
+ }
169
+ }
170
+
171
+ export class LocalEffectVerifier {
172
+ #clock;
173
+ #signer;
174
+ #seq = 0;
175
+
176
+ constructor({ clock, signer }) {
177
+ this.#clock = clock;
178
+ this.#signer = signer;
179
+ this.principal = signer.principal;
180
+ }
181
+
182
+ // reader: { kind: READ_KINDS.*, read: async (probe) => observedState,
183
+ // checkModule: { file_name, sha256 } | null, timeoutMs }
184
+ async observe({ decisionEnv, reportEnv, reader }) {
185
+ const d = decisionEnv.payload;
186
+ const r = reportEnv.payload;
187
+ const req = d.request;
188
+ const eff = effectFor(req.operation);
189
+ this.#seq += 1;
190
+ const probe = eff.probe(req);
191
+ const result = await performRead(reader.read, probe, reader.timeoutMs ?? 30000);
192
+ const observedAt = this.#clock.now();
193
+ const observation = {
194
+ observation_id: "obs-" + d.decision_id.slice(4) + "-" + this.#seq,
195
+ read_kind: reader.kind,
196
+ retrieved_by: this.principal,
197
+ check_module: reader.checkModule ?? null,
198
+ request: probe,
199
+ status: result.status,
200
+ error: result.error,
201
+ body: result.status === "OK" ? { resource: req.resource, state: result.state } : null,
202
+ };
203
+ const a = assessEffect({
204
+ request: req,
205
+ report: r,
206
+ retrievalMethod: RETRIEVAL_METHOD,
207
+ retrievalPrincipal: this.principal,
208
+ observation,
209
+ observedAt,
210
+ });
211
+ const payload = {
212
+ schema_version: PAYLOAD_TYPES.EFFECT_EVIDENCE,
213
+ evidence_id: "evd-" + d.decision_id.slice(4) + "-" + this.#seq,
214
+ decision_id: d.decision_id,
215
+ decision_digest: envelopeDigest(decisionEnv),
216
+ execution_report_digest: envelopeDigest(reportEnv),
217
+ claimed_effect: { operation: req.operation, resource: req.resource, outcome: a.claimed_outcome },
218
+ retrieval_method: RETRIEVAL_METHOD,
219
+ retrieval_principal_ref: this.principal,
220
+ read_kind: reader.kind,
221
+ observed_at: observedAt,
222
+ attested_at: this.#clock.now(),
223
+ resource_id: req.resource,
224
+ expected_state_digest: a.expected_state_digest,
225
+ observed_state_digest: a.observed_state_digest,
226
+ result: a.result,
227
+ reasons: a.reasons,
228
+ evidence_digest: a.evidence_digest,
229
+ observation_id: observation.observation_id,
230
+ observation_digest: digest(observation),
231
+ source_authentication: a.source_authentication,
232
+ freshness: {
233
+ max_age_seconds: a.max_age_seconds,
234
+ finality: a.finality,
235
+ consistency_model: eff.consistency_model,
236
+ },
237
+ coverage_boundary: eff.coverage_boundary,
238
+ limitations: a.limitations,
239
+ };
240
+ return { evidence: signEnvelope(PAYLOAD_TYPES.EFFECT_EVIDENCE, payload, this.#signer), observation, assessment: a };
241
+ }
242
+ }
@@ -0,0 +1,80 @@
1
+ // Effect definition for the local assurance sandbox.
2
+ //
3
+ // Adapted from examples/effect-assurance-demo/src/effects.mjs (PRs #449,
4
+ // #477). The demo defines three synthetic cloud operations; the sandbox has
5
+ // one generic operation, `SetState`: "make these fields of this resource have
6
+ // these values". It covers both the built-in sample action and a developer's
7
+ // own action checked with `--check`.
8
+ //
9
+ // The EXPECTED state is derived only from the signed decision (the fields and
10
+ // values that were authorised), never from anything the executor reports. The
11
+ // OBSERVED state is extracted from the read, limited to the authorised fields
12
+ // (the coverage boundary).
13
+
14
+ import { digest } from "./canonical.mjs";
15
+
16
+ export const OPERATION = "SetState";
17
+
18
+ export const OUTCOMES = Object.freeze({ APPLIED: "APPLIED", NOT_APPLIED: "NOT_APPLIED", PENDING: "PENDING" });
19
+
20
+ // Execution-report status -> the outcome it claims.
21
+ export function claimedOutcome(reportStatus) {
22
+ switch (reportStatus) {
23
+ case "SUCCEEDED":
24
+ return OUTCOMES.APPLIED;
25
+ case "ACCEPTED":
26
+ return OUTCOMES.PENDING;
27
+ case "FAILED":
28
+ return OUTCOMES.NOT_APPLIED;
29
+ default:
30
+ return null;
31
+ }
32
+ }
33
+
34
+ function pick(obj, keys) {
35
+ const out = {};
36
+ const src = obj !== null && typeof obj === "object" && !Array.isArray(obj) ? obj : {};
37
+ for (const k of keys.slice().sort()) {
38
+ out[k] = Object.prototype.hasOwnProperty.call(src, k) ? src[k] : null;
39
+ }
40
+ return out;
41
+ }
42
+
43
+ export const SET_STATE = Object.freeze({
44
+ operation: OPERATION,
45
+ max_age_seconds: 300,
46
+ consistency_model: "read treated as final; eventual consistency is not modelled in the sandbox",
47
+ coverage_boundary: "Only the fields named in the authorised state of one resource; nothing else about the resource was read.",
48
+ probe: (request) => ({ resource: request.resource, fields: Object.keys(request.params.state).sort() }),
49
+ // The read must be about this decision's resource.
50
+ bound: (request, body) => body !== null && typeof body === "object" && body.resource === request.resource,
51
+ expected(request, outcome) {
52
+ if (outcome !== OUTCOMES.APPLIED) return null; // NOT_APPLIED is not checkable without a pre-state
53
+ return { resource: request.resource, state: pick(request.params.state, Object.keys(request.params.state)) };
54
+ },
55
+ // A read only counts if it is an object that carries EVERY authorised field.
56
+ // A missing field must not be read as null: otherwise `{}` (or a string)
57
+ // would "confirm" an authorised `{ deleted_at: null }`.
58
+ observationProblems(request, body) {
59
+ const s = body.state;
60
+ if (s === null || typeof s !== "object" || Array.isArray(s)) return ["OBSERVED_STATE_NOT_AN_OBJECT"];
61
+ const missing = Object.keys(request.params.state)
62
+ .filter((k) => !Object.prototype.hasOwnProperty.call(s, k))
63
+ .sort();
64
+ return missing.length ? ["OBSERVED_FIELDS_MISSING:" + missing.join(",")] : [];
65
+ },
66
+ observed(request, body) {
67
+ return { resource: body.resource, state: pick(body.state, Object.keys(request.params.state)) };
68
+ },
69
+ finality: () => "FINAL",
70
+ });
71
+
72
+ export function effectFor(operation) {
73
+ if (operation !== OPERATION) throw new Error("no effect definition for " + operation);
74
+ return SET_STATE;
75
+ }
76
+
77
+ export function expectedStateDigest(request, outcome) {
78
+ const e = effectFor(request.operation).expected(request, outcome);
79
+ return e === null ? null : digest(e);
80
+ }
@@ -0,0 +1,174 @@
1
+ // Signed envelopes for the local assurance sandbox.
2
+ //
3
+ // Ported from examples/effect-assurance-demo/src/envelope.mjs (PRs #449,
4
+ // #477). Changes: a sandbox-specific signing domain (so a local signature can
5
+ // never be replayed as any other Intentrax envelope), the payload types the
6
+ // sandbox uses, and no revocation handling (local keys are never revoked;
7
+ // they simply expire with the run).
8
+ //
9
+ // { payload_type, payload, signatures: [{ key_id, alg, public_key, sig }] }
10
+ //
11
+ // The signed message is ALWAYS rebuilt by the verifier from `payload_type` and
12
+ // `payload`: DOMAIN || canonical_json({ payload_type, payload }).
13
+ // `public_key` inside a signature entry is SELF-ASSERTED; it is used only to
14
+ // check record integrity when no pinned key matches and never establishes who
15
+ // signed.
16
+
17
+ import { sign as edSign, verify as edVerify } from "node:crypto";
18
+ import { canonicalJson, digest } from "./canonical.mjs";
19
+ import { publicKeyFromRaw, ROLES } from "./keys.mjs";
20
+ import { isoMs } from "./time.mjs";
21
+
22
+ const DOMAIN = "intentrax-local-sandbox-envelope/0.1\n";
23
+
24
+ export const PAYLOAD_TYPES = Object.freeze({
25
+ MANDATE: "intentrax.mandate/0.1",
26
+ DECISION: "intentrax.decision/0.1",
27
+ EXECUTION_REPORT: "intentrax.execution_report/0.1",
28
+ EFFECT_EVIDENCE: "intentrax.effect_evidence/0.1",
29
+ BUNDLE_SEAL: "intentrax.local_bundle_seal/0.1",
30
+ });
31
+
32
+ export const SIGNING_TIME_FIELD = Object.freeze({
33
+ [PAYLOAD_TYPES.MANDATE]: "issued_at",
34
+ [PAYLOAD_TYPES.DECISION]: "decided_at",
35
+ [PAYLOAD_TYPES.EXECUTION_REPORT]: "reported_at",
36
+ [PAYLOAD_TYPES.EFFECT_EVIDENCE]: "attested_at",
37
+ [PAYLOAD_TYPES.BUNDLE_SEAL]: "sealed_at",
38
+ });
39
+
40
+ export function expectedRole(payloadType) {
41
+ switch (payloadType) {
42
+ case PAYLOAD_TYPES.MANDATE:
43
+ return ROLES.PRINCIPAL;
44
+ case PAYLOAD_TYPES.DECISION:
45
+ case PAYLOAD_TYPES.BUNDLE_SEAL:
46
+ return ROLES.DECISION_SERVICE;
47
+ case PAYLOAD_TYPES.EXECUTION_REPORT:
48
+ return ROLES.EXECUTOR;
49
+ case PAYLOAD_TYPES.EFFECT_EVIDENCE:
50
+ return ROLES.EFFECT_VERIFIER;
51
+ default:
52
+ return null;
53
+ }
54
+ }
55
+
56
+ function signingMessage(payloadType, payload) {
57
+ return Buffer.from(DOMAIN + canonicalJson({ payload_type: payloadType, payload }), "utf8");
58
+ }
59
+
60
+ export function signEnvelope(payloadType, payload, signer) {
61
+ const sig = edSign(null, signingMessage(payloadType, payload), signer.privateKey);
62
+ return {
63
+ payload_type: payloadType,
64
+ payload,
65
+ signatures: [{
66
+ key_id: signer.key_id,
67
+ alg: "Ed25519",
68
+ public_key: signer.public_key,
69
+ sig: sig.toString("base64url"),
70
+ }],
71
+ };
72
+ }
73
+
74
+ // Content digest of an envelope: binds payload_type + payload.
75
+ export function envelopeDigest(envelope) {
76
+ return digest({ payload_type: envelope.payload_type, payload: envelope.payload });
77
+ }
78
+
79
+ // Verify one envelope. Returns a structured result; never throws on bad input.
80
+ // integrity: VERIFIED | FAILED
81
+ // authenticity: VERIFIED | FAILED | INSUFFICIENT_EVIDENCE (signer unknown) | NOT_ASSESSED (no key set)
82
+ export function verifyEnvelope(envelope, { pinned = null } = {}) {
83
+ const out = { integrity: "FAILED", authenticity: "FAILED", key_id: null, reasons: [] };
84
+ const fail = (reason, which = "both") => {
85
+ out.reasons.push(reason);
86
+ if (which === "both" || which === "integrity") out.integrity = "FAILED";
87
+ if (which === "both" || which === "authenticity") out.authenticity = "FAILED";
88
+ return out;
89
+ };
90
+ if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
91
+ return fail("ENVELOPE_MALFORMED");
92
+ }
93
+ if (Object.keys(envelope).sort().join(",") !== "payload,payload_type,signatures") {
94
+ return fail("ENVELOPE_UNEXPECTED_FIELDS");
95
+ }
96
+ if (!Object.values(PAYLOAD_TYPES).includes(envelope.payload_type)) {
97
+ return fail("ENVELOPE_UNKNOWN_PAYLOAD_TYPE");
98
+ }
99
+ if (!Array.isArray(envelope.signatures) || envelope.signatures.length !== 1) {
100
+ return fail("ENVELOPE_REQUIRES_EXACTLY_ONE_SIGNATURE");
101
+ }
102
+ const s = envelope.signatures[0];
103
+ if (!s || typeof s !== "object" || Object.keys(s).sort().join(",") !== "alg,key_id,public_key,sig" || s.alg !== "Ed25519") {
104
+ return fail("SIGNATURE_ENTRY_MALFORMED");
105
+ }
106
+ out.key_id = s.key_id;
107
+ let message;
108
+ try {
109
+ message = signingMessage(envelope.payload_type, envelope.payload);
110
+ } catch {
111
+ return fail("PAYLOAD_NOT_CANONICALIZABLE");
112
+ }
113
+ const sig = Buffer.from(String(s.sig), "base64url");
114
+ const check = (publicKey) => {
115
+ try {
116
+ return edVerify(null, message, publicKey, sig);
117
+ } catch {
118
+ return false;
119
+ }
120
+ };
121
+
122
+ const pinnedEntry = pinned ? pinned.get(s.key_id) : undefined;
123
+ if (pinnedEntry) {
124
+ if (s.public_key !== pinnedEntry.public_key) {
125
+ return fail("EMBEDDED_KEY_DIFFERS_FROM_PINNED_KEY");
126
+ }
127
+ if (!check(pinnedEntry.publicKey)) {
128
+ return fail("SIGNATURE_INVALID_FOR_PINNED_KEY");
129
+ }
130
+ out.integrity = "VERIFIED";
131
+ const role = expectedRole(envelope.payload_type);
132
+ if (pinnedEntry.role !== role) {
133
+ return fail("SIGNER_ROLE_MISMATCH:" + pinnedEntry.role + "!=" + role, "authenticity");
134
+ }
135
+ const field = SIGNING_TIME_FIELD[envelope.payload_type];
136
+ // Strict timestamps (explicit offset; #491 parity).
137
+ const signedAt = isoMs(envelope.payload && envelope.payload[field]);
138
+ if (signedAt === null) {
139
+ return fail("SIGNING_TIME_MISSING", "authenticity");
140
+ }
141
+ // The loader guarantees the bounds parse (strict, explicit offset, from < until).
142
+ if (signedAt < isoMs(pinnedEntry.valid_from) || signedAt >= isoMs(pinnedEntry.valid_until)) {
143
+ return fail("SIGNER_KEY_NOT_VALID_AT_SIGNING_TIME", "authenticity");
144
+ }
145
+ out.authenticity = "VERIFIED";
146
+ out.signer = {
147
+ key_id: pinnedEntry.key_id,
148
+ role: pinnedEntry.role,
149
+ principal: pinnedEntry.principal,
150
+ environment: pinnedEntry.environment,
151
+ trust_bearing: pinnedEntry.trust_bearing,
152
+ };
153
+ return out;
154
+ }
155
+
156
+ let embedded;
157
+ try {
158
+ embedded = publicKeyFromRaw(String(s.public_key));
159
+ } catch {
160
+ return fail("SIGNATURE_UNVERIFIABLE_NO_KEY");
161
+ }
162
+ if (!check(embedded)) {
163
+ return fail("SIGNATURE_INVALID_FOR_EMBEDDED_KEY");
164
+ }
165
+ out.integrity = "VERIFIED";
166
+ if (pinned) {
167
+ out.authenticity = "INSUFFICIENT_EVIDENCE";
168
+ out.reasons.push("SIGNER_NOT_IN_PINNED_KEY_SET");
169
+ } else {
170
+ out.authenticity = "NOT_ASSESSED";
171
+ out.reasons.push("NO_LOCAL_KEY_SET_SUPPLIED");
172
+ }
173
+ return out;
174
+ }
@@ -0,0 +1,32 @@
1
+ // Example read-only check for `intentrax sandbox --check`.
2
+ //
3
+ // Copy this file, point it at YOUR system, and run it AFTER your agent's
4
+ // action has run:
5
+ //
6
+ // intentrax sandbox --check ./my-check.mjs
7
+ //
8
+ // Contract:
9
+ // - `expected` (required): the fields your action should have set, and the
10
+ // values it should have set them to. Plain JSON, integers only. This is
11
+ // what the local decision authorises, and what the read is compared with.
12
+ // - `resource` (optional): a label for the thing being checked.
13
+ // - default export: an async function that READS the current state and
14
+ // returns an object containing at least the fields in `expected`. Only
15
+ // those fields are compared (the coverage boundary).
16
+ //
17
+ // Read-only by contract: the sandbox calls this function once and never
18
+ // calls your write path. It cannot stop this function from writing, so keep
19
+ // it to reads. Because you wrote it, the sandbox labels the read
20
+ // SELF_REPORTED, not an Intentrax-pulled authoritative read.
21
+
22
+ export const resource = "ticket:EXAMPLE-1";
23
+
24
+ export const expected = { status: "closed", assignee: "agent:triage" };
25
+
26
+ export default async function check({ resource: _resource, fields: _fields }) {
27
+ // Replace with a real read of your system, for example:
28
+ // const res = await fetch(`https://your-api.example/tickets/1`, { headers: { authorization: `Bearer ${readOnlyToken}` } });
29
+ // const ticket = await res.json();
30
+ // return { status: ticket.status, assignee: ticket.assignee };
31
+ return { status: "closed", assignee: "agent:triage" };
32
+ }