@callcium/sdk 0.1.0 → 0.3.0

package/dist/index.js

@@ -20,19 +20,27 @@ var CallciumError = class CallciumError extends Error {
 * Thrown by `PolicyEnforcer.enforce` when calldata fails policy enforcement.
 * Distinct from `CallciumError("VALIDATION_ERROR")`, which signals static
 * issues in the policy itself.
-* Carries the full list of violations (one per failed group).
+*
+* Carries the full list of structured violations (one per failed group). The
+* `Error.message` is a minimal non-lossy diagnostic summary built from the
+* first violation's structured fields — not a presentation contract. Consumers
+* rendering violations to users should iterate `violations` directly.
 */
 var PolicyViolationError = class PolicyViolationError extends Error {
 	violations;
 	constructor(violations) {
-		const first = violations[0];
-		const msg = first ? `Policy violation: ${first.message}` : "Policy violation";
-		super(msg);
+		super(formatDiagnostic(violations[0]));
 		this.name = "PolicyViolationError";
 		this.violations = violations;
 		Object.setPrototypeOf(this, PolicyViolationError.prototype);
 	}
 };
+/** Build a stack-trace-friendly diagnostic line from a violation's code and coordinates. */
+function formatDiagnostic(violation) {
+	if (!violation) return "Policy violation";
+	const location = "group" in violation ? ` at group ${violation.group} rule ${violation.rule}` : "";
+	return `Policy violation: ${violation.code}${location}`;
+}
 //#endregion
 //#region src/bytes.ts
 /** Regex that matches a valid hex body (even number of hex chars). */
@@ -1404,6 +1412,35 @@ function toBigInt(bytes, offset = 0) {
 function isSigned(typeCode) {
 	return typeCode >= TypeCode.INT_MIN && typeCode <= TypeCode.INT_MAX;
 }
+/**
+* Canonicalize a raw 256-bit calldata word to its ABI value for the declared type (Policy Spec §7.8).
+* A scalar loaded from untrusted calldata may carry bits outside the declared width; masking
+* unsigned/address/bool/function/bytesN to width and sign-extending signed integers makes the
+* comparison use the canonical ABI value rather than the raw bytes.
+* @param value - The raw 256-bit word loaded from calldata.
+* @param typeCode - The declared type code of the value.
+* @returns The canonicalized 256-bit value.
+*/
+function canonicalize(value, typeCode) {
+	if (typeCode <= TypeCode.UINT_MAX) {
+		const bits = BigInt((typeCode + 1) * 8);
+		return bits === 256n ? value : value & (1n << bits) - 1n;
+	}
+	if (typeCode <= TypeCode.INT_MAX) {
+		const bits = (typeCode - TypeCode.INT_MIN + 1) * 8;
+		return bits === 256 ? value : BigInt.asUintN(256, BigInt.asIntN(bits, value));
+	}
+	if (typeCode === TypeCode.ADDRESS) return value & (1n << 160n) - 1n;
+	if (typeCode === TypeCode.BOOL) return value & 1n;
+	if (typeCode === TypeCode.FUNCTION) return value >> 64n << 64n;
+	if (typeCode >= TypeCode.FIXED_BYTES_MIN && typeCode <= TypeCode.FIXED_BYTES_MAX) {
+		const n = typeCode - TypeCode.FIXED_BYTES_MIN + 1;
+		if (n === 32) return value;
+		const padBits = BigInt((32 - n) * 8);
+		return value >> padBits << padBits;
+	}
+	return value;
+}
 /** Return true when the operator code (with or without NOT flag) is a LENGTH_* variant. */
 function isLengthOp(opCode) {
 	const base = opCode & ~Op.NOT;
@@ -2707,11 +2744,11 @@ function locate(tree, callData, pathBytes, baseOffset) {
 	for (let i = 0; i < paramIndex; i++) head += headContribution(tree[i]);
 	let base = baseOffset;
 	let node = tree[paramIndex];
-	for (let s = 1; s < stepCount; s++) {
-		const step = readStep(pathBytes, s);
+	for (let stepIndex = 1; stepIndex < stepCount; stepIndex++) {
+		const step = readStep(pathBytes, stepIndex);
 		if (isQuantifier(step)) {
-			const remaining = pathBytes.subarray((s + 1) * 2);
-			for (let r = 0; r < remaining.length / 2; r++) if (isQuantifier(readStep(remaining, r))) throw new CallciumError("INVALID_QUANTIFIER", "Nested quantifiers are not supported.");
+			const remaining = pathBytes.subarray((stepIndex + 1) * 2);
+			for (let remainingStepIndex = 0; remainingStepIndex < remaining.length / 2; remainingStepIndex++) if (isQuantifier(readStep(remaining, remainingStepIndex))) throw new CallciumError("INVALID_QUANTIFIER", "Nested quantifiers are not supported.");
 			return {
 				ok: true,
 				type: "quantifier",
@@ -2887,8 +2924,8 @@ function loadSlice(callData, location) {
 function descendPath(callData, location, pathBytes) {
 	const stepCount = pathBytes.length / 2;
 	let { head, base, node } = location;
-	for (let s = 0; s < stepCount; s++) {
-		const step = readStep(pathBytes, s);
+	for (let stepIndex = 0; stepIndex < stepCount; stepIndex++) {
+		const step = readStep(pathBytes, stepIndex);
 		const result = descend(node, callData, head, base, step);
 		if (result.type === "violation") return {
 			ok: false,
@@ -2916,38 +2953,27 @@ function addressToBigInt(hex) {
 	padded.set(bytes, 32 - bytes.length);
 	return toBigInt(padded, 0);
 }
-/** Format a bigint as a compact hex string without leading-zero padding. */
-function compactHex(value) {
-	if (value === 0n) return "0x0";
-	return `0x${value.toString(16)}`;
-}
-/** Truncate a hex string to at most maxChars characters, adding ellipsis if needed. */
-function truncateHexForMessage(hex, maxChars = 66) {
-	if (hex.length <= maxChars) return hex;
-	return `${hex.slice(0, maxChars - 1)}…`;
-}
-/** Format a decoded operand as decimal for length ops, otherwise compact hex. */
-function formatOperandValue(value, opCode) {
-	return isLengthOp(opCode) ? value.toString(10) : compactHex(value);
-}
-/** Format the constraint (operator + operands) from a single lookupOp call. */
-function formatConstraint(opCode, operandData) {
-	const negated = (opCode & Op.NOT) !== 0;
-	const { label, operands } = lookupOp(opCode);
-	const op = negated ? `not ${label}` : label;
-	let formattedOperands;
-	if (operands === "variadic") formattedOperands = `(${operandData.length / 32} values)`;
-	else if (operands === "range") {
-		const min = toBigInt(operandData, 0);
-		const max = toBigInt(operandData, 32);
-		formattedOperands = `[${formatOperandValue(min, opCode)}, ${formatOperandValue(max, opCode)}]`;
-	} else formattedOperands = formatOperandValue(toBigInt(operandData, 0), opCode);
-	return `${op} ${formattedOperands}`;
-}
-/** Build a self-contained VALUE_MISMATCH message for a scalar or length comparison. */
-function mismatchMessage(opCode, actual, operandData) {
-	const display = typeof actual === "number" ? String(actual) : truncateHexForMessage(compactHex(actual));
-	return `constraint ${formatConstraint(opCode, operandData)} violated by ${display}`;
+/**
+* Walk a descriptor subtree through path steps and return the terminal leaf type code.
+*
+* Used only for violation metadata. Valid policies have structurally valid
+* quantifier suffixes (enforced by `PolicyValidator`); if a hand-crafted blob
+* violates that invariant, return the last resolvable node's type code as
+* best-effort diagnostic context.
+*/
+function resolveLeafTypeCode(elementNode, remainingPath) {
+	let node = elementNode;
+	const stepCount = remainingPath.length / 2;
+	for (let step = 0; step < stepCount; step++) {
+		const childIndex = readU16(remainingPath, step * 2);
+		if (node.type === "tuple") {
+			const field = node.fields[childIndex];
+			if (!field) break;
+			node = field;
+		} else if (node.type === "staticArray" || node.type === "dynamicArray") node = node.element;
+		else break;
+	}
+	return node.typeCode;
 }
 /**
 * Check a policy against ABI-encoded call data without throwing on violations.
@@ -2963,10 +2989,7 @@ function check(policy, callData, context) {
 	if (!decoded.isSelectorless) {
 		if (callDataBytes.length < 4) return {
 			ok: false,
-			violations: [{
-				code: "MISSING_SELECTOR",
-				message: "Calldata too short to contain a selector"
-			}]
+			violations: [{ code: "MISSING_SELECTOR" }]
 		};
 		const expectedSelector = decoded.selector.value;
 		const actualSelector = bytesToHex(callDataBytes.subarray(0, 4));
@@ -2974,8 +2997,8 @@ function check(policy, callData, context) {
 			ok: false,
 			violations: [{
 				code: "SELECTOR_MISMATCH",
-				message: `Expected selector ${expectedSelector}, got ${actualSelector}`,
-				resolvedValue: actualSelector
+				resolvedValue: actualSelector,
+				expectedValue: expectedSelector
 			}]
 		};
 	}
@@ -3028,8 +3051,10 @@ function evaluateRule(rule, tree, callDataBytes, baseOffset, groupIndex, ruleInd
 		group: groupIndex,
 		rule: ruleIndex,
 		code: locResult.code,
-		message: `Navigation failed: ${locResult.code}`,
-		path: rule.path.value
+		scope: Scope.CALLDATA,
+		path: rule.path.value,
+		opCode,
+		operandData: rule.data.value
 	};
 	if (locResult.type === "quantifier") return evaluateQuantifier(locResult.quantifier, callDataBytes, opCode, operandData, groupIndex, ruleIndex, rule.path.value);
 	return evaluateLeaf(locResult.location, callDataBytes, opCode, operandData, groupIndex, ruleIndex, rule.path.value);
@@ -3044,23 +3069,33 @@ function evaluateContextRule(pathBytes, opCode, operandData, groupIndex, ruleInd
 		group: groupIndex,
 		rule: ruleIndex,
 		code: "MISSING_CONTEXT",
-		message: `Context property ${propInfo.label} not provided`,
-		path: pathHex
+		scope: Scope.CONTEXT,
+		path: pathHex,
+		typeCode: propInfo.typeCode
 	};
 	let value;
 	if (typeof contextValue === "string") value = addressToBigInt(contextValue);
 	else value = contextValue;
-	if (!applyOperator(opCode, value, 32, operandData, TypeCode.UINT_MAX)) return {
+	if (!applyOperator(opCode, value, 32, operandData, propInfo.typeCode)) return {
 		group: groupIndex,
 		rule: ruleIndex,
 		code: "VALUE_MISMATCH",
-		message: mismatchMessage(opCode, value, operandData),
+		scope: Scope.CONTEXT,
 		path: pathHex,
+		opCode,
+		operandData: bytesToHex(operandData),
+		typeCode: propInfo.typeCode,
 		resolvedValue: bigintToHex(value)
 	};
 	return null;
 }
-/** Load a value from calldata at the given location and apply the operator. */
+/**
+* Load a value from calldata at the given location and apply the operator.
+*
+* `resolvedValue` is normalised at the decision point: length operators encode
+* the byte/element count as a hex bigint; scalar operators preserve the full
+* 32-byte ABI word so downstream rendering can decode left-aligned `bytesN` faithfully.
+*/
 function applyLeafOperator(callDataBytes, location, opCode, operandData) {
 	const { node } = location;
 	if (isLengthOp(opCode)) {
@@ -3072,61 +3107,69 @@ function applyLeafOperator(callDataBytes, location, opCode, operandData) {
 		} else valueLength = node.staticSize;
 		return {
 			passed: applyOperator(opCode, 0n, valueLength, operandData, node.typeCode),
-			length: valueLength
+			resolvedValue: bigintToHex(BigInt(valueLength))
 		};
 	}
 	const result = loadScalar(callDataBytes, location);
 	if (!result.ok) return { error: result.code };
-	const value = toBigInt(result.value, 0);
+	const value = canonicalize(toBigInt(result.value, 0), node.typeCode);
 	return {
 		passed: applyOperator(opCode, value, 32, operandData, node.typeCode),
-		value
+		resolvedValue: bigintToHex(value)
 	};
 }
 /** Evaluate a leaf rule, producing a violation on failure or null on pass. */
 function evaluateLeaf(location, callDataBytes, opCode, operandData, groupIndex, ruleIndex, pathHex) {
 	const result = applyLeafOperator(callDataBytes, location, opCode, operandData);
-	if ("error" in result) {
-		const message = isLengthOp(opCode) ? `Failed to read length: ${result.error}` : `Failed to load value: ${result.error}`;
-		return {
-			group: groupIndex,
-			rule: ruleIndex,
-			code: result.error,
-			message,
-			path: pathHex
-		};
-	}
-	if (!result.passed) {
-		const actual = result.value !== void 0 ? result.value : result.length ?? 0;
-		return {
-			group: groupIndex,
-			rule: ruleIndex,
-			code: "VALUE_MISMATCH",
-			message: mismatchMessage(opCode, actual, operandData),
-			path: pathHex,
-			resolvedValue: bigintToHex(typeof actual === "number" ? BigInt(actual) : actual)
-		};
-	}
+	const typeCode = location.node.typeCode;
+	if ("error" in result) return {
+		group: groupIndex,
+		rule: ruleIndex,
+		code: result.error,
+		scope: Scope.CALLDATA,
+		path: pathHex,
+		opCode,
+		operandData: bytesToHex(operandData),
+		typeCode
+	};
+	if (!result.passed) return {
+		group: groupIndex,
+		rule: ruleIndex,
+		code: "VALUE_MISMATCH",
+		scope: Scope.CALLDATA,
+		path: pathHex,
+		opCode,
+		operandData: bytesToHex(operandData),
+		typeCode,
+		resolvedValue: result.resolvedValue
+	};
 	return null;
 }
 /** Evaluate a quantified rule by iterating over array elements with ALL/ANY semantics. */
 function evaluateQuantifier(qResult, callDataBytes, opCode, operandData, groupIndex, ruleIndex, pathHex) {
 	const { quantifier, location: arrayLocation, remainingPath } = qResult;
+	const operandHex = bytesToHex(operandData);
+	const arrayNode = arrayLocation.node;
+	const leafTypeCode = resolveLeafTypeCode(arrayNode.type === "staticArray" || arrayNode.type === "dynamicArray" ? arrayNode.element : arrayNode, remainingPath);
 	const shapeResult = arrayShape(callDataBytes, arrayLocation);
 	if (!shapeResult.ok) return {
 		group: groupIndex,
 		rule: ruleIndex,
 		code: shapeResult.code,
-		message: `Failed to read array shape: ${shapeResult.code}`,
-		path: pathHex
+		scope: Scope.CALLDATA,
+		path: pathHex,
+		opCode,
+		operandData: operandHex,
+		typeCode: leafTypeCode
 	};
 	const shape = shapeResult.shape;
 	if (shape.length > Limits.MAX_QUANTIFIED_ARRAY_LENGTH) return {
 		group: groupIndex,
 		rule: ruleIndex,
 		code: "QUANTIFIER_LIMIT_EXCEEDED",
-		message: `Array length ${shape.length} exceeds maximum ${Limits.MAX_QUANTIFIED_ARRAY_LENGTH}`,
-		path: pathHex
+		scope: Scope.CALLDATA,
+		path: pathHex,
+		resolvedValue: bigintToHex(BigInt(shape.length))
 	};
 	if (shape.length === 0) {
 		if (quantifier === Quantifier.ALL_OR_EMPTY) return null;
@@ -3134,7 +3177,7 @@ function evaluateQuantifier(qResult, callDataBytes, opCode, operandData, groupIn
 			group: groupIndex,
 			rule: ruleIndex,
 			code: "QUANTIFIER_EMPTY_ARRAY",
-			message: "Quantifier applied to empty array",
+			scope: Scope.CALLDATA,
 			path: pathHex
 		};
 	}
@@ -3147,70 +3190,82 @@ function evaluateQuantifier(qResult, callDataBytes, opCode, operandData, groupIn
 				group: groupIndex,
 				rule: ruleIndex,
 				code: elemResult.code,
-				message: `Quantifier element ${elemIndex}: ${elemResult.code}`,
-				path: pathHex
+				scope: Scope.CALLDATA,
+				path: pathHex,
+				opCode,
+				operandData: operandHex,
+				typeCode: leafTypeCode,
+				elementIndex: elemIndex
 			};
 			continue;
 		}
 		const elemLocation = elemResult.location;
-		let elemPassed;
+		let leafLocation;
 		if (hasSuffix) {
-			const leafResult = descendPath(callDataBytes, elemLocation, remainingPath);
-			if (!leafResult.ok) {
-				if (isUniversal) return {
-					group: groupIndex,
-					rule: ruleIndex,
-					code: leafResult.code,
-					message: `Quantifier element ${elemIndex} navigation failed: ${leafResult.code}`,
-					path: pathHex
-				};
-				continue;
-			}
-			elemPassed = evaluateLeafValue(leafResult.location, callDataBytes, opCode, operandData);
-		} else {
-			const leafResult = applyLeafOperator(callDataBytes, elemLocation, opCode, operandData);
-			if ("error" in leafResult) {
+			const navResult = descendPath(callDataBytes, elemLocation, remainingPath);
+			if (!navResult.ok) {
 				if (isUniversal) return {
 					group: groupIndex,
 					rule: ruleIndex,
-					code: leafResult.error,
-					message: `Quantifier element ${elemIndex}: ${leafResult.error}`,
-					path: pathHex
+					code: navResult.code,
+					scope: Scope.CALLDATA,
+					path: pathHex,
+					opCode,
+					operandData: operandHex,
+					typeCode: leafTypeCode,
+					elementIndex: elemIndex
 				};
 				continue;
 			}
-			elemPassed = leafResult.passed;
+			leafLocation = navResult.location;
+		} else leafLocation = elemLocation;
+		const applied = applyLeafOperator(callDataBytes, leafLocation, opCode, operandData);
+		if ("error" in applied) {
+			if (isUniversal) return {
+				group: groupIndex,
+				rule: ruleIndex,
+				code: applied.error,
+				scope: Scope.CALLDATA,
+				path: pathHex,
+				opCode,
+				operandData: operandHex,
+				typeCode: leafTypeCode,
+				elementIndex: elemIndex
+			};
+			continue;
 		}
-		if (isUniversal && !elemPassed) return {
+		if (isUniversal && !applied.passed) return {
 			group: groupIndex,
 			rule: ruleIndex,
 			code: "VALUE_MISMATCH",
-			message: `constraint ${formatConstraint(opCode, operandData)} violated at element ${elemIndex}`,
-			path: pathHex
+			scope: Scope.CALLDATA,
+			path: pathHex,
+			opCode,
+			operandData: operandHex,
+			typeCode: leafTypeCode,
+			resolvedValue: applied.resolvedValue,
+			elementIndex: elemIndex
 		};
-		if (!isUniversal && elemPassed) return null;
+		if (!isUniversal && applied.passed) return null;
 	}
 	if (isUniversal) return null;
 	return {
 		group: groupIndex,
 		rule: ruleIndex,
 		code: "VALUE_MISMATCH",
-		message: `constraint ${formatConstraint(opCode, operandData)} violated by all elements`,
-		path: pathHex
+		scope: Scope.CALLDATA,
+		path: pathHex,
+		opCode,
+		operandData: operandHex,
+		typeCode: leafTypeCode
 	};
 }
-/** Apply a leaf operator and return a boolean. Returns false on calldata read failure. */
-function evaluateLeafValue(location, callDataBytes, opCode, operandData) {
-	const result = applyLeafOperator(callDataBytes, location, opCode, operandData);
-	if ("error" in result) return false;
-	return result.passed;
-}
 /** Check and enforce policies against ABI-encoded call data. */
 const PolicyEnforcer = {
 	check,
 	enforce
 };
 //#endregion
-export { CallciumError, ContextProperty, Descriptor, DescriptorCoder, Limits, Op, PolicyBuilder, PolicyCoder, PolicyEnforcer, PolicyValidator, PolicyViolationError, Quantifier, Scope, TypeCode, arg, blockNumber, blockTimestamp, bytesToHex, chainId, hexToBytes, isOpAllowed, isQuantifier, lookupContextProperty, lookupOp, lookupQuantifier, lookupScope, lookupTypeCode, msgSender, msgValue, parsePathSteps, toAddress, txOrigin };
+export { CallciumError, ContextProperty, Descriptor, DescriptorCoder, Limits, Op, PolicyBuilder, PolicyCoder, PolicyEnforcer, PolicyValidator, PolicyViolationError, Quantifier, Scope, TypeCode, arg, blockNumber, blockTimestamp, bytesToHex, chainId, hexToBytes, isLengthOp, isOpAllowed, isQuantifier, lookupContextProperty, lookupOp, lookupQuantifier, lookupScope, lookupTypeCode, msgSender, msgValue, parsePathSteps, toAddress, txOrigin };
 
 //# sourceMappingURL=index.js.map