@crediolabs/policy-synth 1.0.0 → 1.1.1

package/dist/run/index.js

@@ -18,6 +18,7 @@
 // drive the CLI (which calls into the same core directly without MCP).
 import { createHash } from 'node:crypto';
 import { rpc } from '@stellar/stellar-sdk';
+import { PLACEHOLDER_INTERPRETER_ADDRESS } from "../adapters/interpreter/adapter.js";
 import { declarePredicate, encodePredicate, recordTransaction, synthesizeFromRecording, } from "../index.js";
 import { findAuthorityOverlaps, } from "../install/authority-overlap.js";
 import { buildInstallPolicyXdr, buildRevokePolicyXdr, rpcClientFromServer, } from "../install/build-install-policy.js";
@@ -25,7 +26,7 @@ import { getInterpreterInfo } from "../install/get-interpreter-info.js";
 import { accountRuleReaderFromServer, collectObservedRules } from "../install/read-account-rules.js";
 import { decodePredicate } from "../predicate/decode.js";
 import { evaluate, generateCases } from "../simulate/index.js";
-import { DeclarePolicyInputSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, NETWORK_PASSPHRASES, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_WASM_SHA256, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, VerifyPolicyInputSchema, } from "./schemas.js";
+import { DeclarePolicyInputSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, NETWORK_PASSPHRASES, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_WASM_SHA256, PINNED_OZ_POLICY_ADDRESS_BY_NETWORK, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, VerifyPolicyInputSchema, } from "./schemas.js";
 // Re-export the underlying Zod schemas so the MCP package (and any other
 // downstream consumer) can import the canonical input shapes from the same
 // module that owns the tool-body glue. The strict schemas are the source of
@@ -95,7 +96,24 @@ export async function runSynthesizePolicy(raw) {
     }
     const input = parsed.data;
     try {
-        const recorded = input.recordedTx;
+        // `hash` is the agent-friendly alternative to `recordedTx`: re-record here
+        // rather than make the caller retype a recording it cannot copy faithfully.
+        // A recording failure is returned as-is, so the caller sees why the hash was
+        // refused instead of a synthesis error about a payload it never sent.
+        let recorded;
+        if (input.recordedTx === undefined) {
+            const rerecorded = await runRecordTransaction({
+                hash: input.transactionHash,
+                network: input.network,
+            });
+            if (!rerecorded.ok) {
+                return { ok: false, error: rerecorded.error };
+            }
+            recorded = rerecorded.data;
+        }
+        else {
+            recorded = input.recordedTx;
+        }
         return await synthesizeFromRecording(recorded, {
             network: input.network,
             ...(input.userResponses !== undefined ? { userResponses: input.userResponses } : {}),
@@ -117,10 +135,143 @@ export async function runInstallPolicy(raw) {
     }
     const input = parsed.data;
     const network = input.network ?? 'testnet';
+    // `fromHash` builds the rule here rather than accepting a transcribed copy.
+    // The pinning gates below then run against the rule we just synthesized, so
+    // this path is gated identically to a caller-supplied one - it is a shortcut
+    // for the caller, never for the checks.
+    let rule = input.rule;
+    if (rule === undefined && input.fromPredicate !== undefined) {
+        const fp = input.fromPredicate;
+        let scope;
+        try {
+            scope = contextTypeForPredicate(decodePredicate(fp.encodedPredicate));
+        }
+        catch (e) {
+            return toolFailure('install_policy', e);
+        }
+        rule = {
+            contextRuleType: scope,
+            name: fp.name ?? 'policy',
+            validUntilLedger: fp.validUntilLedger ?? null,
+            signers: fp.signers.map((address) => ({ kind: 'delegated', address })),
+            policies: [
+                {
+                    kind: 'interpreter',
+                    interpreterAddress: PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network],
+                    predicateBlobBase64: fp.encodedPredicate,
+                },
+            ],
+        };
+    }
+    if (rule === undefined) {
+        // Typed rather than inline: every tool body takes `unknown`, so a
+        // misspelled key here would compile and fail only at runtime, as a
+        // validation error blamed on the caller. Naming the type restores the
+        // check on this hop.
+        const synthArgs = {
+            source: 'recording',
+            network,
+            transactionHash: input.fromHash?.transactionHash,
+            interpreter: { smartAccountAddress: input.smartAccount },
+            ...(input.fromHash?.userResponses !== undefined
+                ? { userResponses: input.fromHash.userResponses }
+                : {}),
+        };
+        const synthesized = await runSynthesizePolicy(synthArgs);
+        if (!synthesized.ok) {
+            return { ok: false, error: synthesized.error };
+        }
+        // The synthesizer saw a spend it could not bound. Installing anyway yields
+        // a rule that reads as a cap and enforces nothing, and nothing downstream
+        // catches it: it installs cleanly and verifies cleanly, because a missing
+        // constraint generates no deny case that could fail. That combination
+        // reached the chain once. Refuse rather than emit a warning to skim past.
+        const unbounded = synthesized.data.ambiguities.some((a) => a.code === 'AMOUNT_BOUND_MISSING');
+        if (unbounded && input.allowUnboundedAmount !== true) {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: 'install_policy: the recorded call spends an amount this policy does not bound, so the rule would constrain everything about the call except how much it moves; set `fromHash.userResponses.limitAmount` to the per-call cap, or `allowUnboundedAmount: true` to install an unbounded rule deliberately',
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        // Synthesis leaves the signer set empty - it reads a transaction, and which
+        // keys a rule binds is a security decision no single recording answers.
+        // The caller names them here.
+        rule = {
+            ...synthesized.data.contextRule,
+            signers: (input.fromHash?.signers ?? []).map((address) => ({
+                kind: 'delegated',
+                address,
+            })),
+        };
+    }
+    // A rule that governs no key is refused on chain, and the refusal arrives as
+    // a bare contract error code with nothing to act on. Say what is missing
+    // instead, while the caller still has the recording in hand.
+    if (rule.signers.length === 0) {
+        return {
+            ok: false,
+            error: {
+                code: 'INSTALL_BUILD_FAILED',
+                message: 'install_policy: the rule names no signer, so it would govern no key; name the keys it applies to',
+                severity: 'error',
+                retryable: false,
+                remediation: { toolCall: { name: 'install_policy', args: {} } },
+            },
+        };
+    }
     // ---- Pinning gates (default-deny) ----
     const expectedInterpreter = PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network];
     const expectedRpc = RPC_URL_BY_NETWORK[network];
-    const pinningError = enforceInterpreterPin(input.rule.policies, input.allowUnpinnedInterpreter, expectedInterpreter);
+    // Synthesis stamps every interpreter policy with the placeholder marker: it
+    // is handed a recording, not a network, so it emits a marker rather than
+    // inventing a deploy address. Install DOES know the network, and resolves
+    // the pin just above, so it fills the marker in here - otherwise the
+    // synthesize -> install path is unreachable, because the marker is not a
+    // strkey and fails the pin on every call. Only the exact marker is replaced;
+    // a caller-supplied address is still checked against the pin unchanged, so
+    // this widens nothing.
+    rule = {
+        ...rule,
+        policies: rule.policies.map((p) => p.kind === 'interpreter' && p.interpreterAddress === PLACEHOLDER_INTERPRETER_ADDRESS
+            ? { ...p, interpreterAddress: expectedInterpreter }
+            : p),
+    };
+    // A rolling total, when asked for. The predicate bounds each call; this
+    // bounds the sum across calls, which is state the interpreter does not keep.
+    // Both sit on the one rule and compose as all-of.
+    if (input.spendingLimit !== undefined) {
+        if (rule.contextRuleType.kind !== 'call_contract') {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: `install_policy: a spending limit meters transfers of one token, so the rule must be scoped to that token's contract; this rule's scope is "${rule.contextRuleType.kind}"`,
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        rule = {
+            ...rule,
+            policies: [
+                ...rule.policies,
+                {
+                    kind: 'spending_limit',
+                    policyAddress: PINNED_OZ_POLICY_ADDRESS_BY_NETWORK[network].spending_limit,
+                    periodLedgers: input.spendingLimit.periodLedgers,
+                    spendingLimit: input.spendingLimit.amount,
+                },
+            ],
+        };
+    }
+    const pinningError = enforceInterpreterPin(rule.policies, input.allowUnpinnedInterpreter, expectedInterpreter);
     if (pinningError) {
         return { ok: false, error: pinningError };
     }
@@ -136,7 +287,7 @@ export async function runInstallPolicy(raw) {
         return toolFailure('install_policy', e);
     }
     try {
-        const interpreterPolicy = input.rule.policies.find((p) => p.kind === 'interpreter');
+        const interpreterPolicy = rule.policies.find((p) => p.kind === 'interpreter');
         const encodedPredicate = interpreterPolicy?.predicateBlobBase64 ?? '';
         const predicateHash = createHash('sha256')
             .update(Buffer.from(encodedPredicate, 'base64'))
@@ -145,8 +296,10 @@ export async function runInstallPolicy(raw) {
             smartAccount: input.smartAccount,
             sourceAccount: input.sourceAccount,
             networkPassphrase: NETWORK_PASSPHRASES[network],
-            rule: input.rule,
-            installNonce: input.installNonce,
+            rule,
+            // A fresh rule has no stored nonce, so 1 is the value the interpreter
+            // expects unless the caller is deliberately re-installing.
+            installNonce: input.installNonce ?? 1,
             encodedPredicate,
             predicateHash,
             rpc: rpcClient,
@@ -171,8 +324,8 @@ export async function runInstallPolicy(raw) {
                     // no existing rule this install replaces. A sentinel no real id
                     // can equal keeps every observed rule in scope.
                     ruleId: -1,
-                    contextType: input.rule.contextRuleType,
-                    signers: input.rule.signers,
+                    contextType: rule.contextRuleType,
+                    signers: rule.signers,
                     predicate: decodePredicate(encodedPredicate),
                 },
                 existing: observed,
@@ -266,23 +419,116 @@ function noInvocationError(toolName) {
         retryable: false,
     };
 }
+/** Scope a rule to whatever contract its predicate pins.
+ *
+ *  Taking this from the predicate rather than from a separate argument means
+ *  the rule's scope cannot drift from what the predicate actually checks. A
+ *  predicate that pins no contract yields the default (account-wide) type,
+ *  which is what an unpinned predicate means. Only the top level is walked:
+ *  a contract pin nested under an `or` does not scope the rule, because the
+ *  other branch would not be covered by it. */
+export function contextTypeForPredicate(predicate) {
+    const conjuncts = predicate.op === 'and' ? predicate.children : [predicate];
+    for (const node of conjuncts) {
+        if (node.op !== 'eq')
+            continue;
+        if (node.left?.kind !== 'call_contract')
+            continue;
+        if (node.right?.kind !== 'literal_address')
+            continue;
+        return { kind: 'call_contract', contract: node.right.value };
+    }
+    return { kind: 'default' };
+}
+/** Resolve what `simulate_policy` and `verify_policy` evaluate.
+ *
+ *  Both want a predicate TREE plus the recording it came from, and neither is
+ *  something a caller holds by default: the tree is only returned by
+ *  `synthesize_policy` under `explain`, so a caller who did not ask for it has
+ *  nothing to pass and skips the check. Skipping is the worst outcome here -
+ *  these two ARE the check - so a transaction hash is accepted instead and the
+ *  server rebuilds both from it. Recording is deterministic for a settled
+ *  transaction, so this evaluates the same predicate the synthesiser produced. */
+async function resolveCheckInputs(input, tool) {
+    const network = input.network ?? 'testnet';
+    // The call to check against: whichever the caller supplied, recording only
+    // when they gave a hash instead.
+    let permitTx;
+    if (input.permitTx !== undefined) {
+        permitTx = input.permitTx;
+    }
+    else {
+        const recordArgs = { hash: input.transactionHash, network };
+        const recorded = await runRecordTransaction(recordArgs);
+        if (!recorded.ok)
+            return { ok: false, error: recorded.error };
+        permitTx = recorded.data;
+    }
+    // The thing to check. A caller-supplied predicate wins over re-synthesis,
+    // in either form: a DECLARED policy has no recording behind it, so
+    // re-deriving one from the transaction would check a different predicate
+    // than the one the caller is asking about.
+    if (input.predicate !== undefined) {
+        return { ok: true, data: { predicate: input.predicate, permitTx } };
+    }
+    if (input.encodedPredicate !== undefined) {
+        try {
+            return { ok: true, data: { predicate: decodePredicate(input.encodedPredicate), permitTx } };
+        }
+        catch (e) {
+            return toolFailure(tool, e);
+        }
+    }
+    const synthArgs = {
+        source: 'recording',
+        network,
+        // The schema's inferred type is `passthrough`, so it carries an index
+        // signature the core type does not; the shapes agree field for field.
+        recordedTx: permitTx,
+        explain: true,
+        ...(input.smartAccount !== undefined
+            ? { interpreter: { smartAccountAddress: input.smartAccount } }
+            : {}),
+        ...(input.userResponses !== undefined ? { userResponses: input.userResponses } : {}),
+    };
+    const synthesized = await runSynthesizePolicy(synthArgs);
+    if (!synthesized.ok)
+        return { ok: false, error: synthesized.error };
+    const tree = synthesized.explain?.predicateTree;
+    if (!tree) {
+        return {
+            ok: false,
+            error: {
+                code: TOOL_ERROR_CODE[tool],
+                message: `${tool}: synthesis produced no predicate to check for that transaction`,
+                severity: 'error',
+                retryable: false,
+                remediation: { toolCall: { name: tool, args: {} } },
+            },
+        };
+    }
+    return { ok: true, data: { predicate: tree, permitTx } };
+}
 /** `simulate_policy` body - evaluate a predicate against one recorded call.
  *
  *  The evaluator is a second implementation of the on-chain semantics, and the
  *  conformance harness asserts it agrees with the Rust interpreter case for
  *  case. A verdict here is therefore a claim about what the contract would do,
  *  not a guess. */
-export function runSimulatePolicy(raw) {
+export async function runSimulatePolicy(raw) {
     const parsed = SimulatePolicyInputSchema.safeParse(raw);
     if (!parsed.success) {
         return { ok: false, error: validationError('simulate_policy', parsed.error.issues) };
     }
     const input = parsed.data;
-    const ctx = evalContextFromRecording(input.permitTx);
+    const resolved = await resolveCheckInputs(input, 'simulate_policy');
+    if (!resolved.ok)
+        return { ok: false, error: resolved.error };
+    const ctx = evalContextFromRecording(resolved.data.permitTx);
     if (!ctx)
         return { ok: false, error: noInvocationError('simulate_policy') };
     try {
-        const res = evaluate(input.predicate, ctx);
+        const res = evaluate(resolved.data.predicate, ctx);
         return {
             ok: true,
             data: {
@@ -356,17 +602,20 @@ export function runDeclarePolicy(raw) {
  *  very transaction it was synthesised from. A deny case that permits means it
  *  is too LOOSE: some mutation of that transaction still gets through. `ok` is
  *  true only when neither holds. */
-export function runVerifyPolicy(raw) {
+export async function runVerifyPolicy(raw) {
     const parsed = VerifyPolicyInputSchema.safeParse(raw);
     if (!parsed.success) {
         return { ok: false, error: validationError('verify_policy', parsed.error.issues) };
     }
     const input = parsed.data;
-    const ctx = evalContextFromRecording(input.permitTx);
+    const resolved = await resolveCheckInputs(input, 'verify_policy');
+    if (!resolved.ok)
+        return { ok: false, error: resolved.error };
+    const ctx = evalContextFromRecording(resolved.data.permitTx);
     if (!ctx)
         return { ok: false, error: noInvocationError('verify_policy') };
     try {
-        const predicate = input.predicate;
+        const predicate = resolved.data.predicate;
         const cases = generateCases(predicate, ctx);
         const permitRes = evaluate(predicate, cases.permit);
         const denies = cases.denies.map((d) => {