@crediolabs/policy-synth 0.1.13 → 0.1.15

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

@@ -13,9 +13,12 @@
 // (b) key material the server does not have, so we ship the simpler ONE-CALL
 // shape. The wallet signature covers the change.
 //
-// `buildInstallPolicyXdr` returns CALL 1 ONLY. Call 2 (interpreter.install)
-// needs the rule id the account assigns in call 1, so it cannot be pre-built
-// and is documented in the response envelope under `followUp`.
+// `buildInstallPolicyXdr` installs the policy in ONE call. `add_context_rule`
+// takes `policies` as a `Map<policy_address, install_param>` and the account
+// forwards each install_param to that policy, so the interpreter stores the
+// predicate document as part of this same transaction. Earlier revisions
+// documented a second `interpreter.install` call; that was wrong, and issuing
+// it fails - the account re-enters the interpreter while it is mid-install.
 
 import { createHash } from 'node:crypto'
 import {
@@ -31,6 +34,13 @@ import {
   xdr,
 } from '@stellar/stellar-sdk'
 import { buildAddContextRuleArgs, DEFAULT_GRAMMAR_VERSION } from './build-add-context-rule.ts'
+import {
+  accountEntry,
+  authDigest,
+  authPayload,
+  delegatedSignerEntry,
+  signaturePayload,
+} from './oz-auth.ts'
 
 /** Minimal Soroban RPC surface the install pipeline needs. Test seams
  *  inject a stub so the builder stays deterministic; production builds
@@ -209,19 +219,17 @@ export interface BuildInstallPolicyResult {
   smartAccount: string
   /** Source account (echo) - the address that must sign. */
   sourceAccount: string
-  /** The host-call target + fn name. Call 2 (interpreter.install) is NOT
-   *  emitted here; the account assigns the rule id in call 1 and call 2
-   *  needs that id to bind its `context_rule_ids`. See `followUp` below. */
+  /** The host-call target + fn name. This single call installs the policy
+   *  outright: `add_context_rule` takes `policies` as a
+   *  `Map<policy_address, install_param>`, and the account forwards each
+   *  install_param to that policy. For an interpreter policy the param
+   *  carries the predicate and its hash, so the interpreter stores the
+   *  document as part of this transaction. There is no second call.
+   *
+   *  Verified on testnet 2026-08-01: a rule created by this builder alone
+   *  permits a matching operator call and denies a non-matching one with
+   *  interpreter code #100 - not #206 MissingState. */
   call: { contract: string; fn: 'add_context_rule' }
-  /** The follow-up call the caller MUST issue after this one confirms.
-   *  The rule id the account assigns in call 1 is required to bind the
-   *  interpreter's `install` auth context. */
-  followUp: {
-    contract: 'interpreter'
-    fn: 'install'
-    requiresRuleIdFromCallOne: true
-    hint: string
-  }
   /** Human-readable description of the install call, decoded FROM the
    *  built unsigned XDR (not from the input args). The wallet signature
    *  binds to bytes; the review card has to bind to the same bytes, so
@@ -236,9 +244,6 @@ export interface BuildInstallPolicyResult {
   rootInvocationXdr: string
 }
 
-const FOLLOWUP_HINT =
-  'after this tx confirms, read the rule id via account.get_context_rules_count()-1 (or get the receipt events), then call runInstallPolicy a second time with the interpreter as the target and the rule id in context_rule_ids - OR hand-build the install() call directly with the OZ auth pattern.'
-
 /** Build the unsigned transaction envelope for `account.add_context_rule(...)`.
  *  The output XDR is signed by the wallet, not by us. */
 export async function buildInstallPolicyXdr(
@@ -265,36 +270,33 @@ export async function buildInstallPolicyXdr(
     }
   )
 
-  // 2. Network pass: source account sequence + latest ledger.
+  // 2. Fetch the source sequence, then build the recording transaction with a
+  //    bare host call. The recording pass assigns the smart-account auth nonce
+  //    and root invocation needed to construct OZ's AuthPayload.
   const source = await args.rpc.getAccount(args.sourceAccount)
-  const latest = await args.rpc.getLatestLedger()
-  const validUntilLedger =
-    latest.sequence + (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_LEDGERS)
-
-  // 3. Build the unsigned transaction envelope with the bare host call.
-  const op = Operation.invokeHostFunction({
-    func: xdr.HostFunction.hostFunctionTypeInvokeContract(
-      new xdr.InvokeContractArgs({
-        contractAddress: new Address(args.smartAccount).toScAddress(),
-        functionName: 'add_context_rule',
-        args: [...callArgs],
-      })
-    ),
-    auth: [],
-  })
+  const hostFunction = xdr.HostFunction.hostFunctionTypeInvokeContract(
+    new xdr.InvokeContractArgs({
+      contractAddress: new Address(args.smartAccount).toScAddress(),
+      functionName: 'add_context_rule',
+      args: [...callArgs],
+    })
+  )
+  const makeOperation = (auth: xdr.SorobanAuthorizationEntry[] = []) =>
+    Operation.invokeHostFunction({ func: hostFunction, auth })
   const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE
-  const tx = buildUnsignedTx({
-    sourceAccount: args.sourceAccount,
-    sequence: source.sequenceNumber(),
-    fee: baseFee,
-    networkPassphrase: args.networkPassphrase,
-    op,
-  })
-
-  // 4. Simulation pass. Returns the auth nonce + rootInvocation the wallet
-  //    signature binds to. We do NOT add the AuthPayload here - the wallet
-  //    injects auth entries using its own __check_auth flow.
-  const recorded = await args.rpc.simulateTransaction(tx)
+  const buildTx = (op: xdr.Operation) =>
+    buildUnsignedTx({
+      sourceAccount: args.sourceAccount,
+      sequence: source.sequenceNumber(),
+      fee: baseFee,
+      networkPassphrase: args.networkPassphrase,
+      op,
+    })
+  const recordingTx = buildTx(makeOperation())
+
+  // 3. Recording simulation: capture the smart account's nonce and invocation
+  //    tree. Nothing is signed here.
+  const recorded = await args.rpc.simulateTransaction(recordingTx)
   if (rpc.Api.isSimulationError(recorded)) {
     // Short, stable reason. The full `simulateTransaction` error (which
     // carries host + URL detail) stays in the SDK's own logs - never
@@ -314,24 +316,51 @@ export async function buildInstallPolicyXdr(
     )
   }
 
-  // 5. Decode the structured description FROM the unsigned XDR. The human
-  //    approval binds to the bytes the wallet will sign; deriving this from
-  //    the input args would re-describe the caller's intent rather than the
-  //    transaction. Re-parse the envelope we just built so the description
-  //    reflects what the wallet actually signs, not what we thought it would.
-  const describes = decodeInstallCallDescribes(tx, op, args.installNonce)
+  // 4. `add_context_rule` is authorised by the deploy-time admin rule (rule 0).
+  //    The delegated signer uses source-account credentials, so its signature
+  //    bytes stay empty and the ordinary transaction-envelope signature covers
+  //    the call when the consumer signs it.
+  const validUntilLedger =
+    (await args.rpc.getLatestLedger()).sequence +
+    (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_UNTIL_LEDGERS)
+  const contextRuleIds = [0]
+  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)),
+  ]
+
+  // 5. Simulate again with the OZ entries already attached. The SDK preserves
+  //    existing auth during assembly and adds the simulated Soroban footprint +
+  //    resource fee, yielding a complete unsigned envelope.
+  const txWithAuth = buildTx(makeOperation(authEntries))
+  const enforcing = await args.rpc.simulateTransaction(txWithAuth)
+  if (rpc.Api.isSimulationError(enforcing)) {
+    throw new Error('install_policy: auth simulateTransaction failed')
+  }
+  const finalTx = rpc.assembleTransaction(txWithAuth, enforcing).build()
+
+  // 6. Decode the structured description FROM the final assembled transaction.
+  //    The human approval binds to the exact bytes the wallet will sign.
+  const describes = decodeInstallCallDescribes(finalTx, args.installNonce)
 
   return {
-    unsignedXdr: tx.toEnvelope().toXDR().toString('base64'),
+    unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
     smartAccount: args.smartAccount,
     sourceAccount: args.sourceAccount,
     call: { contract: args.smartAccount, fn: 'add_context_rule' },
-    followUp: {
-      contract: 'interpreter',
-      fn: 'install',
-      requiresRuleIdFromCallOne: true,
-      hint: FOLLOWUP_HINT,
-    },
     describes,
     authNonce: original.credentials().address().nonce().toString(),
     authValidUntilLedger: validUntilLedger,
@@ -360,30 +389,26 @@ export async function buildRevokePolicyXdr(args: {
   authValidUntilLedgers?: number
 }): Promise<BuildRevokePolicyResult> {
   const source = await args.rpc.getAccount(args.sourceAccount)
-  const latest = await args.rpc.getLatestLedger()
-  const validUntilLedger =
-    latest.sequence + (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_LEDGERS)
-
-  const op = Operation.invokeHostFunction({
-    func: xdr.HostFunction.hostFunctionTypeInvokeContract(
-      new xdr.InvokeContractArgs({
-        contractAddress: new Address(args.smartAccount).toScAddress(),
-        functionName: 'remove_context_rule',
-        args: [xdr.ScVal.scvU32(args.ruleId)],
-      })
-    ),
-    auth: [],
-  })
+  const hostFunction = xdr.HostFunction.hostFunctionTypeInvokeContract(
+    new xdr.InvokeContractArgs({
+      contractAddress: new Address(args.smartAccount).toScAddress(),
+      functionName: 'remove_context_rule',
+      args: [xdr.ScVal.scvU32(args.ruleId)],
+    })
+  )
+  const makeOperation = (auth: xdr.SorobanAuthorizationEntry[] = []) =>
+    Operation.invokeHostFunction({ func: hostFunction, auth })
   const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE
-  const tx = buildUnsignedTx({
-    sourceAccount: args.sourceAccount,
-    sequence: source.sequenceNumber(),
-    fee: baseFee,
-    networkPassphrase: args.networkPassphrase,
-    op,
-  })
-
-  const recorded = await args.rpc.simulateTransaction(tx)
+  const buildTx = (op: xdr.Operation) =>
+    buildUnsignedTx({
+      sourceAccount: args.sourceAccount,
+      sequence: source.sequenceNumber(),
+      fee: baseFee,
+      networkPassphrase: args.networkPassphrase,
+      op,
+    })
+
+  const recorded = await args.rpc.simulateTransaction(buildTx(makeOperation()))
   if (rpc.Api.isSimulationError(recorded)) {
     // Short, stable reason. The full `simulateTransaction` error (which
     // carries host + URL detail) stays in the SDK's own logs - never
@@ -403,8 +428,41 @@ export async function buildRevokePolicyXdr(args: {
     )
   }
 
+  // Removal is master-only, so the deploy-time admin rule authorises it. The
+  // recorded rootInvocation still includes remove_context_rule(ruleId), binding
+  // the auth payload to the exact rule being removed. As with install,
+  // source-account credentials carry the delegated signer entry and the
+  // consumer supplies only the ordinary envelope signature.
+  const validUntilLedger =
+    (await args.rpc.getLatestLedger()).sequence +
+    (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_UNTIL_LEDGERS)
+  const contextRuleIds = [0]
+  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('revoke_policy: auth simulateTransaction failed')
+  }
+  const finalTx = rpc.assembleTransaction(txWithAuth, enforcing).build()
+
   return {
-    unsignedXdr: tx.toEnvelope().toXDR().toString('base64'),
+    unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
     smartAccount: args.smartAccount,
     sourceAccount: args.sourceAccount,
     call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },
@@ -425,7 +483,7 @@ export interface BuildRevokePolicyResult {
 }
 
 /** ~25 minutes at 5s/ledger. */
-const DEFAULT_AUTH_VALID_LEDGERS = 300
+const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 300
 
 // ---- internals ----
 
@@ -476,12 +534,11 @@ function buildUnsignedTx(args: {
   return tx
 }
 
-/** Decode the install call's structured fields directly out of the
- *  built (transaction, operation) pair. The bytes are the source of
- *  truth: a human reviewing the install wants to see what the wallet
- *  will actually sign, not what we think it will. The decode is
- *  deliberately strict - any shape we did not build ourselves throws
- *  a ToolError, since that would mean the XDR was tampered with (or
+/** Decode the install call's structured fields directly out of the final
+ *  assembled transaction. The bytes are the source of truth: a human reviewing
+ *  the install wants to see what the wallet will actually sign, not what we
+ *  think it will. The decode is deliberately strict - any shape we did not
+ *  build ourselves throws, since that would mean the XDR was tampered with (or
  *  the encoder changed and this descriptor lags).
  *
  *  `expectedInstallNonce` is a fallback for the rare case where the
@@ -489,11 +546,17 @@ function buildUnsignedTx(args: {
  *  caller already knows it. */
 function decodeInstallCallDescribes(
   tx: Transaction,
-  op: xdr.Operation,
   expectedInstallNonce: number
 ): InstallCallDescribes {
+  const operations = tx.toEnvelope().v1().tx().operations()
+  if (operations.length !== 1 || !operations[0]) {
+    throw new Error(
+      `install_policy: final transaction has ${operations.length} operations, expected 1`
+    )
+  }
+  const op = operations[0]
   const hostFn = op.body().invokeHostFunctionOp()?.hostFunction()
-  if (!hostFn || hostFn.switch().name !== 'hostFunctionTypeInvokeContract') {
+  if (hostFn?.switch().name !== 'hostFunctionTypeInvokeContract') {
     throw new Error(
       'install_policy: built op is not an invokeHostFunction(invokeContract(...)) call'
     )
@@ -661,10 +724,6 @@ function decodeInstallCallDescribes(
   // `observedInstallNonce` is the nonce baked into whichever interpreter
   // policy is present; when none, fall back to the caller-supplied value.
   const installNonce = observedInstallNonce ?? expectedInstallNonce
-  // Touch `tx` so the linter does not flag it as unused - the parameter
-  // documents that the caller built this Transaction; we re-parse the
-  // operation off it as a sanity check.
-  void tx
   return {
     targetContract,
     fnName: 'add_context_rule',

package/src/install/oz-auth.ts

@@ -0,0 +1,140 @@
+// Build the authorization entries OpenZeppelin's smart account requires.
+//
+// This is the piece that makes an end-to-end test of the account -> policy
+// path possible. Without it, every attempt to exercise `__check_auth`
+// produces a false positive: mocked auth skips `__check_auth` entirely,
+// direct invocation is rejected by the host, and recording-mode simulation
+// does not verify auth at all.
+//
+// Two entries are needed per call:
+//
+//   1. The ACCOUNT's entry. Its `signature` slot is not a signature - OZ puts
+//      an `AuthPayload { signers, context_rule_ids }` there, which
+//      `__check_auth` receives as its `signatures` argument.
+//
+//   2. One entry per DELEGATED signer. `do_check_auth` calls
+//      `addr.require_auth_for_args((auth_digest,))` for each, which is a
+//      nested authorization requirement the host will not record during
+//      simulation (it never runs `__check_auth` in recording mode), so it has
+//      to be constructed by hand.
+//
+// The digest OZ binds is NOT the raw auth payload hash:
+//
+//   auth_digest = sha256(signature_payload || xdr(context_rule_ids))
+//
+// where `signature_payload` is the standard Soroban authorization preimage
+// hash. See `do_check_auth` in
+// stellar-contracts/packages/accounts/src/smart_account/storage.rs.
+
+import { Address, hash, xdr } from '@stellar/stellar-sdk'
+
+const sym = (s: string) => xdr.ScVal.scvSymbol(s)
+const u32 = (n: number) => xdr.ScVal.scvU32(n)
+const vec = (i: xdr.ScVal[]) => xdr.ScVal.scvVec(i)
+const bytes = (b: Buffer) => xdr.ScVal.scvBytes(b)
+
+function struct(fields: Record<string, xdr.ScVal>): xdr.ScVal {
+  return xdr.ScVal.scvMap(
+    Object.keys(fields)
+      .sort()
+      .map((k) => new xdr.ScMapEntry({ key: sym(k), val: fields[k]! }))
+  )
+}
+
+/** `Signer::Delegated(addr)`. */
+export const delegatedSigner = (a: string) => vec([sym('Delegated'), new Address(a).toScVal()])
+
+/** The standard Soroban authorization preimage hash for one entry. */
+export function signaturePayload(
+  networkPassphrase: string,
+  nonce: xdr.Int64,
+  signatureExpirationLedger: number,
+  invocation: xdr.SorobanAuthorizedInvocation
+): Buffer {
+  const preimage = xdr.HashIdPreimage.envelopeTypeSorobanAuthorization(
+    new xdr.HashIdPreimageSorobanAuthorization({
+      networkId: hash(Buffer.from(networkPassphrase)),
+      nonce,
+      signatureExpirationLedger,
+      invocation,
+    })
+  )
+  return hash(preimage.toXDR())
+}
+
+/**
+ * `sha256(signature_payload || xdr(context_rule_ids))`.
+ *
+ * OZ binds the selected rule ids into the digest so a signature for one rule
+ * cannot be replayed against another.
+ */
+export function authDigest(payload: Buffer, contextRuleIds: number[]): Buffer {
+  const idsXdr = vec(contextRuleIds.map(u32)).toXDR()
+  return hash(Buffer.concat([payload, idsXdr]))
+}
+
+/** `AuthPayload { signers, context_rule_ids }` - the account's "signature". */
+export function authPayload(
+  signerAddresses: string[],
+  contextRuleIds: number[],
+  signatureFor: (addr: string) => Buffer
+): xdr.ScVal {
+  return struct({
+    signers: xdr.ScVal.scvMap(
+      signerAddresses
+        .map((a) => new xdr.ScMapEntry({ key: delegatedSigner(a), val: bytes(signatureFor(a)) }))
+        // Host maps must be sorted by key.
+        .sort((x, y) => Buffer.compare(x.key().toXDR(), y.key().toXDR()))
+    ),
+    context_rule_ids: vec(contextRuleIds.map(u32)),
+  })
+}
+
+/**
+ * The nested entry a `Delegated` signer needs.
+ *
+ * `require_auth_for_args` authorizes the CURRENT frame, which while
+ * `__check_auth` is running is the account contract executing `__check_auth`,
+ * with the digest as its single argument.
+ *
+ * The signer is the transaction source here, so source-account credentials
+ * carry it and no separate signature is required.
+ */
+export function delegatedSignerEntry(
+  accountId: string,
+  digest: Buffer
+): xdr.SorobanAuthorizationEntry {
+  return new xdr.SorobanAuthorizationEntry({
+    credentials: xdr.SorobanCredentials.sorobanCredentialsSourceAccount(),
+    rootInvocation: new xdr.SorobanAuthorizedInvocation({
+      function: xdr.SorobanAuthorizedFunction.sorobanAuthorizedFunctionTypeContractFn(
+        new xdr.InvokeContractArgs({
+          contractAddress: new Address(accountId).toScAddress(),
+          functionName: '__check_auth',
+          args: [bytes(digest)],
+        })
+      ),
+      subInvocations: [],
+    }),
+  })
+}
+
+/** Rebuild the account's entry with the AuthPayload in the signature slot. */
+export function accountEntry(
+  original: xdr.SorobanAuthorizationEntry,
+  signatureExpirationLedger: number,
+  payload: xdr.ScVal
+): xdr.SorobanAuthorizationEntry {
+  const creds = original.credentials().address()
+  return new xdr.SorobanAuthorizationEntry({
+    credentials: xdr.SorobanCredentials.sorobanCredentialsAddress(
+      new xdr.SorobanAddressCredentials({
+        address: creds.address(),
+        nonce: creds.nonce(),
+        signatureExpirationLedger,
+        signature: payload,
+      })
+    ),
+    rootInvocation: original.rootInvocation(),
+  })
+}

package/src/run/index.ts

@@ -300,9 +300,9 @@ export async function runVerifyPolicy(raw: unknown): Promise<ToolResponse<true>>
  *  Returns the unsigned Soroban transaction envelope (base64 XDR) the
  *  wallet signs. The wallet signature IS the user-confirmation step - no
  *  `action_id` two-call pair (the server is stateless, see server.ts:10-12).
- *  Per design decision 4, only CALL 1 (account.add_context_rule) is
- *  emitted; CALL 2 (interpreter.install) requires the rule id the account
- *  assigns in call 1 and is documented under `followUp` in the response.
+ *  One call installs the policy outright: `add_context_rule` carries the
+ *  predicate to the interpreter in its `policies` install_param, so no
+ *  separate `interpreter.install` call is needed or possible.
  *
  *  Default-deny: an interpreter policy address other than the pinned
  *  testnet interpreter is REFUSED (the smart account would delegate to