@crediolabs/policy-synth 0.1.18 → 0.2.0

package/src/install/build-merge-policy.ts

@@ -0,0 +1,219 @@
+//! Transactions for the merge remedy.
+//!
+//! `plan-merge-policy.ts` decides WHAT should happen; this builds the XDR for
+//! the step the caller asked for. Two calls, in order, because OZ refuses to
+//! attach a policy that is already on the rule:
+//!
+//!   step 1 `detach`    -> `account.remove_policy(rule_id, policy_id)`
+//!   step 2 `reinstall` -> `account.add_policy(rule_id, interpreter, param)`
+//!
+//! The two cannot be emitted together. Simulating step 2 while the old
+//! attachment is still there hits `DuplicatePolicy`, so the second transaction
+//! is only buildable once the first has confirmed.
+//!
+//! Both calls route through the smart account and are authorised the same way
+//! as `revoke_policy`: against the deploy-time admin rule, with the recorded
+//! `rootInvocation` binding the auth payload to this exact rule and policy.
+//! Detaching runs our `uninstall`, which is master-gated, so the signer has to
+//! be a master of the rule either way.
+
+import {
+  Account,
+  Address,
+  BASE_FEE,
+  Operation,
+  rpc,
+  TransactionBuilder,
+  xdr,
+} from '@stellar/stellar-sdk'
+import { DEFAULT_GRAMMAR_VERSION, encodePolicyInstallParams } from './build-add-context-rule.ts'
+import type { InstallRpcClient } from './build-install-policy.ts'
+import {
+  accountEntry,
+  authDigest,
+  authPayload,
+  delegatedSignerEntry,
+  signaturePayload,
+} from './oz-auth.ts'
+import type { MergeStep } from './plan-merge-policy.ts'
+
+/** Matches the window the install and revoke builders use. */
+const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 100
+
+/**
+ * The context rule the merge authorises AGAINST, which is not the rule being
+ * merged.
+ *
+ * Both calls mutate the smart account itself, so they need the account's own
+ * authorisation, and this builder asks rule 0 for it - the same assumption the
+ * install and revoke builders make. OpenZeppelin does NOT enforce any
+ * admin semantic for rule 0: it is simply the first rule the account's
+ * constructor created, and OZ's reference account creates it as `Default`
+ * covering every context.
+ *
+ * The assumption is therefore load-bearing and unverified at build time. If
+ * rule 0 does not exist, does not cover `CallContract(<smart account>)`, or
+ * does not list the source account as a signer, the transaction is built and
+ * then fails when submitted, and the operator pays the fee for a transaction
+ * that was never signable. Changing it is a wire-visible change: the id is
+ * hashed into the auth digest.
+ */
+export const ADMIN_CONTEXT_RULE_ID = 0
+
+export interface BuildMergePolicyArgs {
+  smartAccount: string
+  sourceAccount: string
+  networkPassphrase: string
+  ruleId: number
+  /** OZ registry id of the interpreter policy on this rule, from the plan. */
+  policyId: number
+  interpreterAddress: string
+  step: MergeStep
+  /** Only needed for `reinstall`: the merged predicate, already encoded. */
+  encodedPredicate?: string
+  predicateHash?: string
+  /** Nonce for the reinstall. Read from chain rather than assumed: a detach
+   *  whose uninstall panicked leaves the old nonce in place. */
+  installNonce?: number
+  /** Oracle bounds to carry over from the document being replaced. */
+  oracleParams?: {
+    maxStalenessSeconds?: number
+    maxDeviationBps?: number
+    maxCrossFeedDeviationBps?: number
+  }
+  rpc: InstallRpcClient
+  baseFee?: number
+  authValidUntilLedgers?: number
+}
+
+export interface BuildMergePolicyResult {
+  unsignedXdr: string
+  smartAccount: string
+  sourceAccount: string
+  step: MergeStep
+  call: { contract: string; fn: 'remove_policy' | 'add_policy'; ruleId: number }
+  authNonce: string
+  authValidUntilLedger: number
+  rootInvocationXdr: string
+}
+
+function hostFunctionFor(args: BuildMergePolicyArgs): xdr.HostFunction {
+  if (args.step === 'detach') {
+    return xdr.HostFunction.hostFunctionTypeInvokeContract(
+      new xdr.InvokeContractArgs({
+        contractAddress: new Address(args.smartAccount).toScAddress(),
+        functionName: 'remove_policy',
+        args: [xdr.ScVal.scvU32(args.ruleId), xdr.ScVal.scvU32(args.policyId)],
+      })
+    )
+  }
+
+  if (!args.encodedPredicate || !args.predicateHash) {
+    throw new Error('merge_policy: reinstall needs the merged predicate and its hash')
+  }
+  return xdr.HostFunction.hostFunctionTypeInvokeContract(
+    new xdr.InvokeContractArgs({
+      contractAddress: new Address(args.smartAccount).toScAddress(),
+      functionName: 'add_policy',
+      args: [
+        xdr.ScVal.scvU32(args.ruleId),
+        new Address(args.interpreterAddress).toScVal(),
+        // Same encoder as a fresh install: the field order is ABI-significant
+        // and it re-hashes the predicate to confirm the supplied hash.
+        encodePolicyInstallParams({
+          encodedPredicate: args.encodedPredicate,
+          predicateHash: args.predicateHash,
+          installNonce: args.installNonce ?? 1,
+          grammarVersion: DEFAULT_GRAMMAR_VERSION,
+          ...(args.oracleParams ? { oracleParams: args.oracleParams } : {}),
+        }),
+      ],
+    })
+  )
+}
+
+/**
+ * Build the unsigned transaction for one step of the merge.
+ *
+ * The auth dance mirrors `buildRevokePolicyXdr`: simulate once to record the
+ * account's auth entry, rebuild with the payload bound to that recorded
+ * `rootInvocation`, then assemble. Binding to the recorded invocation rather
+ * than to the input arguments is what makes the signature commit to the exact
+ * rule and policy being changed.
+ */
+export async function buildMergePolicyXdr(
+  args: BuildMergePolicyArgs
+): Promise<BuildMergePolicyResult> {
+  const fn = args.step === 'detach' ? 'remove_policy' : 'add_policy'
+  const source = await args.rpc.getAccount(args.sourceAccount)
+  const hostFunction = hostFunctionFor(args)
+  const makeOperation = (auth: xdr.SorobanAuthorizationEntry[] = []) =>
+    Operation.invokeHostFunction({ func: hostFunction, auth })
+  const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE
+
+  const buildTx = (op: xdr.Operation) =>
+    new TransactionBuilder(new Account(args.sourceAccount, source.sequenceNumber()), {
+      fee: baseFee,
+      networkPassphrase: args.networkPassphrase,
+    })
+      .addOperation(op)
+      .setTimeout(0)
+      .build()
+
+  const recorded = await args.rpc.simulateTransaction(buildTx(makeOperation()))
+  if (rpc.Api.isSimulationError(recorded)) {
+    // Short and stable, like the other builders: the SDK's full error carries
+    // host and URL detail that has no business in a user-facing message.
+    throw new Error(`merge_policy: ${fn} simulateTransaction failed`)
+  }
+  const original = (recorded.result?.auth ?? []).find(
+    (entry) =>
+      entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
+      Address.fromScAddress(entry.credentials().address().address()).toString() ===
+        args.smartAccount
+  )
+  if (!original) {
+    throw new Error(
+      `merge_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`
+    )
+  }
+
+  const validUntilLedger =
+    (await args.rpc.getLatestLedger()).sequence +
+    (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_UNTIL_LEDGERS)
+  const contextRuleIds = [ADMIN_CONTEXT_RULE_ID]
+  const digest = authDigest(
+    signaturePayload(
+      args.networkPassphrase,
+      original.credentials().address().nonce(),
+      validUntilLedger,
+      original.rootInvocation()
+    ),
+    contextRuleIds
+  )
+  const authEntries = [
+    accountEntry(
+      original,
+      validUntilLedger,
+      authPayload([args.sourceAccount], contextRuleIds, () => Buffer.alloc(0))
+    ),
+    ...contextRuleIds.map(() => delegatedSignerEntry(args.smartAccount, digest)),
+  ]
+  const txWithAuth = buildTx(makeOperation(authEntries))
+  const enforcing = await args.rpc.simulateTransaction(txWithAuth)
+  if (rpc.Api.isSimulationError(enforcing)) {
+    throw new Error(`merge_policy: ${fn} auth simulateTransaction failed`)
+  }
+  const finalTx = rpc.assembleTransaction(txWithAuth, enforcing).build()
+
+  return {
+    unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+    smartAccount: args.smartAccount,
+    sourceAccount: args.sourceAccount,
+    step: args.step,
+    call: { contract: args.smartAccount, fn, ruleId: args.ruleId },
+    authNonce: original.credentials().address().nonce().toString(),
+    authValidUntilLedger: validUntilLedger,
+    rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
+  }
+}

package/src/install/index.ts

@@ -12,6 +12,29 @@
 // Exported here rather than from the package root to keep the root surface
 // about synthesis, and because these are transaction-building primitives whose
 // callers should know they are reaching for them.
+
+// Cross-rule authority analysis. A caller installing a policy needs to know
+// whether its signers can already reach the same calls through another context
+// rule, because OZ lets the signer name the rule and enforces only that one's
+// policies. Without this, a second, tighter rule reads as a restriction while
+// restricting nothing.
+export {
+  ANY,
+  type AuthorityOverlap,
+  type ContextType,
+  effectiveSelectors,
+  findAuthorityOverlaps,
+  type IntendedInstall,
+  intersectSelectors,
+  type MergeResult,
+  mergeIntoAnd,
+  type ObservedRule,
+  type OverlapSeverity,
+  permittedSelectors,
+  type RuleClass,
+  type Selector,
+  signerKey,
+} from './authority-overlap.ts'
 export {
   ADD_CONTEXT_RULE_SYMBOL,
   type AddContextRuleArgs,
@@ -19,3 +42,14 @@ export {
   buildAddContextRuleArgs,
   DEFAULT_GRAMMAR_VERSION,
 } from './build-add-context-rule.ts'
+export {
+  type AccountRuleReader,
+  accountRuleReaderFromServer,
+  type CollectedRules,
+  collectObservedRules,
+  decodeContextRule,
+  decodeContextType,
+  decodeSigner,
+  docLedgerKey,
+  MAX_RULE_ID_SCAN,
+} from './read-account-rules.ts'

package/src/install/plan-merge-policy.ts

@@ -0,0 +1,133 @@
+//! Planning the merge remedy for a cross-rule authority overlap.
+//!
+//! When two rules our interpreter polices can serve the same calls, the
+//! tightening remedy is to replace one rule's predicate with the conjunction
+//! of both (see `authority-overlap.ts`). Carrying that out against an OZ smart
+//! account is not one call, and the reasons are worth stating because they
+//! shape the whole tool:
+//!
+//!   1. A Soroban transaction carries exactly ONE operation - "smart contract
+//!      transactions can only have one operation per transaction" - so the
+//!      detach and the re-attach cannot be bundled even though the host would
+//!      run them in order happily. And `add_policy` panics `DuplicatePolicy`
+//!      while the policy is still attached (`smart_account/storage.rs`
+//!      `add_policy`), so the second transaction cannot even be simulated
+//!      until the first has confirmed.
+//!   2. `remove_policy` calls `try_uninstall` and DISCARDS the result
+//!      (`smart_account/storage.rs`: `let _ = ...try_uninstall(...)`), so the
+//!      policy is detached whether or not our `uninstall` succeeded. When it
+//!      succeeded the document, nonce, signer hash, master set and counters
+//!      are gone and the re-install is a fresh install at nonce 1. When it
+//!      panicked - our `uninstall` panics `MissingState` if the master set has
+//!      been archived - the nonce SURVIVES, and re-installing at 1 would be
+//!      refused on chain as a replay, leaving the rule stuck unpoliced. The
+//!      nonce is therefore READ at reinstall time rather than assumed.
+//!   3. Because of (2), any rate-limit or spend window on that rule is reset
+//!      by the merge. A signer who had consumed most of a window gets a clean
+//!      one. That is a real cost of tightening this way and the caller has to
+//!      be told, not discover it.
+//!   4. So the caller performs step 1, waits for it to confirm, then asks for
+//!      step 2.
+//!
+//! This module is pure. It decides what should happen and why; the XDR is
+//! built by `build-merge-policy.ts`.
+
+import type { PredicateNode } from '../types.ts'
+import type { ObservedRule } from './authority-overlap.ts'
+import { type MergeResult, mergeIntoAnd } from './authority-overlap.ts'
+
+export type MergeStep = 'detach' | 'reinstall'
+
+export interface MergePlanRefused {
+  ok: false
+  /** Why the merge cannot proceed, in terms the caller can act on. */
+  reason: string
+}
+
+export interface MergePlanAccepted {
+  ok: true
+  /** The conjunction to install in step 2. */
+  predicate: PredicateNode
+  /** OZ registry id of the interpreter policy on this rule, for
+   *  `remove_policy`. */
+  policyId: number
+  /** Oracle bounds to re-install with the merged predicate. Carried from the
+   *  document being replaced: they are tighten-only overrides against the wasm
+   *  defaults, so omitting them would quietly widen the policy while the
+   *  operator believed they were tightening it. */
+  oracleParams?: {
+    maxStalenessSeconds?: number
+    maxDeviationBps?: number
+    maxCrossFeedDeviationBps?: number
+  }
+  /** Consequences the caller must see BEFORE signing step 1, because step 1 is
+   *  the destructive one. */
+  warnings: string[]
+  /** What the caller should do after the requested step confirms. */
+  followUp: string
+}
+
+export type MergePlan = MergePlanRefused | MergePlanAccepted
+
+/** The interpreter's registry id on a rule, or null when it is not attached
+ *  or the ids were not readable. */
+export function interpreterPolicyId(rule: ObservedRule, interpreterAddress: string): number | null {
+  const index = rule.policyAddresses.indexOf(interpreterAddress)
+  if (index < 0) return null
+  const id = rule.policyIds?.[index]
+  return typeof id === 'number' ? id : null
+}
+
+/**
+ * Decide whether the merge can proceed, and say what it will cost.
+ *
+ * Refuses rather than guesses whenever the account is not in the shape the
+ * remedy assumes: the rule must be policed by our interpreter, its predicate
+ * must have been readable, and the ids needed to detach it must be present. A
+ * merge built on a predicate we could not read would silently replace a rule
+ * with something narrower or wider than its author wrote.
+ */
+export function planMergePolicy(args: {
+  rule: ObservedRule
+  interpreterAddress: string
+  incoming: PredicateNode
+  step: MergeStep
+}): MergePlan {
+  const policyId = interpreterPolicyId(args.rule, args.interpreterAddress)
+  if (policyId === null) {
+    return {
+      ok: false,
+      reason: `rule ${args.rule.id} is not policed by the interpreter at ${args.interpreterAddress}, or its policy ids could not be read, so there is nothing to merge into and no id to detach. The merge hard-pins to that interpreter and has no opt-out: the auth digest it builds binds to the audited deployment. A rule installed against a different interpreter has to be replaced rather than merged.`,
+    }
+  }
+
+  const existing = args.rule.predicate
+  if (!existing) {
+    return {
+      ok: false,
+      reason: `the predicate installed on rule ${args.rule.id} could not be read, so it cannot be conjoined; merging against an unknown predicate would replace the rule with something other than what its author wrote`,
+    }
+  }
+
+  const merged: MergeResult = mergeIntoAnd(existing, args.incoming)
+  if (!merged.ok || !merged.predicate) {
+    return { ok: false, reason: merged.reason ?? 'the two predicates cannot be conjoined' }
+  }
+
+  const warnings = [
+    `detaching the policy uninstalls it, which removes every counter on rule ${args.rule.id}: any rate limit or spend window there restarts from zero after the merge`,
+    'the rule is unpoliced between the two transactions, so a signer of it is unconstrained by this policy until step 2 confirms',
+  ]
+
+  return {
+    ok: true,
+    predicate: merged.predicate,
+    policyId,
+    ...(args.rule.oracleBounds ? { oracleParams: args.rule.oracleBounds } : {}),
+    warnings,
+    followUp:
+      args.step === 'detach'
+        ? "sign and submit this transaction, wait for it to confirm, then call again with step: 'reinstall' to install the merged predicate"
+        : 'sign and submit this transaction; the merged predicate is then the only policy governing this rule',
+  }
+}