@intentrax/sdk 1.1.1 → 1.3.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
@@ -130,8 +130,9 @@ npx @intentrax/sdk verify-proof node_modules/@intentrax/sdk/examples/sandbox/tam
130
130
  ```
131
131
 
132
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>`.
133
+ downloaded from your tenant's `/v1/proofs/{proof_id}/export?format=json`. The
134
+ production key set is bundled, so you don't need any flags. Pass extra key sets
135
+ (for example, ones that revoke a key) with `--trusted-keys <file>`.
135
136
 
136
137
  `verify-proof` reads a registry-backed proof lookup JSON export and, offline:
137
138
 
@@ -143,13 +144,19 @@ pass the production key set Intentrax publishes with `--trusted-keys <file>`.
143
144
  4. checks each signer against published key sets: the bundled production set
144
145
  (`trust/production-key-set.json`, trust-bearing), the bundled sandbox set
145
146
  (`trust/sandbox-key-set.json`, not trust-bearing), and any `--trusted-keys` files.
146
- A revocation in any loaded set wins.
147
+ A revocation in any loaded set wins;
148
+ 5. checks that at least the key set's `min_trusted_signers` distinct trusted keys
149
+ signed. The production set requires 2. A proof's own quorum isn't enough,
150
+ because a signature can be stripped along with the quorum and roster entries
151
+ that describe it. When several sets vouch for the signers, the strictest
152
+ minimum applies.
147
153
 
148
154
  | Status | Exit | Meaning |
149
155
  |---|---|---|
150
- | `PASS` | 0 | Every signer is a published, trust-bearing key |
156
+ | `PASS` | 0 | Every signer is a published, trust-bearing key, and enough distinct keys signed |
151
157
  | `SANDBOX_NON_TRUST_BEARING` | 0 | Every signer is a published sandbox key: the mechanics check out, but this is not production assurance |
152
158
  | `UNPINNED_SIGNER` | 3 | Signatures are valid, but a signer is not in any trusted key set, so who signed is unproven |
159
+ | `INSUFFICIENT_TRUSTED_SIGNERS` | 3 | Every signer is trusted, but fewer distinct keys signed than the key set requires (signatures may have been stripped) |
153
160
  | `REVOKED_SIGNER`, `MIXED_TRUST` | 3 | Not a trusted result |
154
161
  | (none) | 2 | An integrity, signature, or binding check failed (failed closed) |
155
162
 
@@ -216,3 +223,40 @@ validity, or regenerate a proof — `verified` is exactly the backend's
216
223
  `"pass"`), never a raw signature; a value that looks like raw signing material
217
224
  is refused so it can never leak. An absent or malformed envelope yields a safe,
218
225
  non-verified reading rather than throwing.
226
+
227
+ Binding the rendered output to a proof (execute request `/1.1`):
228
+
229
+ ```js
230
+ import { bindIntentExecuteOutput, verificationPointerMetaTag } from "@intentrax/sdk";
231
+ import { executeIntentHttp } from "@intentrax/sdk/http";
232
+
233
+ // Bind exactly the text the page will show inside its data-intentrax-output
234
+ // region(s). The request becomes schema /1.1 with an output_binding block.
235
+ const request = bindIntentExecuteOutput({
236
+ intent_id: "intent-refund-8812",
237
+ tenant_id: process.env.INTENTRAX_TENANT_ID,
238
+ action: "APPROVE_REFUND",
239
+ idempotency_key: "refund-8812-v1",
240
+ proof_chain_fixture_ref: "intent-execute",
241
+ schema_version: "intentrax.runtime.intent_execute.request/1.0",
242
+ }, renderedOutput);
243
+
244
+ const result = await executeIntentHttp(request, transport, {
245
+ base_url: process.env.INTENTRAX_BASE_URL,
246
+ api_key: process.env.INTENTRAX_API_KEY,
247
+ });
248
+ ```
249
+
250
+ The engine seals the binding inside the signed proof (`aep.output_binding`,
251
+ `binding_source: PRODUCER_DECLARED_AT_ISSUANCE`), and the public verifier
252
+ relays it only from that signed proof. The browser extension recomputes the
253
+ `intentrax-content/1.0` hash over the page's visible marked output and shows the
254
+ green Verification Mark only when the proof is valid and the hashes match. A
255
+ copy of the proof id on different content stays neutral.
256
+
257
+ `validateIntentExecuteRequest` mirrors the engine: `output_binding` is accepted
258
+ only under `/1.1` (a `/1.0` body carrying it is refused as `body`), is decoded
259
+ strictly (exactly `content_hash`, `hash_algorithm`, `normalization`), and its
260
+ `content_hash` must be 64 lowercase hex, optionally `sha256:`-prefixed. `/1.0`
261
+ requests are unchanged. The execute lane is fail-closed per tenant (HTTP 423
262
+ until live execution is enabled, HTTP 403 until the tenant is allowlisted).
package/cli/intentrax.mjs CHANGED
@@ -5,7 +5,7 @@ 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.1.1";
8
+ const VERSION = "1.3.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";
@@ -22,7 +22,11 @@ const AEP_HASH_DOMAIN = "INTENTRAX_PROOF_CANONICAL_AEP_V1";
22
22
  const SIGNATURE_PAYLOAD_HASH_DOMAIN = "INTENTRAX_TRUST_SIGNATURE_PAYLOAD_V1";
23
23
  const SIGNATURE_PAYLOAD_VERSION = "intentrax.trust.signature_payload/1.0";
24
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";
25
+ // 1.1 adds a required min_trusted_signers: how many distinct trust-bearing keys
26
+ // (by key_id) must have signed a proof for it to PASS. 1.0 is still accepted,
27
+ // but only for sets with no trust-bearing keys (sandbox sets).
28
+ const PUBLISHED_KEY_SET_SCHEMA_VERSION = "intentrax.trust.published_key_set/1.1";
29
+ const PUBLISHED_KEY_SET_SCHEMA_VERSION_V1 = "intentrax.trust.published_key_set/1.0";
26
30
  const BUILT_IN_KEY_SET_URLS = Object.freeze([
27
31
  // Published production signer keys (trust-bearing), exported from the production
28
32
  // keyring with engine/cmd/sovereign-public-key-set.
@@ -1195,9 +1199,10 @@ function buildLocalProofVerificationReport(proofExport, proofExportPath, reportP
1195
1199
  const withoutHash = {
1196
1200
  schema_version: LOCAL_PROOF_VERIFICATION_SCHEMA_VERSION,
1197
1201
  verifier_version: LOCAL_PROOF_VERIFIER_VERSION,
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.
1202
+ // PASS only when every signer is a published, trust-bearing key and at least
1203
+ // min_trusted_signers distinct trusted keys signed. Valid signatures from
1204
+ // keys you have not chosen to trust prove nothing about who signed, so they
1205
+ // never yield PASS.
1201
1206
  status: trust.signer_trust === "TRUSTED" ? "PASS" : trust.signer_trust,
1202
1207
  signer_trust: trust.signer_trust,
1203
1208
  trust_bearing: trust.signer_trust === "TRUSTED",
@@ -1206,6 +1211,10 @@ function buildLocalProofVerificationReport(proofExport, proofExportPath, reportP
1206
1211
  signed_bytes: "verification_bundle.payload.canonical_payload_json",
1207
1212
  required_signatures: signatures.required,
1208
1213
  valid_signatures: signatures.signers.length,
1214
+ // The published policy from the key sets, not the proof's own quorum: a
1215
+ // proof's roster and quorum metadata can be reduced together.
1216
+ min_trusted_signers: trust.min_trusted_signers,
1217
+ distinct_trusted_signers: trust.distinct_trusted_signers,
1209
1218
  signers: trust.signers,
1210
1219
  },
1211
1220
  key_sets: keySets.map((set) => ({ key_set_id: set.key_set_id, environment: set.environment, source: set.source })),
@@ -1231,7 +1240,8 @@ function buildLocalProofVerificationReport(proofExport, proofExportPath, reportP
1231
1240
  ed25519_signatures_verified: true,
1232
1241
  signature_quorum_satisfied: true,
1233
1242
  signed_payload_binds_record_aep: true,
1234
- signers_pinned_to_published_keys: trust.signer_trust === "TRUSTED" || trust.signer_trust === "SANDBOX_NON_TRUST_BEARING",
1243
+ signers_pinned_to_published_keys: trust.signer_trust === "TRUSTED" || trust.signer_trust === "SANDBOX_NON_TRUST_BEARING" || trust.signer_trust === "INSUFFICIENT_TRUSTED_SIGNERS",
1244
+ min_trusted_signers_met: trust.signer_trust === "TRUSTED",
1235
1245
  canonical_json_authoritative: true,
1236
1246
  pdf_receipt_non_authoritative: true,
1237
1247
  },
@@ -1415,9 +1425,20 @@ function parsePublishedKeySet(source, origin) {
1415
1425
  }
1416
1426
  const set = parseSingleJSON(source, "trusted key set");
1417
1427
  const invalid = [];
1418
- if (!isRecord(set) || set.schema_version !== PUBLISHED_KEY_SET_SCHEMA_VERSION) invalid.push("schema_version");
1428
+ if (!isRecord(set) || ![PUBLISHED_KEY_SET_SCHEMA_VERSION, PUBLISHED_KEY_SET_SCHEMA_VERSION_V1].includes(set.schema_version)) invalid.push("schema_version");
1419
1429
  if (isRecord(set) && !stableNonEmpty(set.key_set_id)) invalid.push("key_set_id");
1420
1430
  if (!isRecord(set) || !Array.isArray(set.keys) || set.keys.length === 0) invalid.push("keys");
1431
+ if (isRecord(set) && Array.isArray(set.keys)) {
1432
+ const keyIds = new Set(set.keys.filter(isRecord).map((key) => key.key_id));
1433
+ if (set.schema_version === PUBLISHED_KEY_SET_SCHEMA_VERSION) {
1434
+ // The policy must be satisfiable by this set's own keys.
1435
+ if (!Number.isInteger(set.min_trusted_signers) || set.min_trusted_signers < 1 || set.min_trusted_signers > keyIds.size) invalid.push("min_trusted_signers");
1436
+ } else if (set.schema_version === PUBLISHED_KEY_SET_SCHEMA_VERSION_V1) {
1437
+ if (Object.hasOwn(set, "min_trusted_signers")) invalid.push("min_trusted_signers");
1438
+ // A 1.0 set cannot state a minimum trusted-signer count, so it may not anchor trust.
1439
+ if (set.keys.some((key) => isRecord(key) && key.trust_bearing === true)) invalid.push("schema_version");
1440
+ }
1441
+ }
1421
1442
  if (isRecord(set) && Array.isArray(set.keys)) {
1422
1443
  for (const [index, key] of set.keys.entries()) {
1423
1444
  if (!isRecord(key)
@@ -1432,13 +1453,17 @@ function parsePublishedKeySet(source, origin) {
1432
1453
  }
1433
1454
  }
1434
1455
  if (invalid.length > 0) {
1435
- fail(`trusted key set is invalid (${origin}): ${sortedUnique(invalid).join(",")}`);
1456
+ const hint = invalid.includes("schema_version") || invalid.includes("min_trusted_signers")
1457
+ ? ` (trust-bearing keys need ${PUBLISHED_KEY_SET_SCHEMA_VERSION} with an integer min_trusted_signers between 1 and the number of distinct key_ids)`
1458
+ : "";
1459
+ fail(`trusted key set is invalid (${origin}): ${sortedUnique(invalid).join(",")}${hint}`);
1436
1460
  }
1437
1461
  const environments = [...new Set(set.keys.map((key) => key.environment).filter(stableNonEmpty))];
1438
1462
  return {
1439
1463
  key_set_id: set.key_set_id,
1440
1464
  environment: environments.length === 1 ? environments[0] : "mixed",
1441
1465
  source: origin,
1466
+ min_trusted_signers: set.schema_version === PUBLISHED_KEY_SET_SCHEMA_VERSION ? set.min_trusted_signers : 1,
1442
1467
  keys: set.keys,
1443
1468
  };
1444
1469
  }
@@ -1461,13 +1486,26 @@ function classifySignerTrust(signers, keySets) {
1461
1486
  ?? null;
1462
1487
  return { key_id: signer.key_id, key_version: signer.key_version, public_key_hash: signer.public_key_hash, anchor };
1463
1488
  });
1489
+ // The strictest policy wins: every key set that vouches for any signer as
1490
+ // trust-bearing contributes its min_trusted_signers, and the maximum applies.
1491
+ // Supplying an extra, laxer set cannot lower the bundled production policy.
1492
+ let minTrustedSigners = 1;
1493
+ for (const set of keySets) {
1494
+ const vouches = set.keys.some((key) => key.trust_bearing === true && key.status !== "REVOKED"
1495
+ && signers.some((signer) => key.key_id === signer.key_id && key.key_version === signer.key_version && key.public_key_material === signer.public_key_material));
1496
+ if (vouches) minTrustedSigners = Math.max(minTrustedSigners, set.min_trusted_signers);
1497
+ }
1498
+ // Versions of one key are one signer.
1499
+ const distinctTrustedSigners = new Set(resolved.filter((signer) => signer.anchor?.trust_bearing === true && signer.anchor.status !== "REVOKED").map((signer) => signer.key_id)).size;
1464
1500
  let signerTrust;
1465
1501
  if (resolved.some((signer) => signer.anchor?.status === "REVOKED")) signerTrust = "REVOKED_SIGNER";
1466
1502
  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";
1503
+ else if (resolved.every((signer) => signer.anchor.trust_bearing === true)) {
1504
+ signerTrust = distinctTrustedSigners >= minTrustedSigners ? "TRUSTED" : "INSUFFICIENT_TRUSTED_SIGNERS";
1505
+ }
1468
1506
  else if (resolved.every((signer) => signer.anchor.trust_bearing === false)) signerTrust = "SANDBOX_NON_TRUST_BEARING";
1469
1507
  else signerTrust = "MIXED_TRUST";
1470
- return { signer_trust: signerTrust, signers: resolved };
1508
+ return { signer_trust: signerTrust, signers: resolved, min_trusted_signers: minTrustedSigners, distinct_trusted_signers: distinctTrustedSigners };
1471
1509
  }
1472
1510
 
1473
1511
  function signerTrustMessage(report) {
@@ -1477,6 +1515,10 @@ function signerTrustMessage(report) {
1477
1515
  if (report.signer_trust === "REVOKED_SIGNER") {
1478
1516
  return "intentrax: a signing key is REVOKED in the trusted key set; this proof must not be relied on.";
1479
1517
  }
1518
+ if (report.signer_trust === "INSUFFICIENT_TRUSTED_SIGNERS") {
1519
+ const verification = report.signature_verification;
1520
+ return `intentrax: every signer is a published trust-bearing key, but only ${verification.distinct_trusted_signers} distinct key(s) signed and the published key set requires ${verification.min_trusted_signers}. Signatures may have been stripped from this proof; it must not be relied on.`;
1521
+ }
1480
1522
  if (report.signer_trust === "MIXED_TRUST") {
1481
1523
  return "intentrax: the proof mixes trust-bearing and sandbox signers; it is not a production-trusted proof.";
1482
1524
  }
@@ -2687,17 +2729,24 @@ Proof export verification:
2687
2729
  not required. The JSON export is authoritative; PDF receipts are companions.
2688
2730
 
2689
2731
  Result (status / exit code):
2690
- PASS 0 every signer is a published, trust-bearing key
2732
+ PASS 0 every signer is a published, trust-bearing key,
2733
+ and at least the key set's min_trusted_signers
2734
+ distinct keys signed
2691
2735
  SANDBOX_NON_TRUST_BEARING 0 every signer is a published sandbox key: the
2692
2736
  mechanics check out, but it is not production
2693
2737
  assurance
2694
2738
  UNPINNED_SIGNER 3 signatures are valid but a signer is not in
2695
2739
  any trusted key set (who signed is unproven)
2740
+ INSUFFICIENT_TRUSTED_SIGNERS 3 every signer is trusted, but fewer distinct
2741
+ keys signed than the published key set
2742
+ requires (signatures may have been stripped)
2696
2743
  REVOKED_SIGNER / MIXED_TRUST 3
2697
2744
  any integrity or signature failure exits 2 (failed closed)
2698
2745
 
2699
- The SDK ships the sandbox key set (trust/sandbox-key-set.json). Supply
2700
- production keys with --trusted-keys <file> (repeatable).
2746
+ The SDK ships the production key set (trust/production-key-set.json,
2747
+ min_trusted_signers 2) and the sandbox key set (trust/sandbox-key-set.json).
2748
+ Add more sets, for example revocations, with --trusted-keys <file>
2749
+ (repeatable).
2701
2750
 
2702
2751
  PDF receipt verification:
2703
2752
  verify-pdf-receipt reads downloaded PDF receipt bytes, checks the PDF header,
package/index.d.ts CHANGED
@@ -6,6 +6,7 @@ export declare const AGENT_GATEWAY_ADMISSION_REQUEST_HASH_DOMAIN: "INTENTRAX_AGE
6
6
  export declare const AGENT_ADMISSION_SCHEMA_VERSION: "intentrax.runtime.agent_admission_request/1.0";
7
7
  export declare const AGENT_ADMISSION_ENDPOINT: "/v1/agent/admissions";
8
8
  export declare const INTENT_EXECUTE_REQUEST_SCHEMA_VERSION: "intentrax.runtime.intent_execute.request/1.0";
9
+ export declare const INTENT_EXECUTE_REQUEST_SCHEMA_VERSION_V11: "intentrax.runtime.intent_execute.request/1.1";
9
10
  export declare const INTENT_EXECUTE_ENDPOINT: "/v1/intents/execute";
10
11
  export declare const INTENT_EXECUTE_MAX_REQUEST_BYTES: 4096;
11
12
  export declare const RECEIPT_VERIFICATION_REQUEST_SCHEMA_VERSION: "intentrax.runtime.proof_verification.request/1.0";
@@ -45,14 +46,28 @@ export type AgentGatewayAdmissionRequest = {
45
46
  idempotency_key_hash: string;
46
47
  };
47
48
 
48
- export type IntentExecuteRequest = {
49
- schema_version: "intentrax.runtime.intent_execute.request/1.0";
49
+ type IntentExecuteRequestFields = {
50
50
  intent_id: string;
51
51
  tenant_id: string;
52
52
  action: string;
53
53
  idempotency_key: string;
54
54
  proof_chain_fixture_ref: string;
55
55
  };
56
+ export type IntentExecuteRequestV10 = IntentExecuteRequestFields & {
57
+ schema_version: "intentrax.runtime.intent_execute.request/1.0";
58
+ };
59
+ // /1.1: the /1.0 fields plus an optional producer-declared output_binding that
60
+ // the engine seals into the signed proof. content_hash may be the bare 64
61
+ // lowercase hex buildOutputBinding emits or the same with a "sha256:" prefix.
62
+ export type IntentExecuteRequestV11 = IntentExecuteRequestFields & {
63
+ schema_version: "intentrax.runtime.intent_execute.request/1.1";
64
+ output_binding?: {
65
+ content_hash: string;
66
+ hash_algorithm: "SHA-256";
67
+ normalization: "intentrax-content/1.0";
68
+ };
69
+ };
70
+ export type IntentExecuteRequest = IntentExecuteRequestV10 | IntentExecuteRequestV11;
56
71
 
57
72
  export type ReceiptVerificationRequest = {
58
73
  schema_version: "intentrax.runtime.proof_verification.request/1.0";
@@ -208,6 +223,10 @@ export declare function buildVerifierHandoffEnvelope(request: VerifierHandoffReq
208
223
  error: SDKError;
209
224
  };
210
225
  export declare function validateIntentExecuteRequest(request: unknown): string[];
226
+ export declare function bindIntentExecuteOutput(
227
+ request: IntentExecuteRequestFields & { schema_version?: string },
228
+ renderedOutput: string | readonly string[],
229
+ ): IntentExecuteRequestV11 & { output_binding: OutputBinding };
211
230
  export declare function buildIntentExecuteEnvelope(request: IntentExecuteRequest): {
212
231
  status: "PASS";
213
232
  output: {
package/index.js CHANGED
@@ -12,6 +12,12 @@ export const AGENT_ADMISSION_ENDPOINT = "/v1/agent/admissions";
12
12
  // (HTTP 423 until LiveExecutionEnabled, HTTP 403 until the tenant is
13
13
  // allowlisted). See engine/internal/runtime/intentexecute/intentexecute.go.
14
14
  export const INTENT_EXECUTE_REQUEST_SCHEMA_VERSION = "intentrax.runtime.intent_execute.request/1.0";
15
+ // /1.1 adds exactly one OPTIONAL field to /1.0: output_binding, the
16
+ // producer-declared `intentrax-content/1.0` hash of the rendered output. The
17
+ // engine seals it into the signed proof (aep.output_binding,
18
+ // binding_source PRODUCER_DECLARED_AT_ISSUANCE); see
19
+ // engine/internal/runtime/intentexecute/output_binding.go.
20
+ export const INTENT_EXECUTE_REQUEST_SCHEMA_VERSION_V11 = "intentrax.runtime.intent_execute.request/1.1";
15
21
  export const INTENT_EXECUTE_ENDPOINT = "/v1/intents/execute";
16
22
  // Mirrors intentexecute.MaxRequestBytes: the engine rejects a canonical body
17
23
  // larger than this with HTTP 400.
@@ -65,6 +71,10 @@ const INTENT_EXECUTE_REQUIRED_FIELDS = [
65
71
  "proof_chain_fixture_ref",
66
72
  ];
67
73
 
74
+ // The engine decodes a /1.1 output_binding with DisallowUnknownFields into
75
+ // exactly these three string fields (intentexecute.OutputBinding).
76
+ const INTENT_EXECUTE_OUTPUT_BINDING_FIELDS = ["content_hash", "hash_algorithm", "normalization"];
77
+
68
78
  const RECEIPT_VERIFICATION_REQUIRED_FIELDS = [
69
79
  "schema_version",
70
80
  "receipt_id",
@@ -562,25 +572,31 @@ export function buildAgentGatewayAdmissionEnvelope(request) {
562
572
  }
563
573
 
564
574
  // validateIntentExecuteRequest mirrors the engine's intentexecute.validateRequest
565
- // (and its DecodeRequest strictness): exactly the six fields, an UPPER_SNAKE
566
- // action, and a canonical body no larger than the engine's limit. It computes
567
- // NO proof/hash truth — receipt_id, request_hash, registry_proof_id, and
568
- // response_hash are the engine's to produce.
575
+ // (and its DecodeRequest strictness): exactly the six fields (plus an optional
576
+ // output_binding under /1.1 only), an UPPER_SNAKE action, and a canonical body
577
+ // no larger than the engine's limit. It computes NO proof/hash truth —
578
+ // receipt_id, request_hash, registry_proof_id, and response_hash are the
579
+ // engine's to produce.
569
580
  export function validateIntentExecuteRequest(request) {
570
581
  if (request === null || typeof request !== "object" || Array.isArray(request)) {
571
582
  return ["intent_execute_request"];
572
583
  }
573
584
  const invalid = [];
585
+ const isV11 = request.schema_version === INTENT_EXECUTE_REQUEST_SCHEMA_VERSION_V11;
574
586
  // Unknown fields are a 400 at the engine (DisallowUnknownFields); reject them
575
- // here too so the SDK never emits a body the engine would refuse.
587
+ // here too so the SDK never emits a body the engine would refuse. A /1.0 body
588
+ // carrying output_binding is such an unknown field.
576
589
  for (const key of Object.keys(request)) {
577
- if (!INTENT_EXECUTE_REQUIRED_FIELDS.includes(key)) {
590
+ if (!INTENT_EXECUTE_REQUIRED_FIELDS.includes(key) && !(isV11 && key === "output_binding")) {
578
591
  invalid.push("body");
579
592
  }
580
593
  }
581
- if (request.schema_version !== INTENT_EXECUTE_REQUEST_SCHEMA_VERSION) {
594
+ if (request.schema_version !== INTENT_EXECUTE_REQUEST_SCHEMA_VERSION && !isV11) {
582
595
  invalid.push("schema_version");
583
596
  }
597
+ if (isV11 && Object.prototype.hasOwnProperty.call(request, "output_binding")) {
598
+ invalid.push(...validateIntentExecuteOutputBinding(request.output_binding));
599
+ }
584
600
  if (!isNonEmptyStable(request.intent_id)) {
585
601
  invalid.push("intent_id");
586
602
  }
@@ -598,7 +614,10 @@ export function validateIntentExecuteRequest(request) {
598
614
  if (!isNonEmptyStable(request.proof_chain_fixture_ref)) {
599
615
  invalid.push("proof_chain_fixture_ref");
600
616
  }
601
- if (invalid.every((field) => field !== "body")) {
617
+ // Size-check only an otherwise-valid body: an invalid field (e.g. an explicit
618
+ // `undefined`) may not be canonicalizable, and must surface as a structured
619
+ // FAIL naming that field rather than a canonical_json throw.
620
+ if (invalid.length === 0) {
602
621
  const canonicalBytes = Buffer.byteLength(canonicalJson(request), "utf8");
603
622
  if (canonicalBytes > INTENT_EXECUTE_MAX_REQUEST_BYTES) {
604
623
  invalid.push("body");
@@ -607,6 +626,58 @@ export function validateIntentExecuteRequest(request) {
607
626
  return [...new Set(invalid)].sort();
608
627
  }
609
628
 
629
+ // validateIntentExecuteOutputBinding mirrors the engine's decodeOutputBinding +
630
+ // validateOutputBinding: a non-null object of exactly the three string fields
631
+ // (anything else is a decode error, reported as "output_binding"), then a
632
+ // sealable content_hash, the SHA-256 algorithm and the intentrax-content/1.0
633
+ // normalization.
634
+ function validateIntentExecuteOutputBinding(binding) {
635
+ if (binding === null || typeof binding !== "object" || Array.isArray(binding)) {
636
+ return ["output_binding"];
637
+ }
638
+ for (const key of Object.keys(binding)) {
639
+ if (!INTENT_EXECUTE_OUTPUT_BINDING_FIELDS.includes(key) || typeof binding[key] !== "string") {
640
+ return ["output_binding"];
641
+ }
642
+ }
643
+ const invalid = [];
644
+ if (!isSealableOutputContentHash(binding.content_hash)) {
645
+ invalid.push("output_binding.content_hash");
646
+ }
647
+ if (binding.hash_algorithm !== CANONICAL_OUTPUT_HASH_ALGORITHM) {
648
+ invalid.push("output_binding.hash_algorithm");
649
+ }
650
+ if (binding.normalization !== CANONICAL_OUTPUT_NORMALIZATION) {
651
+ invalid.push("output_binding.normalization");
652
+ }
653
+ return invalid;
654
+ }
655
+
656
+ // isSealableOutputContentHash mirrors the engine's sealedContentHash: the bare
657
+ // 64 lowercase hex the SDK emits, or the same with a "sha256:" prefix. Uppercase,
658
+ // other prefixes, other lengths, and a degenerate digest (one repeated digit)
659
+ // are refused.
660
+ function isSealableOutputContentHash(value) {
661
+ if (typeof value !== "string") return false;
662
+ const digest = value.startsWith("sha256:") ? value.slice("sha256:".length) : value;
663
+ if (!SHA256_RE.test(digest)) return false;
664
+ return digest.split("").some((char) => char !== digest[0]);
665
+ }
666
+
667
+ // bindIntentExecuteOutput returns a NEW /1.1 execute request: the caller's
668
+ // request with schema_version /1.1 and output_binding = buildOutputBinding of
669
+ // the output the producer is about to render. The input is not mutated. Pass
670
+ // the result to buildIntentExecuteEnvelope / executeIntentHttp, which validate
671
+ // it. Bind exactly what the page will show inside its data-intentrax-output
672
+ // region(s): the browser extension recomputes this hash over that visible text.
673
+ export function bindIntentExecuteOutput(request, renderedOutput) {
674
+ return {
675
+ ...request,
676
+ schema_version: INTENT_EXECUTE_REQUEST_SCHEMA_VERSION_V11,
677
+ output_binding: buildOutputBinding(renderedOutput),
678
+ };
679
+ }
680
+
610
681
  // buildIntentExecuteEnvelope is a THIN envelope builder: it validates and
611
682
  // passes the caller-supplied body through verbatim. It performs no hashing and
612
683
  // asserts no proof truth.
package/index.ts CHANGED
@@ -12,6 +12,12 @@ export const AGENT_ADMISSION_ENDPOINT = "/v1/agent/admissions";
12
12
  // (HTTP 423 until LiveExecutionEnabled, HTTP 403 until the tenant is
13
13
  // allowlisted). See engine/internal/runtime/intentexecute/intentexecute.go.
14
14
  export const INTENT_EXECUTE_REQUEST_SCHEMA_VERSION = "intentrax.runtime.intent_execute.request/1.0";
15
+ // /1.1 adds exactly one OPTIONAL field to /1.0: output_binding, the
16
+ // producer-declared `intentrax-content/1.0` hash of the rendered output. The
17
+ // engine seals it into the signed proof (aep.output_binding,
18
+ // binding_source PRODUCER_DECLARED_AT_ISSUANCE); see
19
+ // engine/internal/runtime/intentexecute/output_binding.go.
20
+ export const INTENT_EXECUTE_REQUEST_SCHEMA_VERSION_V11 = "intentrax.runtime.intent_execute.request/1.1";
15
21
  export const INTENT_EXECUTE_ENDPOINT = "/v1/intents/execute";
16
22
  // Mirrors intentexecute.MaxRequestBytes: the engine rejects a canonical body
17
23
  // larger than this with HTTP 400.
@@ -65,6 +71,10 @@ const INTENT_EXECUTE_REQUIRED_FIELDS = [
65
71
  "proof_chain_fixture_ref",
66
72
  ];
67
73
 
74
+ // The engine decodes a /1.1 output_binding with DisallowUnknownFields into
75
+ // exactly these three string fields (intentexecute.OutputBinding).
76
+ const INTENT_EXECUTE_OUTPUT_BINDING_FIELDS = ["content_hash", "hash_algorithm", "normalization"];
77
+
68
78
  const RECEIPT_VERIFICATION_REQUIRED_FIELDS = [
69
79
  "schema_version",
70
80
  "receipt_id",
@@ -562,25 +572,31 @@ export function buildAgentGatewayAdmissionEnvelope(request) {
562
572
  }
563
573
 
564
574
  // validateIntentExecuteRequest mirrors the engine's intentexecute.validateRequest
565
- // (and its DecodeRequest strictness): exactly the six fields, an UPPER_SNAKE
566
- // action, and a canonical body no larger than the engine's limit. It computes
567
- // NO proof/hash truth — receipt_id, request_hash, registry_proof_id, and
568
- // response_hash are the engine's to produce.
575
+ // (and its DecodeRequest strictness): exactly the six fields (plus an optional
576
+ // output_binding under /1.1 only), an UPPER_SNAKE action, and a canonical body
577
+ // no larger than the engine's limit. It computes NO proof/hash truth —
578
+ // receipt_id, request_hash, registry_proof_id, and response_hash are the
579
+ // engine's to produce.
569
580
  export function validateIntentExecuteRequest(request) {
570
581
  if (request === null || typeof request !== "object" || Array.isArray(request)) {
571
582
  return ["intent_execute_request"];
572
583
  }
573
584
  const invalid = [];
585
+ const isV11 = request.schema_version === INTENT_EXECUTE_REQUEST_SCHEMA_VERSION_V11;
574
586
  // Unknown fields are a 400 at the engine (DisallowUnknownFields); reject them
575
- // here too so the SDK never emits a body the engine would refuse.
587
+ // here too so the SDK never emits a body the engine would refuse. A /1.0 body
588
+ // carrying output_binding is such an unknown field.
576
589
  for (const key of Object.keys(request)) {
577
- if (!INTENT_EXECUTE_REQUIRED_FIELDS.includes(key)) {
590
+ if (!INTENT_EXECUTE_REQUIRED_FIELDS.includes(key) && !(isV11 && key === "output_binding")) {
578
591
  invalid.push("body");
579
592
  }
580
593
  }
581
- if (request.schema_version !== INTENT_EXECUTE_REQUEST_SCHEMA_VERSION) {
594
+ if (request.schema_version !== INTENT_EXECUTE_REQUEST_SCHEMA_VERSION && !isV11) {
582
595
  invalid.push("schema_version");
583
596
  }
597
+ if (isV11 && Object.prototype.hasOwnProperty.call(request, "output_binding")) {
598
+ invalid.push(...validateIntentExecuteOutputBinding(request.output_binding));
599
+ }
584
600
  if (!isNonEmptyStable(request.intent_id)) {
585
601
  invalid.push("intent_id");
586
602
  }
@@ -598,7 +614,10 @@ export function validateIntentExecuteRequest(request) {
598
614
  if (!isNonEmptyStable(request.proof_chain_fixture_ref)) {
599
615
  invalid.push("proof_chain_fixture_ref");
600
616
  }
601
- if (invalid.every((field) => field !== "body")) {
617
+ // Size-check only an otherwise-valid body: an invalid field (e.g. an explicit
618
+ // `undefined`) may not be canonicalizable, and must surface as a structured
619
+ // FAIL naming that field rather than a canonical_json throw.
620
+ if (invalid.length === 0) {
602
621
  const canonicalBytes = Buffer.byteLength(canonicalJson(request), "utf8");
603
622
  if (canonicalBytes > INTENT_EXECUTE_MAX_REQUEST_BYTES) {
604
623
  invalid.push("body");
@@ -607,6 +626,58 @@ export function validateIntentExecuteRequest(request) {
607
626
  return [...new Set(invalid)].sort();
608
627
  }
609
628
 
629
+ // validateIntentExecuteOutputBinding mirrors the engine's decodeOutputBinding +
630
+ // validateOutputBinding: a non-null object of exactly the three string fields
631
+ // (anything else is a decode error, reported as "output_binding"), then a
632
+ // sealable content_hash, the SHA-256 algorithm and the intentrax-content/1.0
633
+ // normalization.
634
+ function validateIntentExecuteOutputBinding(binding) {
635
+ if (binding === null || typeof binding !== "object" || Array.isArray(binding)) {
636
+ return ["output_binding"];
637
+ }
638
+ for (const key of Object.keys(binding)) {
639
+ if (!INTENT_EXECUTE_OUTPUT_BINDING_FIELDS.includes(key) || typeof binding[key] !== "string") {
640
+ return ["output_binding"];
641
+ }
642
+ }
643
+ const invalid = [];
644
+ if (!isSealableOutputContentHash(binding.content_hash)) {
645
+ invalid.push("output_binding.content_hash");
646
+ }
647
+ if (binding.hash_algorithm !== CANONICAL_OUTPUT_HASH_ALGORITHM) {
648
+ invalid.push("output_binding.hash_algorithm");
649
+ }
650
+ if (binding.normalization !== CANONICAL_OUTPUT_NORMALIZATION) {
651
+ invalid.push("output_binding.normalization");
652
+ }
653
+ return invalid;
654
+ }
655
+
656
+ // isSealableOutputContentHash mirrors the engine's sealedContentHash: the bare
657
+ // 64 lowercase hex the SDK emits, or the same with a "sha256:" prefix. Uppercase,
658
+ // other prefixes, other lengths, and a degenerate digest (one repeated digit)
659
+ // are refused.
660
+ function isSealableOutputContentHash(value) {
661
+ if (typeof value !== "string") return false;
662
+ const digest = value.startsWith("sha256:") ? value.slice("sha256:".length) : value;
663
+ if (!SHA256_RE.test(digest)) return false;
664
+ return digest.split("").some((char) => char !== digest[0]);
665
+ }
666
+
667
+ // bindIntentExecuteOutput returns a NEW /1.1 execute request: the caller's
668
+ // request with schema_version /1.1 and output_binding = buildOutputBinding of
669
+ // the output the producer is about to render. The input is not mutated. Pass
670
+ // the result to buildIntentExecuteEnvelope / executeIntentHttp, which validate
671
+ // it. Bind exactly what the page will show inside its data-intentrax-output
672
+ // region(s): the browser extension recomputes this hash over that visible text.
673
+ export function bindIntentExecuteOutput(request, renderedOutput) {
674
+ return {
675
+ ...request,
676
+ schema_version: INTENT_EXECUTE_REQUEST_SCHEMA_VERSION_V11,
677
+ output_binding: buildOutputBinding(renderedOutput),
678
+ };
679
+ }
680
+
610
681
  // buildIntentExecuteEnvelope is a THIN envelope builder: it validates and
611
682
  // passes the caller-supplied body through verbatim. It performs no hashing and
612
683
  // asserts no proof truth.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@intentrax/sdk",
3
- "version": "1.1.1",
3
+ "version": "1.3.0",
4
4
  "description": "Intentrax deterministic public SDK for proof verification and API-wrapper execution.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -21,6 +21,7 @@
21
21
  "trust_bearing": true
22
22
  }
23
23
  ],
24
+ "min_trusted_signers": 2,
24
25
  "published_at": "2026-11-12T13:55:49Z",
25
- "schema_version": "intentrax.trust.published_key_set/1.0"
26
+ "schema_version": "intentrax.trust.published_key_set/1.1"
26
27
  }