@crediolabs/policy-synth 1.1.1 → 1.3.0

package/src/install/read-account-rules.ts

@@ -27,12 +27,13 @@ import {
   Contract,
   Keypair,
   rpc,
+  scValToNative,
   TransactionBuilder,
   xdr,
 } from '@stellar/stellar-sdk'
 import { decodePredicate } from '../predicate/decode.ts'
 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 const K_DOC = 1
@@ -173,6 +174,49 @@ export function decodeStoredPredicateBytes(v: xdr.ScVal): Buffer | 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: string, ruleId: number): xdr.ScVal {
+  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: string,
+  smartAccount: string,
+  ruleId: number
+): xdr.LedgerKey {
+  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: xdr.ScVal): SpendCap | undefined {
+  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 }
+}
+
 // ---- collection -----
 
 /** The three reads the scan needs. Kept as an interface so the collection
@@ -189,6 +233,14 @@ export interface AccountRuleReader {
     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
@@ -227,6 +279,10 @@ export async 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> {
   const count = await args.reader.getContextRuleCount(args.smartAccount)
@@ -259,6 +315,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)
   }
 
@@ -309,5 +375,12 @@ export function accountRuleReaderFromServer(
       if (!entry || entry.switch() !== xdr.LedgerEntryType.contractData()) 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/src/run/index.ts

@@ -18,6 +18,7 @@
 // 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.ts'
 import {
@@ -236,6 +237,38 @@ export async function runSynthesizePolicy(raw: unknown): Promise<
   }
 }
 
+/** 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: AuthorityOverlap[] | null,
+  allowAuthorityOverlap: boolean | undefined
+): string | undefined {
+  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: unknown
 ): Promise<ToolResponse<BuildInstallPolicyResult & { authorityScan: AuthorityOverlap[] | null }>> {
@@ -450,10 +483,73 @@ export async function runInstallPolicy(
               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: string | undefined
+    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)
   }
@@ -868,6 +964,7 @@ async function resolveExistingRules(
       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
     return collected.rules

package/src/run/schemas.ts

@@ -381,6 +381,15 @@ export const ObservedRuleSchema = z.object({
   signers: z.array(SignerDraftSchema),
   policyAddresses: z.array(z.string()),
   predicate: 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: z
+    .object({
+      amount: z.string().regex(/^[0-9]+$/),
+      periodLedgers: z.number().int().positive().max(U32_MAX),
+    })
+    .optional(),
 })
 
 const ContextRuleDraftSchema = z
@@ -713,6 +722,22 @@ export const InstallPolicyInputSchema = z
      *  knows. Supply it only to re-install over an existing rule, where the
      *  interpreter wants `stored_nonce + 1`. */
     installNonce: z.number().int().positive().optional(),
+    /** Absolute path to write the unsigned envelope to.
+     *
+     *  The envelope runs to several thousand characters, and without this the
+     *  only route onto disk is the CALLER re-emitting it - through a model, a
+     *  shell argument, or both. That transport mangles it: observed in practice
+     *  as a file of the right length whose bytes no longer parse
+     *  ("xdr padding contains non-zero bytes"), and as silent truncation.
+     *  Writing it here takes the caller out of the transport entirely.
+     *
+     *  Opt-in: omitted, nothing is written and behaviour is unchanged. */
+    outPath: z
+      .string()
+      .min(1)
+      .refine((p) => p.startsWith('/'), 'outPath must be an absolute path')
+      .refine((p) => !p.includes('\0'), 'outPath must not contain a null byte')
+      .optional(),
     /** Optional RPC URL override. Defaults to the pinned RPC for the
      *  selected `network` (testnet by default, mainnet when
      *  `network: 'mainnet'`); the override is refused unless
@@ -756,6 +781,18 @@ export const InstallPolicyInputSchema = z
      *  unaffected; only the case the synthesizer explicitly flagged is
      *  refused. */
     allowUnboundedAmount: z.boolean().optional(),
+    /** Opt-in to installing a rule that the cross-rule scan proves cannot bind.
+     *
+     *  An OZ account resolves a call against the rule the caller NAMES, so a
+     *  key on several rules gets the MAXIMUM authority over them, never the
+     *  intersection. A key that also sits on a rule with no policy is therefore
+     *  unconstrained: it names that rule and the new predicate never runs.
+     *
+     *  Default-deny, and only for the case the scan can PROVE - an unpoliced
+     *  neighbour sharing signers and selectors. A neighbour carrying a policy
+     *  this tool cannot decode stays advisory, because "cannot decode" is not
+     *  "proved unsafe" and refusing it would block installs on a guess. */
+    allowAuthorityOverlap: z.boolean().optional(),
     /** Opt-in to pointing the rule's interpreter policy at any address
      *  other than the pinned interpreter for the selected network.
      *  Default-deny: a caller that controls the interpreter can permit