@callcium/sdk 0.9.0 → 0.11.0

package/src/policy-enforcer.ts

@@ -1,21 +1,13 @@
-import { hexToBytes, bytesToHex, readU16, readU32, bigintToHex } from "./bytes";
-import { loadWord, readPointer } from "./calldata-reader";
-import {
-  PolicyFormat as PF,
-  Scope,
-  MAX_CONTEXT_PROPERTY_ID,
-  Limits,
-  Op,
-  TypeCode,
-  classifyTypeCode,
-  lookupContextProperty,
-} from "./constants";
+import { hexToBytes, bytesToHex, readU16, readU32, bigintToHex, toAddress } from "./bytes";
+import { loadWord, readLength, readPointer } from "./calldata-reader";
+import { PolicyFormat as PF, Scope, Op, TypeCode, lookupContextProperty } from "./constants";
 import { CallciumError, PolicyViolationError } from "./errors";
-import { applyOperator, toBigInt, isLengthOp, isLengthValidType, canonicalize } from "./operators";
+import { applyOperator, toBigInt, isLengthValidType, canonicalize } from "./operators";
 import { decodePolicy } from "./policy-coder";
 
 import type { ReadResult } from "./calldata-reader";
 import type {
+  Address,
   Context,
   DecodedRule,
   EnforceResult,
@@ -30,20 +22,27 @@ import type {
 // Helpers
 ///////////////////////////////////////////////////////////////////////////
 
-/** Violations that abort evaluation instead of failing only their group (spec §9.3). */
-const ABORT_VIOLATION_CODES: ReadonlySet<ViolationCode> = new Set<ViolationCode>([
+/** Violations that abort evaluation instead of failing only their group. */
+const abortViolationCodes: ReadonlySet<ViolationCode> = new Set<ViolationCode>([
   "CALLDATA_OUT_OF_BOUNDS",
   "ARRAY_INDEX_OUT_OF_BOUNDS",
   "NON_CANONICAL_VALUE",
   "QUANTIFIER_LIMIT_EXCEEDED",
 ]);
 
-/** Convert a hex address to a 256-bit bigint (zero-padded to 32 bytes). */
-function addressToBigInt(hex: string): bigint {
-  const bytes = hexToBytes(hex);
-  const padded = new Uint8Array(32);
-  padded.set(bytes, 32 - bytes.length);
-  return toBigInt(padded, 0);
+/**
+ * Read a supplied context value as the 32-byte word that carries it.
+ * @throws {CallciumError} When an integer lies outside the range a 32-byte word represents.
+ */
+function contextValueToWord(value: bigint | Address): bigint {
+  if (typeof value === "string") return BigInt(toAddress(value));
+  if (BigInt.asUintN(256, value) !== value) {
+    throw new CallciumError(
+      "CONTEXT_VALUE_OVERFLOW",
+      `Context value ${value} is outside the range a 32-byte word represents`,
+    );
+  }
+  return value;
 }
 
 ///////////////////////////////////////////////////////////////////////////
@@ -56,7 +55,8 @@ function addressToBigInt(hex: string): bigint {
  * @param callData - ABI-encoded call data as 0x-prefixed hex string.
  * @param context - Optional execution context for context-scoped rules.
  * @returns Pass with matched group index, or fail with one violation per evaluated failing group.
- * @throws {CallciumError} If the policy blob is structurally malformed.
+ * @throws {CallciumError} If the policy blob is structurally malformed, or a context value a rule
+ * reads is not an address or an integer a 32-byte word represents.
  */
 function check(policy: Hex, callData: Hex, context?: Context): EnforceResult {
   const { policy: decoded, data: policyBytes } = decodePolicy(policy);
@@ -100,8 +100,8 @@ function check(policy: Hex, callData: Hex, context?: Context): EnforceResult {
       const violation = evaluateRule(rule, policyBytes, callDataBytes, baseOffset, groupIndex, ruleIndex, context);
       if (violation !== null) {
         allViolations.push(violation);
-        if (ABORT_VIOLATION_CODES.has(violation.code)) {
-          // Abort violations reject the policy outright; later groups are not consulted (spec §9.3).
+        if (abortViolationCodes.has(violation.code)) {
+          // Abort violations reject the policy outright; later groups are not consulted.
           return { ok: false, violations: allViolations };
         }
         groupFailed = true;
@@ -123,7 +123,8 @@ function check(policy: Hex, callData: Hex, context?: Context): EnforceResult {
  * @param callData - ABI-encoded call data as 0x-prefixed hex string.
  * @param context - Optional execution context for context-scoped rules.
  * @throws {PolicyViolationError} If the policy rejects the call data.
- * @throws {CallciumError} If the policy blob is structurally malformed.
+ * @throws {CallciumError} If the policy blob is structurally malformed, or a context value a rule
+ * reads is not an address or an integer a 32-byte word represents.
  */
 function enforce(policy: Hex, callData: Hex, context?: Context): void {
   const result = check(policy, callData, context);
@@ -177,15 +178,24 @@ function evaluateRule(
   );
 }
 
+/** An `EQ_CTX` operand resolved to its word, or the missing property's type code. */
+type ReferenceOperand = bigint | { ctxTypeCode: number };
+
 /**
  * Resolve an EQ_CTX operand word to the referenced context property's value as a raw word.
  * Returns the missing property's type code when the context does not supply it.
  */
-function resolveContextOperand(operandData: Uint8Array, context?: Context): bigint | { ctxTypeCode: number } {
-  const propInfo = lookupContextProperty(Number(toBigInt(operandData, 0)));
-  const value = context?.[propInfo.contextKey];
-  if (value === undefined) return { ctxTypeCode: propInfo.typeCode };
-  return typeof value === "string" ? addressToBigInt(value) : value;
+function resolveContextOperand(operandData: Uint8Array, context?: Context): ReferenceOperand {
+  const propertyInfo = lookupContextProperty(Number(toBigInt(operandData, 0)));
+  const value = context?.[propertyInfo.contextKey];
+  if (value === undefined) return { ctxTypeCode: propertyInfo.typeCode };
+  return contextValueToWord(value);
+}
+
+/** Resolve the reference operand of an `EQ_CTX` rule; every other operator reads a literal. */
+function referenceOperand(opCode: number, operandData: Uint8Array, context?: Context): ReferenceOperand | undefined {
+  if ((opCode & ~Op.NOT) !== Op.EQ_CTX) return undefined;
+  return resolveContextOperand(operandData, context);
 }
 
 ///////////////////////////////////////////////////////////////////////////
@@ -237,8 +247,8 @@ function chainResolve(
     const meta = readU16(hint, hop + PF.HINT_HOP_META_OFFSET);
     let elems = base;
     if ((meta & PF.HINT_META_DYNAMIC_ARRAY) !== 0) {
-      const length = readPointer(callData, elems);
-      if (typeof length !== "number") return length;
+      const length = readLength(callData, elems);
+      if (typeof length !== "bigint") return length;
       if (index >= length) return { code: "ARRAY_INDEX_OUT_OF_BOUNDS" };
       elems += 32;
     }
@@ -278,30 +288,24 @@ function evalTarget(
   block: TargetBlock,
   opCode: number,
   operandData: Uint8Array,
-  context?: Context,
+  ctxOperand?: ReferenceOperand,
 ): TargetResult {
   const typeCode = block.typeCode;
 
   // A dynamic target's chain ends at its payload, so the word there is the declared length.
   if (isLengthValidType(typeCode)) {
-    if (!isLengthOp(opCode)) {
-      throw new CallciumError("OPERATOR_TARGET_MISMATCH", "Value operator on a target without a scalar word.");
-    }
-    const length = readPointer(callData, target);
-    if (typeof length !== "number") return { error: length.code };
+    const length = readLength(callData, target);
+    if (typeof length !== "bigint") return { error: length.code };
 
     // The declared payload of `length` items must lie within calldata past the length word.
     const stride = typeCode === TypeCode.DYNAMIC_ARRAY ? (block.targetMeta & PF.HINT_META_STRIDE_MASK) * 32 : 1;
     const room = callData.length - (target + 32);
-    if (stride !== 0 && length > Math.floor(room / stride)) return { error: "CALLDATA_OUT_OF_BOUNDS" };
+    if (stride !== 0 && length > BigInt(Math.floor(room / stride))) return { error: "CALLDATA_OUT_OF_BOUNDS" };
 
     const passed = applyOperator(opCode, 0n, length, operandData, typeCode);
-    return { passed, value: BigInt(length) };
+    return { passed, value: length };
   }
 
-  if (classifyTypeCode(typeCode).typeClass !== "elementary") {
-    throw new CallciumError("OPERATOR_TARGET_MISMATCH", "Operator target does not carry a scalar word.");
-  }
   const word = loadWord(callData, target);
   if (!(word instanceof Uint8Array)) return { error: word.code };
 
@@ -310,14 +314,13 @@ function evalTarget(
     return { error: "NON_CANONICAL_VALUE", value };
   }
 
-  if ((opCode & ~Op.NOT) === Op.EQ_CTX) {
-    const operand = resolveContextOperand(operandData, context);
-    if (typeof operand !== "bigint") return { error: "MISSING_CONTEXT", ctxTypeCode: operand.ctxTypeCode };
-    const passed = (value === operand) !== ((opCode & Op.NOT) !== 0);
-    return { passed, value, ctxOperand: operand };
+  if (ctxOperand !== undefined) {
+    if (typeof ctxOperand !== "bigint") return { error: "MISSING_CONTEXT", ctxTypeCode: ctxOperand.ctxTypeCode };
+    const passed = (value === ctxOperand) !== ((opCode & Op.NOT) !== 0);
+    return { passed, value, ctxOperand };
   }
 
-  const passed = applyOperator(opCode, value, 32, operandData, typeCode);
+  const passed = applyOperator(opCode, value, 32n, operandData, typeCode);
   return { passed, value };
 }
 
@@ -335,17 +338,24 @@ type RuleFrame = {
   typeCode: number;
 };
 
-/** Build a navigation violation for a read the enforcer cannot perform. */
-function navigationViolation(frame: RuleFrame, code: NavigationViolationCode, elementIndex?: number): Violation {
+/** The coordinates, target and operator fields every violation of a calldata rule carries. */
+function ruleFields(frame: RuleFrame) {
   return {
     group: frame.group,
     rule: frame.rule,
-    code,
     scope: Scope.CALLDATA,
     path: frame.path,
     opCode: frame.opCode,
     operandData: bytesToHex(frame.operandData),
     typeCode: frame.typeCode,
+  };
+}
+
+/** Build a navigation violation for a read the enforcer cannot perform. */
+function navigationViolation(frame: RuleFrame, code: NavigationViolationCode, elementIndex?: number): Violation {
+  return {
+    code,
+    ...ruleFields(frame),
     ...(elementIndex !== undefined && { elementIndex }),
   };
 }
@@ -354,27 +364,17 @@ function navigationViolation(frame: RuleFrame, code: NavigationViolationCode, el
 function targetViolation(frame: RuleFrame, result: TargetResult, elementIndex?: number): Violation | null {
   if ("error" in result) {
     if (result.error === "MISSING_CONTEXT") {
+      // The type reported is the absent property's, not the target the operator reads.
       return {
-        group: frame.group,
-        rule: frame.rule,
         code: result.error,
-        scope: Scope.CALLDATA,
-        path: frame.path,
-        opCode: frame.opCode,
-        operandData: bytesToHex(frame.operandData),
+        ...ruleFields(frame),
         typeCode: result.ctxTypeCode,
       };
     }
     if (result.error === "NON_CANONICAL_VALUE") {
       return {
-        group: frame.group,
-        rule: frame.rule,
         code: result.error,
-        scope: Scope.CALLDATA,
-        path: frame.path,
-        opCode: frame.opCode,
-        operandData: bytesToHex(frame.operandData),
-        typeCode: frame.typeCode,
+        ...ruleFields(frame),
         resolvedValue: bigintToHex(result.value),
         ...(elementIndex !== undefined && { elementIndex }),
       };
@@ -384,14 +384,8 @@ function targetViolation(frame: RuleFrame, result: TargetResult, elementIndex?:
 
   if (result.passed) return null;
   return {
-    group: frame.group,
-    rule: frame.rule,
     code: "VALUE_MISMATCH",
-    scope: Scope.CALLDATA,
-    path: frame.path,
-    opCode: frame.opCode,
-    operandData: bytesToHex(frame.operandData),
-    typeCode: frame.typeCode,
+    ...ruleFields(frame),
     resolvedValue: bigintToHex(result.value),
     ...(result.ctxOperand !== undefined && { resolvedOperand: bigintToHex(result.ctxOperand) }),
     ...(elementIndex !== undefined && { elementIndex }),
@@ -447,7 +441,14 @@ function evaluateCalldataRule(
 
   return targetViolation(
     frame,
-    evalTarget(callDataBytes, base + block.targetDelta, block, opCode, operandData, context),
+    evalTarget(
+      callDataBytes,
+      base + block.targetDelta,
+      block,
+      opCode,
+      operandData,
+      referenceOperand(opCode, operandData, context),
+    ),
   );
 }
 
@@ -492,27 +493,27 @@ function evaluateQuantified(
   let elems = chained + arrayDelta;
 
   // A frame declaring no count spans a dynamic array, whose length word precedes its elements.
-  let count = readU16(hint, frameOffset + PF.HINT_FRAME_COUNT_OFFSET);
-  if (count === 0) {
-    const length = readPointer(callDataBytes, elems);
-    if (typeof length !== "number") return navigationViolation(frame, length.code);
+  let count = BigInt(readU16(hint, frameOffset + PF.HINT_FRAME_COUNT_OFFSET));
+  if (count === 0n) {
+    const length = readLength(callDataBytes, elems);
+    if (typeof length !== "bigint") return navigationViolation(frame, length.code);
     count = length;
     elems += 32;
   }
 
-  if (count > Limits.MAX_QUANTIFIED_ARRAY_LENGTH) {
+  if (count > BigInt(PF.MAX_QUANTIFIED_ARRAY_LENGTH)) {
     return {
       group: groupIndex,
       rule: ruleIndex,
       code: "QUANTIFIER_LIMIT_EXCEEDED",
       scope: Scope.CALLDATA,
       path: pathHex,
-      resolvedValue: bigintToHex(BigInt(count)),
+      resolvedValue: bigintToHex(count),
     };
   }
 
   const isUniversal = kind === PF.HINT_KIND_ALL;
-  if (count === 0) {
+  if (count === 0n) {
     if (isUniversal) return null;
     return {
       group: groupIndex,
@@ -527,15 +528,16 @@ function evaluateQuantified(
   const elemStride = (meta & PF.HINT_META_STRIDE_MASK) * 32;
   const elemIsDynamic = (meta & PF.HINT_META_ELEM_DYNAMIC) !== 0;
 
-  // A reference operand resolves identically for every element; any element's result carries it.
-  let ctxOperand: bigint | undefined;
+  // A reference operand resolves identically for every element, so it resolves before iterating.
+  const reference = referenceOperand(opCode, operandData, context);
+
   for (let elemIndex = 0; elemIndex < count; elemIndex++) {
     const slot = elems + elemIndex * elemStride;
     let elem: number = slot;
     if (elemIsDynamic) {
       const followed = follow(callDataBytes, elems, slot);
       // Navigation failures abort under every quantifier: calldata the enforcer cannot read is
-      // not an element that merely fails the operator (spec §9.3).
+      // not an element that merely fails the operator.
       if (typeof followed !== "number") return navigationViolation(frame, followed.code, elemIndex);
       elem = followed;
     }
@@ -547,10 +549,10 @@ function evaluateQuantified(
       base = chainedElem;
     }
 
-    const applied = evalTarget(callDataBytes, base + block.targetDelta, block, opCode, operandData, context);
+    const applied = evalTarget(callDataBytes, base + block.targetDelta, block, opCode, operandData, reference);
     if ("error" in applied) {
       // Error results end the rule whatever the quantifier: a later element cannot rescue
-      // calldata the enforcer cannot read (abort effects, spec §9.3), and a missing context
+      // calldata the enforcer cannot read (an abort effect), and a missing context
       // property is missing for every element alike (group-local).
       return targetViolation(frame, applied, elemIndex);
     }
@@ -561,21 +563,14 @@ function evaluateQuantified(
     } else if (isUniversal) {
       return targetViolation(frame, applied, elemIndex);
     }
-    ctxOperand = applied.ctxOperand;
   }
 
   if (isUniversal) return null;
   // Existential (ANY) failure: every element rejected the constraint.
   return {
-    group: groupIndex,
-    rule: ruleIndex,
     code: "VALUE_MISMATCH",
-    scope: Scope.CALLDATA,
-    path: pathHex,
-    opCode,
-    operandData: bytesToHex(operandData),
-    typeCode: block.typeCode,
-    ...(ctxOperand !== undefined && { resolvedOperand: bigintToHex(ctxOperand) }),
+    ...ruleFields(frame),
+    ...(typeof reference === "bigint" && { resolvedOperand: bigintToHex(reference) }),
   };
 }
 
@@ -594,34 +589,15 @@ function evaluateContextRule(
   context?: Context,
 ): Violation | null {
   const propertyId = readU16(pathBytes, 0);
-
-  if (propertyId > MAX_CONTEXT_PROPERTY_ID) {
-    throw new CallciumError(
-      "UNKNOWN_CONTEXT_PROPERTY",
-      `Unknown context property ID 0x${propertyId.toString(16).padStart(4, "0")}`,
-    );
-  }
-
-  const propInfo = lookupContextProperty(propertyId);
-  const contextValue = context?.[propInfo.contextKey];
+  const propertyInfo = lookupContextProperty(propertyId);
+  const contextValue = context?.[propertyInfo.contextKey];
+  const site = { group: groupIndex, rule: ruleIndex, scope: Scope.CONTEXT, path: pathHex };
 
   if (contextValue === undefined) {
-    return {
-      group: groupIndex,
-      rule: ruleIndex,
-      code: "MISSING_CONTEXT",
-      scope: Scope.CONTEXT,
-      path: pathHex,
-      typeCode: propInfo.typeCode,
-    };
+    return { code: "MISSING_CONTEXT", ...site, typeCode: propertyInfo.typeCode };
   }
 
-  let value: bigint;
-  if (typeof contextValue === "string") {
-    value = addressToBigInt(contextValue);
-  } else {
-    value = contextValue;
-  }
+  const value = contextValueToWord(contextValue);
 
   let result: boolean;
   let ctxOperand: bigint | undefined;
@@ -629,11 +605,8 @@ function evaluateContextRule(
     const operand = resolveContextOperand(operandData, context);
     if (typeof operand !== "bigint") {
       return {
-        group: groupIndex,
-        rule: ruleIndex,
         code: "MISSING_CONTEXT",
-        scope: Scope.CONTEXT,
-        path: pathHex,
+        ...site,
         opCode,
         operandData: bytesToHex(operandData),
         typeCode: operand.ctxTypeCode,
@@ -642,19 +615,16 @@ function evaluateContextRule(
     result = (value === operand) !== ((opCode & Op.NOT) !== 0);
     ctxOperand = operand;
   } else {
-    result = applyOperator(opCode, value, 32, operandData, propInfo.typeCode);
+    result = applyOperator(opCode, value, 32n, operandData, propertyInfo.typeCode);
   }
 
   if (!result) {
     return {
-      group: groupIndex,
-      rule: ruleIndex,
       code: "VALUE_MISMATCH",
-      scope: Scope.CONTEXT,
-      path: pathHex,
+      ...site,
       opCode,
       operandData: bytesToHex(operandData),
-      typeCode: propInfo.typeCode,
+      typeCode: propertyInfo.typeCode,
       resolvedValue: bigintToHex(value),
       ...(ctxOperand !== undefined && { resolvedOperand: bigintToHex(ctxOperand) }),
     };