@crediolabs/policy-synth 0.1.3 → 0.1.5

package/dist/synth/deny-cases.js

@@ -0,0 +1,377 @@
+import { MAX_SCVAL_CLONE_DEPTH } from "../types.js";
+import { literalNumericBigInt } from "./predicate-literals.js";
+const ORACLE_CASES = [
+    ['oracle_stale', 'stale'],
+    ['oracle_missing', 'missing'],
+    ['oracle_deviation_exceeded', 'deviation'],
+    ['oracle_paused', 'paused'],
+];
+// Deterministic XLM/USDC adjacency fixture; the shared registry can replace this boundary later.
+const ADJACENT_ASSETS = [
+    'CAS3J7GYLGXMF6TDJ5WQ2PEN4GRVNXJUIQ2TZU3ZB3OQ2V4DRCWI7WPF',
+    'CCWCLTASNDT57N3BCHOSVB5QWMV5URK4BXLDDF6ZZQYMBQ4OKZA3ZB2N',
+];
+/** Build deterministic model-evaluated alternatives without mutating the intended call. */
+export function generateCases(predicate, permitCtx) {
+    const facts = inspectPredicate(predicate);
+    const denies = [];
+    for (const comparison of facts.comparisons) {
+        if (comparison.left.kind !== 'amount')
+            continue;
+        const mutated = mutateBigIntRecord(permitCtx, 'amountByToken', comparison.left.token, comparison);
+        if (mutated)
+            denies.push({ dimension: 'amount', ctx: mutated });
+    }
+    const movedTokens = new Set();
+    for (const comparison of facts.comparisons) {
+        if (comparison.left.kind === 'amount' || comparison.left.kind === 'window_spent') {
+            movedTokens.add(comparison.left.token);
+        }
+    }
+    for (const token of movedTokens) {
+        denies.push({ dimension: 'asset', ctx: mutateAsset(predicate, permitCtx, token) });
+    }
+    const contractConstraints = [
+        ...facts.comparisons.filter((node) => node.op === 'eq' &&
+            node.left.kind === 'call_contract' &&
+            node.right.kind === 'literal_address'),
+        ...facts.memberships.filter((node) => node.needle.kind === 'call_contract'),
+    ];
+    for (const _constraint of contractConstraints) {
+        const ctx = cloneContext(permitCtx);
+        ctx.contract = distinctText(permitCtx.contract, 'contract');
+        denies.push({ dimension: 'contract', ctx });
+    }
+    const functionConstraints = [
+        ...facts.comparisons.filter((node) => node.op === 'eq' && node.left.kind === 'call_fn' && node.right.kind === 'literal_symbol'),
+        ...facts.memberships.filter((node) => node.needle.kind === 'call_fn'),
+    ];
+    for (const _constraint of functionConstraints) {
+        const ctx = cloneContext(permitCtx);
+        ctx.fn = distinctText(permitCtx.fn, 'function');
+        denies.push({ dimension: 'function', ctx });
+    }
+    if (permitCtx.validUntilLedger !== undefined) {
+        const ctx = cloneContext(permitCtx);
+        ctx.atLedger = permitCtx.validUntilLedger + 1;
+        denies.push({ dimension: 'timing', ctx });
+    }
+    for (const comparison of facts.comparisons) {
+        if (comparison.left.kind !== 'window_spent')
+            continue;
+        const mutated = mutateBigIntRecord(permitCtx, 'windowSpentByToken', comparison.left.token, comparison, false);
+        if (mutated)
+            denies.push({ dimension: 'time_window', ctx: mutated });
+    }
+    for (const comparison of facts.comparisons) {
+        if (comparison.left.kind !== 'invocation_count_in_window')
+            continue;
+        if (comparison.right.kind !== 'literal_u32')
+            continue;
+        const ctx = cloneContext(permitCtx);
+        ctx.invocationCountByWindow[comparison.left.windowSecs] = violatingNumber(comparison.op, comparison.right.value);
+        denies.push({ dimension: 'invocation_count', ctx });
+    }
+    // Ordered numeric bound on a call_arg (e.g. a SoroSwap input-amount cap
+    // `call_arg[0] <= limit`). A violating deny case pushes the arg past the
+    // bound so the leaf is exercised - and, critically, so `minimize` keeps it:
+    // a conjunct that no deny case needs is pruned as redundant, which would
+    // silently drop a caller-requested restriction.
+    for (const comparison of facts.comparisons) {
+        if (comparison.op === 'eq' || comparison.left.kind !== 'call_arg')
+            continue;
+        const violating = violatingArgScVal(comparison.op, comparison.right);
+        if (!violating)
+            continue;
+        const ctx = cloneContext(permitCtx);
+        ctx.args[comparison.left.index] = violating;
+        denies.push({ dimension: 'arg_amount_bound', ctx });
+    }
+    const argumentConstraints = [];
+    for (const comparison of facts.comparisons) {
+        if (comparison.op === 'eq' &&
+            comparison.left.kind === 'call_arg' &&
+            comparison.right.kind !== 'literal_vec') {
+            argumentConstraints.push({ index: comparison.left.index });
+        }
+    }
+    for (const membership of facts.memberships) {
+        if (membership.needle.kind === 'call_arg') {
+            argumentConstraints.push({ index: membership.needle.index });
+        }
+    }
+    for (const constraint of argumentConstraints) {
+        const ctx = cloneContext(permitCtx);
+        ctx.args[constraint.index] = { type: 'other', value: 'deny-case-opaque-argument' };
+        denies.push({ dimension: 'arg_bound', ctx });
+    }
+    const scopedArgumentIndices = new Set(argumentConstraints.map(({ index }) => index));
+    for (const comparison of facts.comparisons) {
+        if (comparison.op === 'eq' &&
+            comparison.left.kind === 'call_arg' &&
+            comparison.right.kind === 'literal_vec') {
+            scopedArgumentIndices.add(comparison.left.index);
+        }
+    }
+    if (contractConstraints.length > 0 &&
+        functionConstraints.length > 0 &&
+        scopedArgumentIndices.size > 0) {
+        const ctx = cloneContext(permitCtx);
+        ctx.contract = distinctText(permitCtx.contract, 'authorized-call-contract');
+        ctx.fn = distinctText(permitCtx.fn, 'authorized-call-function');
+        for (const index of scopedArgumentIndices) {
+            ctx.args[index] = { type: 'other', value: 'deny-case-authorized-call-argument' };
+        }
+        denies.push({ dimension: 'scope_contract_fn_arg', ctx });
+    }
+    const oracleComparisons = facts.comparisons.filter((node) => node.left.kind === 'oracle_price');
+    for (const [dimension, error] of ORACLE_CASES) {
+        for (const comparison of oracleComparisons) {
+            if (comparison.left.kind !== 'oracle_price')
+                continue;
+            const ctx = cloneContext(permitCtx);
+            ctx.oraclePriceByAsset[comparison.left.asset] = { error };
+            denies.push({ dimension, ctx });
+        }
+    }
+    for (const comparison of facts.comparisons) {
+        if (comparison.op !== 'eq' ||
+            comparison.left.kind !== 'call_arg' ||
+            comparison.right.kind !== 'literal_vec') {
+            continue;
+        }
+        const ctx = cloneContext(permitCtx);
+        ctx.args[comparison.left.index] = differentVector(ctx.args[comparison.left.index]);
+        denies.push({ dimension: 'soroswap_allowed_path', ctx });
+    }
+    // Version mismatch, malformed predicates, master authorization, and nonce replay are install-time checks and are intentionally omitted from model-evaluated cases.
+    return { permit: cloneContext(permitCtx), denies };
+}
+function inspectPredicate(predicate) {
+    const facts = { comparisons: [], memberships: [] };
+    visit(predicate, facts);
+    return facts;
+}
+function visit(node, facts) {
+    switch (node.op) {
+        case 'and':
+        case 'or':
+            for (const child of node.children)
+                visit(child, facts);
+            return;
+        case 'not':
+            visit(node.child, facts);
+            return;
+        case 'in':
+            facts.memberships.push(node);
+            return;
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte':
+            facts.comparisons.push(node);
+    }
+}
+function mutateBigIntRecord(permitCtx, recordKey, token, comparison, preferScaledAmount = true) {
+    if (comparison.right.kind !== 'literal_i128')
+        return null;
+    try {
+        const current = BigInt(permitCtx[recordKey][token] ?? '0');
+        const bound = BigInt(comparison.right.value);
+        const value = violatingBigInt(comparison.op, current, bound, preferScaledAmount);
+        const ctx = cloneContext(permitCtx);
+        ctx[recordKey][token] = value.toString();
+        return ctx;
+    }
+    catch {
+        return null;
+    }
+}
+function violatingBigInt(op, current, bound, preferScaledAmount) {
+    if (preferScaledAmount) {
+        const scaledCandidates = [(current * 101n) / 100n, current * 10n];
+        for (const candidate of scaledCandidates) {
+            if (!bigIntComparison(op, candidate, bound))
+                return candidate;
+        }
+    }
+    return boundaryViolatingBigInt(op, bound);
+}
+/** The single value at the boundary that violates `<selector> op bound`:
+ *  bound+1 for `lte`/`eq`, bound-1 for `gte`, and bound itself for the strict
+ *  `lt`/`gt`. */
+function boundaryViolatingBigInt(op, bound) {
+    switch (op) {
+        case 'lt':
+        case 'gt':
+            return bound;
+        case 'lte':
+        case 'eq':
+            return bound + 1n;
+        case 'gte':
+            return bound - 1n;
+    }
+}
+function violatingNumber(op, bound) {
+    switch (op) {
+        case 'lt':
+        case 'gt':
+            return bound;
+        case 'lte':
+        case 'eq':
+            return bound + 1;
+        case 'gte':
+            return bound - 1;
+    }
+}
+/** Build an ScVal that VIOLATES an ordered numeric bound on a call_arg, given
+ *  the comparison op and its numeric-literal right-hand side. Returns null when
+ *  the literal is not an integer (the bound is not a numeric compare). The arg
+ *  is emitted as an i128 - the recorder's numeric args are read via BigInt, so
+ *  the wire type only needs to be a numeric ScVal to exercise the bound. */
+function violatingArgScVal(op, right) {
+    const bound = literalNumericBigInt(right);
+    if (bound === null)
+        return null;
+    return { type: 'i128', value: boundaryViolatingBigInt(op, bound).toString() };
+}
+function bigIntComparison(op, value, bound) {
+    switch (op) {
+        case 'eq':
+            return value === bound;
+        case 'lt':
+            return value < bound;
+        case 'lte':
+            return value <= bound;
+        case 'gt':
+            return value > bound;
+        case 'gte':
+            return value >= bound;
+    }
+}
+function mutateAsset(predicate, permitCtx, token) {
+    const binding = findAddressBinding(predicate, token);
+    const adjacent = adjacentAsset(token);
+    const ctx = cloneContext(permitCtx);
+    moveRecordEntry(ctx.amountByToken, token, adjacent);
+    moveRecordEntry(ctx.windowSpentByToken, token, adjacent);
+    if (binding.contract && ctx.contract === token)
+        ctx.contract = adjacent;
+    for (const index of binding.argumentIndices) {
+        const value = ctx.args[index];
+        if (value)
+            ctx.args[index] = replaceAddress(value, token, adjacent);
+    }
+    return ctx;
+}
+function findAddressBinding(predicate, address) {
+    const facts = inspectPredicate(predicate);
+    let contract = false;
+    const argumentIndices = new Set();
+    for (const comparison of facts.comparisons) {
+        if (comparison.op !== 'eq' || !leafContainsAddress(comparison.right, address))
+            continue;
+        if (comparison.left.kind === 'call_contract')
+            contract = true;
+        if (comparison.left.kind === 'call_arg')
+            argumentIndices.add(comparison.left.index);
+    }
+    for (const membership of facts.memberships) {
+        if (!membership.haystack.some((leaf) => leafContainsAddress(leaf, address)))
+            continue;
+        if (membership.needle.kind === 'call_contract')
+            contract = true;
+        if (membership.needle.kind === 'call_arg')
+            argumentIndices.add(membership.needle.index);
+    }
+    return { contract, argumentIndices };
+}
+function leafContainsAddress(leaf, address) {
+    if (leaf.kind === 'literal_address')
+        return leaf.value === address;
+    if (leaf.kind === 'literal_vec') {
+        return leaf.elements.some((element) => leafContainsAddress(element, address));
+    }
+    return false;
+}
+function moveRecordEntry(record, from, to) {
+    const value = record[from];
+    if (value === undefined)
+        return;
+    delete record[from];
+    record[to] = value;
+}
+function replaceAddress(value, from, to) {
+    if (value.type === 'address') {
+        return value.value === from ? { type: 'address', value: to } : { ...value };
+    }
+    if (value.type === 'vec') {
+        return { type: 'vec', value: value.value.map((item) => replaceAddress(item, from, to)) };
+    }
+    return { ...value };
+}
+function differentVector(actual) {
+    if (actual?.type !== 'vec')
+        return { type: 'vec', value: [] };
+    if (actual.value.length === 0) {
+        return { type: 'vec', value: [{ type: 'other', value: 'deny-case-extra-hop' }] };
+    }
+    if (actual.value.length > 1) {
+        const reversed = actual.value.map(cloneScVal).reverse();
+        if (JSON.stringify(reversed) !== JSON.stringify(actual.value)) {
+            return { type: 'vec', value: reversed };
+        }
+    }
+    const value = actual.value.map(cloneScVal);
+    value[0] = { type: 'other', value: 'deny-case-different-hop' };
+    return { type: 'vec', value };
+}
+function adjacentAsset(asset) {
+    return asset === ADJACENT_ASSETS[0] ? ADJACENT_ASSETS[1] : ADJACENT_ASSETS[0];
+}
+function distinctText(value, label) {
+    return `${value}#${label}`;
+}
+function cloneContext(ctx) {
+    const cloned = {
+        contract: ctx.contract,
+        fn: ctx.fn,
+        args: ctx.args.map(cloneScVal),
+        atLedger: ctx.atLedger,
+        nowSeconds: ctx.nowSeconds,
+        amountByToken: { ...ctx.amountByToken },
+        windowSpentByToken: { ...ctx.windowSpentByToken },
+        invocationCountByWindow: { ...ctx.invocationCountByWindow },
+        oraclePriceByAsset: Object.fromEntries(Object.entries(ctx.oraclePriceByAsset).map(([asset, entry]) => [
+            asset,
+            'error' in entry ? { error: entry.error } : { ...entry },
+        ])),
+    };
+    if (ctx.validUntilLedger !== undefined)
+        cloned.validUntilLedger = ctx.validUntilLedger;
+    if (ctx.signerWeights !== undefined)
+        cloned.signerWeights = { ...ctx.signerWeights };
+    return cloned;
+}
+function cloneScVal(value, depth = 0) {
+    // Recursion is bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec
+    // payload cannot RangeError the JS stack during deny-case mutation. Over-depth
+    // throws a ToolError-shaped error that the `synthesizeFromRecording` envelope
+    // (item 3) converts to a structured `{ok:false, error}`.
+    if (value.type === 'vec') {
+        if (depth >= MAX_SCVAL_CLONE_DEPTH) {
+            throw cloneDepthError(value);
+        }
+        return { type: 'vec', value: value.value.map((v) => cloneScVal(v, depth + 1)) };
+    }
+    return { ...value };
+}
+function cloneDepthError(value) {
+    const err = new Error(`ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`);
+    err.code = 'SYNTHESIS_ERROR';
+    err.severity = 'error';
+    err.retryable = false;
+    err.depthContext = value.type;
+    throw err;
+}

package/dist/synth/evaluate.d.ts

@@ -0,0 +1,39 @@
+import type { PredicateNode, ScVal } from '../types.ts';
+export interface EvalContext {
+    /** Contract the interpreter is asked to enforce against. */
+    contract: string;
+    /** Function name on that contract. */
+    fn: string;
+    /** Decoded `ScVal[]` of the top-level authorized call. */
+    args: ScVal[];
+    /** Ledger sequence at which the interpreter is invoked. */
+    atLedger: number;
+    /** Optional policy expiry; absent -> step 1 is skipped. */
+    validUntilLedger?: number;
+    /** Unix seconds; used by `now` / `valid_until` leaves. */
+    nowSeconds: number;
+    /** Per-token amount moved by the current call (i128 decimal string). */
+    amountByToken: Record<string, string>;
+    /** Per-token window-rolling spend prior to this call (i128 decimal string). */
+    windowSpentByToken: Record<string, string>;
+    /** Recorded invocation counts keyed by window seconds. */
+    invocationCountByWindow: Record<number, number>;
+    /** Optional signer-weight map for the threshold gate. Absent -> skip. */
+    signerWeights?: Record<string, number>;
+    /** Per-asset oracle snapshot. Missing keys default to ORACLE_STALE. */
+    oraclePriceByAsset: Record<string, {
+        price: string;
+        timestampSeconds: number;
+    } | {
+        error: 'stale' | 'missing' | 'deviation' | 'paused' | 'decimals' | 'fingerprint';
+    }>;
+}
+export type EvalResult = {
+    permit: true;
+} | {
+    permit: false;
+    reason: string;
+};
+/** Evaluate a `PredicateNode` against the candidate call described by `ctx`.
+ *  Pure function. Returns `{ permit: true }` or `{ permit: false; reason }`. */
+export declare function evaluate(predicate: PredicateNode, ctx: EvalContext): EvalResult;