@crediolabs/policy-synth 0.1.18 → 0.2.0

package/dist-cjs/run/index.js

@@ -18,20 +18,28 @@
 // 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).
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VerifyPolicyInputSchema = exports.ToolErrorSchema = exports.TESTNET_RPC_URL = exports.SynthesizePolicyInputSchema = exports.SimulatePolicyInputSchema = exports.RPC_URL_BY_NETWORK = exports.RevokePolicyInputSchema = exports.RecordTransactionInputSchema = exports.RecordedTransactionSchema = exports.PredicateNodeSchema = exports.PredicateLeafSchema = exports.PINNED_INTERPRETER_WASM_SHA256 = exports.PINNED_INTERPRETER_TESTNET_ADDRESS = exports.PINNED_INTERPRETER_MAINNET_ADDRESS = exports.PINNED_INTERPRETER_GRAMMAR_VERSION = exports.PINNED_INTERPRETER_ADDRESS_BY_NETWORK = exports.OzAdapterConfigSchema = exports.OraclePriceFixtureSchema = exports.NetworkSchema = exports.MandateSpecSchema = exports.MAINNET_RPC_URL = exports.InterpreterOptionsSchema = exports.InstallPolicyInputSchema = exports.GetInterpreterInfoInputSchema = exports.ComposeUserResponsesSchema = void 0;
+exports.VerifyPolicyInputSchema = exports.ToolErrorSchema = exports.TESTNET_RPC_URL = exports.SynthesizePolicyInputSchema = exports.SimulatePolicyInputSchema = exports.RPC_URL_BY_NETWORK = exports.RevokePolicyInputSchema = exports.RecordTransactionInputSchema = exports.RecordedTransactionSchema = exports.PredicateNodeSchema = exports.PredicateLeafSchema = exports.PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK = exports.PINNED_INTERPRETER_TESTNET_ADDRESS = exports.PINNED_INTERPRETER_MAINNET_ADDRESS = exports.PINNED_INTERPRETER_GRAMMAR_VERSION = exports.PINNED_INTERPRETER_ADDRESS_BY_NETWORK = exports.OzAdapterConfigSchema = exports.OraclePriceFixtureSchema = exports.NetworkSchema = exports.MandateSpecSchema = exports.MAINNET_RPC_URL = exports.InterpreterOptionsSchema = exports.InstallPolicyInputSchema = exports.GetInterpreterInfoInputSchema = exports.ComposeUserResponsesSchema = void 0;
 exports.runRecordTransaction = runRecordTransaction;
 exports.runSynthesizePolicy = runSynthesizePolicy;
 exports.runSimulatePolicy = runSimulatePolicy;
 exports.runVerifyPolicy = runVerifyPolicy;
 exports.runInstallPolicy = runInstallPolicy;
+exports.enforceAuthorityScan = enforceAuthorityScan;
+exports.runMergePolicy = runMergePolicy;
 exports.runRevokePolicy = runRevokePolicy;
 exports.runGetInterpreterInfo = runGetInterpreterInfo;
 exports.caughtError = caughtError;
 const node_crypto_1 = require("node:crypto");
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const index_ts_1 = require("../index.js");
+const authority_overlap_ts_1 = require("../install/authority-overlap.js");
 const build_install_policy_ts_1 = require("../install/build-install-policy.js");
+const build_merge_policy_ts_1 = require("../install/build-merge-policy.js");
 const get_interpreter_info_ts_1 = require("../install/get-interpreter-info.js");
+const plan_merge_policy_ts_1 = require("../install/plan-merge-policy.js");
+const read_account_rules_ts_1 = require("../install/read-account-rules.js");
+const decode_ts_1 = require("../predicate/decode.js");
+const encode_ts_1 = require("../predicate/encode.js");
 const index_ts_2 = require("../verify/index.js");
 const schemas_ts_1 = require("./schemas.js");
 // Re-export the underlying Zod schemas so the MCP package (and any other
@@ -52,7 +60,7 @@ Object.defineProperty(exports, "PINNED_INTERPRETER_ADDRESS_BY_NETWORK", { enumer
 Object.defineProperty(exports, "PINNED_INTERPRETER_GRAMMAR_VERSION", { enumerable: true, get: function () { return schemas_ts_2.PINNED_INTERPRETER_GRAMMAR_VERSION; } });
 Object.defineProperty(exports, "PINNED_INTERPRETER_MAINNET_ADDRESS", { enumerable: true, get: function () { return schemas_ts_2.PINNED_INTERPRETER_MAINNET_ADDRESS; } });
 Object.defineProperty(exports, "PINNED_INTERPRETER_TESTNET_ADDRESS", { enumerable: true, get: function () { return schemas_ts_2.PINNED_INTERPRETER_TESTNET_ADDRESS; } });
-Object.defineProperty(exports, "PINNED_INTERPRETER_WASM_SHA256", { enumerable: true, get: function () { return schemas_ts_2.PINNED_INTERPRETER_WASM_SHA256; } });
+Object.defineProperty(exports, "PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK", { enumerable: true, get: function () { return schemas_ts_2.PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK; } });
 Object.defineProperty(exports, "PredicateLeafSchema", { enumerable: true, get: function () { return schemas_ts_2.PredicateLeafSchema; } });
 Object.defineProperty(exports, "PredicateNodeSchema", { enumerable: true, get: function () { return schemas_ts_2.PredicateNodeSchema; } });
 Object.defineProperty(exports, "RecordedTransactionSchema", { enumerable: true, get: function () { return schemas_ts_2.RecordedTransactionSchema; } });
@@ -290,6 +298,25 @@ async function runInstallPolicy(raw) {
         const predicateHash = (0, node_crypto_1.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 (0, build_install_policy_ts_1.buildInstallPolicyXdr)({
             smartAccount: input.smartAccount,
             sourceAccount: input.sourceAccount,
@@ -301,7 +328,7 @@ 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 {
@@ -310,6 +337,252 @@ 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`. */
+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 stellar_sdk_1.rpc.Server(args.rpcUrl, { allowHttp: false });
+        const reader = (0, read_account_rules_ts_1.accountRuleReaderFromServer)(server, schemas_ts_1.NETWORK_PASSPHRASES[args.network]);
+        const collected = await (0, read_account_rules_ts_1.collectObservedRules)({
+            reader,
+            smartAccount: args.smartAccount,
+            interpreterAddress: args.interpreterAddress,
+        });
+        const overlaps = (0, authority_overlap_ts_1.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: (0, decode_ts_1.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. */
+async function runMergePolicy(raw) {
+    const parsed = schemas_ts_1.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 = schemas_ts_1.PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network];
+    const expectedRpc = schemas_ts_1.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 stellar_sdk_1.rpc.Server(rpcUrl, { allowHttp: false });
+        const reader = (0, read_account_rules_ts_1.accountRuleReaderFromServer)(server, schemas_ts_1.NETWORK_PASSPHRASES[network]);
+        const collected = await (0, read_account_rules_ts_1.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 = (0, plan_merge_policy_ts_1.planMergePolicy)({
+            rule,
+            interpreterAddress: expectedInterpreter,
+            incoming: (0, decode_ts_1.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 = (0, encode_ts_1.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((0, read_account_rules_ts_1.nonceLedgerKey)(expectedInterpreter, input.smartAccount, input.ruleId));
+            const raw = entries.entries?.[0]?.val;
+            const stored = raw && raw.switch() === stellar_sdk_1.xdr.LedgerEntryType.contractData()
+                ? raw.contractData().val()
+                : undefined;
+            if (stored && stored.switch() === stellar_sdk_1.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 (0, build_merge_policy_ts_1.buildMergePolicyXdr)({
+            smartAccount: input.smartAccount,
+            sourceAccount: input.sourceAccount,
+            networkPassphrase: schemas_ts_1.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: (0, build_install_policy_ts_1.rpcClientFromServer)(server, schemas_ts_1.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
@@ -369,12 +642,12 @@ 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
@@ -414,7 +687,7 @@ async function runGetInterpreterInfo(raw) {
         const info = (0, get_interpreter_info_ts_1.getInterpreterInfo)({
             pinnedAddress,
             pinnedGrammarVersion: schemas_ts_1.PINNED_INTERPRETER_GRAMMAR_VERSION,
-            pinnedWasmHash: schemas_ts_1.PINNED_INTERPRETER_WASM_SHA256,
+            pinnedWasmHash: schemas_ts_1.PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK[network],
             network,
             ...(deployedGrammarVersion !== undefined ? { deployedGrammarVersion } : {}),
         });