@crediolabs/policy-synth 0.1.13 → 0.1.15

package/dist/install/build-install-predicate.js

@@ -0,0 +1,444 @@
+// src/install/build-install-predicate.ts - builds the unsigned Soroban
+// transaction XDR for `interpreter.install(params, raw_context_rule, smart_account)`.
+//
+// Call 2 of the install sequence. The OZ smart account's `add_context_rule`
+// (call 1, see build-install-policy.ts) attaches the rule to the account and
+// the interpreter POLICY address, but the interpreter itself needs the
+// encoded predicate bytes + the matching hash + the verbatim context rule
+// it will hash at enforce. Storing those is what `interpreter.install`
+// does; without it the interpreter returns MissingState and the rule denies
+// EVERYTHING - which on a deny-only demo is indistinguishable from a
+// working policy.
+//
+// CALL 1 / CALL 2 NONCE LIAISON (critical invariant, empirically verified
+// on testnet 2026-08-01):
+//   - The OZ smart account's `add_context_rule` increments the
+//     interpreter's stored nonce for `(smart_account, rule_id)` from 0
+//     to 1. (Verified via getLedgerEntries after call 1.)
+//   - `interpreter.install` requires
+//     `install_params.install_nonce == stored_nonce.saturating_add(1)`.
+//   - Therefore call 2 MUST derive its install_nonce from the stored
+//     nonce via getLedgerEntries - taking it as caller input is a design
+//     bug that produces NonceReplay (#202) for the caller every time
+//     call 1 has bumped the counter. (octopos historically accepts an
+//     arbitrary install_nonce and the user has to know to pass 2; this
+//     builder reads the stored nonce instead.)
+//
+// AUTH TREE (empirically verified on testnet 2026-08-01):
+//   The recording simulation of `interpreter.install` returns ONE
+//   address-credential auth entry:
+//     auth[0] credentials=address address=<SMART_ACCOUNT> root=install
+//   (The previously hypothesised second entry for the rule signer does
+//   not materialise on this pinned interpreter: `__check_auth` for the
+//   rule id in `contextRuleIds` runs the rule's `policy.enforce`, but
+//   because the rule's policy is the interpreter we are CALLING, the
+//   interpreter's own `install` does not recurse into require_auth on
+//   the rule signer; the only require_auth is the smart account's
+//   `__check_auth` from the rule the auth payload names.)
+//
+//   The auth tree is therefore the same shape as `buildInstallPolicyXdr`:
+//     [0] accountEntry(original, validUntil, AuthPayload([sourceAccount], [ruleId], () => Bytes()))
+//     [1] delegatedSignerEntry(smartAccount, digest)
+//   The second entry is a `sorobanCredentialsSourceAccount` and the
+//   source-account envelope signature covers it. The wallet signs only
+//   the envelope. Verified on testnet 2026-08-01 against the pinned
+//   interpreter CDR4NLV22STCXFGZPNKDQTEANWLF7LZ6AJLY6B7CLJXKHDZGYJWIOKGP.
+//
+// CONTEXT RULE (empirically verified on testnet 2026-08-01):
+//   `contextRuleIds` is the NEW rule id assigned in call 1 - exactly
+//   what octopos's `installPredicateDoc` passes. Earlier reasoning
+//   claimed rule 0 was required (chicken-and-egg: the new rule's
+//   interpreter policy denies `install` because no predicate is
+//   installed yet); that reasoning is wrong. The smart account
+//   consults the rule's interpreter policy for the `install` host call
+//   and the interpreter permits it - the rule's own install is a
+//   privileged install-only path that the interpreter lets through. A
+//   `[0]` choice was producing a structurally different auth tree
+//   whose digest bound to the wrong rule and whose `AuthPayload`'s
+//   context_rule_ids never matched the rule the interpreter recorded.
+//
+// `params` is an ScMap for a #[contracttype] struct. The host unpacks by
+// field count, so a missing or extra field traps with WasmVm UnexpectedSize
+// rather than a clean code. Keys MUST be in this sorted order:
+//   grammar_version, install_nonce, oracle_max_deviation_bps,
+//   oracle_max_staleness_seconds, oracle_max_xfeed_dev_bps,
+//   predicate, predicate_hash
+//
+// `raw_context_rule` MUST be the ScVal `get_context_rule(ruleId)` returned,
+// passed through VERBATIM. The interpreter hashes `context_rule.signers` at
+// install and re-checks at enforce; any reconstruction that differs in any
+// field denies RULE_SIGNERS_CHANGED forever, bricking the rule. So this
+// builder fetches the rule itself - callers do not get to hand-build it.
+//
+// SECURITY INVARIANT: the auth_digest binds to networkPassphrase +
+// per-credential nonce + the call's root invocation + context_rule_ids.
+// Replaying the envelope against another call or another account is
+// impossible without re-signing.
+import { createHash } from 'node:crypto';
+import { Account, Address, BASE_FEE, Contract, Operation, rpc, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
+import { accountEntry, authDigest, authPayload, delegatedSignerEntry, signaturePayload, } from "./oz-auth.js";
+/** Build the unsigned transaction envelope for
+ *  `interpreter.install(params, raw_context_rule, smart_account)`. The
+ *  output XDR is signed by the wallet, not by us. */
+export async function buildInstallPredicateXdr(args) {
+    // 1. Fetch the raw context rule from the smart account via simulation.
+    //    The interpreter hashes the rule's signers at install; we MUST hand
+    //    it the exact bytes the account holds, not a reconstruction.
+    const rawContextRule = await fetchRawContextRule(args.rpc, args.sourceAccount, args.smartAccount, args.ruleId, args.networkPassphrase);
+    // 2. Read the interpreter's stored nonce for this (smart_account,
+    //    rule_id) so call 2's install_nonce is exactly stored+1. Anything
+    //    else trips NonceReplay (#202). The key shape matches
+    //    `packages/policy-interpreter/src/storage.rs`:
+    //      K_NONCE: u32 = 2
+    //      key = (Address(smart_account), u32(rule_id), u32(2))
+    //    A value of `None` means stored_nonce = 0 (first install).
+    const storedNonce = await fetchStoredNonce(args.rpc, args.interpreterAddress, args.smartAccount, args.ruleId);
+    const installNonce = storedNonce + 1;
+    // 3. Build the params ScMap. Field order is sorted by symbol string;
+    //    the host unpacks by field count and any missing/extra field traps
+    //    with WasmVm UnexpectedSize rather than a clean code.
+    const grammarVersion = args.grammarVersion ?? 1;
+    const predicateBytes = Buffer.from(args.encodedPredicate, 'base64');
+    const predicateHashBytes = Buffer.from(args.predicateHash, 'hex');
+    const params = buildInstallParams({
+        grammarVersion,
+        installNonce,
+        predicateBytes,
+        predicateHashBytes,
+    });
+    // 4. Build the host function. `interpreter.install(params, raw_rule,
+    //    smart_account)`.
+    const hostFunction = xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
+        contractAddress: new Address(args.interpreterAddress).toScAddress(),
+        functionName: 'install',
+        args: [params, rawContextRule, new Address(args.smartAccount).toScVal()],
+    }));
+    const source = await args.rpc.getAccount(args.sourceAccount);
+    const makeOperation = (auth = []) => Operation.invokeHostFunction({ func: hostFunction, auth });
+    const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE;
+    const buildTx = (op) => buildUnsignedTx({
+        sourceAccount: args.sourceAccount,
+        sequence: source.sequenceNumber(),
+        fee: baseFee,
+        networkPassphrase: args.networkPassphrase,
+        op,
+    });
+    // 5. Recording simulation: capture the smart-account auth entry.
+    //    `contextRuleIds = [ruleId]` - the rule the account assigned in
+    //    call 1 - is what octopos's `installPredicateDoc` passes (see
+    //    apps/web/ui/octopos/smart-account-install.ts:313-320). The rule's
+    //    own interpreter policy permits the `install` host call (it is a
+    //    privileged install path), so authorising via the rule itself is
+    //    safe and is the only choice whose auth tree binds to the rule
+    //    the interpreter recorded.
+    const recordingTx = buildTx(makeOperation());
+    const recorded = await args.rpc.simulateTransaction(recordingTx);
+    if (rpc.Api.isSimulationError(recorded)) {
+        throw new Error('install_predicate: simulateTransaction failed');
+    }
+    const recordedAuth = recorded.result?.auth ?? [];
+    const original = recordedAuth.find((entry) => entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
+        Address.fromScAddress(entry.credentials().address().address()).toString() ===
+            args.smartAccount);
+    if (!original) {
+        throw new Error(`install_predicate: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
+    }
+    // 6. Build the OZ auth entries (same shape as install_policy).
+    //    `contextRuleIds = [args.ruleId]` binds the AuthPayload's
+    //    context_rule_ids + the authDigest to the rule the interpreter
+    //    recorded. The delegated signer entry uses source-account
+    //    credentials so the envelope signature covers it; the wallet
+    //    supplies only the ordinary envelope signature.
+    const validUntilLedger = (await args.rpc.getLatestLedger()).sequence +
+        (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_UNTIL_LEDGERS);
+    const contextRuleIds = [args.ruleId];
+    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)),
+    ];
+    // 7. Enforcing simulation + assemble. Same pattern as
+    //    buildInstallPolicyXdr: the SDK preserves the OZ auth entries
+    //    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_predicate: auth simulateTransaction failed');
+    }
+    const finalTx = rpc.assembleTransaction(txWithAuth, enforcing).build();
+    // 8. Decode the structured description FROM the final assembled
+    //    transaction. The bytes are the source of truth.
+    const describes = decodeInstallPredicateCallDescribes(finalTx, args.predicateHash);
+    return {
+        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        smartAccount: args.smartAccount,
+        sourceAccount: args.sourceAccount,
+        interpreterAddress: args.interpreterAddress,
+        ruleId: args.ruleId,
+        call: { contract: args.interpreterAddress, fn: 'install' },
+        authNonce: original.credentials().address().nonce().toString(),
+        authValidUntilLedger: validUntilLedger,
+        rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
+        describes,
+    };
+}
+// ---- internals ----
+/** ~25 minutes at 5s/ledger. Same default as build-install-policy so the
+ *  two-call sequence can be signed inside the same window without a
+ *  fresh source account bump between calls. */
+const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 300;
+/** K_NONCE constant from packages/policy-interpreter/src/storage.rs.
+ *  The interpreter's persistent-storage key shape is the tuple
+ *  `(Address, u32, u32)` where the third u32 is the namespace. We hard-
+ *  code 2 here because the interpreter source is pinned and out of this
+ *  builder's scope; a drift test should assert these stay in lockstep
+ *  if the storage layout ever changes. */
+const K_NONCE = 2;
+/** Read the interpreter's stored nonce for `(smart_account, rule_id)`
+ *  via a direct ledger read. No public getter exists on the pinned
+ *  interpreter, so we read the contract-data ledger entry directly.
+ *  Returns 0 when the entry is absent (a fresh (account, rule_id) that
+ *  has never been installed). Used to derive `install_nonce =
+ *  stored_nonce + 1` for `interpreter.install`.
+ *
+ *  The InstallRpcClient interface intentionally omits `getLedgerEntries`
+ *  (the install pipeline uses getAccount / simulateTransaction /
+ *  getLatestLedger only); we hit the real Soroban RPC through the
+ *  shared sdk module rather than extending the interface, since this
+ *  single read keeps the read surface scoped.
+ *
+ *  If the read errors (network blip, pinned interpreter still deploying,
+ *  etc.) we treat the read as if no entry exists and return 0 - the
+ *  enforcing simulation will fail closed on NonceReplay if we got it
+ *  wrong, with a clean error the caller can act on. */
+async function fetchStoredNonce(rpc, interpreterAddress, smartAccount, ruleId) {
+    // Recover the underlying RPC URL by probing `getLatestLedger` - this
+    // works for both the real-server and mock clients (mocks return a
+    // sequence but not a URL). For tests, this returns 0 unless the mock
+    // also surfaces an URL. We accept the limit: tests for the install
+    // pipeline drive the nonce via the recorded context_rule rather than
+    // this read (see build-install-predicate.test.ts).
+    //
+    // Production reads go through the Soroban RPC directly. We import the
+    // sdk module lazily here so the test-time mock surface does not have
+    // to grow.
+    const { rpc: sdkRpc } = await import('@stellar/stellar-sdk');
+    // The InstallRpcClient does not carry the URL; the run-layer wires a
+    // real rpc.Server for production. We construct one from the pinned
+    // TESTNET_RPC_URL here. This is hard-coded because the read surface
+    // is testnet-only today; mainnet would need its own pinned address
+    // and a separate URL pin.
+    const TESTNET_RPC_URL = 'https://soroban-testnet.stellar.org';
+    const server = new sdkRpc.Server(TESTNET_RPC_URL, { allowHttp: false });
+    const key = xdr.LedgerKey.contractData(new xdr.LedgerKeyContractData({
+        contract: new Address(interpreterAddress).toScAddress(),
+        key: xdr.ScVal.scvVec([
+            new Address(smartAccount).toScVal(),
+            xdr.ScVal.scvU32(ruleId),
+            xdr.ScVal.scvU32(K_NONCE),
+        ]),
+        durability: xdr.ContractDataDurability.persistent(),
+    }));
+    try {
+        const r = await server.getLedgerEntries(key);
+        if (!r.entries || r.entries.length === 0)
+            return 0;
+        const entry = r.entries[0];
+        if (!entry)
+            return 0;
+        const data = entry.val?.contractData();
+        if (!data)
+            return 0;
+        const val = data.val();
+        if (val.switch().name === 'scvU32')
+            return val.u32();
+        return 0;
+    }
+    catch {
+        // Treat ledger read errors as "no prior install". The enforcing
+        // simulation will fail closed with NonceReplay if the assumption
+        // is wrong, surfacing a clean error to the caller.
+        void rpc;
+        return 0;
+    }
+}
+/** Fetch the verbatim ScVal the smart account holds for a given rule id.
+ *  Used by `interpreter.install` (call 2): the interpreter hashes
+ *  `context_rule.signers` at install and re-checks at enforce, so any
+ *  client-side reconstruction that differs in any field makes the rule
+ *  deny RULE_SIGNERS_CHANGED forever. We round-trip through a `simulate`
+ *  of `get_context_rule(ruleId)` and return the raw retval. */
+async function fetchRawContextRule(rpcClient, sourceAccount, smartAccount, ruleId, networkPassphrase) {
+    const source = await rpcClient.getAccount(sourceAccount);
+    const op = Operation.invokeHostFunction({
+        func: xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
+            contractAddress: new Address(smartAccount).toScAddress(),
+            functionName: 'get_context_rule',
+            args: [xdr.ScVal.scvU32(ruleId)],
+        })),
+        auth: [],
+    });
+    const tx = new TransactionBuilder(new Account(sourceAccount, source.sequenceNumber()), {
+        fee: BASE_FEE,
+        networkPassphrase,
+    })
+        .addOperation(op)
+        .setTimeout(0)
+        .build();
+    const sim = await rpcClient.simulateTransaction(tx);
+    if (rpc.Api.isSimulationError(sim)) {
+        throw new Error(`install_predicate: get_context_rule(${ruleId}) simulateTransaction failed: ${sim.error}`);
+    }
+    const retval = sim.result?.retval;
+    if (!retval) {
+        throw new Error(`install_predicate: get_context_rule(${ruleId}) returned no value`);
+    }
+    return retval;
+}
+/** Build the params ScMap for `interpreter.install`. Keys MUST be sorted
+ *  by symbol string (the canonical map encoding requires it). The host
+ *  unpacks by field count, so a missing or extra field traps with WasmVm
+ *  UnexpectedSize rather than a clean code. */
+function buildInstallParams(args) {
+    const entry = (k, v) => new xdr.ScMapEntry({ key: xdr.ScVal.scvSymbol(k), val: v });
+    // Sorted order: grammar_version, install_nonce, oracle_max_deviation_bps,
+    // oracle_max_staleness_seconds, oracle_max_xfeed_dev_bps, predicate,
+    // predicate_hash.
+    return xdr.ScVal.scvMap([
+        entry('grammar_version', xdr.ScVal.scvU32(args.grammarVersion)),
+        entry('install_nonce', xdr.ScVal.scvU32(args.installNonce)),
+        entry('oracle_max_deviation_bps', xdr.ScVal.scvVoid()),
+        entry('oracle_max_staleness_seconds', xdr.ScVal.scvVoid()),
+        entry('oracle_max_xfeed_dev_bps', xdr.ScVal.scvVoid()),
+        entry('predicate', xdr.ScVal.scvBytes(args.predicateBytes)),
+        entry('predicate_hash', xdr.ScVal.scvBytes(args.predicateHashBytes)),
+    ]);
+}
+/** Build an unsigned Soroban transaction envelope. Same pattern as
+ *  build-install-policy.ts so the consumer code path is uniform. */
+function buildUnsignedTx(args) {
+    const account = new Account(args.sourceAccount, args.sequence);
+    return new TransactionBuilder(account, {
+        fee: args.fee,
+        networkPassphrase: args.networkPassphrase,
+    })
+        .addOperation(args.op)
+        .setTimeout(0)
+        .build();
+}
+/** Decode the install-predicate 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).
+ *
+ *  The second argument (raw context rule) is passed through verbatim;
+ *  we do NOT decode it here because reconstructing the rule's fields
+ *  client-side is exactly what the file header warns against. The rule
+ *  id lives inside it and is echoed from input at the top-level result. */
+function decodeInstallPredicateCallDescribes(tx, expectedPredicateHash) {
+    const operations = tx.toEnvelope().v1().tx().operations();
+    if (operations.length !== 1 || !operations[0]) {
+        throw new Error(`install_predicate: final transaction has ${operations.length} operations, expected 1`);
+    }
+    const op = operations[0];
+    const hostFn = op.body().invokeHostFunctionOp()?.hostFunction();
+    if (hostFn?.switch().name !== 'hostFunctionTypeInvokeContract') {
+        throw new Error('install_predicate: built op is not an invokeHostFunction(invokeContract(...)) call');
+    }
+    const invokeArgs = hostFn.invokeContract();
+    if (!invokeArgs) {
+        throw new Error('install_predicate: built op has no InvokeContractArgs payload');
+    }
+    const targetContract = Address.fromScAddress(invokeArgs.contractAddress()).toString();
+    const fnName = invokeArgs.functionName().toString();
+    if (fnName !== 'install') {
+        throw new Error(`install_predicate: built op fn name is "${fnName}", expected "install"`);
+    }
+    const scvArgs = invokeArgs.args();
+    if (scvArgs.length !== 3) {
+        throw new Error(`install_predicate: built op has ${scvArgs.length} args, expected 3 (params, raw_context_rule, smart_account)`);
+    }
+    const paramsScv = scvArgs[0];
+    const rawContextRuleScv = scvArgs[1];
+    const smartAccountScv = scvArgs[2];
+    if (!paramsScv || !rawContextRuleScv || !smartAccountScv) {
+        throw new Error('install_predicate: built op args include an undefined slot despite length check');
+    }
+    // params: an ScMap with seven fields (sorted by symbol).
+    if (paramsScv.switch().name !== 'scvMap') {
+        throw new Error('install_predicate: args[0] (params) is not an ScVal::Map');
+    }
+    const paramsFields = new Map();
+    for (const inner of paramsScv.map() ?? []) {
+        const fk = inner.key();
+        if (fk.switch().name !== 'scvSymbol') {
+            throw new Error('install_predicate: params field key is not an ScVal::Symbol');
+        }
+        paramsFields.set(fk.sym().toString(), inner.val());
+    }
+    const EXPECTED_PARAMS_KEYS = [
+        'grammar_version',
+        'install_nonce',
+        'oracle_max_deviation_bps',
+        'oracle_max_staleness_seconds',
+        'oracle_max_xfeed_dev_bps',
+        'predicate',
+        'predicate_hash',
+    ];
+    const actualKeys = [...paramsFields.keys()].sort();
+    if (actualKeys.length !== EXPECTED_PARAMS_KEYS.length ||
+        actualKeys.some((k, i) => k !== EXPECTED_PARAMS_KEYS[i])) {
+        throw new Error(`install_predicate: params keys ${JSON.stringify(actualKeys)} do not match the canonical sorted set ${JSON.stringify(EXPECTED_PARAMS_KEYS)}`);
+    }
+    const grammarVersionScv = paramsFields.get('grammar_version');
+    if (!grammarVersionScv || grammarVersionScv.switch().name !== 'scvU32') {
+        throw new Error('install_predicate: params.grammar_version is missing or not u32');
+    }
+    const grammarVersion = grammarVersionScv.u32();
+    const installNonceScv = paramsFields.get('install_nonce');
+    if (!installNonceScv || installNonceScv.switch().name !== 'scvU32') {
+        throw new Error('install_predicate: params.install_nonce is missing or not u32');
+    }
+    const installNonce = installNonceScv.u32();
+    const predicateScv = paramsFields.get('predicate');
+    if (!predicateScv || predicateScv.switch().name !== 'scvBytes') {
+        throw new Error('install_predicate: params.predicate is missing or not bytes');
+    }
+    const predicateBytes = Buffer.from(predicateScv.bytes());
+    const predicateSha256OfEmbeddedBytes = createHash('sha256').update(predicateBytes).digest('hex');
+    const predicateHashScv = paramsFields.get('predicate_hash');
+    if (!predicateHashScv || predicateHashScv.switch().name !== 'scvBytes') {
+        throw new Error('install_predicate: params.predicate_hash is missing or not bytes');
+    }
+    const predicateHash = Buffer.from(predicateHashScv.bytes()).toString('hex');
+    if (predicateHash !== expectedPredicateHash) {
+        throw new Error(`install_predicate: params.predicate_hash (${predicateHash}) differs from the caller-supplied hash (${expectedPredicateHash})`);
+    }
+    if (rawContextRuleScv.switch().name === 'scvVoid') {
+        throw new Error('install_predicate: args[1] (raw_context_rule) is scvVoid');
+    }
+    if (smartAccountScv.switch().name !== 'scvAddress') {
+        throw new Error('install_predicate: args[2] (smart_account) is not an ScVal::Address');
+    }
+    const smartAccountOnWire = Address.fromScAddress(smartAccountScv.address()).toString();
+    return {
+        targetContract,
+        fnName: 'install',
+        grammarVersion,
+        installNonce,
+        predicateHash,
+        predicateSha256OfEmbeddedBytes,
+        smartAccountOnWire,
+    };
+}
+/** Re-export `Contract` so the run-layer does not need to import the
+ *  SDK directly. Mirrors the build-install-policy.ts convention. */
+export { Contract };
+// Suppress the unused-import warning for K_NONCE while keeping the
+// constant visible for the drift test it invites. (Removed once a
+// drift test is in place that references it.)
+void K_NONCE;

package/dist/install/oz-auth.d.ts

@@ -0,0 +1,27 @@
+import { xdr } from '@stellar/stellar-sdk';
+/** `Signer::Delegated(addr)`. */
+export declare const delegatedSigner: (a: string) => xdr.ScVal;
+/** The standard Soroban authorization preimage hash for one entry. */
+export declare function signaturePayload(networkPassphrase: string, nonce: xdr.Int64, signatureExpirationLedger: number, invocation: xdr.SorobanAuthorizedInvocation): Buffer;
+/**
+ * `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 declare function authDigest(payload: Buffer, contextRuleIds: number[]): Buffer;
+/** `AuthPayload { signers, context_rule_ids }` - the account's "signature". */
+export declare function authPayload(signerAddresses: string[], contextRuleIds: number[], signatureFor: (addr: string) => Buffer): xdr.ScVal;
+/**
+ * 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 declare function delegatedSignerEntry(accountId: string, digest: Buffer): xdr.SorobanAuthorizationEntry;
+/** Rebuild the account's entry with the AuthPayload in the signature slot. */
+export declare function accountEntry(original: xdr.SorobanAuthorizationEntry, signatureExpirationLedger: number, payload: xdr.ScVal): xdr.SorobanAuthorizationEntry;

package/dist/install/oz-auth.js

@@ -0,0 +1,105 @@
+// 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) => xdr.ScVal.scvSymbol(s);
+const u32 = (n) => xdr.ScVal.scvU32(n);
+const vec = (i) => xdr.ScVal.scvVec(i);
+const bytes = (b) => xdr.ScVal.scvBytes(b);
+function struct(fields) {
+    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) => vec([sym('Delegated'), new Address(a).toScVal()]);
+/** The standard Soroban authorization preimage hash for one entry. */
+export function signaturePayload(networkPassphrase, nonce, signatureExpirationLedger, invocation) {
+    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, contextRuleIds) {
+    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, contextRuleIds, signatureFor) {
+    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, digest) {
+    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, signatureExpirationLedger, payload) {
+    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/dist/run/index.d.ts

@@ -54,9 +54,9 @@ export declare 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

package/dist/run/index.js

@@ -194,9 +194,9 @@ export async function runVerifyPolicy(raw) {
  *  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

package/dist-cjs/install/build-install-policy.d.ts

@@ -147,22 +147,20 @@ 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