@crediolabs/policy-synth 1.1.1 → 1.3.0

package/dist/install/authority-overlap.d.ts

@@ -24,6 +24,24 @@ export type ContextType = {
  *  - `unpoliced`: no policy at all. Whatever its context type allows, its
  *    signers may do without constraint. */
 export type RuleClass = 'interpreter' | 'foreign' | 'unpoliced';
+/** An OZ `spending_limit`'s parameters. `amount` is in the token's smallest
+ *  unit; the period is a LEDGER count, not seconds. */
+export interface SpendCap {
+    amount: string;
+    periodLedgers: number;
+}
+/** The policy contracts this tool can recognise by address. Supplying them lets
+ *  the scan reason about a neighbour's SPEND CAP instead of treating any
+ *  non-interpreter policy as opaque.
+ *
+ *  Recognition is what licenses the strong conclusion. "This rule has no spend
+ *  cap" is only sound when every policy on it is accounted for; a single
+ *  unrecognised address could be somebody else's cap, so such a rule stays
+ *  advisory. */
+export interface KnownPolicies {
+    interpreter: string;
+    spendingLimit: string;
+}
 export interface ObservedRule {
     id: number;
     contextType: ContextType;
@@ -33,6 +51,11 @@ export interface ObservedRule {
     /** Decoded predicate. Present only when the rule is policed by OUR
      *  interpreter and the stored document was readable. */
     predicate?: PredicateNode;
+    /** The attached spend cap's parameters, when the reader could read them from
+     *  the policy's own storage. Attachment is decided from `policyAddresses`, so
+     *  this being absent does NOT mean the rule is uncapped - only that the
+     *  numbers are unknown. */
+    spendCap?: SpendCap;
 }
 export interface IntendedInstall {
     /** Rule the predicate is being installed onto. A re-install onto the same
@@ -42,9 +65,15 @@ export interface IntendedInstall {
     contextType: ContextType;
     signers: SignerDraft[];
     predicate: PredicateNode;
+    /** The rolling cap being installed alongside the predicate, when one is.
+     *  Its presence is what makes a neighbour's LACK of a cap a finding: without
+     *  it there is no total for a neighbour to route around. */
+    spendCap?: SpendCap;
 }
 export type OverlapSeverity = 
-/** A neighbouring rule imposes no constraint at all on the shared calls. */
+/** A neighbouring rule imposes no constraint at all on the shared calls, or
+ *  imposes no ROLLING TOTAL on calls the new rule caps. Either way the new
+ *  rule's bound does not hold for a signer who can name this one. */
 'bypass'
 /** A neighbouring policy exists but what it permits cannot be read. */
  | 'unknown'
@@ -60,6 +89,14 @@ export interface AuthorityOverlap {
     sharedSigners: SignerDraft[];
     /** The selectors both rules can serve. Non-empty by construction. */
     sharedSelectors: Selector[];
+    /** This neighbour's own rolling cap, when it has one this tool could read.
+     *  A spend cap is keyed by (account, RULE id), so two capped rules do not
+     *  share a budget - a signer on both may spend the SUM. */
+    spendCap?: SpendCap;
+    /** True when the new rule installs a rolling total and this neighbour serves
+     *  some of the same calls WITHOUT one, which voids the total rather than
+     *  merely widening it. Only set when every policy here was recognised. */
+    capBypass?: true;
     advice: string;
 }
 /** Canonical key for signer equality. Mirrors OZ's `Signer` enum: a delegated
@@ -98,4 +135,7 @@ export declare function effectiveSelectors(rule: ObservedRule): Selector[];
 export declare function findAuthorityOverlaps(args: {
     intended: IntendedInstall;
     existing: ObservedRule[];
+    /** Omit to skip spend-cap reasoning entirely: every neighbour is then judged
+     *  exactly as before, on its policies' presence rather than their meaning. */
+    knownPolicies?: KnownPolicies;
 }): AuthorityOverlap[];

package/dist/install/authority-overlap.js

@@ -191,14 +191,38 @@ function classifyRule(rule) {
         return 'unpoliced';
     return rule.predicate ? 'interpreter' : 'foreign';
 }
-function adviceFor(cls, ruleId) {
+/** Is the OZ spend cap attached to this rule? Decided by ADDRESS, so it holds
+ *  whether or not the cap's parameters could be read. */
+function hasSpendCap(rule, known) {
+    return rule.policyAddresses.includes(known.spendingLimit);
+}
+/** Every policy on the rule is one this tool knows the semantics of, so
+ *  "there is no spend cap here" is an observation rather than an assumption. */
+function allPoliciesRecognised(rule, known) {
+    return rule.policyAddresses.every((addr) => addr === known.interpreter || addr === known.spendingLimit);
+}
+function capBypassAdvice(ruleId) {
+    return `the rolling total you are installing will not bind: rule ${ruleId} serves some of the same calls for a shared signer and carries NO spend cap, so that signer spends through it without one. A cap is stored per RULE, never per key. Remove the shared signer from rule ${ruleId}, put an equivalent cap on it, or narrow it so it no longer serves these calls.`;
+}
+/** How a signer's spend adds up across two capped rules. Same period or not,
+ *  the budgets are separate; saying so with the numbers beats saying it in the
+ *  abstract, which is what the caller has to reason about. */
+function combinedCapNote(mine, theirs) {
+    if (mine.periodLedgers === theirs.periodLedgers) {
+        const total = (BigInt(mine.amount) + BigInt(theirs.amount)).toString();
+        return ` Its cap is ${theirs.amount} over the same ${theirs.periodLedgers}-ledger period as yours, and the two budgets are separate, so a shared signer may spend ${total} in total.`;
+    }
+    return ` Its cap is ${theirs.amount} over ${theirs.periodLedgers} ledgers against your ${mine.amount} over ${mine.periodLedgers}; the periods differ, so the two budgets neither share nor cancel and a shared signer draws on both.`;
+}
+function adviceFor(cls, ruleId, theirCap, myCap) {
+    const capNote = theirCap !== undefined && myCap !== undefined ? combinedCapNote(myCap, theirCap) : '';
     switch (cls) {
         case 'unpoliced':
             return `rule ${ruleId} has no policy attached, so a shared signer may make these calls with no constraint at all - the predicate you are installing will never run for them. Remove the shared signer from rule ${ruleId}, or attach a policy to it.`;
         case 'foreign':
-            return `rule ${ruleId} is policed by a contract this tool cannot decode, so its authority over these calls is unknown. Review it by hand before relying on the new rule.`;
+            return `rule ${ruleId} is policed by a contract this tool cannot decode, so its authority over these calls is unknown. Review it by hand before relying on the new rule.${capNote}`;
         case 'interpreter':
-            return `a shared signer may name rule ${ruleId} instead, so the new rule will not restrict these calls. To TIGHTEN, edit rule ${ruleId} itself rather than adding a second rule. To ADD a separate capability, keep both and expect neither to constrain the other.`;
+            return `a shared signer may name rule ${ruleId} instead, so the new rule will not restrict these calls. To TIGHTEN, edit rule ${ruleId} itself rather than adding a second rule. To ADD a separate capability, keep both and expect neither to constrain the other.${capNote}`;
     }
 }
 /**
@@ -222,17 +246,42 @@ export function findAuthorityOverlaps(args) {
         if (sharedSelectors.length === 0)
             continue;
         const ruleClass = classifyRule(rule);
+        // A rolling total is keyed by (account, rule id), so it constrains THIS
+        // rule and nothing else. If the new rule carries one and a neighbour serves
+        // the same calls without one, the signer names the neighbour and spends
+        // without limit - the total was never a bound on the key. Proven on testnet
+        // in `docs/audit/evidence/oz-two-rule-blend-cap.log`, where an uncapped
+        // sibling rule passed the very amount the capped rule refused.
+        //
+        // Sound only when every policy on the neighbour was recognised. One
+        // unrecognised address could be another spend cap, and refusing an install
+        // over a policy we cannot read would be a guess, not a proof.
+        // An unpoliced neighbour is excluded deliberately. It has no policies, so
+        // it passes the "everything recognised, no cap" test vacuously - but the
+        // finding there is not that a total leaks, it is that NOTHING constrains
+        // those calls. Reporting the narrower cause would send the reader looking
+        // for a spend cap when the rule needs a policy at all.
+        const capBypass = ruleClass !== 'unpoliced' &&
+            args.knownPolicies !== undefined &&
+            args.intended.spendCap !== undefined &&
+            allPoliciesRecognised(rule, args.knownPolicies) &&
+            !hasSpendCap(rule, args.knownPolicies);
+        const severity = ruleClass === 'unpoliced' || capBypass
+            ? 'bypass'
+            : ruleClass === 'foreign'
+                ? 'unknown'
+                : 'not-restricting';
         out.push({
             ruleId: rule.id,
             ruleClass,
-            severity: ruleClass === 'unpoliced'
-                ? 'bypass'
-                : ruleClass === 'foreign'
-                    ? 'unknown'
-                    : 'not-restricting',
+            severity,
             sharedSigners: shared,
             sharedSelectors,
-            advice: adviceFor(ruleClass, rule.id),
+            ...(rule.spendCap !== undefined ? { spendCap: rule.spendCap } : {}),
+            ...(capBypass ? { capBypass: true } : {}),
+            advice: capBypass
+                ? capBypassAdvice(rule.id)
+                : adviceFor(ruleClass, rule.id, rule.spendCap, args.intended.spendCap),
         });
     }
     return out;

package/dist/install/read-account-rules.d.ts

@@ -1,6 +1,6 @@
 import { rpc, xdr } from '@stellar/stellar-sdk';
 import type { SignerDraft } from '../types.ts';
-import type { ContextType, ObservedRule } from './authority-overlap.ts';
+import type { ContextType, ObservedRule, SpendCap } from './authority-overlap.ts';
 /** `storage.rs` - the third element of the persistent doc key tuple. */
 export declare const K_DOC = 1;
 /** Persistent-storage key for a rule's stored document:
@@ -19,6 +19,20 @@ export declare function decodeSigner(v: xdr.ScVal): SignerDraft | undefined;
 export declare function decodeContextRule(v: xdr.ScVal): ObservedRule | undefined;
 /** The interpreter's `StoredDoc { predicate_bytes }`. */
 export declare function decodeStoredPredicateBytes(v: xdr.ScVal): Buffer | undefined;
+/** Persistent-storage key for a rule's spend-cap data:
+ *  `SpendingLimitStorageKey::AccountContext(account, rule_id)`, which the host
+ *  encodes as an enum variant - the symbol first, then the payload. */
+export declare function spendCapKeyScVal(smartAccount: string, ruleId: number): xdr.ScVal;
+/** Ledger key for the OZ spend cap's own persistent entry. The policy exposes
+ *  `get_spending_limit_data`, but that PANICS when nothing is installed, and a
+ *  panic is indistinguishable from an RPC fault at the call site. Reading the
+ *  entry lets "no cap here" come back as an absence instead. */
+export declare function spendCapLedgerKey(spendingLimit: string, smartAccount: string, ruleId: number): xdr.LedgerKey;
+/** `SpendingLimitData`, of which only the two installed parameters matter here.
+ *  The running total and the history are deliberately ignored: they say what
+ *  has been spent so far, which changes every call, while the scan is about
+ *  what the rule PERMITS. */
+export declare function decodeSpendCap(v: xdr.ScVal): SpendCap | undefined;
 /** The three reads the scan needs. Kept as an interface so the collection
  *  below is testable without a network. */
 export interface AccountRuleReader {
@@ -29,6 +43,10 @@ export interface AccountRuleReader {
     /** The interpreter's persistent `StoredDoc` entry, read as a ledger entry.
      *  Undefined when no document is stored for that rule. */
     getStoredDoc(interpreter: string, smartAccount: string, ruleId: number): Promise<xdr.ScVal | undefined>;
+    /** The OZ spend cap's persistent entry for this rule, read as a ledger entry.
+     *  Optional so an existing reader keeps working: without it the scan simply
+     *  reports no cap parameters, which is the same as it behaved before. */
+    getSpendCapData?(spendingLimit: string, smartAccount: string, ruleId: number): Promise<xdr.ScVal | undefined>;
 }
 /** 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
@@ -64,6 +82,10 @@ export declare function collectObservedRules(args: {
     reader: AccountRuleReader;
     smartAccount: string;
     interpreterAddress: string;
+    /** The pinned OZ spend cap. Supplying it fills in the PARAMETERS of a
+     *  neighbour's cap; whether one is attached at all is decided from the
+     *  rule's policy addresses and does not depend on this read succeeding. */
+    spendingLimitAddress?: string;
     maxRuleIdScan?: number;
 }): Promise<CollectedRules>;
 /**

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

@@ -19,7 +19,7 @@
 //!
 //! The decoders 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 { Account, Address, BASE_FEE, Contract, Keypair, rpc, scValToNative, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
 import { decodePredicate } from "../predicate/decode.js";
 /** `storage.rs` - the third element of the persistent doc key tuple. */
 export const K_DOC = 1;
@@ -147,6 +147,43 @@ export function decodeStoredPredicateBytes(v) {
         return undefined;
     return field.bytes();
 }
+/** Persistent-storage key for a rule's spend-cap data:
+ *  `SpendingLimitStorageKey::AccountContext(account, rule_id)`, which the host
+ *  encodes as an enum variant - the symbol first, then the payload. */
+export function spendCapKeyScVal(smartAccount, ruleId) {
+    return xdr.ScVal.scvVec([
+        xdr.ScVal.scvSymbol('AccountContext'),
+        new Address(smartAccount).toScVal(),
+        xdr.ScVal.scvU32(ruleId),
+    ]);
+}
+/** Ledger key for the OZ spend cap's own persistent entry. The policy exposes
+ *  `get_spending_limit_data`, but that PANICS when nothing is installed, and a
+ *  panic is indistinguishable from an RPC fault at the call site. Reading the
+ *  entry lets "no cap here" come back as an absence instead. */
+export function spendCapLedgerKey(spendingLimit, smartAccount, ruleId) {
+    return xdr.LedgerKey.contractData(new xdr.LedgerKeyContractData({
+        contract: new Address(spendingLimit).toScAddress(),
+        key: spendCapKeyScVal(smartAccount, ruleId),
+        durability: xdr.ContractDataDurability.persistent(),
+    }));
+}
+/** `SpendingLimitData`, of which only the two installed parameters matter here.
+ *  The running total and the history are deliberately ignored: they say what
+ *  has been spent so far, which changes every call, while the scan is about
+ *  what the rule PERMITS. */
+export function decodeSpendCap(v) {
+    const periodLedgers = u32Of(mapField(v, 'period_ledgers'));
+    const limit = mapField(v, 'spending_limit');
+    if (periodLedgers === undefined || !limit)
+        return undefined;
+    if (limit.switch() !== xdr.ScValType.scvI128())
+        return undefined;
+    const amount = scValToNative(limit);
+    if (typeof amount !== 'bigint')
+        return undefined;
+    return { amount: amount.toString(), periodLedgers };
+}
 /** 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. */
@@ -195,6 +232,16 @@ export async function collectObservedRules(args) {
                 unreadablePredicateRuleIds.push(rule.id);
             }
         }
+        const spendCapAddress = args.spendingLimitAddress;
+        if (spendCapAddress !== undefined && rule.policyAddresses.includes(spendCapAddress)) {
+            const data = await args.reader.getSpendCapData?.(spendCapAddress, args.smartAccount, rule.id);
+            const cap = data ? decodeSpendCap(data) : undefined;
+            // An unreadable cap is left absent rather than guessed at. The rule still
+            // counts as capped, because attachment came from its policy addresses,
+            // so failing this read weakens the REPORT and never the refusal.
+            if (cap)
+                rule.spendCap = cap;
+        }
         rules.push(rule);
     }
     return { rules, unreadablePredicateRuleIds, incomplete: rules.length < count };
@@ -237,5 +284,13 @@ export function accountRuleReaderFromServer(server, networkPassphrase) {
                 return undefined;
             return entry.contractData().val();
         },
+        async getSpendCapData(spendingLimit, smartAccount, ruleId) {
+            const key = spendCapLedgerKey(spendingLimit, 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

@@ -38,6 +38,23 @@ export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<
         predicateTree: PredicateNode | null;
     };
 }>;
+/** The refusal message for an install the cross-rule scan proves cannot bind,
+ *  or `undefined` when the install may proceed.
+ *
+ *  Only `bypass` refuses, and it covers two proofs. Either the neighbouring
+ *  rule carries NO policy, so a shared signer names it and the new predicate
+ *  never runs; or the install carries a rolling total and a fully recognised
+ *  neighbour serves the same calls without one, so the total is not a bound on
+ *  the key. Both are proofs from data already in hand.
+ *
+ *  `unknown` (a neighbour policed by a contract this tool cannot decode) stays
+ *  advisory: it may well be tighter, and refusing on "cannot decode" would
+ *  block installs on a guess. A `null` scan is NOT CHECKED, which is not
+ *  evidence of a bypass and must not refuse on its own.
+ *
+ *  Separated from the tool body so the decision can be tested without a
+ *  network: the install it guards cannot be built without one. */
+export declare function authorityBypassRefusal(scan: AuthorityOverlap[] | null, allowAuthorityOverlap: boolean | undefined): string | undefined;
 export declare function runInstallPolicy(raw: unknown): Promise<ToolResponse<BuildInstallPolicyResult & {
     authorityScan: AuthorityOverlap[] | null;
 }>>;

package/dist/run/index.js

@@ -17,6 +17,7 @@
 // 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 { readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { rpc } from '@stellar/stellar-sdk';
 import { PLACEHOLDER_INTERPRETER_ADDRESS } from "../adapters/interpreter/adapter.js";
 import { declarePredicate, encodePredicate, recordTransaction, synthesizeFromRecording, } from "../index.js";
@@ -128,6 +129,36 @@ export async function runSynthesizePolicy(raw) {
         return toolFailure('synthesize_policy', e);
     }
 }
+/** The refusal message for an install the cross-rule scan proves cannot bind,
+ *  or `undefined` when the install may proceed.
+ *
+ *  Only `bypass` refuses, and it covers two proofs. Either the neighbouring
+ *  rule carries NO policy, so a shared signer names it and the new predicate
+ *  never runs; or the install carries a rolling total and a fully recognised
+ *  neighbour serves the same calls without one, so the total is not a bound on
+ *  the key. Both are proofs from data already in hand.
+ *
+ *  `unknown` (a neighbour policed by a contract this tool cannot decode) stays
+ *  advisory: it may well be tighter, and refusing on "cannot decode" would
+ *  block installs on a guess. A `null` scan is NOT CHECKED, which is not
+ *  evidence of a bypass and must not refuse on its own.
+ *
+ *  Separated from the tool body so the decision can be tested without a
+ *  network: the install it guards cannot be built without one. */
+export function authorityBypassRefusal(scan, allowAuthorityOverlap) {
+    if (scan === null || allowAuthorityOverlap === true)
+        return undefined;
+    const proven = scan.filter((o) => o.severity === 'bypass');
+    if (proven.length === 0)
+        return undefined;
+    const ids = proven.map((o) => o.ruleId).join(', ');
+    // A cap bypass leaves the predicate working, so "constrains nothing" would
+    // overstate it and send the caller looking for the wrong defect.
+    const consequence = proven.every((o) => o.capBypass === true)
+        ? 'This rule would install cleanly and its rolling total would not hold'
+        : 'This rule would install cleanly and constrain nothing';
+    return `install_policy: ${proven[0]?.advice ?? ''} ${consequence}, so it is refused (rule ${ids}); set \`allowAuthorityOverlap: true\` to install anyway.`;
+}
 export async function runInstallPolicy(raw) {
     const parsed = InstallPolicyInputSchema.safeParse(raw);
     if (!parsed.success) {
@@ -327,10 +358,71 @@ export async function runInstallPolicy(raw) {
                     contextType: rule.contextRuleType,
                     signers: rule.signers,
                     predicate: decodePredicate(encodedPredicate),
+                    ...(input.spendingLimit !== undefined
+                        ? {
+                            spendCap: {
+                                amount: input.spendingLimit.amount,
+                                periodLedgers: input.spendingLimit.periodLedgers,
+                            },
+                        }
+                        : {}),
                 },
                 existing: observed,
+                // Both addresses are pinned, so a neighbour's policies can be
+                // named rather than merely counted - which is what lets the scan
+                // say a rule has no spend cap instead of that it has something
+                // unreadable.
+                knownPolicies: {
+                    interpreter: expectedInterpreter,
+                    spendingLimit: PINNED_OZ_POLICY_ADDRESS_BY_NETWORK[network].spending_limit,
+                },
             });
-        return { ok: true, data: { ...result, authorityScan } };
+        // A `bypass` overlap is not a warning, it is a proof that this rule cannot
+        // bind the key it names: the neighbour carries NO policy, so the signer
+        // names that rule instead and the predicate never runs. Returning `ok` with
+        // the finding buried in `authorityScan` puts the whole protection on the
+        // caller reading a field, and the caller here is usually an agent that
+        // checks whether the call succeeded. Refuse, and let the caller opt in.
+        //
+        // Only the provable class. `unknown` - a neighbour whose policy this tool
+        // cannot decode - stays advisory: it may well be tighter, and refusing on
+        // "cannot decode" would block installs on a guess.
+        const bypassRefusal = authorityBypassRefusal(authorityScan, input.allowAuthorityOverlap);
+        if (bypassRefusal !== undefined) {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: bypassRefusal,
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        // Write the envelope here when asked, so it never travels through the
+        // caller. `writtenTo` is what the caller should hand to a signer.
+        let writtenTo;
+        if (input.outPath !== undefined) {
+            // Write beside the target and rename, which is atomic within a
+            // filesystem. A plain write truncates first, so anything watching the
+            // directory - a signer picking up envelopes is the obvious case - can
+            // read a half-written file and report a malformed TRANSACTION. With a
+            // rename the path either does not exist or holds the whole envelope.
+            const staging = `${input.outPath}.partial`;
+            await writeFile(staging, result.unsignedXdr, 'utf8');
+            const readBack = await readFile(staging, 'utf8');
+            if (readBack !== result.unsignedXdr) {
+                await rm(staging, { force: true });
+                throw new Error(`outPath: wrote ${result.unsignedXdr.length} characters to ${input.outPath} but read back ${readBack.length}; the file was not persisted intact`);
+            }
+            await rename(staging, input.outPath);
+            writtenTo = input.outPath;
+        }
+        return {
+            ok: true,
+            data: { ...result, authorityScan, ...(writtenTo !== undefined ? { writtenTo } : {}) },
+        };
     }
     catch (e) {
         return toolFailure('install_policy', e);
@@ -708,6 +800,7 @@ async function resolveExistingRules(input, network, interpreterAddress) {
             reader: accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[network]),
             smartAccount: input.smartAccount,
             interpreterAddress,
+            spendingLimitAddress: PINNED_OZ_POLICY_ADDRESS_BY_NETWORK[network].spending_limit,
         });
         if (collected.incomplete)
             return null;