@crediolabs/policy-synth 0.1.12 → 0.1.13

package/dist-cjs/install/build-install-policy.js

@@ -0,0 +1,431 @@
+"use strict";
+// src/install/build-install-policy.ts - builds the unsigned Soroban
+// transaction XDR for `account.add_context_rule(...)` and
+// `account.remove_context_rule(...)`.
+//
+// The MCP server is stateless and holds no key material (server.ts:10-12),
+// so this module NEVER signs. The caller (the wallet / CLI / SDK consumer)
+// wraps the returned XDR in a transaction envelope and signs that envelope
+// with their wallet; the wallet signature IS the user-confirmation step.
+//
+// We deliberately depart from the spec in plans/phase-04 which calls for a
+// two-call `install_policy`/`confirm_install` pair backed by a host-signed
+// short-TTL `action_id`. That contract requires (a) a stateful store and
+// (b) key material the server does not have, so we ship the simpler ONE-CALL
+// shape. The wallet signature covers the change.
+//
+// `buildInstallPolicyXdr` returns CALL 1 ONLY. Call 2 (interpreter.install)
+// needs the rule id the account assigns in call 1, so it cannot be pre-built
+// and is documented in the response envelope under `followUp`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GRAMMAR_VERSION = exports.Contract = void 0;
+exports.rpcClientFromServer = rpcClientFromServer;
+exports.buildInstallPolicyXdr = buildInstallPolicyXdr;
+exports.buildRevokePolicyXdr = buildRevokePolicyXdr;
+const node_crypto_1 = require("node:crypto");
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+Object.defineProperty(exports, "Contract", { enumerable: true, get: function () { return stellar_sdk_1.Contract; } });
+const build_add_context_rule_ts_1 = require("./build-add-context-rule.js");
+Object.defineProperty(exports, "DEFAULT_GRAMMAR_VERSION", { enumerable: true, get: function () { return build_add_context_rule_ts_1.DEFAULT_GRAMMAR_VERSION; } });
+/** Convert a real rpc.Server into the InstallRpcClient surface. The
+ *  `getContractVersion` lookup uses `simulateTransaction` against
+ *  `contract.call('grammar_version')` and decodes the returned u32.
+ *
+ *  The passphrase is a REQUIRED argument rather than something read off the
+ *  server: `rpc.Server` does not carry one, so reaching for
+ *  `server.networkPassphrase` yielded a non-string and every version probe
+ *  died with "Invalid passphrase provided to Transaction". The caller knows
+ *  which network it dialled; make it say so. */
+function rpcClientFromServer(server, networkPassphrase) {
+    return {
+        getAccount: (address) => server.getAccount(address),
+        simulateTransaction: (tx) => server.simulateTransaction(tx),
+        getLatestLedger: () => server.getLatestLedger(),
+        async getContractVersion(address) {
+            // The source account is constructed locally rather than fetched. This is
+            // a read-only simulation, so the sequence number is never checked, and a
+            // random key does NOT exist on chain - asking the network for it returns
+            // 404 and the version probe fails for a reason that has nothing to do
+            // with the contract being probed.
+            const account = new stellar_sdk_2.Account(stellar_sdk_1.Keypair.random().publicKey(), '0');
+            const tx = new stellar_sdk_1.TransactionBuilder(account, {
+                fee: stellar_sdk_1.BASE_FEE,
+                networkPassphrase,
+            })
+                .addOperation(new stellar_sdk_1.Contract(address).call('grammar_version'))
+                .setTimeout(30)
+                .build();
+            const sim = await server.simulateTransaction(tx);
+            if (stellar_sdk_1.rpc.Api.isSimulationError(sim)) {
+                throw new Error(`getContractVersion: simulateTransaction failed: ${sim.error}`);
+            }
+            if (!sim.result?.retval) {
+                throw new Error('getContractVersion: grammar_version() returned no value');
+            }
+            const native = (0, stellar_sdk_1.scValToBigInt)(sim.result.retval);
+            if (typeof native !== 'bigint') {
+                throw new Error('getContractVersion: grammar_version() did not return an integer');
+            }
+            return Number(native);
+        },
+    };
+}
+const FOLLOWUP_HINT = 'after this tx confirms, read the rule id via account.get_context_rules_count()-1 (or get the receipt events), then call runInstallPolicy a second time with the interpreter as the target and the rule id in context_rule_ids - OR hand-build the install() call directly with the OZ auth pattern.';
+/** Build the unsigned transaction envelope for `account.add_context_rule(...)`.
+ *  The output XDR is signed by the wallet, not by us. */
+async function buildInstallPolicyXdr(args) {
+    // 1. Pure arg encoding first - fail closed on any limit / shape problem
+    //    BEFORE we burn a network round-trip on a malformed call.
+    const callArgs = (0, build_add_context_rule_ts_1.buildAddContextRuleArgs)({
+        contextRuleType: args.rule.contextRuleType,
+        name: args.rule.name,
+        validUntilLedger: args.rule.validUntilLedger,
+        signers: args.rule.signers,
+        policies: args.rule.policies.map(adaptPolicyRef),
+    }, {
+        signers: args.rule.signers,
+        policies: args.rule.policies.map(adaptPolicyRef),
+        installNonce: args.installNonce,
+        encodedPredicate: args.encodedPredicate,
+        predicateHash: args.predicateHash,
+        ...(args.oracleParams ? { oracleParams: args.oracleParams } : {}),
+        ...(args.grammarVersion !== undefined ? { grammarVersion: args.grammarVersion } : {}),
+    });
+    // 2. Network pass: source account sequence + latest ledger.
+    const source = await args.rpc.getAccount(args.sourceAccount);
+    const latest = await args.rpc.getLatestLedger();
+    const validUntilLedger = latest.sequence + (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_LEDGERS);
+    // 3. Build the unsigned transaction envelope with the bare host call.
+    const op = stellar_sdk_1.Operation.invokeHostFunction({
+        func: stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
+            contractAddress: new stellar_sdk_1.Address(args.smartAccount).toScAddress(),
+            functionName: 'add_context_rule',
+            args: [...callArgs],
+        })),
+        auth: [],
+    });
+    const baseFee = args.baseFee !== undefined ? String(args.baseFee) : stellar_sdk_1.BASE_FEE;
+    const tx = buildUnsignedTx({
+        sourceAccount: args.sourceAccount,
+        sequence: source.sequenceNumber(),
+        fee: baseFee,
+        networkPassphrase: args.networkPassphrase,
+        op,
+    });
+    // 4. Simulation pass. Returns the auth nonce + rootInvocation the wallet
+    //    signature binds to. We do NOT add the AuthPayload here - the wallet
+    //    injects auth entries using its own __check_auth flow.
+    const recorded = await args.rpc.simulateTransaction(tx);
+    if (stellar_sdk_1.rpc.Api.isSimulationError(recorded)) {
+        // Short, stable reason. The full `simulateTransaction` error (which
+        // carries host + URL detail) stays in the SDK's own logs - never
+        // reflected back into a user-facing message where it would
+        // reconnoitre the RPC.
+        throw new Error('install_policy: simulateTransaction failed');
+    }
+    const original = (recorded.result?.auth ?? []).find((entry) => entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
+        stellar_sdk_1.Address.fromScAddress(entry.credentials().address().address()).toString() ===
+            args.smartAccount);
+    if (!original) {
+        throw new Error(`install_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
+    }
+    // 5. Decode the structured description FROM the unsigned XDR. The human
+    //    approval binds to the bytes the wallet will sign; deriving this from
+    //    the input args would re-describe the caller's intent rather than the
+    //    transaction. Re-parse the envelope we just built so the description
+    //    reflects what the wallet actually signs, not what we thought it would.
+    const describes = decodeInstallCallDescribes(tx, op, args.installNonce);
+    return {
+        unsignedXdr: tx.toEnvelope().toXDR().toString('base64'),
+        smartAccount: args.smartAccount,
+        sourceAccount: args.sourceAccount,
+        call: { contract: args.smartAccount, fn: 'add_context_rule' },
+        followUp: {
+            contract: 'interpreter',
+            fn: 'install',
+            requiresRuleIdFromCallOne: true,
+            hint: FOLLOWUP_HINT,
+        },
+        describes,
+        authNonce: original.credentials().address().nonce().toString(),
+        authValidUntilLedger: validUntilLedger,
+        rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
+    };
+}
+/** Build an unsigned XDR for `account.remove_context_rule(ruleId)`. The
+ *  smart account itself handles uninstalling each attached policy (calling
+ *  `interpreter.uninstall` for the interpreter policy); this builder only
+ *  emits the account-side removal call.
+ *
+ *  Who may authorise it is the ACCOUNT's decision, and the account's source is
+ *  not in this repo. The interpreter's own `uninstall` is master-gated, but
+ *  that is a different entry point from this one, so do not restate it as the
+ *  rule for this call. What is proven on testnet is that the account's
+ *  deployer can revoke. This builder does not pre-check the signer: it would
+ *  be guessing at a contract it cannot read, and the chain is the authority. */
+async function buildRevokePolicyXdr(args) {
+    const source = await args.rpc.getAccount(args.sourceAccount);
+    const latest = await args.rpc.getLatestLedger();
+    const validUntilLedger = latest.sequence + (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_LEDGERS);
+    const op = stellar_sdk_1.Operation.invokeHostFunction({
+        func: stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
+            contractAddress: new stellar_sdk_1.Address(args.smartAccount).toScAddress(),
+            functionName: 'remove_context_rule',
+            args: [stellar_sdk_1.xdr.ScVal.scvU32(args.ruleId)],
+        })),
+        auth: [],
+    });
+    const baseFee = args.baseFee !== undefined ? String(args.baseFee) : stellar_sdk_1.BASE_FEE;
+    const tx = buildUnsignedTx({
+        sourceAccount: args.sourceAccount,
+        sequence: source.sequenceNumber(),
+        fee: baseFee,
+        networkPassphrase: args.networkPassphrase,
+        op,
+    });
+    const recorded = await args.rpc.simulateTransaction(tx);
+    if (stellar_sdk_1.rpc.Api.isSimulationError(recorded)) {
+        // Short, stable reason. The full `simulateTransaction` error (which
+        // carries host + URL detail) stays in the SDK's own logs - never
+        // reflected back into a user-facing message where it would
+        // reconnoitre the RPC.
+        throw new Error('revoke_policy: simulateTransaction failed');
+    }
+    const original = (recorded.result?.auth ?? []).find((entry) => entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
+        stellar_sdk_1.Address.fromScAddress(entry.credentials().address().address()).toString() ===
+            args.smartAccount);
+    if (!original) {
+        throw new Error(`revoke_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
+    }
+    return {
+        unsignedXdr: tx.toEnvelope().toXDR().toString('base64'),
+        smartAccount: args.smartAccount,
+        sourceAccount: args.sourceAccount,
+        call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },
+        authNonce: original.credentials().address().nonce().toString(),
+        authValidUntilLedger: validUntilLedger,
+        rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
+    };
+}
+/** ~25 minutes at 5s/ledger. */
+const DEFAULT_AUTH_VALID_LEDGERS = 300;
+// ---- internals ----
+/** Adapter: turn the install-policy wire `PolicyRef` shape into the core
+ *  `PolicyRef` shape `buildAddContextRuleArgs` expects. Keeps the wire
+ *  schema hand-rolled + flat (the strict union would need a recursive
+ *  schema) while delegating to the proven encoder for the actual bytes. */
+function adaptPolicyRef(p) {
+    if (p.kind === 'interpreter') {
+        return {
+            kind: 'interpreter',
+            interpreterAddress: p.interpreterAddress,
+            predicateBlobBase64: p.predicateBlobBase64,
+        };
+    }
+    return {
+        kind: 'oz_builtin',
+        instanceAddress: p.instanceAddress,
+        primitive: p.primitive,
+    };
+}
+/** Build an unsigned Soroban transaction envelope. The `sequence` is
+ *  whatever `getAccount().sequenceNumber()` returned (a string of digits
+ *  the SDK accepts). No signing. The returned Transaction is what
+ *  `simulateTransaction` accepts. */
+function buildUnsignedTx(args) {
+    const account = new stellar_sdk_2.Account(args.sourceAccount, args.sequence);
+    const tx = new stellar_sdk_1.TransactionBuilder(account, {
+        fee: args.fee,
+        networkPassphrase: args.networkPassphrase,
+    })
+        .addOperation(args.op)
+        .setTimeout(0)
+        .build();
+    // `TransactionBuilder.build()` returns a Transaction whose envelope
+    // has empty signatures. The wallet re-reads the unsigned XDR, appends
+    // its signature, and broadcasts. We do NOT sign here.
+    return tx;
+}
+/** Decode the install call's structured fields directly out of the
+ *  built (transaction, operation) pair. The bytes are the source of
+ *  truth: a human reviewing the install wants to see what the wallet
+ *  will actually sign, not what we think it will. The decode is
+ *  deliberately strict - any shape we did not build ourselves throws
+ *  a ToolError, since that would mean the XDR was tampered with (or
+ *  the encoder changed and this descriptor lags).
+ *
+ *  `expectedInstallNonce` is a fallback for the rare case where the
+ *  install has no interpreter policy (no `install_nonce` to read); the
+ *  caller already knows it. */
+function decodeInstallCallDescribes(tx, op, expectedInstallNonce) {
+    const hostFn = op.body().invokeHostFunctionOp()?.hostFunction();
+    if (!hostFn || hostFn.switch().name !== 'hostFunctionTypeInvokeContract') {
+        throw new Error('install_policy: built op is not an invokeHostFunction(invokeContract(...)) call');
+    }
+    const invokeArgs = hostFn.invokeContract();
+    if (!invokeArgs) {
+        throw new Error('install_policy: built op has no InvokeContractArgs payload');
+    }
+    const targetContract = stellar_sdk_1.Address.fromScAddress(invokeArgs.contractAddress()).toString();
+    const fnName = invokeArgs.functionName().toString();
+    if (fnName !== 'add_context_rule') {
+        throw new Error(`install_policy: built op fn name is "${fnName}", expected "add_context_rule"`);
+    }
+    const scvArgs = invokeArgs.args();
+    if (scvArgs.length !== 5) {
+        throw new Error(`install_policy: built op has ${scvArgs.length} args, expected 5 (context_type, name, valid_until, signers, policies)`);
+    }
+    const contextType = scvArgs[0];
+    const nameScv = scvArgs[1];
+    const validUntilScv = scvArgs[2];
+    const signersScv = scvArgs[3];
+    const policiesScv = scvArgs[4];
+    // The length check above pins these as defined; the local references
+    // satisfy noUncheckedIndexedAccess on the accessors below.
+    if (!nameScv || !validUntilScv || !signersScv || !policiesScv || !contextType) {
+        throw new Error('install_policy: built op args include an undefined slot despite length check');
+    }
+    // name
+    if (nameScv.switch().name !== 'scvString') {
+        throw new Error('install_policy: args[1] (name) is not an ScVal::String');
+    }
+    const ruleName = nameScv.str().toString();
+    // valid_until (Option<u32> -> void when absent)
+    let validUntilLedger;
+    if (validUntilScv.switch().name === 'scvVoid') {
+        validUntilLedger = null;
+    }
+    else if (validUntilScv.switch().name === 'scvU32') {
+        validUntilLedger = validUntilScv.u32();
+    }
+    else {
+        throw new Error('install_policy: args[2] (valid_until) is neither void nor u32');
+    }
+    // signers (Vec<Vec<Symbol, Address[, Bytes]>>)
+    if (signersScv.switch().name !== 'scvVec') {
+        throw new Error('install_policy: args[3] (signers) is not an ScVal::Vec');
+    }
+    const signers = [];
+    for (const signerScv of signersScv.vec() ?? []) {
+        if (signerScv.switch().name !== 'scvVec') {
+            throw new Error('install_policy: a signer entry is not an ScVal::Vec');
+        }
+        const tuple = signerScv.vec() ?? [];
+        const tag = tuple[0]?.sym().toString();
+        const inner = tuple[1];
+        if (tag === 'Delegated') {
+            if (!inner || inner.switch().name !== 'scvAddress') {
+                throw new Error('install_policy: a Delegated signer is missing its Address');
+            }
+            signers.push({
+                kind: 'delegated',
+                address: stellar_sdk_1.Address.fromScAddress(inner.address()).toString(),
+            });
+            continue;
+        }
+        if (tag === 'External') {
+            if (!inner || inner.switch().name !== 'scvAddress') {
+                throw new Error('install_policy: an External signer is missing its verifier Address');
+            }
+            signers.push({
+                kind: 'external',
+                verifier: stellar_sdk_1.Address.fromScAddress(inner.address()).toString(),
+            });
+            continue;
+        }
+        throw new Error(`install_policy: signer tag "${tag ?? '<missing>'}" is not Delegated|External`);
+    }
+    // policies (Map<Address, Val>). Re-derive an interpreter-vs-OZ primitive
+    // classification by inspecting the value's map keys (PolicyInstallParams
+    // starts with `grammar_version`/`install_nonce`/`predicate`; OZ primitive
+    // params start with `spending_limit`/`threshold`/`period_ledgers`).
+    if (policiesScv.switch().name !== 'scvMap') {
+        throw new Error('install_policy: args[4] (policies) is not an ScVal::Map');
+    }
+    const policies = [];
+    let observedInstallNonce = null;
+    for (const entry of policiesScv.map() ?? []) {
+        const key = entry.key();
+        if (key.switch().name !== 'scvAddress') {
+            throw new Error('install_policy: a policies map entry has a non-Address key');
+        }
+        const address = stellar_sdk_1.Address.fromScAddress(key.address()).toString();
+        const val = entry.val();
+        if (val.switch().name !== 'scvMap') {
+            throw new Error(`install_policy: policies[${address}] value is not an ScVal::Map (got ${val.switch().name})`);
+        }
+        const fields = new Map();
+        for (const inner of val.map() ?? []) {
+            const fk = inner.key();
+            if (fk.switch().name !== 'scvSymbol') {
+                throw new Error(`install_policy: policies[${address}] field key is not an ScVal::Symbol`);
+            }
+            fields.set(fk.sym().toString(), inner.val());
+        }
+        // Interpreter policy fields carry grammar_version/install_nonce/predicate.
+        // OZ primitives carry spending_limit/period_ledgers/threshold/signers.
+        if (fields.has('predicate') || fields.has('grammar_version') || fields.has('install_nonce')) {
+            const installNonceScv = fields.get('install_nonce');
+            if (!installNonceScv || installNonceScv.switch().name !== 'scvU32') {
+                throw new Error(`install_policy: interpreter policy ${address} is missing a u32 install_nonce`);
+            }
+            const installNonce = installNonceScv.u32();
+            const predicateScv = fields.get('predicate');
+            if (!predicateScv || predicateScv.switch().name !== 'scvBytes') {
+                throw new Error(`install_policy: interpreter policy ${address} is missing its bytes predicate`);
+            }
+            const predicateBytes = Buffer.from(predicateScv.bytes());
+            const predicateSha256OfEmbeddedBytes = (0, node_crypto_1.createHash)('sha256')
+                .update(predicateBytes)
+                .digest('hex');
+            const predicateHashScv = fields.get('predicate_hash');
+            const predicateHash = predicateHashScv && predicateHashScv.switch().name === 'scvBytes'
+                ? Buffer.from(predicateHashScv.bytes()).toString('hex')
+                : '';
+            policies.push({
+                kind: 'interpreter',
+                address,
+                installNonce,
+                predicateHash,
+                predicateSha256OfEmbeddedBytes,
+            });
+            observedInstallNonce = installNonce;
+            continue;
+        }
+        // OZ built-in primitive. Distinguish by the parameter shape we
+        // emitted; matching one of the three primitives exactly pins the
+        // kind we built.
+        if (fields.has('spending_limit') && fields.has('period_ledgers')) {
+            policies.push({ kind: 'oz_builtin', address, primitive: 'spending_limit' });
+            continue;
+        }
+        if (fields.has('threshold') && fields.has('signer_weights')) {
+            policies.push({ kind: 'oz_builtin', address, primitive: 'weighted_threshold' });
+            continue;
+        }
+        if (fields.has('threshold')) {
+            policies.push({ kind: 'oz_builtin', address, primitive: 'simple_threshold' });
+            continue;
+        }
+        throw new Error(`install_policy: policies[${address}] value has an unknown field set; the encoder may have drifted`);
+    }
+    // `observedInstallNonce` is the nonce baked into whichever interpreter
+    // policy is present; when none, fall back to the caller-supplied value.
+    const installNonce = observedInstallNonce ?? expectedInstallNonce;
+    // Touch `tx` so the linter does not flag it as unused - the parameter
+    // documents that the caller built this Transaction; we re-parse the
+    // operation off it as a sanity check.
+    void tx;
+    return {
+        targetContract,
+        fnName: 'add_context_rule',
+        ruleName,
+        validUntilLedger,
+        signers,
+        policies,
+        installNonce,
+    };
+}
+// Local re-import to avoid pulling the class from the SDK module path
+// at the top of the file (avoids the unused-import lint).
+const stellar_sdk_2 = require("@stellar/stellar-sdk");

package/dist-cjs/install/get-interpreter-info.d.ts

@@ -0,0 +1,29 @@
+import type { Network } from '../types.ts';
+export interface InterpreterInfo {
+    /** Pinned interpreter contract address. */
+    pinnedAddress: string;
+    /** Pinned grammar version (matches SELF_VERSION in version.rs). */
+    pinnedGrammarVersion: number;
+    /** Pinned wasm sha256 (hex). */
+    pinnedWasmHash: string;
+    /** Network this pin applies to (the address + hash are network-scoped). */
+    network: Network;
+    /** Present only when the caller supplied a live `deployedGrammarVersion`. */
+    deployedGrammarVersion?: number;
+    /** True when `deployedGrammarVersion` matches `pinnedGrammarVersion`.
+     *  Absent when no live verification was performed. */
+    liveMatchesPin?: boolean;
+}
+/** Build the interpreter-info response. When `deployedGrammarVersion` is
+ *  supplied (after a live RPC `grammar_version()` call by the run layer),
+ *  compares it to the pin and sets `liveMatchesPin`. When absent, returns
+ *  the pin alone. */
+export declare function getInterpreterInfo(args: {
+    pinnedAddress: string;
+    pinnedGrammarVersion: number;
+    pinnedWasmHash: string;
+    network: Network;
+    /** When supplied, the u32 returned by the live contract's
+     *  `grammar_version()` RPC call. */
+    deployedGrammarVersion?: number;
+}): InterpreterInfo;

package/dist-cjs/install/get-interpreter-info.js

@@ -0,0 +1,44 @@
+"use strict";
+// src/install/get-interpreter-info.ts - read-only fingerprint lookup for
+// the interpreter contract.
+//
+// Returns the pinned deployment fingerprint + (optionally) compares a
+// caller-supplied live `grammar_version` against the pin. No fabricated
+// audit field; a real deployed-contract check is worth more than a fake
+// reference.
+//
+// Per design decision 5: phase-04's "audit #44" is aspirational and has no
+// source-of-truth in the repo. Returning a fabricated audit id would be a
+// lie on a security surface. The honest outputs are:
+//   - the pinned address (DEPLOYMENTS.md)
+//   - the pinned grammar version (SELF_VERSION in version.rs)
+//   - the pinned wasm sha256 (DEPLOYMENTS.md)
+//   - an OPTIONAL `deployedGrammarVersion` returned by a live `grammar_version()`
+//     RPC call, with a `liveMatchesPin` boolean the caller can dispatch on. A
+//     mismatch means the deployed wasm is NOT the pinned artifact - the caller
+//     should refuse to install until they redeploy.
+//
+// The RPC plumbing lives in the run layer (`run/index.ts`); this module
+// stays pure so it is testable without a network.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInterpreterInfo = getInterpreterInfo;
+/** Build the interpreter-info response. When `deployedGrammarVersion` is
+ *  supplied (after a live RPC `grammar_version()` call by the run layer),
+ *  compares it to the pin and sets `liveMatchesPin`. When absent, returns
+ *  the pin alone. */
+function getInterpreterInfo(args) {
+    const info = {
+        pinnedAddress: args.pinnedAddress,
+        pinnedGrammarVersion: args.pinnedGrammarVersion,
+        pinnedWasmHash: args.pinnedWasmHash,
+        network: args.network,
+    };
+    if (typeof args.deployedGrammarVersion === 'number') {
+        return {
+            ...info,
+            deployedGrammarVersion: args.deployedGrammarVersion,
+            liveMatchesPin: args.deployedGrammarVersion === args.pinnedGrammarVersion,
+        };
+    }
+    return info;
+}

package/dist-cjs/run/index.d.ts

@@ -1,10 +1,14 @@
 import { type ErrorCode, type PredicateNode, type ProposedPolicy, type RecordedTransaction, type ToolError, type ToolResponse } from '../index.ts';
+import { type BuildInstallPolicyResult, type BuildRevokePolicyResult } from '../install/build-install-policy.ts';
+import { getInterpreterInfo } from '../install/get-interpreter-info.ts';
 import type { SimulationResult } from '../verify/envelope.ts';
-import { type RecordTransactionInput, type SynthesizePolicyInput } from './schemas.ts';
-export type { RecordTransactionInput, SynthesizePolicyInput } from './schemas.ts';
-export { ComposeUserResponsesSchema, InterpreterOptionsSchema, MandateSpecSchema, NetworkSchema, OzAdapterConfigSchema, RecordedTransactionSchema, RecordTransactionInputSchema, SynthesizePolicyInputSchema, ToolErrorSchema, } from './schemas.ts';
+import { type RecordTransactionInput, type SimulatePolicyInput, type SynthesizePolicyInput, type VerifyPolicyInput } from './schemas.ts';
+export type { GetInterpreterInfoInput, InstallPolicyInput, RecordTransactionInput, RevokePolicyInput, SimulatePolicyInput, SynthesizePolicyInput, VerifyPolicyInput, } from './schemas.ts';
+export { ComposeUserResponsesSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, InterpreterOptionsSchema, MandateSpecSchema, NetworkSchema, OraclePriceFixtureSchema, OzAdapterConfigSchema, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_TESTNET_ADDRESS, PINNED_INTERPRETER_WASM_SHA256, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, ToolErrorSchema, VerifyPolicyInputSchema, } from './schemas.ts';
 export type RunRecordTransactionInput = RecordTransactionInput;
 export type RunSynthesizePolicyInput = SynthesizePolicyInput;
+export type RunSimulatePolicyInput = SimulatePolicyInput;
+export type RunVerifyPolicyInput = VerifyPolicyInput;
 /** `record_transaction` body - wraps `recordTransaction`. The tool input
  *  matches the core RecordInput minus the injected `fetcher` (the transport
  *  layer does not own the RPC). Returns the core ToolResponse unchanged.
@@ -35,6 +39,47 @@ export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<
         simulation: SimulationResult;
     };
 }>;
+/** `simulate_policy` body - thin wrapper over `simulatePolicy`. The engine
+ *  already returns fail-closed `{ok:false, error}` for runtime failures
+ *  (SIMULATION_ERROR), so the try/catch envelope is for raw SDK throws
+ *  only - same pattern as the other two wrappers. The predicate is
+ *  passed inline (stateless by design; no `proposed_policy_id` lookup). */
+export declare function runSimulatePolicy(raw: unknown): Promise<ToolResponse<SimulationResult>>;
+/** `verify_policy` body - thin wrapper over `verifyPolicy`. The engine
+ *  already returns `{ok:false, error}` with code VERIFICATION_FAILED when
+ *  the minimality check fails; the try/catch envelope is for raw SDK
+ *  throws only. Mirrors `runSimulatePolicy` exactly. */
+export declare function runVerifyPolicy(raw: unknown): Promise<ToolResponse<true>>;
+/** `install_policy` body - thin wrapper over `buildInstallPolicyXdr`.
+ *  Returns the unsigned Soroban transaction envelope (base64 XDR) the
+ *  wallet signs. The wallet signature IS the user-confirmation step - no
+ *  `action_id` two-call pair (the server is stateless, see server.ts:10-12).
+ *  Per design decision 4, only CALL 1 (account.add_context_rule) is
+ *  emitted; CALL 2 (interpreter.install) requires the rule id the account
+ *  assigns in call 1 and is documented under `followUp` in the response.
+ *
+ *  Default-deny: an interpreter policy address other than the pinned
+ *  testnet interpreter is REFUSED (the smart account would delegate to
+ *  an interpreter the caller controls); the same applies to a non-pinned
+ *  RPC URL (the auth nonce the wallet signs comes from the RPC). Both
+ *  gates accept an explicit opt-in flag. */
+export declare function runInstallPolicy(raw: unknown): Promise<ToolResponse<BuildInstallPolicyResult>>;
+/** `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
+ *  is master-only; the source account MUST be the master signer set.
+ *
+ *  Same RPC pin as install: a non-pinned `rpcUrl` is refused unless
+ *  `allowUnpinnedRpcUrl: true`. Revoke does not carry an interpreter
+ *  policy payload, so the interpreter pin is not re-checked here. */
+export declare function runRevokePolicy(raw: unknown): Promise<ToolResponse<BuildRevokePolicyResult>>;
+/** `get_interpreter_info` body - thin wrapper over `getInterpreterInfo`.
+ *  Returns the pinned deployment fingerprint + an optional live
+ *  `grammar_version()` comparison. The audit field is deliberately
+ *  OMITTED (phase-04's "audit #44" has no source of truth in the repo -
+ *  fabricating it would be a lie on a security surface; the live
+ *  mismatch check is worth MORE). */
+export declare function runGetInterpreterInfo(raw: unknown): Promise<ToolResponse<ReturnType<typeof getInterpreterInfo>>>;
 /** Build a canonical ToolError for a thrown exception caught by the tool
  *  envelope. The MCP SDK stringifies thrown objects as "[object Object]" by
  *  default, so we extract a string-friendly message and tag the original
@@ -46,4 +91,4 @@ export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<
  *  Exported as `_caughtError` (the leading underscore signals the test-only
  *  seam) so the suite in run/index.test.ts can drive the envelope path
  *  without standing up a full recordTransaction pipeline. */
-export declare function caughtError(toolName: 'record_transaction' | 'synthesize_policy', code: ErrorCode, e: unknown): ToolError;
+export declare function caughtError(toolName: 'record_transaction' | 'synthesize_policy' | 'simulate_policy' | 'verify_policy' | 'install_policy' | 'revoke_policy' | 'get_interpreter_info', code: ErrorCode, e: unknown): ToolError;