@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/index.js CHANGED
@@ -160,6 +160,17 @@ export function createIdempotencyKey(request) {
160
160
  return sha256Hex(IDEMPOTENCY_KEY_DOMAIN + canonicalJson(idempotencyInput(request)));
161
161
  }
162
162
 
163
+ // admissionIdempotencyKeyHash derives the agent-admission request's
164
+ // idempotency_key_hash from the SAME logical idempotency key the client later
165
+ // sends to execute. Set execute Request.idempotency_key = createIdempotencyKey(request)
166
+ // (raw) and admission Request.idempotency_key_hash = admissionIdempotencyKeyHash(request)
167
+ // (the SHA-256 of that raw key). The two are then provably the same logical key —
168
+ // one raw, one hashed — so a durable admission receipt can be correlated against
169
+ // the execution that carried the same key.
170
+ export function admissionIdempotencyKeyHash(request) {
171
+ return sha256Hex(createIdempotencyKey(request));
172
+ }
173
+
163
174
  export function buildVerificationEnvelope(request) {
164
175
  const invalidFields = validateVerificationRequest(request);
165
176
  if (invalidFields.length > 0) {
@@ -624,3 +635,296 @@ export function buildIntentExecuteEnvelope(request) {
624
635
  },
625
636
  };
626
637
  }
638
+
639
+ // ===========================================================================
640
+ // Verification Mark response envelope — the SDK/MCP machine substrate.
641
+ //
642
+ // A backend-produced, PUBLIC-SAFE projection of a proof's verification status:
643
+ // { display_state, proof_id, verify_url, assurance_level, signature }.
644
+ // The SDK is a strict READER. It validates the envelope's SHAPE and normalizes
645
+ // it into a verdict a consumer can branch on. It NEVER re-derives crypto, never
646
+ // recomputes validity, never regenerates a proof: `verified` is EXACTLY the
647
+ // backend's display_state === "verified", nothing more. `signature` is a STATUS
648
+ // projection (e.g. "pass"/"fail"/"Not Available"), never a raw signature; a
649
+ // value that looks like raw signing material is refused so it can never leak.
650
+ // ===========================================================================
651
+
652
+ export const VERIFICATION_MARK_ENVELOPE_KEY = "intentrax_verification";
653
+ export const VERIFICATION_MARK_ENVELOPE_SCHEMA_VERSION = "intentrax.public_sdk.verification_mark_envelope/1.0";
654
+ export const VERIFICATION_MARK_VERIFIED_STATE = "verified";
655
+ export const VERIFICATION_MARK_NOT_AVAILABLE = "Not Available";
656
+
657
+ // display_state -> severity. Mirrors the backend §2 MARK_STATE_TABLE. Fail
658
+ // NEUTRAL, not fail-red: only a concrete failure/revocation is "negative".
659
+ export const VERIFICATION_MARK_STATE_SEVERITY = Object.freeze({
660
+ verified: "green",
661
+ proof_available: "neutral",
662
+ checking: "neutral",
663
+ not_found: "neutral",
664
+ unavailable: "neutral",
665
+ share_expired: "neutral",
666
+ failed: "negative",
667
+ revoked: "negative",
668
+ });
669
+
670
+ const VERIFICATION_MARK_DISPLAY_STATES = new Set(Object.keys(VERIFICATION_MARK_STATE_SEVERITY));
671
+ const VERIFICATION_MARK_ASSURANCE_LEVELS = new Set([1, 2, 3, 4]);
672
+ const VERIFICATION_MARK_SIGNATURE_MAX_LEN = 64;
673
+ const VERIFICATION_MARK_PROOF_ID_MAX_LEN = 128;
674
+ const VERIFICATION_MARK_URL_MAX_LEN = 2048;
675
+ const CONTROL_CHAR_RE = /[\u0000-\u001F\u007F]/;
676
+ // A public-safe field must never carry raw signing material or a secret. This
677
+ // guards the SDK from ever surfacing a raw signature/key/token even if a
678
+ // malformed upstream stuffs one into a nominally public field.
679
+ const VERIFICATION_MARK_SECRET_VALUE_RE = /-----BEGIN|BEGIN (?:RSA|EC|DSA|PGP|OPENSSH)|sk-(?:live|test)|bearer\s|private[_ -]?key|signing[_ -]?material|api[_-]?key|access[_-]?token|refresh[_-]?token/i;
680
+
681
+ function isVerificationMarkRecord(value) {
682
+ return value !== null && typeof value === "object" && !Array.isArray(value);
683
+ }
684
+
685
+ export function isVerificationMarkDisplayState(value) {
686
+ return typeof value === "string" && VERIFICATION_MARK_DISPLAY_STATES.has(value);
687
+ }
688
+
689
+ export function verificationMarkSeverity(displayState) {
690
+ return isVerificationMarkDisplayState(displayState) ? VERIFICATION_MARK_STATE_SEVERITY[displayState] : null;
691
+ }
692
+
693
+ function isPublicSafeString(value) {
694
+ return typeof value === "string" && !CONTROL_CHAR_RE.test(value) && !VERIFICATION_MARK_SECRET_VALUE_RE.test(value);
695
+ }
696
+
697
+ function normalizePlaceholderText(value, maxLen) {
698
+ if (typeof value !== "string") return null;
699
+ const trimmed = value.trim();
700
+ if (trimmed === "" || trimmed === VERIFICATION_MARK_NOT_AVAILABLE) return null;
701
+ if (trimmed.length > maxLen || !isPublicSafeString(trimmed)) return null;
702
+ return trimmed;
703
+ }
704
+
705
+ // normalizeVerificationMarkSignature — the signature STATUS projection. Returns
706
+ // the public-safe status token, or null when it is absent, a placeholder, or
707
+ // looks like raw signing material (which is never surfaced). It is NEVER
708
+ // re-derived or cryptographically verified — shape only.
709
+ export function normalizeVerificationMarkSignature(value) {
710
+ return normalizePlaceholderText(value, VERIFICATION_MARK_SIGNATURE_MAX_LEN);
711
+ }
712
+
713
+ function normalizeVerificationMarkAssuranceLevel(value) {
714
+ return typeof value === "number" && VERIFICATION_MARK_ASSURANCE_LEVELS.has(value) ? value : null;
715
+ }
716
+
717
+ function normalizeVerificationMarkVerifyUrl(value) {
718
+ const text = normalizePlaceholderText(value, VERIFICATION_MARK_URL_MAX_LEN);
719
+ if (text === null) return null;
720
+ // Root-relative verifier paths are public-safe as-is.
721
+ if (text.startsWith("/") && !text.startsWith("//")) return text;
722
+ let url;
723
+ try {
724
+ url = new URL(text);
725
+ } catch {
726
+ return null;
727
+ }
728
+ if (url.protocol !== "https:" && url.protocol !== "http:") return null;
729
+ if (url.username !== "" || url.password !== "") return null;
730
+ return url.toString();
731
+ }
732
+
733
+ // validateVerificationMarkEnvelope — SHAPE-ONLY validation of the backend's
734
+ // public-safe verification envelope. Returns the sorted list of invalid field
735
+ // names ([] when the shape is well-formed). It performs NO crypto: it never
736
+ // verifies the signature, recomputes validity, or regenerates a proof.
737
+ export function validateVerificationMarkEnvelope(envelope) {
738
+ if (!isVerificationMarkRecord(envelope)) {
739
+ return ["verification_mark_envelope"];
740
+ }
741
+ const invalid = [];
742
+ if (!isVerificationMarkDisplayState(envelope.display_state)) invalid.push("display_state");
743
+ if (typeof envelope.proof_id !== "string") invalid.push("proof_id");
744
+ if (typeof envelope.verify_url !== "string") invalid.push("verify_url");
745
+ if (!(envelope.assurance_level === null || normalizeVerificationMarkAssuranceLevel(envelope.assurance_level) !== null)) {
746
+ invalid.push("assurance_level");
747
+ }
748
+ if (typeof envelope.signature !== "string") invalid.push("signature");
749
+ // A public-safe envelope must never carry raw secret material in any string
750
+ // field — reject the whole envelope if it does rather than pass it through.
751
+ for (const field of ["proof_id", "verify_url", "signature"]) {
752
+ const value = envelope[field];
753
+ if (typeof value === "string" && !isPublicSafeString(value)) {
754
+ invalid.push(field);
755
+ }
756
+ }
757
+ return [...new Set(invalid)].sort();
758
+ }
759
+
760
+ // normalizeVerificationMarkEnvelope — validate + project the envelope into a
761
+ // canonical, public-safe verdict. Returns null when the shape is invalid.
762
+ // Placeholder ("Not Available") and secret-looking values collapse to null per
763
+ // field. `verified` is EXACTLY the backend display_state === "verified" — the
764
+ // SDK asserts no independent verdict and recomputes no crypto.
765
+ export function normalizeVerificationMarkEnvelope(envelope) {
766
+ if (validateVerificationMarkEnvelope(envelope).length > 0) return null;
767
+ const displayState = envelope.display_state;
768
+ return {
769
+ schema_version: VERIFICATION_MARK_ENVELOPE_SCHEMA_VERSION,
770
+ display_state: displayState,
771
+ severity: VERIFICATION_MARK_STATE_SEVERITY[displayState],
772
+ verified: displayState === VERIFICATION_MARK_VERIFIED_STATE,
773
+ proof_id: normalizePlaceholderText(envelope.proof_id, VERIFICATION_MARK_PROOF_ID_MAX_LEN),
774
+ verify_url: normalizeVerificationMarkVerifyUrl(envelope.verify_url),
775
+ assurance_level: normalizeVerificationMarkAssuranceLevel(envelope.assurance_level),
776
+ signature: normalizeVerificationMarkSignature(envelope.signature),
777
+ };
778
+ }
779
+
780
+ // extractVerificationMarkEnvelope — locate the verification envelope on an
781
+ // arbitrary response object. Handles the bare envelope, the `intentrax_verification`
782
+ // key at the top level, and the same key nested under an MCP tool result's
783
+ // `structuredContent` / a `result` / `output` wrapper. Returns the raw envelope
784
+ // candidate (unvalidated) or null.
785
+ export function extractVerificationMarkEnvelope(response) {
786
+ if (!isVerificationMarkRecord(response)) return null;
787
+ if (isVerificationMarkDisplayState(response.display_state) && "signature" in response) {
788
+ return response;
789
+ }
790
+ const wrappers = [
791
+ response,
792
+ isVerificationMarkRecord(response.structuredContent) ? response.structuredContent : undefined,
793
+ isVerificationMarkRecord(response.result) ? response.result : undefined,
794
+ isVerificationMarkRecord(response.output) ? response.output : undefined,
795
+ ];
796
+ for (const wrapper of wrappers) {
797
+ if (wrapper && isVerificationMarkRecord(wrapper[VERIFICATION_MARK_ENVELOPE_KEY])) {
798
+ return wrapper[VERIFICATION_MARK_ENVELOPE_KEY];
799
+ }
800
+ }
801
+ // MCP tool results nest the payload under structuredContent; recurse one level
802
+ // so a proof record carried there is still found.
803
+ if (isVerificationMarkRecord(response.structuredContent)) {
804
+ return extractVerificationMarkEnvelope(response.structuredContent);
805
+ }
806
+ return null;
807
+ }
808
+
809
+ function absentVerificationVerdict(present) {
810
+ return {
811
+ present,
812
+ valid: false,
813
+ verified: false,
814
+ display_state: null,
815
+ severity: null,
816
+ proof_id: null,
817
+ verify_url: null,
818
+ assurance_level: null,
819
+ signature: null,
820
+ };
821
+ }
822
+
823
+ // readVerificationVerdict — the consumer entry point. Given any response that
824
+ // may carry a verification envelope, returns a normalized verdict:
825
+ // { present, valid, verified, display_state, severity, proof_id, verify_url,
826
+ // assurance_level, signature }.
827
+ // `verified` is the backend display_state === "verified" — never a client-side
828
+ // crypto decision. An absent or malformed envelope yields a safe, non-verified
829
+ // reading rather than throwing.
830
+ export function readVerificationVerdict(response) {
831
+ const raw = extractVerificationMarkEnvelope(response);
832
+ if (raw === null) return absentVerificationVerdict(false);
833
+ const normalized = normalizeVerificationMarkEnvelope(raw);
834
+ if (normalized === null) return absentVerificationVerdict(true);
835
+ return {
836
+ present: true,
837
+ valid: true,
838
+ verified: normalized.verified,
839
+ display_state: normalized.display_state,
840
+ severity: normalized.severity,
841
+ proof_id: normalized.proof_id,
842
+ verify_url: normalized.verify_url,
843
+ assurance_level: normalized.assurance_level,
844
+ signature: normalized.signature,
845
+ };
846
+ }
847
+
848
+ // ===========================================================================
849
+ // Rendered-output binding — PRODUCER side of `intentrax-content/1.0`.
850
+ //
851
+ // The browser extension (the chrome-rendered "padlock for AI") only shows green
852
+ // when the VISIBLE text of the page's marked output region hashes to the
853
+ // output hash the proof is bound to. These helpers let a producer compute that
854
+ // hash from the exact text it renders, using the one canonical normalization
855
+ // (docs/architecture/verification-mark-spec.md Appendix A). They MUST stay
856
+ // byte-identical to browser-extension/src/binding.js `normalizeContent`; the
857
+ // shared vectors in contracts/test_vectors/verification_mark/ pin that.
858
+ //
859
+ // This is hashing of the PRODUCER'S OWN output, not proof truth: it asserts no
860
+ // verdict, signs nothing, and never makes a mark green on its own. Green still
861
+ // requires the engine-issued proof to carry this hash and the verifier to
862
+ // return it (see docs/architecture/verification-mark-enablement-checklist.md).
863
+ // ===========================================================================
864
+
865
+ export const CANONICAL_OUTPUT_NORMALIZATION = "intentrax-content/1.0";
866
+ export const CANONICAL_OUTPUT_HASH_ALGORITHM = "SHA-256";
867
+ export const VERIFICATION_POINTER_META_NAME = "intentrax-verification";
868
+ export const VERIFICATION_OUTPUT_REGION_ATTRIBUTE = "data-intentrax-output";
869
+
870
+ // normalizeCanonicalOutput — the `intentrax-content/1.0` normalization:
871
+ // NFC; CRLF/CR -> LF; collapse runs of space/tab/FF/VT/NBSP to one space;
872
+ // strip horizontal whitespace around newlines and collapse blank-line runs to a
873
+ // single LF; trim. Accepts one region string, or an array of region strings
874
+ // (one per marked region, in document order) which are joined exactly as the
875
+ // extension joins them: each region followed by "\n".
876
+ export function normalizeCanonicalOutput(content) {
877
+ const raw = Array.isArray(content)
878
+ ? content.map((region) => (typeof region === "string" ? region : "") + "\n").join("")
879
+ : typeof content === "string" ? content : "";
880
+ return raw
881
+ .normalize("NFC")
882
+ .replace(/\r\n?/g, "\n")
883
+ .replace(/[ \t\f\v\u00a0]+/g, " ")
884
+ .replace(/[ \t]*\n[ \t]*/g, "\n")
885
+ .replace(/\n{2,}/g, "\n")
886
+ .trim();
887
+ }
888
+
889
+ // canonicalOutputHash — bare lowercase 64-hex SHA-256 over the UTF-8 bytes of
890
+ // the normalized output (the canonical `content_hash` spelling).
891
+ export function canonicalOutputHash(content) {
892
+ return sha256Hex(normalizeCanonicalOutput(content));
893
+ }
894
+
895
+ // buildOutputBinding — the `output_binding` block a producer hands to the
896
+ // engine at proof generation, and that the verifier returns for the extension.
897
+ export function buildOutputBinding(content) {
898
+ return {
899
+ content_hash: canonicalOutputHash(content),
900
+ hash_algorithm: CANONICAL_OUTPUT_HASH_ALGORITHM,
901
+ normalization: CANONICAL_OUTPUT_NORMALIZATION,
902
+ };
903
+ }
904
+
905
+ function escapeVerificationPointerAttribute(value) {
906
+ return String(value)
907
+ .replace(/&/g, "&")
908
+ .replace(/"/g, """)
909
+ .replace(/</g, "&lt;")
910
+ .replace(/>/g, "&gt;");
911
+ }
912
+
913
+ // verificationPointerMetaTag — the page-level POINTER the extension detects:
914
+ // <meta name="intentrax-verification" content="proof_id={id};verify_url={url}">
915
+ // It carries only the proof id and an https verify URL — never the proof. The
916
+ // producer additionally wraps the rendered output in an element carrying
917
+ // `data-intentrax-output`. Returns null for an unsafe proof id or URL.
918
+ export function verificationPointerMetaTag({ proof_id: proofId, verify_url: verifyUrl } = {}) {
919
+ if (!isSafeProofID(proofId)) return null;
920
+ let url;
921
+ try {
922
+ url = new URL(verifyUrl);
923
+ } catch {
924
+ return null;
925
+ }
926
+ if (url.protocol !== "https:" || url.username !== "" || url.password !== "") return null;
927
+ const href = url.toString();
928
+ if (href.includes(";")) return null;
929
+ return `<meta name="${VERIFICATION_POINTER_META_NAME}" content="${escapeVerificationPointerAttribute(`proof_id=${proofId};verify_url=${href}`)}">`;
930
+ }
package/index.ts CHANGED
@@ -160,6 +160,17 @@ export function createIdempotencyKey(request) {
160
160
  return sha256Hex(IDEMPOTENCY_KEY_DOMAIN + canonicalJson(idempotencyInput(request)));
161
161
  }
162
162
 
163
+ // admissionIdempotencyKeyHash derives the agent-admission request's
164
+ // idempotency_key_hash from the SAME logical idempotency key the client later
165
+ // sends to execute. Set execute Request.idempotency_key = createIdempotencyKey(request)
166
+ // (raw) and admission Request.idempotency_key_hash = admissionIdempotencyKeyHash(request)
167
+ // (the SHA-256 of that raw key). The two are then provably the same logical key —
168
+ // one raw, one hashed — so a durable admission receipt can be correlated against
169
+ // the execution that carried the same key.
170
+ export function admissionIdempotencyKeyHash(request) {
171
+ return sha256Hex(createIdempotencyKey(request));
172
+ }
173
+
163
174
  export function buildVerificationEnvelope(request) {
164
175
  const invalidFields = validateVerificationRequest(request);
165
176
  if (invalidFields.length > 0) {
@@ -480,7 +491,7 @@ export function validateAgentGatewayAdmissionRequest(request) {
480
491
  invalid.push("schema_version");
481
492
  }
482
493
  for (const field of ["evidence_refs", "proof_refs"]) {
483
- if (!Array.isArray(request[field]) || request[field].length === 0 || request[field].some((ref) => !isSha256Ref(ref))) {
494
+ if (!Array.isArray(request[field]) || request[field].length === 0 || request[field].some((value) => !isSha256Ref(value))) {
484
495
  invalid.push(field);
485
496
  }
486
497
  }
@@ -624,3 +635,296 @@ export function buildIntentExecuteEnvelope(request) {
624
635
  },
625
636
  };
626
637
  }
638
+
639
+ // ===========================================================================
640
+ // Verification Mark response envelope — the SDK/MCP machine substrate.
641
+ //
642
+ // A backend-produced, PUBLIC-SAFE projection of a proof's verification status:
643
+ // { display_state, proof_id, verify_url, assurance_level, signature }.
644
+ // The SDK is a strict READER. It validates the envelope's SHAPE and normalizes
645
+ // it into a verdict a consumer can branch on. It NEVER re-derives crypto, never
646
+ // recomputes validity, never regenerates a proof: `verified` is EXACTLY the
647
+ // backend's display_state === "verified", nothing more. `signature` is a STATUS
648
+ // projection (e.g. "pass"/"fail"/"Not Available"), never a raw signature; a
649
+ // value that looks like raw signing material is refused so it can never leak.
650
+ // ===========================================================================
651
+
652
+ export const VERIFICATION_MARK_ENVELOPE_KEY = "intentrax_verification";
653
+ export const VERIFICATION_MARK_ENVELOPE_SCHEMA_VERSION = "intentrax.public_sdk.verification_mark_envelope/1.0";
654
+ export const VERIFICATION_MARK_VERIFIED_STATE = "verified";
655
+ export const VERIFICATION_MARK_NOT_AVAILABLE = "Not Available";
656
+
657
+ // display_state -> severity. Mirrors the backend §2 MARK_STATE_TABLE. Fail
658
+ // NEUTRAL, not fail-red: only a concrete failure/revocation is "negative".
659
+ export const VERIFICATION_MARK_STATE_SEVERITY = Object.freeze({
660
+ verified: "green",
661
+ proof_available: "neutral",
662
+ checking: "neutral",
663
+ not_found: "neutral",
664
+ unavailable: "neutral",
665
+ share_expired: "neutral",
666
+ failed: "negative",
667
+ revoked: "negative",
668
+ });
669
+
670
+ const VERIFICATION_MARK_DISPLAY_STATES = new Set(Object.keys(VERIFICATION_MARK_STATE_SEVERITY));
671
+ const VERIFICATION_MARK_ASSURANCE_LEVELS = new Set([1, 2, 3, 4]);
672
+ const VERIFICATION_MARK_SIGNATURE_MAX_LEN = 64;
673
+ const VERIFICATION_MARK_PROOF_ID_MAX_LEN = 128;
674
+ const VERIFICATION_MARK_URL_MAX_LEN = 2048;
675
+ const CONTROL_CHAR_RE = /[\u0000-\u001F\u007F]/;
676
+ // A public-safe field must never carry raw signing material or a secret. This
677
+ // guards the SDK from ever surfacing a raw signature/key/token even if a
678
+ // malformed upstream stuffs one into a nominally public field.
679
+ const VERIFICATION_MARK_SECRET_VALUE_RE = /-----BEGIN|BEGIN (?:RSA|EC|DSA|PGP|OPENSSH)|sk-(?:live|test)|bearer\s|private[_ -]?key|signing[_ -]?material|api[_-]?key|access[_-]?token|refresh[_-]?token/i;
680
+
681
+ function isVerificationMarkRecord(value) {
682
+ return value !== null && typeof value === "object" && !Array.isArray(value);
683
+ }
684
+
685
+ export function isVerificationMarkDisplayState(value) {
686
+ return typeof value === "string" && VERIFICATION_MARK_DISPLAY_STATES.has(value);
687
+ }
688
+
689
+ export function verificationMarkSeverity(displayState) {
690
+ return isVerificationMarkDisplayState(displayState) ? VERIFICATION_MARK_STATE_SEVERITY[displayState] : null;
691
+ }
692
+
693
+ function isPublicSafeString(value) {
694
+ return typeof value === "string" && !CONTROL_CHAR_RE.test(value) && !VERIFICATION_MARK_SECRET_VALUE_RE.test(value);
695
+ }
696
+
697
+ function normalizePlaceholderText(value, maxLen) {
698
+ if (typeof value !== "string") return null;
699
+ const trimmed = value.trim();
700
+ if (trimmed === "" || trimmed === VERIFICATION_MARK_NOT_AVAILABLE) return null;
701
+ if (trimmed.length > maxLen || !isPublicSafeString(trimmed)) return null;
702
+ return trimmed;
703
+ }
704
+
705
+ // normalizeVerificationMarkSignature — the signature STATUS projection. Returns
706
+ // the public-safe status token, or null when it is absent, a placeholder, or
707
+ // looks like raw signing material (which is never surfaced). It is NEVER
708
+ // re-derived or cryptographically verified — shape only.
709
+ export function normalizeVerificationMarkSignature(value) {
710
+ return normalizePlaceholderText(value, VERIFICATION_MARK_SIGNATURE_MAX_LEN);
711
+ }
712
+
713
+ function normalizeVerificationMarkAssuranceLevel(value) {
714
+ return typeof value === "number" && VERIFICATION_MARK_ASSURANCE_LEVELS.has(value) ? value : null;
715
+ }
716
+
717
+ function normalizeVerificationMarkVerifyUrl(value) {
718
+ const text = normalizePlaceholderText(value, VERIFICATION_MARK_URL_MAX_LEN);
719
+ if (text === null) return null;
720
+ // Root-relative verifier paths are public-safe as-is.
721
+ if (text.startsWith("/") && !text.startsWith("//")) return text;
722
+ let url;
723
+ try {
724
+ url = new URL(text);
725
+ } catch {
726
+ return null;
727
+ }
728
+ if (url.protocol !== "https:" && url.protocol !== "http:") return null;
729
+ if (url.username !== "" || url.password !== "") return null;
730
+ return url.toString();
731
+ }
732
+
733
+ // validateVerificationMarkEnvelope — SHAPE-ONLY validation of the backend's
734
+ // public-safe verification envelope. Returns the sorted list of invalid field
735
+ // names ([] when the shape is well-formed). It performs NO crypto: it never
736
+ // verifies the signature, recomputes validity, or regenerates a proof.
737
+ export function validateVerificationMarkEnvelope(envelope) {
738
+ if (!isVerificationMarkRecord(envelope)) {
739
+ return ["verification_mark_envelope"];
740
+ }
741
+ const invalid = [];
742
+ if (!isVerificationMarkDisplayState(envelope.display_state)) invalid.push("display_state");
743
+ if (typeof envelope.proof_id !== "string") invalid.push("proof_id");
744
+ if (typeof envelope.verify_url !== "string") invalid.push("verify_url");
745
+ if (!(envelope.assurance_level === null || normalizeVerificationMarkAssuranceLevel(envelope.assurance_level) !== null)) {
746
+ invalid.push("assurance_level");
747
+ }
748
+ if (typeof envelope.signature !== "string") invalid.push("signature");
749
+ // A public-safe envelope must never carry raw secret material in any string
750
+ // field — reject the whole envelope if it does rather than pass it through.
751
+ for (const field of ["proof_id", "verify_url", "signature"]) {
752
+ const value = envelope[field];
753
+ if (typeof value === "string" && !isPublicSafeString(value)) {
754
+ invalid.push(field);
755
+ }
756
+ }
757
+ return [...new Set(invalid)].sort();
758
+ }
759
+
760
+ // normalizeVerificationMarkEnvelope — validate + project the envelope into a
761
+ // canonical, public-safe verdict. Returns null when the shape is invalid.
762
+ // Placeholder ("Not Available") and secret-looking values collapse to null per
763
+ // field. `verified` is EXACTLY the backend display_state === "verified" — the
764
+ // SDK asserts no independent verdict and recomputes no crypto.
765
+ export function normalizeVerificationMarkEnvelope(envelope) {
766
+ if (validateVerificationMarkEnvelope(envelope).length > 0) return null;
767
+ const displayState = envelope.display_state;
768
+ return {
769
+ schema_version: VERIFICATION_MARK_ENVELOPE_SCHEMA_VERSION,
770
+ display_state: displayState,
771
+ severity: VERIFICATION_MARK_STATE_SEVERITY[displayState],
772
+ verified: displayState === VERIFICATION_MARK_VERIFIED_STATE,
773
+ proof_id: normalizePlaceholderText(envelope.proof_id, VERIFICATION_MARK_PROOF_ID_MAX_LEN),
774
+ verify_url: normalizeVerificationMarkVerifyUrl(envelope.verify_url),
775
+ assurance_level: normalizeVerificationMarkAssuranceLevel(envelope.assurance_level),
776
+ signature: normalizeVerificationMarkSignature(envelope.signature),
777
+ };
778
+ }
779
+
780
+ // extractVerificationMarkEnvelope — locate the verification envelope on an
781
+ // arbitrary response object. Handles the bare envelope, the `intentrax_verification`
782
+ // key at the top level, and the same key nested under an MCP tool result's
783
+ // `structuredContent` / a `result` / `output` wrapper. Returns the raw envelope
784
+ // candidate (unvalidated) or null.
785
+ export function extractVerificationMarkEnvelope(response) {
786
+ if (!isVerificationMarkRecord(response)) return null;
787
+ if (isVerificationMarkDisplayState(response.display_state) && "signature" in response) {
788
+ return response;
789
+ }
790
+ const wrappers = [
791
+ response,
792
+ isVerificationMarkRecord(response.structuredContent) ? response.structuredContent : undefined,
793
+ isVerificationMarkRecord(response.result) ? response.result : undefined,
794
+ isVerificationMarkRecord(response.output) ? response.output : undefined,
795
+ ];
796
+ for (const wrapper of wrappers) {
797
+ if (wrapper && isVerificationMarkRecord(wrapper[VERIFICATION_MARK_ENVELOPE_KEY])) {
798
+ return wrapper[VERIFICATION_MARK_ENVELOPE_KEY];
799
+ }
800
+ }
801
+ // MCP tool results nest the payload under structuredContent; recurse one level
802
+ // so a proof record carried there is still found.
803
+ if (isVerificationMarkRecord(response.structuredContent)) {
804
+ return extractVerificationMarkEnvelope(response.structuredContent);
805
+ }
806
+ return null;
807
+ }
808
+
809
+ function absentVerificationVerdict(present) {
810
+ return {
811
+ present,
812
+ valid: false,
813
+ verified: false,
814
+ display_state: null,
815
+ severity: null,
816
+ proof_id: null,
817
+ verify_url: null,
818
+ assurance_level: null,
819
+ signature: null,
820
+ };
821
+ }
822
+
823
+ // readVerificationVerdict — the consumer entry point. Given any response that
824
+ // may carry a verification envelope, returns a normalized verdict:
825
+ // { present, valid, verified, display_state, severity, proof_id, verify_url,
826
+ // assurance_level, signature }.
827
+ // `verified` is the backend display_state === "verified" — never a client-side
828
+ // crypto decision. An absent or malformed envelope yields a safe, non-verified
829
+ // reading rather than throwing.
830
+ export function readVerificationVerdict(response) {
831
+ const raw = extractVerificationMarkEnvelope(response);
832
+ if (raw === null) return absentVerificationVerdict(false);
833
+ const normalized = normalizeVerificationMarkEnvelope(raw);
834
+ if (normalized === null) return absentVerificationVerdict(true);
835
+ return {
836
+ present: true,
837
+ valid: true,
838
+ verified: normalized.verified,
839
+ display_state: normalized.display_state,
840
+ severity: normalized.severity,
841
+ proof_id: normalized.proof_id,
842
+ verify_url: normalized.verify_url,
843
+ assurance_level: normalized.assurance_level,
844
+ signature: normalized.signature,
845
+ };
846
+ }
847
+
848
+ // ===========================================================================
849
+ // Rendered-output binding — PRODUCER side of `intentrax-content/1.0`.
850
+ //
851
+ // The browser extension (the chrome-rendered "padlock for AI") only shows green
852
+ // when the VISIBLE text of the page's marked output region hashes to the
853
+ // output hash the proof is bound to. These helpers let a producer compute that
854
+ // hash from the exact text it renders, using the one canonical normalization
855
+ // (docs/architecture/verification-mark-spec.md Appendix A). They MUST stay
856
+ // byte-identical to browser-extension/src/binding.js `normalizeContent`; the
857
+ // shared vectors in contracts/test_vectors/verification_mark/ pin that.
858
+ //
859
+ // This is hashing of the PRODUCER'S OWN output, not proof truth: it asserts no
860
+ // verdict, signs nothing, and never makes a mark green on its own. Green still
861
+ // requires the engine-issued proof to carry this hash and the verifier to
862
+ // return it (see docs/architecture/verification-mark-enablement-checklist.md).
863
+ // ===========================================================================
864
+
865
+ export const CANONICAL_OUTPUT_NORMALIZATION = "intentrax-content/1.0";
866
+ export const CANONICAL_OUTPUT_HASH_ALGORITHM = "SHA-256";
867
+ export const VERIFICATION_POINTER_META_NAME = "intentrax-verification";
868
+ export const VERIFICATION_OUTPUT_REGION_ATTRIBUTE = "data-intentrax-output";
869
+
870
+ // normalizeCanonicalOutput — the `intentrax-content/1.0` normalization:
871
+ // NFC; CRLF/CR -> LF; collapse runs of space/tab/FF/VT/NBSP to one space;
872
+ // strip horizontal whitespace around newlines and collapse blank-line runs to a
873
+ // single LF; trim. Accepts one region string, or an array of region strings
874
+ // (one per marked region, in document order) which are joined exactly as the
875
+ // extension joins them: each region followed by "\n".
876
+ export function normalizeCanonicalOutput(content) {
877
+ const raw = Array.isArray(content)
878
+ ? content.map((region) => (typeof region === "string" ? region : "") + "\n").join("")
879
+ : typeof content === "string" ? content : "";
880
+ return raw
881
+ .normalize("NFC")
882
+ .replace(/\r\n?/g, "\n")
883
+ .replace(/[ \t\f\v\u00a0]+/g, " ")
884
+ .replace(/[ \t]*\n[ \t]*/g, "\n")
885
+ .replace(/\n{2,}/g, "\n")
886
+ .trim();
887
+ }
888
+
889
+ // canonicalOutputHash — bare lowercase 64-hex SHA-256 over the UTF-8 bytes of
890
+ // the normalized output (the canonical `content_hash` spelling).
891
+ export function canonicalOutputHash(content) {
892
+ return sha256Hex(normalizeCanonicalOutput(content));
893
+ }
894
+
895
+ // buildOutputBinding — the `output_binding` block a producer hands to the
896
+ // engine at proof generation, and that the verifier returns for the extension.
897
+ export function buildOutputBinding(content) {
898
+ return {
899
+ content_hash: canonicalOutputHash(content),
900
+ hash_algorithm: CANONICAL_OUTPUT_HASH_ALGORITHM,
901
+ normalization: CANONICAL_OUTPUT_NORMALIZATION,
902
+ };
903
+ }
904
+
905
+ function escapeVerificationPointerAttribute(value) {
906
+ return String(value)
907
+ .replace(/&/g, "&amp;")
908
+ .replace(/"/g, "&quot;")
909
+ .replace(/</g, "&lt;")
910
+ .replace(/>/g, "&gt;");
911
+ }
912
+
913
+ // verificationPointerMetaTag — the page-level POINTER the extension detects:
914
+ // <meta name="intentrax-verification" content="proof_id={id};verify_url={url}">
915
+ // It carries only the proof id and an https verify URL — never the proof. The
916
+ // producer additionally wraps the rendered output in an element carrying
917
+ // `data-intentrax-output`. Returns null for an unsafe proof id or URL.
918
+ export function verificationPointerMetaTag({ proof_id: proofId, verify_url: verifyUrl } = {}) {
919
+ if (!isSafeProofID(proofId)) return null;
920
+ let url;
921
+ try {
922
+ url = new URL(verifyUrl);
923
+ } catch {
924
+ return null;
925
+ }
926
+ if (url.protocol !== "https:" || url.username !== "" || url.password !== "") return null;
927
+ const href = url.toString();
928
+ if (href.includes(";")) return null;
929
+ return `<meta name="${VERIFICATION_POINTER_META_NAME}" content="${escapeVerificationPointerAttribute(`proof_id=${proofId};verify_url=${href}`)}">`;
930
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@intentrax/sdk",
3
- "version": "1.0.0",
3
+ "version": "1.1.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",
@@ -31,7 +31,8 @@
31
31
  "http.js",
32
32
  "http.ts",
33
33
  "http.d.ts",
34
- "README.md"
34
+ "README.md",
35
+ "trust"
35
36
  ],
36
37
  "keywords": [
37
38
  "intentrax",
@@ -50,12 +51,12 @@
50
51
  },
51
52
  "repository": {
52
53
  "type": "git",
53
- "url": "https://github.com/Adelodun-Adejare/Intentrax.git",
54
- "directory": "sdk/typescript"
54
+ "url": "git+https://github.com/Intentrax/agent-toolkit-for-intentrax.git",
55
+ "directory": "packages/sdk"
55
56
  },
56
- "homepage": "https://intentrax.dev",
57
+ "homepage": "https://www.intentrax.com/developers",
57
58
  "bugs": {
58
- "url": "https://github.com/Adelodun-Adejare/Intentrax/issues"
59
+ "url": "https://www.intentrax.com/developers"
59
60
  },
60
61
  "intentrax": {
61
62
  "sharedSpec": "../shared-specs/public-sdk-conformance.v1.json"