@crediolabs/policy-synth 0.1.18 → 0.2.0

package/dist/run/index.js

@@ -17,17 +17,23 @@
 // No business logic. No retries. No session state. The same call shape can
 // drive the CLI (which calls into the same core directly without MCP).
 import { createHash } from 'node:crypto';
-import { rpc } from '@stellar/stellar-sdk';
+import { rpc, xdr } from '@stellar/stellar-sdk';
 import { placeholderOzConfig, recordTransaction, synthesizeFromMandate, synthesizeFromRecording, } from "../index.js";
+import { findAuthorityOverlaps, } from "../install/authority-overlap.js";
 import { buildInstallPolicyXdr, buildRevokePolicyXdr, rpcClientFromServer, } from "../install/build-install-policy.js";
+import { buildMergePolicyXdr } from "../install/build-merge-policy.js";
 import { getInterpreterInfo } from "../install/get-interpreter-info.js";
+import { planMergePolicy } from "../install/plan-merge-policy.js";
+import { accountRuleReaderFromServer, collectObservedRules, nonceLedgerKey, } from "../install/read-account-rules.js";
+import { decodePredicate } from "../predicate/decode.js";
+import { encodePredicate } from "../predicate/encode.js";
 import { simulatePolicy, verifyPolicy } from "../verify/index.js";
-import { 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 { GetInterpreterInfoInputSchema, InstallPolicyInputSchema, MergePolicyInputSchema, NETWORK_PASSPHRASES, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_WASM_SHA256_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
 // truth - MCP tool shapes are derived from them.
-export { ComposeUserResponsesSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, InterpreterOptionsSchema, MAINNET_RPC_URL, MandateSpecSchema, NetworkSchema, OraclePriceFixtureSchema, OzAdapterConfigSchema, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_MAINNET_ADDRESS, PINNED_INTERPRETER_TESTNET_ADDRESS, PINNED_INTERPRETER_WASM_SHA256, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, TESTNET_RPC_URL, ToolErrorSchema, VerifyPolicyInputSchema, } from "./schemas.js";
+export { ComposeUserResponsesSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, InterpreterOptionsSchema, MAINNET_RPC_URL, MandateSpecSchema, NetworkSchema, OraclePriceFixtureSchema, OzAdapterConfigSchema, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_MAINNET_ADDRESS, PINNED_INTERPRETER_TESTNET_ADDRESS, PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, TESTNET_RPC_URL, ToolErrorSchema, VerifyPolicyInputSchema, } from "./schemas.js";
 /** Map every tool name to its canonical domain error code. Replaces a 7-way
  *  if/else so adding a tool adds one line here rather than a new branch in
  *  each envelope call. */
@@ -254,6 +260,25 @@ export async function runInstallPolicy(raw) {
         const predicateHash = createHash('sha256')
             .update(Buffer.from(encodedPredicate, 'base64'))
             .digest('hex');
+        // ---- Cross-rule authority scan ----
+        // OZ enforces only the policies of the rule the caller names, so a signer
+        // who also sits in a wider rule keeps that wider authority no matter what
+        // this predicate says. Refuse by default when the wider rule has no policy
+        // at all, because that makes this install decorative.
+        const authorityScan = input.skipAuthorityScan
+            ? { ran: false, skipped: true, reason: 'skipped at caller request', overlaps: [] }
+            : await scanAuthorityOverlap({
+                smartAccount: input.smartAccount,
+                interpreterAddress: expectedInterpreter,
+                rule: input.rule,
+                encodedPredicate,
+                rpcUrl: input.rpcUrl ?? expectedRpc,
+                network,
+            });
+        const overlapError = enforceAuthorityScan(authorityScan, input.allowAuthorityOverlap);
+        if (overlapError) {
+            return { ok: false, error: overlapError };
+        }
         const result = await buildInstallPolicyXdr({
             smartAccount: input.smartAccount,
             sourceAccount: input.sourceAccount,
@@ -265,7 +290,7 @@ export async function runInstallPolicy(raw) {
             rpc: rpcClient,
             ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
         });
-        return { ok: true, data: result };
+        return { ok: true, data: authorityScan ? { ...result, authorityScan } : result };
     }
     catch (e) {
         return {
@@ -274,6 +299,252 @@ export async function runInstallPolicy(raw) {
         };
     }
 }
+/** Default-deny on the cross-rule scan.
+ *
+ *  Refuses whenever the scan cannot establish that this policy binds the calls
+ *  it names. An unpoliced neighbour provably does not constrain them. An
+ *  opaque one, policed by a contract this tool cannot decode, is not KNOWN to,
+ *  and "not known to" is not "safe" - the same posture as the interpreter and
+ *  RPC pins. An incomplete scan is refused for the same reason: the overlap
+ *  list is then a subset of the account, so an empty list proves nothing.
+ *
+ *  `not-restricting` is reported but does NOT block. Both rules are ours and
+ *  both constrain the calls, and the conjunction remedy is offered; refusing
+ *  there would also block the legitimate act of adding a separate capability,
+ *  which OZ composes correctly as a union.
+ *
+ *  Returns a ToolError or null, matching `enforceInterpreterPin`. */
+export function enforceAuthorityScan(scan, allowOverlap) {
+    if (!scan || allowOverlap === true)
+        return null;
+    // Default-deny by exclusion rather than by enumeration: anything that is not
+    // the one known-safe severity blocks. Listing the blocking severities
+    // instead would mean a severity added later silently passes until someone
+    // remembers to add it here, and the safe direction is the opposite.
+    const blocking = scan.overlaps.filter((o) => o.severity !== 'not-restricting');
+    const unpoliced = blocking.filter((o) => o.severity === 'bypass').map((o) => o.ruleId);
+    const opaque = blocking.filter((o) => o.severity === 'unknown').map((o) => o.ruleId);
+    const unrecognised = blocking
+        .filter((o) => o.severity !== 'bypass' && o.severity !== 'unknown')
+        .map((o) => o.ruleId);
+    if (blocking.length > 0) {
+        const parts = [
+            unpoliced.length > 0 ? `rule ${unpoliced.join(', ')} has no policy attached` : '',
+            opaque.length > 0
+                ? `rule ${opaque.join(', ')} is policed by a contract this tool cannot decode`
+                : '',
+            unrecognised.length > 0
+                ? `rule ${unrecognised.join(', ')} carries an overlap this build does not recognise`
+                : '',
+        ].filter(Boolean);
+        return {
+            code: 'INSTALL_BUILD_FAILED',
+            message: `install_policy: a signer of this rule can already make the same calls through another context rule, so this policy is not established to restrict them: ${parts.join('; ')}. Remove the shared signer from that rule, attach a policy this tool can read, or set allowAuthorityOverlap: true to install anyway`,
+            severity: 'error',
+            retryable: false,
+            remediation: { toolCall: { name: 'install_policy', args: {} } },
+        };
+    }
+    // A scan that was meant to run and threw tells us nothing. Reporting it in
+    // a string field and proceeding is the same fail-open shape as an incomplete
+    // scan, and a caller that does not read `ran` cannot tell it from a clean
+    // result.
+    if (scan.ran === false && scan.skipped !== true) {
+        return {
+            code: 'INSTALL_BUILD_FAILED',
+            message: `install_policy: the cross-rule authority scan could not run (${scan.reason ?? 'unknown error'}), so it cannot establish that this policy restricts anything; retry, or set allowAuthorityOverlap: true to install without that assurance`,
+            severity: 'error',
+            retryable: true,
+            remediation: { toolCall: { name: 'install_policy', args: {} } },
+        };
+    }
+    if (scan.incomplete === true) {
+        return {
+            code: 'INSTALL_BUILD_FAILED',
+            message: 'install_policy: the account has more context rules than the scan could account for, so the overlap result is incomplete and cannot establish that this policy restricts anything; set allowAuthorityOverlap: true to install without that assurance',
+            severity: 'error',
+            retryable: false,
+            remediation: { toolCall: { name: 'install_policy', args: {} } },
+        };
+    }
+    return null;
+}
+/** Read the account's other context rules and report where this install's
+ *  signers already hold authority over the same calls.
+ *
+ *  A failure to read is reported rather than thrown, and the caller-facing
+ *  decision is made by `enforceAuthorityScan`: a scan that tried and failed
+ *  tells us nothing, so it refuses rather than passing as a clean account.
+ *
+ *  The account data this trusts comes from whichever RPC answered, so a
+ *  hostile RPC could describe an account with no overlapping rules. That is
+ *  bounded by the pin already enforced above: `enforceRpcPin` returns before
+ *  this runs, so the URL is the pinned one for the network unless the caller
+ *  explicitly set `allowUnpinnedRpcUrl`. This scan deliberately does not add a
+ *  second pin check, because two places deciding the same thing drift. */
+async function scanAuthorityOverlap(args) {
+    try {
+        if (!args.encodedPredicate) {
+            // Not applicable rather than failed: this rule installs no interpreter
+            // predicate, so there is nothing of ours for another rule to undercut.
+            // Returning undefined keeps it out of the refusal path, which is
+            // reserved for scans that were meant to run and could not.
+            return undefined;
+        }
+        const server = new rpc.Server(args.rpcUrl, { allowHttp: false });
+        const reader = accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[args.network]);
+        const collected = await collectObservedRules({
+            reader,
+            smartAccount: args.smartAccount,
+            interpreterAddress: args.interpreterAddress,
+        });
+        const overlaps = findAuthorityOverlaps({
+            intended: {
+                // `add_context_rule` always creates a NEW rule, so there is no id to
+                // exclude; -1 matches nothing on the account.
+                ruleId: -1,
+                contextType: toOverlapContextType(args.rule.contextRuleType),
+                signers: args.rule.signers,
+                predicate: decodePredicate(args.encodedPredicate),
+            },
+            existing: collected.rules,
+        });
+        return { ran: true, incomplete: collected.incomplete, overlaps };
+    }
+    catch (e) {
+        return {
+            ran: false,
+            reason: e instanceof Error ? e.message : String(e),
+            overlaps: [],
+        };
+    }
+}
+/** The rule draft names the callee `contract`; the analyser calls it
+ *  `address`. Same value, two vocabularies. */
+function toOverlapContextType(ct) {
+    switch (ct.kind) {
+        case 'call_contract':
+            return { kind: 'call_contract', address: ct.contract };
+        case 'create_contract':
+            return { kind: 'create_contract', wasmHash: ct.wasmHash };
+        default:
+            return { kind: 'default' };
+    }
+}
+/** `merge_policy` body - the tightening remedy for a cross-rule overlap.
+ *
+ *  Replaces a rule's predicate with the conjunction of it and a new one. This
+ *  is the action `install_policy` recommends when it reports an overlap
+ *  between two rules our interpreter polices, and it is deliberately NOT
+ *  something `install_policy` does on its own: it detaches a live policy, so
+ *  the operator has to ask for it.
+ *
+ *  Two transactions in order. `add_policy` refuses a policy already on the
+ *  rule, so the old attachment goes first, and the second transaction cannot
+ *  be simulated until the first confirms. */
+export async function runMergePolicy(raw) {
+    const parsed = MergePolicyInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return { ok: false, error: validationError('install_policy', parsed.error.issues) };
+    }
+    const input = parsed.data;
+    const network = input.network ?? 'testnet';
+    const expectedInterpreter = PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network];
+    const expectedRpc = RPC_URL_BY_NETWORK[network];
+    const rpcPinningError = enforceRpcPin('install_policy', input.rpcUrl, input.allowUnpinnedRpcUrl, expectedRpc, network);
+    if (rpcPinningError)
+        return { ok: false, error: rpcPinningError };
+    try {
+        const rpcUrl = input.rpcUrl ?? expectedRpc;
+        const server = new rpc.Server(rpcUrl, { allowHttp: false });
+        const reader = accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[network]);
+        const collected = await collectObservedRules({
+            reader,
+            smartAccount: input.smartAccount,
+            interpreterAddress: expectedInterpreter,
+        });
+        const rule = collected.rules.find((r) => r.id === input.ruleId);
+        if (!rule) {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: `merge_policy: rule ${input.ruleId} was not found on ${input.smartAccount}${collected.incomplete
+                        ? ' (the rule scan was incomplete, so it may exist but was not reached)'
+                        : ''}`,
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        const plan = planMergePolicy({
+            rule,
+            interpreterAddress: expectedInterpreter,
+            incoming: decodePredicate(input.incomingPredicateBlobBase64),
+            step: input.step,
+        });
+        if (!plan.ok) {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: `merge_policy: ${plan.reason}`,
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        const encoded = encodePredicate(plan.predicate);
+        // The nonce is read, not assumed. OZ's `remove_policy` discards the result
+        // of `try_uninstall`, so a detach whose uninstall panicked - our
+        // `uninstall` panics MissingState when the master set has been archived -
+        // detaches the policy while leaving our nonce behind. Re-installing at 1
+        // would then be refused as a replay and the rule would sit unpoliced.
+        let installNonce = 1;
+        const nonceWarnings = [];
+        if (input.step === 'reinstall') {
+            const entries = await server.getLedgerEntries(nonceLedgerKey(expectedInterpreter, input.smartAccount, input.ruleId));
+            const raw = entries.entries?.[0]?.val;
+            const stored = raw && raw.switch() === xdr.LedgerEntryType.contractData()
+                ? raw.contractData().val()
+                : undefined;
+            if (stored && stored.switch() === xdr.ScValType.scvU32()) {
+                installNonce = stored.u32() + 1;
+                nonceWarnings.push(`the previous uninstall did not complete: rule ${input.ruleId} still holds interpreter state at nonce ${stored.u32()}, so this reinstalls at ${installNonce} rather than 1. The rule's counters were NOT reset.`);
+            }
+        }
+        const built = await buildMergePolicyXdr({
+            smartAccount: input.smartAccount,
+            sourceAccount: input.sourceAccount,
+            networkPassphrase: NETWORK_PASSPHRASES[network],
+            ruleId: input.ruleId,
+            policyId: plan.policyId,
+            interpreterAddress: expectedInterpreter,
+            step: input.step,
+            encodedPredicate: encoded.encodedPredicate,
+            predicateHash: encoded.predicateHash,
+            installNonce,
+            ...(plan.oracleParams ? { oracleParams: plan.oracleParams } : {}),
+            rpc: rpcClientFromServer(server, NETWORK_PASSPHRASES[network]),
+            ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
+        });
+        return {
+            ok: true,
+            data: {
+                ...built,
+                mergedPredicateHash: encoded.predicateHash,
+                mergedPredicateBlobBase64: encoded.encodedPredicate,
+                warnings: [...plan.warnings, ...nonceWarnings],
+                followUp: plan.followUp,
+            },
+        };
+    }
+    catch (e) {
+        return { ok: false, error: caughtError('install_policy', 'INSTALL_BUILD_FAILED', e) };
+    }
+}
 /** `revoke_policy` body - thin wrapper over `buildRevokePolicyXdr`.
  *  Emits an unsigned XDR for `account.remove_context_rule(ruleId)`; the
  *  smart account itself handles uninstalling each attached policy. Auth
@@ -333,12 +604,12 @@ export async function runRevokePolicy(raw) {
  *  fabricating it would be a lie on a security surface; the live
  *  mismatch check is worth MORE).
  *
- *  Network-aware: `input.network` selects which interpreter pin and RPC
- *  to use. Mainnet was rolled out 2026-08-04 - the same wasm hash was
- *  uploaded to mainnet as was exercised on testnet, so a single
- *  `PINNED_INTERPRETER_WASM_SHA256` constant backs both networks.
- *  The address differs because instance ids are network-scoped.
- *  UNAUDITED at the time of writing.
+ *  Network-aware: `input.network` selects the interpreter address, the RPC
+ *  and the wasm hash. The networks run different binaries - testnet carries
+ *  the selector-leaf minimum and the signer-set cap, mainnet predates both -
+ *  so the hash is read through
+ *  `PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK`. UNAUDITED at the time of
+ *  writing.
  *
  *  Same RPC pin as install/revoke: when `verifyLive` triggers an outbound
  *  call, the auth-digest + the answer bind to whichever RPC answered, so
@@ -378,7 +649,7 @@ export async function runGetInterpreterInfo(raw) {
         const info = getInterpreterInfo({
             pinnedAddress,
             pinnedGrammarVersion: PINNED_INTERPRETER_GRAMMAR_VERSION,
-            pinnedWasmHash: PINNED_INTERPRETER_WASM_SHA256,
+            pinnedWasmHash: PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK[network],
             network,
             ...(deployedGrammarVersion !== undefined ? { deployedGrammarVersion } : {}),
         });