@crediolabs/policy-synth 0.1.18 → 0.2.0

package/dist/install/read-account-rules.js

@@ -0,0 +1,283 @@
+//! Reading an OpenZeppelin smart account's context rules back off chain.
+//!
+//! `authority-overlap.ts` needs to know what a signer can already do before a
+//! new policy is installed. That means every rule on the account: its context
+//! type, its signers, its attached policies, and - for rules our interpreter
+//! polices - the predicate itself.
+//!
+//! The predicate is NOT reachable through a contract call. The interpreter
+//! exposes no getter for `StoredDoc` (`lib.rs` publishes only `grammar_version`,
+//! `install`, `enforce`, the pause pair, `uninstall` and
+//! `rotate_master_signer_set`), so it is read as a ledger entry instead. That
+//! keeps this a pure client-side capability: adding a getter would change a
+//! deployed contract's ABI and force a redeploy plus re-audit to obtain data
+//! the ledger already exposes.
+//!
+//! The decoders here are pure so they can be tested without a network; the
+//! caller supplies raw `ScVal`s.
+import { Account, Address, BASE_FEE, Contract, Keypair, rpc, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
+import { decodePredicate } from "../predicate/decode.js";
+/** `storage.rs:295` - the third element of the persistent doc key tuple. */
+export const K_DOC = 1;
+/** Persistent-storage key for a rule's stored document:
+ *  `(account, rule_id, K_DOC)`, per `storage.rs:4`. */
+export function docKeyScVal(smartAccount, ruleId) {
+    return xdr.ScVal.scvVec([
+        new Address(smartAccount).toScVal(),
+        xdr.ScVal.scvU32(ruleId),
+        xdr.ScVal.scvU32(K_DOC),
+    ]);
+}
+/** Ledger key for the interpreter's persistent entry holding that document. */
+export function docLedgerKey(interpreter, smartAccount, ruleId) {
+    return xdr.LedgerKey.contractData(new xdr.LedgerKeyContractData({
+        contract: new Address(interpreter).toScAddress(),
+        key: docKeyScVal(smartAccount, ruleId),
+        durability: xdr.ContractDataDurability.persistent(),
+    }));
+}
+// ---- ScVal helpers -----
+/** Field of a `#[contracttype]` struct, which the host encodes as a map keyed
+ *  by field-name symbol. Returns undefined when the field is absent so a
+ *  caller can distinguish "not there" from "there and empty". */
+function mapField(v, name) {
+    if (v.switch() !== xdr.ScValType.scvMap())
+        return undefined;
+    for (const entry of v.map() ?? []) {
+        const key = entry.key();
+        if (key.switch() === xdr.ScValType.scvSymbol() && key.sym().toString() === name) {
+            return entry.val();
+        }
+    }
+    return undefined;
+}
+function u32Of(v) {
+    return v?.switch() === xdr.ScValType.scvU32() ? v.u32() : undefined;
+}
+function addressOf(v) {
+    if (!v || v.switch() !== xdr.ScValType.scvAddress())
+        return undefined;
+    return Address.fromScAddress(v.address()).toString();
+}
+/** An enum variant of a `#[contracttype]` enum: `ScVal::Vec([Symbol, ...args])`. */
+function enumVariant(v) {
+    if (!v || v.switch() !== xdr.ScValType.scvVec())
+        return undefined;
+    const items = v.vec() ?? [];
+    const head = items[0];
+    if (!head || head.switch() !== xdr.ScValType.scvSymbol())
+        return undefined;
+    return { tag: head.sym().toString(), args: items.slice(1) };
+}
+// ---- decoders -----
+/** OZ `ContextRuleType`. An unrecognised tag is reported as `default`, which
+ *  is the widest reading and therefore the safe one: it makes the rule look
+ *  like it could serve any call, so overlap is over-reported, never missed. */
+export function decodeContextType(v) {
+    const variant = enumVariant(v);
+    if (!variant)
+        return { kind: 'default' };
+    if (variant.tag === 'CallContract') {
+        const addr = addressOf(variant.args[0]);
+        return addr ? { kind: 'call_contract', address: addr } : { kind: 'default' };
+    }
+    if (variant.tag === 'CreateContract') {
+        const arg = variant.args[0];
+        const hash = arg?.switch() === xdr.ScValType.scvBytes() ? arg.bytes().toString('hex') : '';
+        return { kind: 'create_contract', wasmHash: hash };
+    }
+    return { kind: 'default' };
+}
+/** OZ `Signer::Delegated(Address) | Signer::External(Address, Bytes)`. */
+export function decodeSigner(v) {
+    const variant = enumVariant(v);
+    if (!variant)
+        return undefined;
+    if (variant.tag === 'Delegated') {
+        const addr = addressOf(variant.args[0]);
+        return addr ? { kind: 'delegated', address: addr } : undefined;
+    }
+    if (variant.tag === 'External') {
+        const verifier = addressOf(variant.args[0]);
+        const keyArg = variant.args[1];
+        const keyBytes = keyArg?.switch() === xdr.ScValType.scvBytes() ? keyArg.bytes().toString('hex') : '';
+        return verifier ? { kind: 'external', verifier, keyBytes } : undefined;
+    }
+    return undefined;
+}
+/** A full OZ `ContextRule` as returned by `get_context_rule(id)`.
+ *  `predicate` is filled in separately from the ledger entry. */
+export function decodeContextRule(v) {
+    const id = u32Of(mapField(v, 'id'));
+    if (id === undefined)
+        return undefined;
+    const signersVal = mapField(v, 'signers');
+    const signers = [];
+    if (signersVal?.switch() === xdr.ScValType.scvVec()) {
+        for (const s of signersVal.vec() ?? []) {
+            const decoded = decodeSigner(s);
+            if (decoded)
+                signers.push(decoded);
+        }
+    }
+    const policiesVal = mapField(v, 'policies');
+    const policyAddresses = [];
+    if (policiesVal?.switch() === xdr.ScValType.scvVec()) {
+        for (const p of policiesVal.vec() ?? []) {
+            const addr = addressOf(p);
+            if (addr)
+                policyAddresses.push(addr);
+        }
+    }
+    // `policy_ids` is index-aligned with `policies` in OZ's ContextRule. Only
+    // the ids can be passed to `remove_policy`, so a detach is impossible
+    // without them; they are read here rather than looked up again later.
+    const policyIdsVal = mapField(v, 'policy_ids');
+    const policyIds = [];
+    if (policyIdsVal?.switch() === xdr.ScValType.scvVec()) {
+        for (const pid of policyIdsVal.vec() ?? []) {
+            const n = u32Of(pid);
+            if (n !== undefined)
+                policyIds.push(n);
+        }
+    }
+    return {
+        id,
+        contextType: decodeContextType(mapField(v, 'context_type')),
+        signers,
+        policyAddresses,
+        ...(policyIds.length > 0 ? { policyIds } : {}),
+    };
+}
+/** `storage.rs:296` - the third element of the persistent nonce key tuple. */
+export const K_NONCE = 2;
+/** Ledger key for a rule's stored install nonce. Read directly for the same
+ *  reason as the document: the interpreter publishes no getter. */
+export function nonceLedgerKey(interpreter, smartAccount, ruleId) {
+    return xdr.LedgerKey.contractData(new xdr.LedgerKeyContractData({
+        contract: new Address(interpreter).toScAddress(),
+        key: xdr.ScVal.scvVec([
+            new Address(smartAccount).toScVal(),
+            xdr.ScVal.scvU32(ruleId),
+            xdr.ScVal.scvU32(K_NONCE),
+        ]),
+        durability: xdr.ContractDataDurability.persistent(),
+    }));
+}
+export function decodeStoredOracleBounds(v) {
+    const read = (name) => u32Of(mapField(v, name));
+    const staleness = read('oracle_max_staleness_seconds');
+    const deviation = read('oracle_max_deviation_bps');
+    const xfeed = read('oracle_max_xfeed_dev_bps');
+    return {
+        ...(staleness !== undefined ? { maxStalenessSeconds: staleness } : {}),
+        ...(deviation !== undefined ? { maxDeviationBps: deviation } : {}),
+        ...(xfeed !== undefined ? { maxCrossFeedDeviationBps: xfeed } : {}),
+    };
+}
+/** Raw predicate bytes out of a `StoredDoc` ledger entry value. */
+export function decodeStoredPredicateBytes(v) {
+    const field = mapField(v, 'predicate_bytes');
+    if (!field || field.switch() !== xdr.ScValType.scvBytes())
+        return undefined;
+    return field.bytes();
+}
+/** How far the id scan will probe before giving up. OZ imposes no per-account
+ *  rule cap, so there is no exact bound to derive; this one is far above any
+ *  realistic account and keeps a malformed `Count` from spinning forever. */
+export const MAX_RULE_ID_SCAN = 512;
+/**
+ * Every context rule on the account, with predicates filled in for the rules
+ * our interpreter polices.
+ *
+ * Rule ids are NOT contiguous. OZ assigns them from a monotonic `NextId` and
+ * decrements `Count` on removal without ever reusing an id
+ * (`smart_account/storage.rs`: `add_context_rule` bumps `NextId`,
+ * `remove_context_rule` only lowers `Count`), so after any removal
+ * `Count < NextId` and the live ids have gaps. Iterating `0..Count-1` would
+ * silently skip live rules at higher ids, and a skipped rule is a missed
+ * overlap - the one error that reports safety which does not exist. Instead
+ * the scan walks ids upward until it has accounted for `Count` live rules.
+ *
+ * A rule whose predicate cannot be read is deliberately left without one. That
+ * demotes it to the `foreign` class, so the scan reports it as opaque instead
+ * of assuming it is narrow.
+ */
+export async function collectObservedRules(args) {
+    const count = await args.reader.getContextRuleCount(args.smartAccount);
+    const limit = args.maxRuleIdScan ?? MAX_RULE_ID_SCAN;
+    const rules = [];
+    const unreadablePredicateRuleIds = [];
+    let id = 0;
+    while (rules.length < count && id < limit) {
+        const raw = await args.reader.getContextRule(args.smartAccount, id);
+        id++;
+        if (!raw)
+            continue;
+        const rule = decodeContextRule(raw);
+        if (!rule)
+            continue;
+        if (rule.policyAddresses.includes(args.interpreterAddress)) {
+            const doc = await args.reader.getStoredDoc(args.interpreterAddress, args.smartAccount, rule.id);
+            const bytes = doc ? decodeStoredPredicateBytes(doc) : undefined;
+            if (bytes) {
+                try {
+                    rule.predicate = decodePredicate(bytes);
+                    // Carried so a merge can re-install the SAME bounds. They are
+                    // tighten-only overrides, so losing them widens the policy quietly.
+                    if (doc)
+                        rule.oracleBounds = decodeStoredOracleBounds(doc);
+                }
+                catch {
+                    unreadablePredicateRuleIds.push(rule.id);
+                }
+            }
+            else {
+                unreadablePredicateRuleIds.push(rule.id);
+            }
+        }
+        rules.push(rule);
+    }
+    return { rules, unreadablePredicateRuleIds, incomplete: rules.length < count };
+}
+/**
+ * An `AccountRuleReader` over a live RPC server.
+ *
+ * The two OZ getters are read-only simulations, built the same way as
+ * `getContractVersion` in `build-install-policy.ts`: the source account is
+ * constructed locally because a simulation never checks its sequence number,
+ * and asking the network for a random key would 404.
+ *
+ * The stored document is fetched as a ledger entry rather than a contract
+ * call, because the interpreter publishes no getter for it.
+ */
+export function accountRuleReaderFromServer(server, networkPassphrase) {
+    async function simulateCall(contract, method, ...args) {
+        const account = new Account(Keypair.random().publicKey(), '0');
+        const tx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase })
+            .addOperation(new Contract(contract).call(method, ...args))
+            .setTimeout(30)
+            .build();
+        const sim = await server.simulateTransaction(tx);
+        if (rpc.Api.isSimulationError(sim))
+            return undefined;
+        return sim.result?.retval;
+    }
+    return {
+        async getContextRuleCount(smartAccount) {
+            const val = await simulateCall(smartAccount, 'get_context_rules_count');
+            return u32Of(val) ?? 0;
+        },
+        async getContextRule(smartAccount, ruleId) {
+            return simulateCall(smartAccount, 'get_context_rule', xdr.ScVal.scvU32(ruleId));
+        },
+        async getStoredDoc(interpreter, smartAccount, ruleId) {
+            const key = docLedgerKey(interpreter, smartAccount, ruleId);
+            const res = await server.getLedgerEntries(key);
+            const entry = res.entries?.[0]?.val;
+            if (!entry || entry.switch() !== xdr.LedgerEntryType.contractData())
+                return undefined;
+            return entry.contractData().val();
+        },
+    };
+}

package/dist/run/index.d.ts

@@ -1,10 +1,11 @@
 import { type ErrorCode, type PredicateNode, type ProposedPolicy, type RecordedTransaction, type ToolError, type ToolResponse } from '../index.ts';
+import { type AuthorityOverlap } from '../install/authority-overlap.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 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, 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.ts';
+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.ts';
 export type RunRecordTransactionInput = RecordTransactionInput;
 export type RunSynthesizePolicyInput = SynthesizePolicyInput;
 export type RunSimulatePolicyInput = SimulatePolicyInput;
@@ -66,7 +67,91 @@ export declare function runVerifyPolicy(raw: unknown): Promise<ToolResponse<true
  *  comes from the RPC). Both gates accept an explicit opt-in flag.
  *  Pin selection follows `input.network` (defaults to `testnet` so the
  *  pre-mainnet callers keep working unchanged). */
-export declare function runInstallPolicy(raw: unknown): Promise<ToolResponse<BuildInstallPolicyResult>>;
+export declare function runInstallPolicy(raw: unknown): Promise<ToolResponse<InstallPolicyResult>>;
+/** 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 declare function enforceAuthorityScan(scan: AuthorityScanReport | undefined, allowOverlap: boolean | undefined): ToolError | null;
+/** The install response, plus what the cross-rule scan found. The scan is
+ *  advisory data about the account, not part of the transaction, so it is
+ *  additive: a caller that ignores it gets exactly the previous shape. */
+export type InstallPolicyResult = BuildInstallPolicyResult & {
+    authorityScan?: AuthorityScanReport;
+};
+/** What the cross-rule scan found, carried on the install response so the
+ *  review surface can show it alongside the transaction being signed.
+ *
+ *  SCOPE, and it is narrow: this answers "can a signer OF THIS RULE reach the
+ *  same calls through a different rule". A rule sharing no signer with this
+ *  one cannot be reached by this rule's signers, so it is not a way around
+ *  this policy; it is a different principal's authority, which no policy
+ *  installed here was ever going to constrain. Other rules keep their own
+ *  signers, and an account administrator can add signers or rules afterwards.
+ *
+ *  An empty `overlaps` is therefore NOT a statement that the account is safe,
+ *  only that this rule's own signers gain no unconstrained path through the
+ *  rules that exist right now. */
+export interface AuthorityScanReport {
+    /** False when the scan did not run. `reason` then says why, and the absence
+     *  of overlaps proves nothing. */
+    ran: boolean;
+    /** True when the caller passed `skipAuthorityScan`. Distinguishes a
+     *  deliberate skip from a scan that tried and failed: both carry
+     *  `ran: false`, but only the failure refuses the install. Recorded rather
+     *  than omitted so the response shows that no opinion was formed, instead
+     *  of looking like a version that never had the check. */
+    skipped?: boolean;
+    /** True when the account has more rules than the scan accounted for, so the
+     *  overlap list is a subset. */
+    incomplete?: boolean;
+    reason?: string;
+    overlaps: AuthorityOverlap[];
+}
+/** The merge response: one step's transaction plus what it will cost. */
+export interface MergePolicyResult {
+    unsignedXdr: string;
+    smartAccount: string;
+    sourceAccount: string;
+    step: 'detach' | 'reinstall';
+    call: {
+        contract: string;
+        fn: string;
+        ruleId: number;
+    };
+    authNonce: string;
+    authValidUntilLedger: number;
+    rootInvocationXdr: string;
+    /** sha256 of the merged predicate, so the caller can pin what step 2 will
+     *  install while they are still looking at step 1. */
+    mergedPredicateHash: string;
+    mergedPredicateBlobBase64: string;
+    warnings: string[];
+    followUp: string;
+}
+/** `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 declare function runMergePolicy(raw: unknown): Promise<ToolResponse<MergePolicyResult>>;
 /** `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
@@ -84,12 +169,12 @@ export declare function runRevokePolicy(raw: unknown): Promise<ToolResponse<Buil
  *  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