@crediolabs/policy-synth 0.1.3 → 0.1.5

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

@@ -0,0 +1,356 @@
+"use strict";
+// src/synth/compose-from-recording.ts - facts + scope -> PolicyIR (OZ-shape + interpreter-shape).
+//
+// Composes the canonical IR rules the two backends compile FROM. Fail-closed
+// composition rules:
+//
+//   - identify the protocol of the top-level call (registry.identifyProtocol).
+//     When it is unknown (null), emit NO OZ-primitive-producing IR node: the
+//     scope is kept (CallContract + method) and every inferred bound is surfaced
+//     as a descriptive warning. An unrecognised call never compiles to a
+//     permissive OZ primitive.
+//
+//   - carry the recorded top-level function into `rule.scope.method` so the OZ
+//     adapter flags per-method scoping as not covered (CallContract permits every
+//     method on the contract; a per-method restriction needs the interpreter predicate).
+//
+//   - a `spending_limit` (window_spent(token, w) <= limit) is emitted ONLY when
+//     the caller supplies BOTH the limit (userResponses.limitAmount) and the
+//     window (userResponses.windowSeconds). A single recorded spend does NOT
+//     authorise that amount every window, so the observed amount is NEVER used as
+//     an auto-ceiling: a missing limit surfaces AMOUNT_BOUND_MISSING (the observed
+//     amount is offered as a suggestion), a missing window surfaces
+//     DURATION_UNSPECIFIED. EVERY spent token is handled - none is silently
+//     dropped; a single caller limit binds only an unambiguous single-token spend.
+//
+//   - incoming-only flows (e.g. Blend yield claim) emit an `invocation_count`
+//     bound ONLY when the caller supplies the count (userResponses.invocationLimit)
+//     and a window; otherwise FREQUENCY_BOUND_MISSING is surfaced with no
+//     fabricated count.
+//
+//   - the IR carries ONLY constraints justified by the recording (observed
+//     recipient allowlist) + explicit user input. Nothing invented: no oracle
+//     price fabricated from a slippage bound, no synthetic exact-path compare.
+//     Those needs are surfaced as descriptive warnings instead.
+//
+// Split rule (P3 wiring): `ComposeResult` carries BOTH `ir` (OZ-shape) and
+// `interpreterIr` (predicate-shape). Each constraint is routed to EXACTLY ONE
+// adapter:
+//   - `compare window_spent(token, w) <= limit` where `token === scope.contract`
+//     and the protocol is known -> `ir` (OZ lowers to spending_limit).
+//   - everything else the compose step emits (recipient allowlists, per-method
+//     scoping via scope.method, invocation_count bounds, eq_seq swap paths,
+//     oracle_price bounds, AND window_spent where token != scope.contract, i.e.
+//     a SoroSwap input-token cap) -> `interpreterIr`.
+//
+// This prevents the interpreter adapter from emitting a duplicate
+// `window_spent` predicate leaf alongside an OZ `spending_limit` primitive
+// covering the same spend semantic - the two adapters never overlap.
+//
+// The default behavior is `deny_all` (OZ context rules are deny-by-default).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeFromRecording = composeFromRecording;
+const identify_ts_1 = require("../registry/identify.js");
+/** Compose a PolicyIR pair from the lowered facts + the resolved scope.
+ *  Pure (no randomness, no clock); same inputs -> byte-identical result. */
+function composeFromRecording(facts, scopeContract, topLevel, opts) {
+    const interpreterEnabled = opts.interpreterEnabled === true;
+    const ambiguities = [];
+    const warnings = [];
+    const ozConstraints = [];
+    const interpreterConstraints = [];
+    const protocol = topLevel
+        ? (0, identify_ts_1.identifyProtocol)(topLevel.contract, topLevel.fn, topLevel.args, opts.network)
+        : null;
+    const known = protocol !== null;
+    const windowSeconds = opts.userResponses?.windowSeconds;
+    const limitAmount = opts.userResponses?.limitAmount;
+    const spendTokens = Object.keys(facts.spendByToken);
+    // Outgoing spend -> one spending_limit per spent token. A single caller limit
+    // binds only an unambiguous single-token spend; a multi-token flow needs a
+    // per-token limit, so each unmatched token surfaces AMOUNT_BOUND_MISSING.
+    //
+    // Routing: a `window_spent(token, w) <= limit` constraint goes to the OZ IR
+    // only when token === scope.contract (OZ's spending_limit binds the
+    // CallContract target, not a token parameter). Otherwise it goes to the
+    // interpreter IR (the interpreter lowers window_spent to a predicate leaf).
+    if (spendTokens.length > 0 && topLevel) {
+        let durationFlagged = false;
+        for (const token of spendTokens) {
+            const observed = facts.spendByToken[token];
+            if (observed === undefined)
+                continue;
+            if (!known) {
+                warnings.push(`spend of ${observed} (token ${token}) not bounded: unrecognised protocol, spend cap needs the interpreter predicate`);
+                continue;
+            }
+            const limit = spendTokens.length === 1 ? limitAmount : undefined;
+            if (windowSeconds === undefined && !durationFlagged) {
+                ambiguities.push({
+                    code: 'DURATION_UNSPECIFIED',
+                    question: `Recording shows a ${observed}-${token} spend. What rolling window (seconds) should the spending_limit use?`,
+                });
+                durationFlagged = true;
+            }
+            if (limit === undefined) {
+                ambiguities.push({
+                    code: 'AMOUNT_BOUND_MISSING',
+                    question: `Recording shows a ${observed}-${token} spend, but a single spend does not authorise that amount every window. What per-window spending_limit should apply? (observed amount, suggestion only: ${observed})`,
+                });
+                continue;
+            }
+            if (windowSeconds !== undefined && limit !== undefined) {
+                const spendCond = {
+                    op: 'compare',
+                    compare: {
+                        selector: { kind: 'window_spent', token, windowSeconds },
+                        operator: 'lte',
+                        value: limit,
+                    },
+                };
+                if (!interpreterEnabled || token === scopeContract) {
+                    ozConstraints.push(spendCond);
+                }
+                else {
+                    interpreterConstraints.push(spendCond);
+                }
+            }
+        }
+    }
+    // Incoming-only / frequency intent: an invocation_count bound is emitted ONLY
+    // when the caller supplies the count AND a window - never a fabricated `<= 1`.
+    // Routed to the interpreter IR when interpreter is enabled (OZ cannot lower
+    // invocation_count); otherwise to the OZ IR (which flags it as uncovered).
+    //
+    // A recognised swap is NOT an incoming-only flow: it has an outgoing input leg
+    // whose spend simply was not attributed to the source account (the
+    // fee-sponsored / holder != source case). Its real restrictions - exact path,
+    // recipient, and the input-amount cap - come from the protocol-specific pass,
+    // so it does NOT get the incoming-only frequency prompt. A caller who wants to
+    // rate-limit the swap can still supply an invocationLimit + window, which
+    // lowers to an invocation_count for any flow.
+    if (spendTokens.length === 0 && topLevel) {
+        const invocationLimit = opts.userResponses?.invocationLimit;
+        const isRecognisedSwap = protocol?.protocol === 'soroswap';
+        if (known && windowSeconds !== undefined && invocationLimit !== undefined) {
+            const icCond = {
+                op: 'compare',
+                compare: {
+                    selector: { kind: 'invocation_count', windowSeconds },
+                    operator: 'lte',
+                    value: String(invocationLimit),
+                },
+            };
+            if (interpreterEnabled) {
+                interpreterConstraints.push(icCond);
+            }
+            else {
+                ozConstraints.push(icCond);
+            }
+        }
+        else if (!isRecognisedSwap) {
+            ambiguities.push({
+                code: 'FREQUENCY_BOUND_MISSING',
+                question: 'Incoming-only flow - what max invocations per window should the policy enforce?',
+            });
+            warnings.push('frequency bound needed for the incoming-only flow (needs the interpreter predicate); no invocation cap inferred');
+        }
+    }
+    // Per-asset oracle-price bound(s) supplied by the caller -> one
+    // oracle_price compare per entry. Routed to the interpreter IR when enabled;
+    // otherwise to the OZ IR (which flags it as uncovered).
+    const oracleBounds = opts.userResponses?.oraclePriceBound;
+    if (oracleBounds) {
+        for (const b of oracleBounds) {
+            const oracleCond = {
+                op: 'compare',
+                compare: {
+                    selector: { kind: 'oracle_price', asset: b.asset },
+                    operator: b.operator,
+                    value: b.value,
+                },
+            };
+            if (interpreterEnabled) {
+                interpreterConstraints.push(oracleCond);
+            }
+            else {
+                ozConstraints.push(oracleCond);
+            }
+        }
+    }
+    // Observed recipient allowlist (SEP-41) is a real, recorded constraint the OZ
+    // adapter flags as not covered; the interpreter adapter lowers it to an `in`
+    // predicate. Unknown protocols emit nothing here. SoroSwap's swap recipient
+    // (arg[3]) is the source-of-truth for the swapRecipientAllowlist surface.
+    if (topLevel && protocol !== null) {
+        // A SoroSwap input-amount cap binds the caller's limitAmount to call_arg[0]
+        // (the exact amount_in) ONLY when no cumulative outgoing spend was detected
+        // for the source account - i.e. the input token never moved FROM the source
+        // (fee-sponsored swaps, or a holder != source). When a spend WAS detected,
+        // the window_spent path above already consumed the limit, so the per-call
+        // arg cap is skipped to avoid binding one limit to two different semantics.
+        const swapInputAmountCap = spendTokens.length === 0 ? limitAmount : undefined;
+        appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints, warnings, ambiguities, facts, topLevel, protocol, opts.userResponses?.swapRecipientAllowlist, swapInputAmountCap, interpreterEnabled);
+    }
+    // `scope.method` is carried on BOTH IRs so each adapter produces a
+    // self-consistent rule. The interpreter adapter lowers scope.method into a
+    // `call_fn == <method>` predicate leaf (a real restriction); the OZ adapter
+    // flags it as uncovered (CallContract alone permits any method on the
+    // contract).
+    const scope = { contract: scopeContract };
+    if (topLevel?.fn)
+        scope.method = topLevel.fn;
+    const buildRule = (constraints) => {
+        const rule = {
+            roles: [],
+            scope: { ...scope },
+            constraints,
+        };
+        if (opts.userResponses?.validUntilLedger !== undefined) {
+            rule.expiry = { validUntilLedger: opts.userResponses.validUntilLedger };
+        }
+        return rule;
+    };
+    const ir = {
+        chain: 'stellar',
+        defaultBehavior: 'deny_all',
+        rules: [buildRule(ozConstraints)],
+    };
+    const interpreterIr = {
+        chain: 'stellar',
+        defaultBehavior: 'deny_all',
+        rules: [buildRule(interpreterConstraints)],
+    };
+    return { ir, interpreterIr, ambiguities, warnings };
+}
+/** Add the constraints justified by the recording that the OZ backend cannot
+ *  express natively. Each constraint is routed to either `ozConstraints` (the
+ *  OZ adapter lowers it) or `interpreterConstraints` (the interpreter adapter
+ *  lowers it). When `interpreterEnabled` is false, every protocol-specific
+ *  constraint is routed to `ozConstraints` (which flags it as uncovered) so
+ *  callers who haven't opted in keep today's warning-driven behaviour.
+ *  SoroSwap's slippage / oracle / exact-path needs come from `userResponses`
+ *  (oraclePriceBound + limitAmount) + the recorded path (eq_seq on
+ *  call_arg[2]). */
+function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints, warnings, ambiguities, facts, topLevel, protocol, swapRecipientAllowlist, swapInputAmountCap, interpreterEnabled) {
+    // SEP-41 transfer / mint: the `to` arg (index 1) is the recipient. Emit it as
+    // a single-element allowlist; the interpreter adapter lowers it to `in`.
+    // When interpreter is not enabled, route to OZ so the caller sees today's
+    // `value allowlist on arg 1 (arg allowlist)` warning.
+    if (protocol.protocol === 'sep41' && (protocol.fn === 'transfer' || protocol.fn === 'mint')) {
+        const toArg = topLevel.args[1];
+        if (toArg && toArg.type === 'address') {
+            const cond = {
+                op: 'in',
+                selector: { kind: 'arg', argIndex: 1, scalarType: 'address' },
+                values: [toArg.value],
+            };
+            if (interpreterEnabled) {
+                interpreterConstraints.push(cond);
+            }
+            else {
+                ozConstraints.push(cond);
+            }
+        }
+    }
+    // SoroSwap: the recorded hop path -> eq_seq on the path arg (call_arg[2]).
+    // The interpreter adapter is the ONLY way to express an exact ordered
+    // sequence (OZ built-ins cannot). Element order is preserved verbatim.
+    // When multiple paths were recorded, the intersection is emitted as the
+    // canonical single path only if all observations agree; otherwise each is
+    // surfaced descriptively.
+    if (protocol.protocol === 'soroswap') {
+        const paths = facts.allowedPaths?.[topLevel.contract];
+        const route = paths?.length === 1 ? paths[0] : undefined;
+        if (route && route.length > 0 && interpreterEnabled) {
+            const pathArgIndex = 2; // SoroSwap swap_exact_tokens_for_tokens: args = [amount_in, amount_out_min, path, to, deadline]
+            interpreterConstraints.push({
+                op: 'eq_seq',
+                selector: { kind: 'arg', argIndex: pathArgIndex, scalarType: 'address' },
+                values: route,
+            });
+        }
+        else {
+            const pathText = route && route.length > 0 ? `; observed path: ${route.join(' -> ')}` : '';
+            warnings.push(`SoroSwap swap: slippage / oracle price bound and exact hop path need the interpreter predicate${pathText}`);
+        }
+        // Input-amount cap: bind the caller's limitAmount to the swap's input-amount
+        // argument as `call_arg[i] <= limit`. The index is function-specific -
+        // SoroSwap has three swap entrypoints: `swap_exact_tokens_for_tokens` and
+        // `swap_exact_in_for_tokens` take the exact input as arg[0], while
+        // `swap_tokens_for_exact_tokens` takes the MAXIMUM input (`amount_in_max`)
+        // as arg[1] (its arg[0] is the exact OUTPUT, so binding arg[0] there would
+        // cap the wrong value and leave the input unbounded). This is a per-call cap
+        // that does NOT depend on attributing a token movement to the source account
+        // (the fee-sponsored / holder != source case, where the window_spent path
+        // detects no spend). Fail-closed: it only ever restricts the permitted input.
+        // Routed to the interpreter predicate (OZ built-ins cannot express a per-arg
+        // i128 bound); when the interpreter is not enabled it goes to OZ, which flags
+        // it uncovered (a warning). The `type === 'i128'` check is defense in depth -
+        // protocol identification's argsMatchAbi already pins the input arg to i128.
+        const inputArgIndex = soroswapInputAmountArgIndex(protocol.fn);
+        const inputAmountArg = inputArgIndex !== undefined ? topLevel.args[inputArgIndex] : undefined;
+        if (swapInputAmountCap !== undefined &&
+            inputArgIndex !== undefined &&
+            inputAmountArg &&
+            inputAmountArg.type === 'i128') {
+            const cond = {
+                op: 'compare',
+                compare: {
+                    selector: { kind: 'arg', argIndex: inputArgIndex, scalarType: 'i128' },
+                    operator: 'lte',
+                    value: swapInputAmountCap,
+                },
+            };
+            if (interpreterEnabled) {
+                interpreterConstraints.push(cond);
+            }
+            else {
+                ozConstraints.push(cond);
+            }
+        }
+        // Swap recipient (call_arg[3]): when the caller supplies
+        // swapRecipientAllowlist, emit it as an `in` constraint on the recipient
+        // arg. When absent, surface RECIPIENT_ALLOWLIST_EMPTY so the caller is
+        // prompted; proceeding without an allowlist leaves the recipient
+        // unconstrained in the predicate. The ambiguity is only surfaced when
+        // the interpreter is enabled - if it isn't, the swap recipient is just
+        // ignored (today's behaviour).
+        const recipientArg = topLevel.args[3];
+        if (swapRecipientAllowlist && swapRecipientAllowlist.length > 0) {
+            const cond = {
+                op: 'in',
+                selector: { kind: 'arg', argIndex: 3, scalarType: 'address' },
+                values: [...swapRecipientAllowlist],
+            };
+            if (interpreterEnabled) {
+                interpreterConstraints.push(cond);
+            }
+            else {
+                ozConstraints.push(cond);
+            }
+        }
+        else if (interpreterEnabled && recipientArg && recipientArg.type === 'address') {
+            ambiguities.push({
+                code: 'RECIPIENT_ALLOWLIST_EMPTY',
+                question: `Recording shows the swap sending to ${recipientArg.value}. What recipient allowlist should the interpreter predicate bind? (omit to leave recipient unconstrained)`,
+            });
+        }
+    }
+}
+/** Positional index of the input-amount argument for a recognized SoroSwap swap
+ *  function. `swap_exact_tokens_for_tokens` and `swap_exact_in_for_tokens` take
+ *  the exact input as arg[0]; `swap_tokens_for_exact_tokens` takes the maximum
+ *  input (`amount_in_max`) as arg[1] - its arg[0] is the exact OUTPUT. Any other
+ *  function has no positional input-amount argument -> undefined (no cap bound). */
+function soroswapInputAmountArgIndex(fn) {
+    switch (fn) {
+        case 'swap_exact_tokens_for_tokens':
+        case 'swap_exact_in_for_tokens':
+            return 0;
+        case 'swap_tokens_for_exact_tokens':
+            return 1;
+        default:
+            return undefined;
+    }
+}

package/dist-cjs/synth/deny-cases.d.ts

@@ -0,0 +1,12 @@
+import type { PredicateNode } from '../types.ts';
+import type { EvalContext } from './evaluate.ts';
+export interface DenyCase {
+    dimension: string;
+    ctx: EvalContext;
+}
+export interface GeneratedCases {
+    permit: EvalContext;
+    denies: DenyCase[];
+}
+/** Build deterministic model-evaluated alternatives without mutating the intended call. */
+export declare function generateCases(predicate: PredicateNode, permitCtx: EvalContext): GeneratedCases;