@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 +77 -9
- package/cli/intentrax.mjs +330 -18
- package/examples/sandbox/README.md +42 -0
- package/examples/sandbox/sandbox-proof-export.json +318 -0
- package/examples/sandbox/tampered-aep-swap.json +318 -0
- package/examples/sandbox/tampered-roster.json +309 -0
- package/examples/sandbox/tampered-signature.json +318 -0
- package/examples/sandbox/unpinned-signer.json +318 -0
- package/index.d.ts +84 -0
- package/index.js +304 -0
- package/index.ts +305 -1
- package/package.json +7 -6
- package/trust/sandbox-key-set.json +26 -0
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, "<")
|
|
910
|
+
.replace(/>/g, ">");
|
|
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((
|
|
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, "&")
|
|
908
|
+
.replace(/"/g, """)
|
|
909
|
+
.replace(/</g, "<")
|
|
910
|
+
.replace(/>/g, ">");
|
|
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.
|
|
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/
|
|
54
|
-
"directory": "sdk
|
|
54
|
+
"url": "git+https://github.com/Intentrax/agent-toolkit-for-intentrax.git",
|
|
55
|
+
"directory": "packages/sdk"
|
|
55
56
|
},
|
|
56
|
-
"homepage": "https://intentrax.
|
|
57
|
+
"homepage": "https://www.intentrax.com/developers",
|
|
57
58
|
"bugs": {
|
|
58
|
-
"url": "https://
|
|
59
|
+
"url": "https://www.intentrax.com/developers"
|
|
59
60
|
},
|
|
60
61
|
"intentrax": {
|
|
61
62
|
"sharedSpec": "../shared-specs/public-sdk-conformance.v1.json"
|