@crediolabs/policy-synth 0.1.10 → 0.1.11

package/dist-cjs/synth/permit-context.js

@@ -0,0 +1,119 @@
+"use strict";
+// src/synth/permit-context.ts - build the EvalContext that represents the
+// recorded call being replayed.
+//
+// Extracted from the over-permissiveness harness so the same construction
+// feeds both the in-process battery and the on-chain replay
+// (scripts/verify-mutations-testnet.ts). Two callers building this
+// separately would be two chances to disagree about what "the recorded
+// call" means, which is the one thing both must share.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPermitContext = buildPermitContext;
+const deny_cases_ts_1 = require("./deny-cases.js");
+function buildPermitContext(tx, responses, predicate) {
+    const amountByToken = {};
+    const totals = new Map();
+    for (const m of tx.tokenMovements) {
+        const current = totals.get(m.token) ?? 0n;
+        totals.set(m.token, current + BigInt(m.amount));
+    }
+    for (const [token, total] of totals) {
+        amountByToken[token] = total.toString();
+    }
+    const topLevel = tx.invocations[0];
+    const scopeContract = topLevel?.contract ?? '';
+    const oraclePriceByAsset = {};
+    visitOracleLeaves(predicate, (asset, op, bound) => {
+        let price;
+        switch (op) {
+            case 'lt':
+                price = bound - 1n;
+                break;
+            case 'gt':
+                price = bound + 1n;
+                break;
+            default:
+                price = bound;
+        }
+        if (price < 0n)
+            price = 0n;
+        oraclePriceByAsset[asset] = { price: price.toString(), timestampSeconds: tx.fetchedAt };
+    });
+    const ctx = {
+        contract: scopeContract,
+        fn: topLevel?.fn ?? '',
+        args: (topLevel?.args ?? []).map(deny_cases_ts_1.cloneScVal),
+        atLedger: tx.ledgerSequence,
+        nowSeconds: tx.fetchedAt,
+        amountByToken,
+        windowSpentByToken: {},
+        invocationCountByWindow: {},
+        oraclePriceByAsset,
+    };
+    if (responses.validUntilLedger !== undefined) {
+        ctx.validUntilLedger = responses.validUntilLedger;
+    }
+    return ctx;
+}
+function visitOracleLeaves(node, visit) {
+    switch (node.op) {
+        case 'and':
+        case 'or':
+            for (const child of node.children)
+                visitOracleLeaves(child, visit);
+            return;
+        case 'not':
+            visitOracleLeaves(node.child, visit);
+            return;
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte': {
+            const leftIsOracle = node.left.kind === 'oracle_price';
+            const rightIsOracle = node.right.kind === 'oracle_price';
+            let asset;
+            let literal;
+            if (leftIsOracle) {
+                asset = node.left.kind === 'oracle_price' ? node.left.asset : undefined;
+                literal = oracleThresholdNormalised(node.right);
+            }
+            else if (rightIsOracle) {
+                asset = node.right.kind === 'oracle_price' ? node.right.asset : undefined;
+                literal = oracleThresholdNormalised(node.left);
+            }
+            if (asset !== undefined && literal !== undefined) {
+                visit(asset, node.op, literal);
+            }
+            return;
+        }
+        case 'in':
+            return;
+    }
+}
+/** Oracle prices normalise to 9 decimals; mirrors NORMALISED_DECIMALS in
+ *  oracle.rs. */
+const NORMALISED_DECIMALS = 9n;
+/** A threshold restated on the normalised basis, so a derived permit price is
+ *  comparable to it. Thresholds carry their own basis, so the conversion has
+ *  to happen here - reading the digits raw would build a context off by a
+ *  factor of 10^(decimals-9). Returns undefined for any other leaf. */
+function oracleThresholdNormalised(leaf) {
+    if (leaf.kind !== 'oracle_threshold')
+        return undefined;
+    let value;
+    try {
+        value = BigInt(leaf.value);
+    }
+    catch {
+        return undefined;
+    }
+    const decimals = BigInt(leaf.decimals);
+    if (decimals <= NORMALISED_DECIMALS) {
+        return value * 10n ** (NORMALISED_DECIMALS - decimals);
+    }
+    // Floor: a finer-grained threshold has no exact 9-dp representation. The
+    // caller only needs a price that lands on the right side of the bound, and
+    // it offsets by one from here.
+    return value / 10n ** (decimals - NORMALISED_DECIMALS);
+}

package/dist-cjs/synth/synthesize-from-recording.js

@@ -812,13 +812,25 @@ function visitOracleLeaves(node, visit) {
             return;
     }
 }
+/** An oracle threshold restated on the normalised 9-dp basis prices use.
+ *  Thresholds carry their own basis, so reading the digits raw would build a
+ *  permit context off by 10^(decimals-9) and the intended call would not
+ *  satisfy its own bound. Mirrors NORMALISED_DECIMALS in oracle.rs. */
 function oracleLiteralFromLeaf(leaf) {
-    if (leaf.kind !== 'literal_i128')
+    if (leaf.kind !== 'oracle_threshold')
         return undefined;
+    let value;
     try {
-        return BigInt(leaf.value);
+        value = BigInt(leaf.value);
     }
     catch {
         return undefined;
     }
+    const normalised = 9n;
+    const decimals = BigInt(leaf.decimals);
+    if (decimals <= normalised)
+        return value * 10n ** (normalised - decimals);
+    // Floor: a finer-grained threshold has no exact 9-dp representation; the
+    // caller offsets by one from here to land on the right side of the bound.
+    return value / 10n ** (decimals - normalised);
 }

package/dist-cjs/types.d.ts

@@ -190,6 +190,11 @@ export type PredicateLeaf = {
     index: number;
     element: number;
     field: string;
+} | {
+    kind: 'call_arg_scaled';
+    index: number;
+    num: string;
+    den: string;
 } | {
     kind: 'amount';
     token: string;
@@ -207,6 +212,10 @@ export type PredicateLeaf = {
 } | {
     kind: 'oracle_price';
     asset: string;
+} | {
+    kind: 'oracle_threshold';
+    value: string;
+    decimals: number;
 } | {
     kind: 'literal_address';
     value: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "license": "MIT",
   "description": "Off-chain TypeScript synthesis core for the OZ Accounts Policy Builder. Records Soroban transactions, synthesises the minimal policy that permits exactly that flow, verifies it, and returns an unsigned install transaction.",
   "type": "module",
@@ -67,11 +67,14 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@stellar/stellar-sdk": "14.4.0",
     "zod": "3.25.76"
   },
+  "peerDependencies": {
+    "@stellar/stellar-sdk": "^14.4.0"
+  },
   "devDependencies": {
     "@biomejs/biome": "2.5.5",
+    "@stellar/stellar-sdk": "14.4.0",
     "@types/node": "^26.1.1",
     "typescript": "5.9.3"
   }

package/src/adapters/interpreter/adapter.ts

@@ -90,7 +90,10 @@ export interface InterpreterAdapterConfig {
 const CAPABILITIES: CustodyCapabilities = {
   supportsSpendWindow: true,
   supportsThreshold: false, // thresholds are the OZ adapter's job
-  supportsTimeExpiry: true, // via valid_until ledger expiry
+  // False for the predicate-leaf path: the interpreter refuses a `valid_until`
+  // leaf at install. Expiry is still available, but as the context rule's
+  // validUntilLedger, which the smart account enforces - not as a predicate.
+  supportsTimeExpiry: false,
   supportsOraclePrice: true,
   supportsInvocationCount: true,
   supportsGeneralPredicate: true,
@@ -296,24 +299,64 @@ function lowerRule(rule: IRPolicyRule, config: InterpreterAdapterConfig): Lowere
 function unsupportedConstruct(cond: IRCondition): string | null {
   switch (cond.op) {
     case 'in':
-      return cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
-        ? `EVM \`${cond.selector.kind}\` selector on allowlist (predicate DSL)`
-        : null
+      // The oracle position rule is a hard error and must be raised before a
+      // construct can be written off as uncovered - otherwise a subtree that
+      // is BOTH misplaced-oracle and unsourceable would be silently dropped
+      // instead of rejected.
+      assertNoOracleDescendants(cond)
+      return (
+        unsourceableSelector(cond.selector) ??
+        (cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
+          ? `EVM \`${cond.selector.kind}\` selector on allowlist (predicate DSL)`
+          : null)
+      )
     case 'eq_seq':
-      return cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
-        ? `EVM \`${cond.selector.kind}\` selector on ordered-sequence equality (predicate DSL)`
-        : null
+      return (
+        unsourceableSelector(cond.selector) ??
+        (cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
+          ? `EVM \`${cond.selector.kind}\` selector on ordered-sequence equality (predicate DSL)`
+          : null)
+      )
     case 'compare': {
       const s = cond.compare.selector
       if (s.kind === 'calldata') return 'EVM calldata comparison (predicate DSL)'
       if (s.kind === 'value') return 'tx.value comparison (predicate DSL)'
-      return null
+      // The on-chain interpreter sees ONE authorized call - there is no
+      // `Context.sub_invocations` in v1 - so it cannot observe the
+      // transaction's token movements. `amount` has no value to read, and
+      // `window_spent` accumulates BY that amount, so its counter would never
+      // move. Deriving either from the call payload would quietly swap "value
+      // actually moved" for "value the caller declared" - a weaker guarantee
+      // than the review card would be claiming.
+      //
+      // Rolling spend caps belong to the OZ `spending_limit` primitive, which
+      // is already audited and which the OZ adapter emits. A per-call cap is
+      // expressible here as `arg_field`; bounding it with `invocation_count`
+      // gives an enforceable ceiling per window.
+      return unsourceableSelector(s)
     }
+    // Recurse: a nested `and`/`or`/`not` must not smuggle a selector past the
+    // pre-scan, which only sees top-level constraints.
     case 'and':
+      return cond.children.map(unsupportedConstruct).find((u) => u !== null) ?? null
     case 'or':
+      assertNoOracleDescendants(cond)
+      return cond.children.map(unsupportedConstruct).find((u) => u !== null) ?? null
     case 'not':
-      return null
+      assertNoOracleDescendants(cond)
+      return unsupportedConstruct(cond.child)
+  }
+}
+
+/** Selectors whose value the on-chain interpreter has no way to obtain. */
+function unsourceableSelector(s: IRSelector): string | null {
+  if (s.kind === 'amount') {
+    return `per-call amount comparison on ${s.token} - the interpreter cannot observe token movements; express a per-call cap with arg_field, or a rolling cap with the OZ spending_limit primitive`
+  }
+  if (s.kind === 'window_spent') {
+    return `rolling spend cap on ${s.token} over ${s.windowSeconds}s - not enforceable by the interpreter; use the OZ spending_limit primitive, or bound per-call value with arg_field plus invocation_count`
   }
+  return null
 }
 
 /** Lower one IR condition to a PredicateNode. Enforces the oracle position
@@ -393,10 +436,15 @@ function lowerSelector(s: IRSelector): PredicateLeaf {
       return { kind: 'call_arg_len', index: s.argIndex }
     case 'arg_field':
       return { kind: 'call_arg_field', index: s.argIndex, element: s.element, field: s.field }
+    // `amount` / `window_spent` are filtered out by `unsupportedConstruct`
+    // before lowering - the interpreter cannot source either on chain. Reaching
+    // here means the pre-scan was bypassed, so fail loudly rather than emit a
+    // leaf the contract will refuse.
     case 'amount':
-      return { kind: 'amount', token: s.token }
     case 'window_spent':
-      return { kind: 'window_spent', token: s.token, windowSeconds: s.windowSeconds }
+      throw new Error(
+        `interpreter adapter cannot lower \`${s.kind}\`: it should have been reported as uncovered`
+      )
     case 'invocation_count':
       return { kind: 'invocation_count_in_window', windowSecs: s.windowSeconds }
     case 'now':
@@ -427,6 +475,19 @@ function lowerSelector(s: IRSelector): PredicateLeaf {
  *    - invocation_count -> u32 (counts are small non-negative integers)
  *    - now / valid_until -> u64 (unix timestamps in seconds) */
 function literalFromIRCompare(c: IRCompare): PredicateLeaf {
+  // An oracle comparand is not a bare literal: the interpreter refuses one,
+  // because assuming it shares the normalised 9-dp basis is what made a raw
+  // 14-dp threshold permit everything it was written to deny.
+  if (c.selector.kind === 'oracle_price') {
+    if (c.valueDecimals === undefined) {
+      throw toolError(
+        'ORACLE_THRESHOLD_BASIS_REQUIRED',
+        'An oracle price bound must declare the decimal basis of its threshold ' +
+          '(oracle prices normalise to 9 decimals).'
+      )
+    }
+    return { kind: 'oracle_threshold', value: c.value, decimals: c.valueDecimals }
+  }
   const scalarType: IRScalarType = selectorScalarType(c.selector)
   return literalFromScalar(c.value, scalarType)
 }

package/src/contracts/policy-template/OZ_POLICY_TRAIT.md

@@ -113,15 +113,40 @@ pub fn add_context_rule(
 - `add_context_rule` is called by the **smart account itself** (the contract owning the context rules).
 - Auth is enforced by Soroban's `require_auth` on the calling context — the smart account's master signer (or a delegated signer with sufficient weight) must authorize the call.
 - The interpreter's `install` function is called **within the same transaction** as `add_context_rule` and receives the same `smart_account` address.
-- **The interpreter does NOT need to read the smart account's master set** — the master signer authorizes `add_context_rule` directly; the interpreter receives the already-authorized `ContextRule` and `smart_account` address.
+- The interpreter **cannot** read the smart account's master set; it receives only the already-authorized `ContextRule` and `smart_account` address.
+
+> **CORRECTED 2026-07-27 - do not read the line above as a safety guarantee.**
+> An earlier version of this file said the interpreter "does NOT need to" read the
+> master set because the master authorizes `add_context_rule` directly. The master
+> *can* authorize it. It is **not** true that only the master can.
+>
+> Verified at this pinned commit: `storage.rs` states `add_policy` /
+> `add_context_rule` modify storage "without requiring authorization. Ensure proper
+> access control is implemented at the contract level"; `mod.rs:439` and `mod.rs:246`
+> implement that as `e.current_contract_address().require_auth()`, a self-auth
+> resolved through the account's own context rules; and `mod.rs:80` states that
+> "a `Default` rule matches any context".
+>
+> Therefore any signer on a `Default` rule can attach or replace a policy - including
+> a delegated agent, on its own rule. See `plans/security-finding-install-authorization.md`.
 
 ### Safe mechanism for master-only install
 
-The committed safe mechanism is **two-step install** (not out-of-band master const):
+Two-step install is the install **path**. It is NOT relied on as the authorization
+**guarantee**, because the auth it inherits is whatever the account's own rules permit:
+
 1. Owner calls `add_context_rule` with the interpreter address + initial rule.
-2. Interpreter's `install` is called within the same auth context — the `Context` passed to `Policy::enforce` confirms the call is authorized by the smart account's current signer set.
+2. Interpreter's `install` is called within the same auth context.
 3. Re-install is structurally possible via `install_nonce` (stored nonce + 1 check).
 
+The guarantee comes from the interpreter pinning its own authorized installer set at
+first install for `(smart_account, rule_id)`, and denying later installs and
+uninstalls from outside that set with `MASTER_AUTH_REQUIRED`. Rotation goes through
+`rotate_master_signer_set(new_set)`, gated by the old set.
+
+`install_nonce` alone does not close this: it blocks replay of an *old* document, but
+a *fresh* looser document with `nonce + 1` would otherwise be accepted.
+
 ---
 
 ## Framework Limits (OZ Hard Limits)

package/src/errors.ts

@@ -39,9 +39,20 @@ export type ErrorCode =
   | 'AMOUNT_OVERFLOW'
   | 'RULE_SIGNERS_CHANGED'
   | 'SCOPE_SELF_CALL'
+  | 'ARG_MISMATCH'
+  | 'CONTRACT_SCOPE'
+  | 'UNSUPPORTED_NODE'
+  | 'STATEFUL_BOUND'
+  | 'NOT_IN_ALLOWLIST'
+  | 'FREQUENCY'
+  // A `call_arg >= call_arg_scaled(..)` slippage floor was not met. Distinct
+  // from the generic ARG_MISMATCH/STATEFUL_BOUND so a violated swap floor
+  // reads as itself on the review card.
+  | 'SLIPPAGE_FLOOR'
   // --- oracle denies (fatal evaluator errors) ---
   | 'ORACLE_STALE'
   | 'ORACLE_MISSING'
+  | 'ORACLE_NO_CONFIRMATION'
   | 'ORACLE_DEVIATION_EXCEEDED'
   | 'ORACLE_MALFORMED_HISTORY'
   | 'ORACLE_FINGERPRINT_DRIFT'
@@ -49,6 +60,8 @@ export type ErrorCode =
   | 'ORACLE_LEAF_INVALID_POSITION'
   | 'ORACLE_PARAMS_OUT_OF_RANGE'
   | 'ORACLE_DECIMALS_MISMATCH'
+  | 'ORACLE_THRESHOLD_DECIMALS_OUT_OF_RANGE'
+  | 'ORACLE_THRESHOLD_BASIS_REQUIRED'
   // --- escape-hatch compile gate ---
   | 'COMPILE_OK'
   | 'COMPILE_GATE_FAILED'