@intentrax/sdk 1.0.0 → 1.1.1

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 CHANGED
@@ -1,5 +1,18 @@
1
1
  # TypeScript / Node.js SDK
2
2
 
3
+ ## Install
4
+
5
+ ```bash
6
+ npm install @intentrax/sdk
7
+ ```
8
+
9
+ The package is public on npm (Apache-2.0). Everything below that says
10
+ "offline" or "local" runs today with no API key: `init --dry-run`,
11
+ `check-init`, `verify-proof` (sandbox sample proofs, including tampered ones,
12
+ are bundled at `examples/sandbox/`), and `verify-pdf-receipt`. Live execution
13
+ keys and your sandbox base URL are issued after an architectural review at
14
+ <https://www.intentrax.com/request-architectural-review>.
15
+
3
16
  First-wave SDK lane for AI apps, MCP clients, SaaS products, browser-adjacent
4
17
  tooling, and Node.js service integrations.
5
18
 
@@ -13,8 +26,9 @@ Public surfaces:
13
26
  - `@intentrax/sdk/http` for explicit HTTP API-wrapper execution
14
27
  - `intentrax init <adapter>` for local developer adapter onboarding
15
28
  - `intentrax check-init --output-dir <dir>` for offline adapter init verification
16
- - `intentrax verify-proof <proof-export.json>` for local proof export hash and
17
- boundary verification
29
+ - `intentrax verify-proof <proof-export.json>` for offline proof verification:
30
+ integrity hashes, ed25519 signatures and quorum, the signed-payload binding,
31
+ and signer pinning against published key sets
18
32
  - `intentrax verify-pdf-receipt <receipt.pdf>` for local downloaded PDF receipt
19
33
  byte/hash verification
20
34
 
@@ -104,16 +118,46 @@ npx @intentrax/sdk init deepflow
104
118
 
105
119
  Local proof export verification:
106
120
 
121
+ Sandbox sample proofs ship with the package in `examples/sandbox/` (see its
122
+ README): a valid sandbox proof plus tampered and unpinned variants. They are
123
+ produced by the engine's own proof pipeline under published sandbox keys, so
124
+ these commands work immediately after `npm install @intentrax/sdk`, with no key,
125
+ no network, and no runtime:
126
+
107
127
  ```bash
108
- npx @intentrax/sdk verify-proof \
109
- .intentrax-runtime/pilot-local-sovereign/local-sovereign-proof-export.json \
110
- --report-out .intentrax/offline-proof-verification.report.json
128
+ npx @intentrax/sdk verify-proof node_modules/@intentrax/sdk/examples/sandbox/sandbox-proof-export.json
129
+ npx @intentrax/sdk verify-proof node_modules/@intentrax/sdk/examples/sandbox/tampered-aep-swap.json
111
130
  ```
112
131
 
113
- `verify-proof` reads a registry-backed proof lookup JSON export, recomputes the
114
- proof lookup hash, proof record hash, and verification bundle hash, rejects
115
- private key material markers, and writes a deterministic local verification
116
- report. It does not require the runtime server, network access, or private keys.
132
+ To verify your own artifact, point the command at any proof lookup JSON export
133
+ downloaded from your tenant's `/v1/proofs/{proof_id}/export?format=json`, and
134
+ pass the production key set Intentrax publishes with `--trusted-keys <file>`.
135
+
136
+ `verify-proof` reads a registry-backed proof lookup JSON export and, offline:
137
+
138
+ 1. recomputes the proof lookup, proof record, verification bundle, and AEP hashes;
139
+ 2. verifies every ed25519 signature over the signed payload
140
+ (`canonical_payload_json`) and the signature quorum;
141
+ 3. checks that the signed payload carries the record's own AEP, so the AEP cannot
142
+ be rewritten after signing even if every outer hash is recomputed;
143
+ 4. checks each signer against published key sets: the bundled production set
144
+ (`trust/production-key-set.json`, trust-bearing), the bundled sandbox set
145
+ (`trust/sandbox-key-set.json`, not trust-bearing), and any `--trusted-keys` files.
146
+ A revocation in any loaded set wins.
147
+
148
+ | Status | Exit | Meaning |
149
+ |---|---|---|
150
+ | `PASS` | 0 | Every signer is a published, trust-bearing key |
151
+ | `SANDBOX_NON_TRUST_BEARING` | 0 | Every signer is a published sandbox key: the mechanics check out, but this is not production assurance |
152
+ | `UNPINNED_SIGNER` | 3 | Signatures are valid, but a signer is not in any trusted key set, so who signed is unproven |
153
+ | `REVOKED_SIGNER`, `MIXED_TRUST` | 3 | Not a trusted result |
154
+ | (none) | 2 | An integrity, signature, or binding check failed (failed closed) |
155
+
156
+ A passing verification shows the record is unaltered since signing, genuinely
157
+ signed, and bound to its own AEP. It does not show that the described action was
158
+ carried out or had its intended effect. The verifier also rejects private key
159
+ material markers. It does not require the runtime server, network access, or
160
+ private keys.
117
161
  The JSON proof export remains authoritative. Downloaded PDF receipts are
118
162
  human-readable companions and should be checked against their exported hash
119
163
  metadata, not treated as replacement proof material.
@@ -146,3 +190,29 @@ verification request for `POST /v1/proofs/verify`. `buildProofExportHttpRequest`
146
190
  builds `GET /v1/proofs/{proof_id}/export?format=json|aep-json|pdf`; JSON and
147
191
  AEP JSON are authoritative proof exports, while PDF is a deterministic
148
192
  human-readable receipt.
193
+
194
+ Reading a Verification Mark verdict off a response:
195
+
196
+ ```js
197
+ import { readVerificationVerdict } from "@intentrax/sdk";
198
+
199
+ // `response` can be a bare verification envelope, any object carrying an
200
+ // `intentrax_verification` envelope, or an MCP tool result whose
201
+ // `structuredContent` carries one.
202
+ const verdict = readVerificationVerdict(response);
203
+ if (verdict.verified) {
204
+ // verdict.display_state === "verified", verdict.severity === "green"
205
+ console.log(verdict.proof_id, verdict.verify_url, verdict.assurance_level);
206
+ }
207
+ ```
208
+
209
+ The `intentrax_verification` envelope is a backend-produced, public-safe
210
+ projection — `{ display_state, proof_id, verify_url, assurance_level,
211
+ signature }`. The SDK is a strict READER: `readVerificationVerdict`,
212
+ `normalizeVerificationMarkEnvelope`, and `validateVerificationMarkEnvelope`
213
+ validate the envelope's SHAPE only. They never re-derive crypto, recompute
214
+ validity, or regenerate a proof — `verified` is exactly the backend's
215
+ `display_state === "verified"`. `signature` is a STATUS projection (e.g.
216
+ `"pass"`), never a raw signature; a value that looks like raw signing material
217
+ is refused so it can never leak. An absent or malformed envelope yields a safe,
218
+ non-verified reading rather than throwing.
package/cli/intentrax.mjs CHANGED
@@ -1,19 +1,37 @@
1
1
  #!/usr/bin/env node
2
- import { createHash } from "node:crypto";
2
+ import { createHash, createPublicKey, verify as verifySignatureBytes } from "node:crypto";
3
3
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
4
4
  import { dirname, isAbsolute, join, relative, resolve } from "node:path";
5
5
  import { pathToFileURL } from "node:url";
6
6
  import { buildAgentGatewayAdmissionEnvelope } from "../index.js";
7
7
 
8
- const VERSION = "1.0.0";
8
+ const VERSION = "1.1.1";
9
9
  const ADMISSION_SCHEMA_VERSION = "intentrax.runtime.agent_admission_request/1.0";
10
10
  const INIT_SCHEMA_VERSION = "intentrax.onboarding.agent_adapter_init/1.0";
11
11
  const ACTION_RECEIPT_SCHEMA_VERSION = "intentrax.onboarding.agent_adapter_action_receipt/1.0";
12
12
  const HOST_WIRING_GUIDE_SCHEMA_VERSION = "intentrax.onboarding.agent_adapter_host_wiring_guide/1.0";
13
13
  const LOCAL_INIT_CHECK_SCHEMA_VERSION = "intentrax.sdk.agent_adapter_init_offline_check/1.0";
14
14
  const LOCAL_INIT_CHECK_VERIFIER_VERSION = "intentrax-typescript-cli-init-offline-checker/1.0";
15
- const LOCAL_PROOF_VERIFICATION_SCHEMA_VERSION = "intentrax.sdk.local_proof_verification_report/1.0";
16
- const LOCAL_PROOF_VERIFIER_VERSION = "intentrax-typescript-cli-local-proof-verifier/1.0";
15
+ const LOCAL_PROOF_VERIFICATION_SCHEMA_VERSION = "intentrax.sdk.local_proof_verification_report/2.0";
16
+ const LOCAL_PROOF_VERIFIER_VERSION = "intentrax-typescript-cli-local-proof-verifier/2.0";
17
+ // Signature verification (1.1.0). These mirror the engine exactly:
18
+ // aep_hash = SHA-256(AEP_HASH_DOMAIN + canonical_aep_json) (C4.3)
19
+ // payload_hash = SHA-256(SIGNATURE_PAYLOAD_HASH_DOMAIN + canonical_payload_json) (C5.2)
20
+ // each key reference carries an ed25519 signature over canonical_payload_json (C5.4)
21
+ const AEP_HASH_DOMAIN = "INTENTRAX_PROOF_CANONICAL_AEP_V1";
22
+ const SIGNATURE_PAYLOAD_HASH_DOMAIN = "INTENTRAX_TRUST_SIGNATURE_PAYLOAD_V1";
23
+ const SIGNATURE_PAYLOAD_VERSION = "intentrax.trust.signature_payload/1.0";
24
+ const SIGNATURE_PAYLOAD_FIELDS = Object.freeze(["payload_version", "canonical_aep_json", "aep_hash"]);
25
+ const PUBLISHED_KEY_SET_SCHEMA_VERSION = "intentrax.trust.published_key_set/1.0";
26
+ const BUILT_IN_KEY_SET_URLS = Object.freeze([
27
+ // Published production signer keys (trust-bearing), exported from the production
28
+ // keyring with engine/cmd/sovereign-public-key-set.
29
+ new URL("../trust/production-key-set.json", import.meta.url),
30
+ // Published sandbox keys (not trust-bearing).
31
+ new URL("../trust/sandbox-key-set.json", import.meta.url),
32
+ ]);
33
+ const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
34
+ const SIGNER_TRUST_EXIT_CODE = 3;
17
35
  const LOCAL_PDF_RECEIPT_VERIFICATION_SCHEMA_VERSION = "intentrax.sdk.local_pdf_receipt_verification_report/1.0";
18
36
  const LOCAL_PDF_RECEIPT_VERIFIER_VERSION = "intentrax-typescript-cli-local-pdf-receipt-verifier/1.0";
19
37
  const ENDPOINT = "/v1/agent/admissions";
@@ -237,12 +255,18 @@ async function main(argv) {
237
255
  if (command === "verify-proof") {
238
256
  const options = parseVerifyProofOptions(rest);
239
257
  const output = verifyProofExportCommand(subject, options);
258
+ const exitCode = output.status === "PASS" || output.status === "SANDBOX_NON_TRUST_BEARING" ? 0 : SIGNER_TRUST_EXIT_CODE;
240
259
  if (options.json) {
241
260
  console.log(JSON.stringify(output, null, 2));
242
- return 0;
261
+ } else if (output.status === "PASS") {
262
+ console.log(`Intentrax proof export verification PASS: proof=${output.registry_entry_id} signer=TRUSTED report=${output.report_path} hash=${output.report_hash}`);
263
+ } else if (output.status === "SANDBOX_NON_TRUST_BEARING") {
264
+ console.log(`Intentrax proof export verification: SANDBOX — not trust-bearing. Integrity and ed25519 signatures check out, and the signers are published sandbox keys. This shows the verification mechanics, not production assurance. proof=${output.registry_entry_id} report=${output.report_path}`);
243
265
  }
244
- console.log(`Intentrax proof export verification PASS: proof=${output.registry_entry_id} report=${output.report_path} hash=${output.report_hash}`);
245
- return 0;
266
+ if (exitCode !== 0) {
267
+ console.error(signerTrustMessage(output));
268
+ }
269
+ return exitCode;
246
270
  }
247
271
  if (command === "verify-pdf-receipt") {
248
272
  const options = parseVerifyPDFReceiptOptions(rest);
@@ -287,6 +311,9 @@ async function main(argv) {
287
311
  console.log(`Endpoint: ${output.normalized_contract.endpoint}`);
288
312
  console.log(`Next: set INTENTRAX_API_KEY, then run from ${output.submit_sample.working_directory}:`);
289
313
  console.log(output.submit_sample.curl);
314
+ console.log("Note: the default base URL http://127.0.0.1:8080 targets a locally run Intentrax engine; the hosted engine base URL is https://api.intentrax.com (override with --base-url or INTENTRAX_BASE_URL).");
315
+ console.log("INTENTRAX_API_KEY and your sandbox base URL are issued after an architectural review: https://www.intentrax.com/request-architectural-review");
316
+ console.log("Offline check that works right now with no key: npx @intentrax/sdk check-init");
290
317
  return 0;
291
318
  }
292
319
 
@@ -296,7 +323,7 @@ function parseOptions(args) {
296
323
  force: false,
297
324
  json: false,
298
325
  outputDir: "",
299
- baseUrl: "http://127.0.0.1:8080",
326
+ baseUrl: process.env.INTENTRAX_BASE_URL || "http://127.0.0.1:8080",
300
327
  tenantId: "tenant-local-dev",
301
328
  };
302
329
  for (let index = 0; index < args.length; index += 1) {
@@ -1036,6 +1063,7 @@ function parseVerifyProofOptions(args) {
1036
1063
  const options = {
1037
1064
  json: false,
1038
1065
  reportOut: ".intentrax/offline-proof-verification.report.json",
1066
+ trustedKeys: [],
1039
1067
  };
1040
1068
  for (let index = 0; index < args.length; index += 1) {
1041
1069
  const arg = args[index];
@@ -1043,6 +1071,8 @@ function parseVerifyProofOptions(args) {
1043
1071
  options.json = true;
1044
1072
  } else if (arg === "--report-out") {
1045
1073
  options.reportOut = requireValue(args, ++index, arg);
1074
+ } else if (arg === "--trusted-keys") {
1075
+ options.trustedKeys.push(requireValue(args, ++index, arg));
1046
1076
  } else {
1047
1077
  fail(`unknown option: ${arg}`);
1048
1078
  }
@@ -1081,7 +1111,8 @@ function verifyProofExportCommand(proofExportPath, options) {
1081
1111
  fail("proof export contains private material marker");
1082
1112
  }
1083
1113
  const proofExport = parseSingleJSON(source, "proof export");
1084
- const report = buildLocalProofVerificationReport(proofExport, resolvedProofExportPath, resolve(options.reportOut));
1114
+ const keySets = loadPublishedKeySets(options.trustedKeys);
1115
+ const report = buildLocalProofVerificationReport(proofExport, resolvedProofExportPath, resolve(options.reportOut), keySets);
1085
1116
  const reportData = JSON.stringify(report, null, 2) + "\n";
1086
1117
  mkdirSync(dirname(resolve(options.reportOut)), { recursive: true });
1087
1118
  writeFileSync(resolve(options.reportOut), reportData, { mode: 0o600 });
@@ -1149,17 +1180,35 @@ function buildLocalPDFReceiptVerificationReport(bytes, pdfPath, reportPath, expe
1149
1180
  });
1150
1181
  }
1151
1182
 
1152
- function buildLocalProofVerificationReport(proofExport, proofExportPath, reportPath) {
1183
+ function buildLocalProofVerificationReport(proofExport, proofExportPath, reportPath, keySets) {
1153
1184
  const invalid = validateProofLookupExport(proofExport);
1154
1185
  if (invalid.length > 0) {
1155
1186
  fail(`proof export verification failed closed: ${invalid.join(",")}`);
1156
1187
  }
1157
1188
  const record = proofExport.proof_record;
1158
1189
  const bundle = record.verification_bundle;
1190
+ const signatures = verifySignedProofRecord(record);
1191
+ if (signatures.invalid.length > 0) {
1192
+ fail(`proof export verification failed closed: ${signatures.invalid.join(",")}`);
1193
+ }
1194
+ const trust = classifySignerTrust(signatures.signers, keySets);
1159
1195
  const withoutHash = {
1160
1196
  schema_version: LOCAL_PROOF_VERIFICATION_SCHEMA_VERSION,
1161
1197
  verifier_version: LOCAL_PROOF_VERIFIER_VERSION,
1162
- status: "PASS",
1198
+ // PASS only when every signer is a published, trust-bearing key. Valid
1199
+ // signatures from keys you have not chosen to trust prove nothing about who
1200
+ // signed, so they never yield PASS.
1201
+ status: trust.signer_trust === "TRUSTED" ? "PASS" : trust.signer_trust,
1202
+ signer_trust: trust.signer_trust,
1203
+ trust_bearing: trust.signer_trust === "TRUSTED",
1204
+ signature_verification: {
1205
+ algorithm: "ED25519",
1206
+ signed_bytes: "verification_bundle.payload.canonical_payload_json",
1207
+ required_signatures: signatures.required,
1208
+ valid_signatures: signatures.signers.length,
1209
+ signers: trust.signers,
1210
+ },
1211
+ key_sets: keySets.map((set) => ({ key_set_id: set.key_set_id, environment: set.environment, source: set.source })),
1163
1212
  offline: true,
1164
1213
  proof_export_path: proofExportPath,
1165
1214
  report_path: reportPath,
@@ -1178,6 +1227,11 @@ function buildLocalProofVerificationReport(proofExport, proofExportPath, reportP
1178
1227
  proof_lookup_hash_recomputed: true,
1179
1228
  proof_record_hash_recomputed: true,
1180
1229
  registry_bundle_hash_recomputed: true,
1230
+ aep_hash_recomputed: true,
1231
+ ed25519_signatures_verified: true,
1232
+ signature_quorum_satisfied: true,
1233
+ signed_payload_binds_record_aep: true,
1234
+ signers_pinned_to_published_keys: trust.signer_trust === "TRUSTED" || trust.signer_trust === "SANDBOX_NON_TRUST_BEARING",
1181
1235
  canonical_json_authoritative: true,
1182
1236
  pdf_receipt_non_authoritative: true,
1183
1237
  },
@@ -1189,6 +1243,246 @@ function buildLocalProofVerificationReport(proofExport, proofExportPath, reportP
1189
1243
  });
1190
1244
  }
1191
1245
 
1246
+ // Verifies what the record's integrity hashes cannot: that the signatures are
1247
+ // genuine ed25519 signatures over the signed payload, that enough of them are
1248
+ // present, and that the signed payload carries this record's own AEP. Without
1249
+ // the last check the AEP (and every hash derived from it) could be rewritten
1250
+ // after signing while the original signatures still verify.
1251
+ function verifySignedProofRecord(record) {
1252
+ const invalid = [];
1253
+ const bundle = record.verification_bundle;
1254
+ const payload = bundle.payload;
1255
+ const signatureBundle = isRecord(bundle.registry_output) ? bundle.registry_output.signature : undefined;
1256
+ const quorum = isRecord(bundle.key_binding) && isRecord(bundle.key_binding.quorum) ? bundle.key_binding.quorum : undefined;
1257
+ if (!isRecord(payload) || typeof payload.canonical_payload_json !== "string" || !isSHA256(payload.payload_hash)) invalid.push("verification_bundle.payload");
1258
+ if (!isRecord(signatureBundle) || !Array.isArray(signatureBundle.signatures)) invalid.push("verification_bundle.registry_output.signature");
1259
+ if (!isRecord(quorum) || !Number.isInteger(quorum.required_signatures) || quorum.required_signatures < 1) invalid.push("verification_bundle.key_binding.quorum");
1260
+ if (invalid.length > 0) return { invalid, signers: [], required: 0 };
1261
+
1262
+ if (sha256Hex(AEP_HASH_DOMAIN + record.canonical_aep_json) !== record.aep_hash) invalid.push("proof_record.aep_hash");
1263
+ if (sha256Hex(SIGNATURE_PAYLOAD_HASH_DOMAIN + payload.canonical_payload_json) !== payload.payload_hash) invalid.push("verification_bundle.payload.payload_hash");
1264
+ if (signatureBundle.payload_hash !== payload.payload_hash) invalid.push("verification_bundle.registry_output.signature.payload_hash");
1265
+ let signedPayload;
1266
+ try {
1267
+ signedPayload = JSON.parse(payload.canonical_payload_json);
1268
+ } catch {
1269
+ signedPayload = undefined;
1270
+ }
1271
+ const signedFields = isRecord(signedPayload) ? Object.keys(signedPayload) : [];
1272
+ const bindsRecord = isRecord(signedPayload)
1273
+ && signedFields.length === SIGNATURE_PAYLOAD_FIELDS.length
1274
+ && SIGNATURE_PAYLOAD_FIELDS.every((field, index) => signedFields[index] === field)
1275
+ && signedPayload.payload_version === SIGNATURE_PAYLOAD_VERSION
1276
+ && signedPayload.canonical_aep_json === record.canonical_aep_json
1277
+ && signedPayload.aep_hash === record.aep_hash
1278
+ && isRecord(payload.payload)
1279
+ && payload.payload.canonical_aep_json === signedPayload.canonical_aep_json
1280
+ && payload.payload.aep_hash === signedPayload.aep_hash;
1281
+ if (!bindsRecord) invalid.push("verification_bundle.payload.canonical_payload_json");
1282
+
1283
+ invalid.push(...validateSignerRoster(bundle, signatureBundle, quorum, payload));
1284
+
1285
+ const signedBytes = Buffer.from(payload.canonical_payload_json, "utf8");
1286
+ const keyReferences = Array.isArray(bundle.key_references) ? [...bundle.key_references] : [];
1287
+ keyReferences.sort((a, b) => `${a.key_id}\u0000${a.key_version}`.localeCompare(`${b.key_id}\u0000${b.key_version}`));
1288
+ const signers = [];
1289
+ const seen = new Set();
1290
+ for (const key of keyReferences) {
1291
+ const keyLabel = `${key.key_id}@${key.key_version}`;
1292
+ if (seen.has(keyLabel)) {
1293
+ invalid.push("verification_bundle.key_references.duplicate");
1294
+ continue;
1295
+ }
1296
+ seen.add(keyLabel);
1297
+ if (key.key_status === "REVOKED") {
1298
+ invalid.push("verification_bundle.key_references.key_status");
1299
+ continue;
1300
+ }
1301
+ if (key.algorithm !== "ED25519" || !/^[0-9a-f]{64}$/.test(String(key.public_key_material))) {
1302
+ invalid.push("verification_bundle.key_references.public_key_material");
1303
+ continue;
1304
+ }
1305
+ const signature = signatureBundle.signatures.find((candidate) => isRecord(candidate) && candidate.key_id === key.key_id && candidate.key_version === key.key_version);
1306
+ if (!signature || !/^[0-9a-f]{128}$/.test(String(signature.signature_hex))) {
1307
+ invalid.push("verification_bundle.registry_output.signature.signatures");
1308
+ continue;
1309
+ }
1310
+ if (signature.public_key_hash !== sha256Hex(key.public_key_material)) {
1311
+ invalid.push("verification_bundle.registry_output.signature.signatures.public_key_hash");
1312
+ continue;
1313
+ }
1314
+ let valid = false;
1315
+ try {
1316
+ const publicKey = createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(key.public_key_material, "hex")]), format: "der", type: "spki" });
1317
+ valid = verifySignatureBytes(null, signedBytes, publicKey, Buffer.from(signature.signature_hex, "hex"));
1318
+ } catch {
1319
+ valid = false;
1320
+ }
1321
+ if (!valid) {
1322
+ invalid.push("verification_bundle.registry_output.signature.signatures.signature_hex");
1323
+ continue;
1324
+ }
1325
+ signers.push({ key_id: key.key_id, key_version: key.key_version, public_key_material: key.public_key_material, public_key_hash: signature.public_key_hash });
1326
+ }
1327
+ if (invalid.length === 0 && signers.length < quorum.required_signatures) invalid.push("verification_bundle.key_binding.quorum");
1328
+ return { invalid: sortedUnique(invalid), signers, required: quorum.required_signatures };
1329
+ }
1330
+
1331
+ // The signer roster (key_references), the key bindings and the signature bundle
1332
+ // must describe the same signers one-to-one, and the quorum metadata must agree
1333
+ // everywhere. Mirrors the engine's validateBindingAndSignatureMetadata. Without
1334
+ // it, an export could drop a failing signer's key reference and lower the
1335
+ // quorum, and the remaining valid signature would satisfy it.
1336
+ function validateSignerRoster(bundle, signatureBundle, quorum, payload) {
1337
+ const invalid = [];
1338
+ const keyReferences = Array.isArray(bundle.key_references) ? bundle.key_references : [];
1339
+ const bindingList = isRecord(bundle.key_binding) && Array.isArray(bundle.key_binding.keys) ? bundle.key_binding.keys : [];
1340
+ const signatureList = signatureBundle.signatures;
1341
+ const tokenOf = (entry) => (isRecord(entry) ? `${entry.key_id}\u0000${entry.key_version}` : "\u0000invalid");
1342
+
1343
+ if (signatureBundle.required_signatures !== quorum.required_signatures) invalid.push("verification_bundle.registry_output.signature.required_signatures");
1344
+ if (!Number.isInteger(quorum.total_signers)
1345
+ || quorum.required_signatures > quorum.total_signers
1346
+ || signatureBundle.total_signers !== quorum.total_signers
1347
+ || quorum.total_signers !== keyReferences.length) {
1348
+ invalid.push("verification_bundle.registry_output.signature.total_signers");
1349
+ }
1350
+
1351
+ const index = (list, duplicateField) => {
1352
+ const map = new Map();
1353
+ for (const entry of list) {
1354
+ const token = tokenOf(entry);
1355
+ if (map.has(token)) invalid.push(duplicateField);
1356
+ map.set(token, entry);
1357
+ }
1358
+ return map;
1359
+ };
1360
+ const bindings = index(bindingList, "verification_bundle.key_binding.keys.duplicate");
1361
+ const signatures = index(signatureList, "verification_bundle.registry_output.signature.signatures.duplicate");
1362
+ const references = index(keyReferences, "verification_bundle.key_references.duplicate");
1363
+
1364
+ for (const [token, key] of references) {
1365
+ const binding = bindings.get(token);
1366
+ if (!binding) {
1367
+ invalid.push("verification_bundle.key_binding.keys");
1368
+ continue;
1369
+ }
1370
+ const expectedPublicKeyHash = sha256Hex(String(key.public_key_material));
1371
+ if (binding.algorithm !== "ED25519" || key.algorithm !== "ED25519") invalid.push("verification_bundle.key_binding.keys.algorithm");
1372
+ if (binding.key_status !== key.key_status) invalid.push("verification_bundle.key_binding.keys.key_status");
1373
+ if (binding.principal_id !== key.principal_id) invalid.push("verification_bundle.key_binding.keys.principal_id");
1374
+ if (binding.public_key_hash !== expectedPublicKeyHash) invalid.push("verification_bundle.key_binding.keys.public_key_hash");
1375
+ if (!isSHA256(binding.key_binding_hash)) invalid.push("verification_bundle.key_binding.keys.key_binding_hash");
1376
+ const signature = signatures.get(token);
1377
+ if (!signature) {
1378
+ invalid.push("verification_bundle.registry_output.signature.signatures");
1379
+ continue;
1380
+ }
1381
+ if (signature.algorithm !== "ED25519") invalid.push("verification_bundle.registry_output.signature.signatures.algorithm");
1382
+ if (signature.payload_hash !== payload.payload_hash) invalid.push("verification_bundle.registry_output.signature.signatures.payload_hash");
1383
+ if (signature.key_binding_hash !== binding.key_binding_hash) invalid.push("verification_bundle.registry_output.signature.signatures.key_binding_hash");
1384
+ }
1385
+ // Every binding and every signature must belong to a listed signer: nothing
1386
+ // may be dropped from the roster while its signature or binding stays behind.
1387
+ for (const token of bindings.keys()) {
1388
+ if (!references.has(token)) invalid.push("verification_bundle.key_references");
1389
+ }
1390
+ for (const token of signatures.keys()) {
1391
+ if (!references.has(token)) invalid.push("verification_bundle.key_references");
1392
+ }
1393
+ return invalid;
1394
+ }
1395
+
1396
+ // A published key set pins who may sign: production keys (trust_bearing) or
1397
+ // sandbox keys (not trust-bearing). The SDK ships both published sets; extra sets
1398
+ // (or revocations) can be supplied with --trusted-keys.
1399
+ function loadPublishedKeySets(trustedKeyPaths) {
1400
+ const sets = [];
1401
+ for (const url of BUILT_IN_KEY_SET_URLS) {
1402
+ if (existsSync(url)) {
1403
+ sets.push(parsePublishedKeySet(readFileSync(url, "utf8"), `built-in:trust/${url.pathname.split("/").pop()}`));
1404
+ }
1405
+ }
1406
+ for (const keySetPath of trustedKeyPaths) {
1407
+ sets.push(parsePublishedKeySet(readFileSync(resolve(keySetPath), "utf8"), resolve(keySetPath)));
1408
+ }
1409
+ return sets;
1410
+ }
1411
+
1412
+ function parsePublishedKeySet(source, origin) {
1413
+ if (containsForbiddenPrivateMarker(source)) {
1414
+ fail(`trusted key set contains private material marker: ${origin}`);
1415
+ }
1416
+ const set = parseSingleJSON(source, "trusted key set");
1417
+ const invalid = [];
1418
+ if (!isRecord(set) || set.schema_version !== PUBLISHED_KEY_SET_SCHEMA_VERSION) invalid.push("schema_version");
1419
+ if (isRecord(set) && !stableNonEmpty(set.key_set_id)) invalid.push("key_set_id");
1420
+ if (!isRecord(set) || !Array.isArray(set.keys) || set.keys.length === 0) invalid.push("keys");
1421
+ if (isRecord(set) && Array.isArray(set.keys)) {
1422
+ for (const [index, key] of set.keys.entries()) {
1423
+ if (!isRecord(key)
1424
+ || !stableNonEmpty(key.key_id)
1425
+ || !stableNonEmpty(key.key_version)
1426
+ || key.algorithm !== "ED25519"
1427
+ || !/^[0-9a-f]{64}$/.test(String(key.public_key_material))
1428
+ || typeof key.trust_bearing !== "boolean"
1429
+ || !["ACTIVE", "RETIRED", "REVOKED"].includes(key.status)) {
1430
+ invalid.push(`keys.${index}`);
1431
+ }
1432
+ }
1433
+ }
1434
+ if (invalid.length > 0) {
1435
+ fail(`trusted key set is invalid (${origin}): ${sortedUnique(invalid).join(",")}`);
1436
+ }
1437
+ const environments = [...new Set(set.keys.map((key) => key.environment).filter(stableNonEmpty))];
1438
+ return {
1439
+ key_set_id: set.key_set_id,
1440
+ environment: environments.length === 1 ? environments[0] : "mixed",
1441
+ source: origin,
1442
+ keys: set.keys,
1443
+ };
1444
+ }
1445
+
1446
+ function classifySignerTrust(signers, keySets) {
1447
+ const resolved = signers.map((signer) => {
1448
+ // Collect every matching anchor across all key sets: a revocation in ANY
1449
+ // trusted set must win over an ACTIVE entry in another.
1450
+ const matches = [];
1451
+ for (const set of keySets) {
1452
+ for (const key of set.keys) {
1453
+ if (key.key_id === signer.key_id && key.key_version === signer.key_version && key.public_key_material === signer.public_key_material) {
1454
+ matches.push({ key_set_id: set.key_set_id, environment: key.environment ?? set.environment, trust_bearing: key.trust_bearing, status: key.status });
1455
+ }
1456
+ }
1457
+ }
1458
+ const anchor = matches.find((match) => match.status === "REVOKED")
1459
+ ?? matches.find((match) => match.trust_bearing === true)
1460
+ ?? matches[0]
1461
+ ?? null;
1462
+ return { key_id: signer.key_id, key_version: signer.key_version, public_key_hash: signer.public_key_hash, anchor };
1463
+ });
1464
+ let signerTrust;
1465
+ if (resolved.some((signer) => signer.anchor?.status === "REVOKED")) signerTrust = "REVOKED_SIGNER";
1466
+ else if (resolved.length === 0 || resolved.some((signer) => signer.anchor === null)) signerTrust = "UNPINNED_SIGNER";
1467
+ else if (resolved.every((signer) => signer.anchor.trust_bearing === true)) signerTrust = "TRUSTED";
1468
+ else if (resolved.every((signer) => signer.anchor.trust_bearing === false)) signerTrust = "SANDBOX_NON_TRUST_BEARING";
1469
+ else signerTrust = "MIXED_TRUST";
1470
+ return { signer_trust: signerTrust, signers: resolved };
1471
+ }
1472
+
1473
+ function signerTrustMessage(report) {
1474
+ if (report.signer_trust === "UNPINNED_SIGNER") {
1475
+ return "intentrax: signatures are mathematically valid, but at least one signing key is not in any trusted key set, so this proof does NOT establish who signed it. Pass the key set Intentrax publishes with --trusted-keys <file>.";
1476
+ }
1477
+ if (report.signer_trust === "REVOKED_SIGNER") {
1478
+ return "intentrax: a signing key is REVOKED in the trusted key set; this proof must not be relied on.";
1479
+ }
1480
+ if (report.signer_trust === "MIXED_TRUST") {
1481
+ return "intentrax: the proof mixes trust-bearing and sandbox signers; it is not a production-trusted proof.";
1482
+ }
1483
+ return `intentrax: proof verification did not reach a trusted result (${report.signer_trust}).`;
1484
+ }
1485
+
1192
1486
  function validateProofLookupExport(lookup) {
1193
1487
  const invalid = [];
1194
1488
  if (!isRecord(lookup)) return ["proof_export"];
@@ -1726,6 +2020,8 @@ function hostWiringGuideSource(adapterName, adapter, hookStarter, submitSample)
1726
2020
  "export INTENTRAX_API_KEY=\"...\"",
1727
2021
  "```",
1728
2022
  "",
2023
+ "`http://127.0.0.1:8080` targets a locally run Intentrax engine; the hosted engine base URL is `https://api.intentrax.com`. `INTENTRAX_API_KEY` and your sandbox base URL are issued after an architectural review at <https://www.intentrax.com/request-architectural-review>. Before you have a key, `npx @intentrax/sdk check-init` verifies this setup offline and works right now with no key.",
2024
+ "",
1729
2025
  "## Host Binding",
1730
2026
  "",
1731
2027
  hostSnippet,
@@ -2366,7 +2662,7 @@ function printHelp() {
2366
2662
  Usage:
2367
2663
  intentrax init <adapter> [--dry-run] [--force] [--json] [--output-dir <dir>] [--base-url <url>] [--tenant-id <tenant>]
2368
2664
  intentrax check-init --output-dir <dir> [--json]
2369
- intentrax verify-proof <proof-export.json> [--json] [--report-out <file>]
2665
+ intentrax verify-proof <proof-export.json> [--trusted-keys <key-set.json>] [--json] [--report-out <file>]
2370
2666
  intentrax verify-pdf-receipt <receipt.pdf> --pdf-hash <X-Intentrax-PDF-Hash> [--json] [--report-out <file>]
2371
2667
 
2372
2668
  Adapters:
@@ -2382,11 +2678,26 @@ Init verification:
2382
2678
  INTENTRAX_API_KEY or network submission.
2383
2679
 
2384
2680
  Proof export verification:
2385
- verify-proof reads an exported registry-backed proof lookup JSON package,
2386
- recomputes its proof lookup, proof record, and verification bundle hashes,
2387
- rejects private key material markers, and writes a deterministic offline
2388
- report. Runtime access, network access, and private keys are not required.
2389
- The JSON export is authoritative; PDF receipts are human-readable companions.
2681
+ verify-proof reads an exported registry-backed proof lookup JSON package and,
2682
+ offline: recomputes its proof lookup, proof record, verification bundle, and
2683
+ AEP hashes; verifies every ed25519 signature over the signed payload and the
2684
+ signature quorum; checks that the signed payload carries the record's own
2685
+ AEP; and checks each signer against published key sets. It writes a
2686
+ deterministic report. Runtime access, network access, and private keys are
2687
+ not required. The JSON export is authoritative; PDF receipts are companions.
2688
+
2689
+ Result (status / exit code):
2690
+ PASS 0 every signer is a published, trust-bearing key
2691
+ SANDBOX_NON_TRUST_BEARING 0 every signer is a published sandbox key: the
2692
+ mechanics check out, but it is not production
2693
+ assurance
2694
+ UNPINNED_SIGNER 3 signatures are valid but a signer is not in
2695
+ any trusted key set (who signed is unproven)
2696
+ REVOKED_SIGNER / MIXED_TRUST 3
2697
+ any integrity or signature failure exits 2 (failed closed)
2698
+
2699
+ The SDK ships the sandbox key set (trust/sandbox-key-set.json). Supply
2700
+ production keys with --trusted-keys <file> (repeatable).
2390
2701
 
2391
2702
  PDF receipt verification:
2392
2703
  verify-pdf-receipt reads downloaded PDF receipt bytes, checks the PDF header,
@@ -2404,7 +2715,9 @@ Examples:
2404
2715
  intentrax init langgraph
2405
2716
  intentrax init vercel-ai-sdk
2406
2717
  intentrax check-init --output-dir . --json
2407
- intentrax verify-proof .intentrax-runtime/pilot-local-sovereign/local-sovereign-proof-export.json --report-out .intentrax/offline-proof-verification.report.json
2718
+ intentrax verify-proof node_modules/@intentrax/sdk/examples/sandbox/sandbox-proof-export.json
2719
+ intentrax verify-proof node_modules/@intentrax/sdk/examples/sandbox/tampered-aep-swap.json
2720
+ intentrax verify-proof proof-export.json --trusted-keys intentrax-production-keys.json
2408
2721
  intentrax verify-pdf-receipt .intentrax/proof-001-aep-receipt.pdf --pdf-hash <X-Intentrax-PDF-Hash>
2409
2722
  `);
2410
2723
  }
@@ -0,0 +1,42 @@
1
+ # Sandbox proof samples
2
+
3
+ Real proof exports for trying `intentrax verify-proof` offline, with no account,
4
+ key, or network access.
5
+
6
+ They are produced by the Intentrax engine's own proof pipeline
7
+ (`engine/cmd/sandbox-sample-proof-gen`): AEP construction, signature payload,
8
+ ed25519 signing, and registry records, the same code paths as real proofs.
9
+ Two things differ:
10
+
11
+ - the signing keys are **sandbox keys**, published in `trust/sandbox-key-set.json`
12
+ with `trust_bearing: false`. Their signing halves were never stored, so nobody,
13
+ including Intentrax, can sign new proofs with them;
14
+ - the proof describes a `DEV`-environment sandbox tenant (`tenant-sandbox-sample`).
15
+
16
+ A sandbox proof shows **how verification works**. It is not production assurance,
17
+ and the verifier says so.
18
+
19
+ | File | What it is | Expected result |
20
+ |---|---|---|
21
+ | `sandbox-proof-export.json` | A valid sandbox proof | `SANDBOX_NON_TRUST_BEARING`, exit 0 |
22
+ | `tampered-aep-swap.json` | The AEP was rewritten after signing (it now claims `policy.unrestricted`), and every unsigned copy and outer hash was recomputed to match | Fails closed, exit 2: the signed payload no longer carries the record's AEP |
23
+ | `tampered-signature.json` | One signature byte flipped; outer hashes recomputed | Fails closed, exit 2: ed25519 verification fails |
24
+ | `tampered-roster.json` | Starts from the flipped signature, removes that signer from `key_references` and lowers the quorum to 1; outer hashes recomputed | Fails closed, exit 2: the signer roster, key bindings and signature bundle no longer agree |
25
+ | `unpinned-signer.json` | A fully valid proof signed by keys that were never published | `UNPINNED_SIGNER`, exit 3: the signatures are genuine, but who signed is unproven |
26
+
27
+ ```bash
28
+ npx @intentrax/sdk verify-proof node_modules/@intentrax/sdk/examples/sandbox/sandbox-proof-export.json
29
+ npx @intentrax/sdk verify-proof node_modules/@intentrax/sdk/examples/sandbox/tampered-aep-swap.json
30
+ npx @intentrax/sdk verify-proof node_modules/@intentrax/sdk/examples/sandbox/tampered-signature.json
31
+ npx @intentrax/sdk verify-proof node_modules/@intentrax/sdk/examples/sandbox/tampered-roster.json
32
+ npx @intentrax/sdk verify-proof node_modules/@intentrax/sdk/examples/sandbox/unpinned-signer.json
33
+ ```
34
+
35
+ What a passing verification shows: the record has not been altered since it was
36
+ signed, the signatures are genuine ed25519 signatures over the signed payload,
37
+ the signed payload carries this record's own AEP, and the signers are the
38
+ published keys. It does **not** show that the described action was carried out
39
+ or had its intended effect.
40
+
41
+ To verify production proofs, pass the key set Intentrax publishes for production
42
+ signers: `--trusted-keys <file>`.