@crediolabs/policy-synth 1.2.0 → 1.3.0

package/dist-cjs/install/authority-overlap.js

@@ -200,14 +200,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}`;
     }
 }
 /**
@@ -231,17 +255,42 @@ 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-cjs/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-cjs/install/read-account-rules.js

@@ -28,6 +28,9 @@ exports.decodeContextType = decodeContextType;
 exports.decodeSigner = decodeSigner;
 exports.decodeContextRule = decodeContextRule;
 exports.decodeStoredPredicateBytes = decodeStoredPredicateBytes;
+exports.spendCapKeyScVal = spendCapKeyScVal;
+exports.spendCapLedgerKey = spendCapLedgerKey;
+exports.decodeSpendCap = decodeSpendCap;
 exports.collectObservedRules = collectObservedRules;
 exports.accountRuleReaderFromServer = accountRuleReaderFromServer;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
@@ -158,6 +161,43 @@ 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. */
+function spendCapKeyScVal(smartAccount, ruleId) {
+    return stellar_sdk_1.xdr.ScVal.scvVec([
+        stellar_sdk_1.xdr.ScVal.scvSymbol('AccountContext'),
+        new stellar_sdk_1.Address(smartAccount).toScVal(),
+        stellar_sdk_1.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. */
+function spendCapLedgerKey(spendingLimit, smartAccount, ruleId) {
+    return stellar_sdk_1.xdr.LedgerKey.contractData(new stellar_sdk_1.xdr.LedgerKeyContractData({
+        contract: new stellar_sdk_1.Address(spendingLimit).toScAddress(),
+        key: spendCapKeyScVal(smartAccount, ruleId),
+        durability: stellar_sdk_1.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. */
+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() !== stellar_sdk_1.xdr.ScValType.scvI128())
+        return undefined;
+    const amount = (0, stellar_sdk_1.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. */
@@ -206,6 +246,16 @@ 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 };
@@ -248,5 +298,13 @@ 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() !== stellar_sdk_1.xdr.LedgerEntryType.contractData())
+                return undefined;
+            return entry.contractData().val();
+        },
     };
 }

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

@@ -41,9 +41,12 @@ export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<
 /** The refusal message for an install the cross-rule scan proves cannot bind,
  *  or `undefined` when the install may proceed.
  *
- *  Only `bypass` refuses. That class means the neighbouring rule carries NO
- *  policy, so a shared signer names it and the new predicate never runs - a
- *  proof, from data already in hand, that the rule constrains nothing.
+ *  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

package/dist-cjs/run/index.js

@@ -169,9 +169,12 @@ async function runSynthesizePolicy(raw) {
 /** The refusal message for an install the cross-rule scan proves cannot bind,
  *  or `undefined` when the install may proceed.
  *
- *  Only `bypass` refuses. That class means the neighbouring rule carries NO
- *  policy, so a shared signer names it and the new predicate never runs - a
- *  proof, from data already in hand, that the rule constrains nothing.
+ *  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
@@ -186,7 +189,12 @@ function authorityBypassRefusal(scan, allowAuthorityOverlap) {
     if (proven.length === 0)
         return undefined;
     const ids = proven.map((o) => o.ruleId).join(', ');
-    return `install_policy: ${proven[0]?.advice ?? ''} This rule would install cleanly and constrain nothing, so it is refused (rule ${ids}); remove the shared signer from that rule, attach a policy to it, or set \`allowAuthorityOverlap: true\` to install anyway.`;
+    // 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.`;
 }
 async function runInstallPolicy(raw) {
     const parsed = schemas_ts_1.InstallPolicyInputSchema.safeParse(raw);
@@ -387,8 +395,24 @@ async function runInstallPolicy(raw) {
                     contextType: rule.contextRuleType,
                     signers: rule.signers,
                     predicate: (0, decode_ts_1.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: schemas_ts_1.PINNED_OZ_POLICY_ADDRESS_BY_NETWORK[network].spending_limit,
+                },
             });
         // 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
@@ -813,6 +837,7 @@ async function resolveExistingRules(input, network, interpreterAddress) {
             reader: (0, read_account_rules_ts_1.accountRuleReaderFromServer)(server, schemas_ts_1.NETWORK_PASSPHRASES[network]),
             smartAccount: input.smartAccount,
             interpreterAddress,
+            spendingLimitAddress: schemas_ts_1.PINNED_OZ_POLICY_ADDRESS_BY_NETWORK[network].spending_limit,
         });
         if (collected.incomplete)
             return null;

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

@@ -2554,6 +2554,19 @@ export declare const ObservedRuleSchema: z.ZodObject<{
     }>]>, "many">;
     policyAddresses: z.ZodArray<z.ZodString, "many">;
     predicate: z.ZodOptional<z.ZodType<unknown, z.ZodTypeDef, unknown>>;
+    /** Parameters of an OZ spend cap already on this rule. Reporting only:
+     *  whether a neighbour is capped is read from `policyAddresses`, so omitting
+     *  this never turns a capped rule into an uncapped one. */
+    spendCap: z.ZodOptional<z.ZodObject<{
+        amount: z.ZodString;
+        periodLedgers: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        amount: string;
+        periodLedgers: number;
+    }, {
+        amount: string;
+        periodLedgers: number;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     signers: ({
         address: string;
@@ -2574,6 +2587,10 @@ export declare const ObservedRuleSchema: z.ZodObject<{
         kind: "create_contract";
         wasmHash: string;
     };
+    spendCap?: {
+        amount: string;
+        periodLedgers: number;
+    } | undefined;
     predicate?: unknown;
 }, {
     signers: ({
@@ -2595,6 +2612,10 @@ export declare const ObservedRuleSchema: z.ZodObject<{
         kind: "create_contract";
         wasmHash: string;
     };
+    spendCap?: {
+        amount: string;
+        periodLedgers: number;
+    } | undefined;
     predicate?: unknown;
 }>;
 /** Pinned interpreter address (testnet).
@@ -2805,6 +2826,19 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         }>]>, "many">;
         policyAddresses: z.ZodArray<z.ZodString, "many">;
         predicate: z.ZodOptional<z.ZodType<unknown, z.ZodTypeDef, unknown>>;
+        /** Parameters of an OZ spend cap already on this rule. Reporting only:
+         *  whether a neighbour is capped is read from `policyAddresses`, so omitting
+         *  this never turns a capped rule into an uncapped one. */
+        spendCap: z.ZodOptional<z.ZodObject<{
+            amount: z.ZodString;
+            periodLedgers: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            amount: string;
+            periodLedgers: number;
+        }, {
+            amount: string;
+            periodLedgers: number;
+        }>>;
     }, "strip", z.ZodTypeAny, {
         signers: ({
             address: string;
@@ -2825,6 +2859,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }, {
         signers: ({
@@ -2846,6 +2884,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }>, "many">>;
     /** The smart account contract address (C...) that will receive the rule. */
@@ -3471,6 +3513,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }[] | undefined;
     rule?: z.objectOutputType<{
@@ -3608,6 +3654,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }[] | undefined;
     rule?: z.objectInputType<{
@@ -3745,6 +3795,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }[] | undefined;
     rule?: z.objectOutputType<{
@@ -3882,6 +3936,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }[] | undefined;
     rule?: z.objectInputType<{
@@ -4019,6 +4077,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }[] | undefined;
     rule?: z.objectOutputType<{
@@ -4156,6 +4218,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }[] | undefined;
     rule?: z.objectInputType<{

package/dist-cjs/run/schemas.js

@@ -341,6 +341,15 @@ exports.ObservedRuleSchema = zod_1.z.object({
     signers: zod_1.z.array(SignerDraftSchema),
     policyAddresses: zod_1.z.array(zod_1.z.string()),
     predicate: exports.PredicateNodeSchema.optional(),
+    /** Parameters of an OZ spend cap already on this rule. Reporting only:
+     *  whether a neighbour is capped is read from `policyAddresses`, so omitting
+     *  this never turns a capped rule into an uncapped one. */
+    spendCap: zod_1.z
+        .object({
+        amount: zod_1.z.string().regex(/^[0-9]+$/),
+        periodLedgers: zod_1.z.number().int().positive().max(U32_MAX),
+    })
+        .optional(),
 });
 const ContextRuleDraftSchema = zod_1.z
     .object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "license": "MIT",
   "description": "Off-chain TypeScript synthesis core for the OZ Accounts Policy Builder. Records Soroban transactions, synthesises the minimal policy that permits exactly that flow, verifies it, and returns an unsigned install transaction.",
   "type": "module",

package/src/install/authority-overlap.ts

@@ -50,6 +50,26 @@ export type ContextType =
  *    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
@@ -59,6 +79,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 {
@@ -69,10 +94,16 @@ 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'
@@ -89,6 +120,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
 }
 
@@ -265,14 +304,45 @@ function classifyRule(rule: ObservedRule): RuleClass {
   return rule.predicate ? 'interpreter' : 'foreign'
 }
 
-function adviceFor(cls: RuleClass, ruleId: number): string {
+/** 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: ObservedRule, known: KnownPolicies): boolean {
+  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: ObservedRule, known: KnownPolicies): boolean {
+  return rule.policyAddresses.every(
+    (addr) => addr === known.interpreter || addr === known.spendingLimit
+  )
+}
+
+function capBypassAdvice(ruleId: number): string {
+  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: SpendCap, theirs: SpendCap): string {
+  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: RuleClass, ruleId: number, theirCap?: SpendCap, myCap?: SpendCap): string {
+  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}`
   }
 }
 
@@ -287,6 +357,9 @@ function adviceFor(cls: RuleClass, ruleId: number): string {
 export 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[] {
   const intendedSelectors = intersectSelectors(
     selectorsForContextType(args.intended.contextType),
@@ -304,18 +377,46 @@ 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: OverlapSeverity =
+      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 as const } : {}),
+      advice: capBypass
+        ? capBypassAdvice(rule.id)
+        : adviceFor(ruleClass, rule.id, rule.spendCap, args.intended.spendCap),
     })
   }