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