@crediolabs/policy-synth 0.1.13 → 0.1.15

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

@@ -0,0 +1,479 @@
+"use strict";
+// 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.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Contract = void 0;
+exports.buildInstallPredicateXdr = buildInstallPredicateXdr;
+const node_crypto_1 = require("node:crypto");
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+Object.defineProperty(exports, "Contract", { enumerable: true, get: function () { return stellar_sdk_1.Contract; } });
+const oz_auth_ts_1 = require("./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. */
+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 = stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
+        contractAddress: new stellar_sdk_1.Address(args.interpreterAddress).toScAddress(),
+        functionName: 'install',
+        args: [params, rawContextRule, new stellar_sdk_1.Address(args.smartAccount).toScVal()],
+    }));
+    const source = await args.rpc.getAccount(args.sourceAccount);
+    const makeOperation = (auth = []) => stellar_sdk_1.Operation.invokeHostFunction({ func: hostFunction, auth });
+    const baseFee = args.baseFee !== undefined ? String(args.baseFee) : stellar_sdk_1.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 (stellar_sdk_1.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' &&
+        stellar_sdk_1.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 = (0, oz_auth_ts_1.authDigest)((0, oz_auth_ts_1.signaturePayload)(args.networkPassphrase, original.credentials().address().nonce(), validUntilLedger, original.rootInvocation()), contextRuleIds);
+    const authEntries = [
+        (0, oz_auth_ts_1.accountEntry)(original, validUntilLedger, (0, oz_auth_ts_1.authPayload)([args.sourceAccount], contextRuleIds, () => Buffer.alloc(0))),
+        ...contextRuleIds.map(() => (0, oz_auth_ts_1.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 (stellar_sdk_1.rpc.Api.isSimulationError(enforcing)) {
+        throw new Error('install_predicate: auth simulateTransaction failed');
+    }
+    const finalTx = stellar_sdk_1.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 Promise.resolve().then(() => __importStar(require('@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 = stellar_sdk_1.xdr.LedgerKey.contractData(new stellar_sdk_1.xdr.LedgerKeyContractData({
+        contract: new stellar_sdk_1.Address(interpreterAddress).toScAddress(),
+        key: stellar_sdk_1.xdr.ScVal.scvVec([
+            new stellar_sdk_1.Address(smartAccount).toScVal(),
+            stellar_sdk_1.xdr.ScVal.scvU32(ruleId),
+            stellar_sdk_1.xdr.ScVal.scvU32(K_NONCE),
+        ]),
+        durability: stellar_sdk_1.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 = stellar_sdk_1.Operation.invokeHostFunction({
+        func: stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
+            contractAddress: new stellar_sdk_1.Address(smartAccount).toScAddress(),
+            functionName: 'get_context_rule',
+            args: [stellar_sdk_1.xdr.ScVal.scvU32(ruleId)],
+        })),
+        auth: [],
+    });
+    const tx = new stellar_sdk_1.TransactionBuilder(new stellar_sdk_1.Account(sourceAccount, source.sequenceNumber()), {
+        fee: stellar_sdk_1.BASE_FEE,
+        networkPassphrase,
+    })
+        .addOperation(op)
+        .setTimeout(0)
+        .build();
+    const sim = await rpcClient.simulateTransaction(tx);
+    if (stellar_sdk_1.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 stellar_sdk_1.xdr.ScMapEntry({ key: stellar_sdk_1.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 stellar_sdk_1.xdr.ScVal.scvMap([
+        entry('grammar_version', stellar_sdk_1.xdr.ScVal.scvU32(args.grammarVersion)),
+        entry('install_nonce', stellar_sdk_1.xdr.ScVal.scvU32(args.installNonce)),
+        entry('oracle_max_deviation_bps', stellar_sdk_1.xdr.ScVal.scvVoid()),
+        entry('oracle_max_staleness_seconds', stellar_sdk_1.xdr.ScVal.scvVoid()),
+        entry('oracle_max_xfeed_dev_bps', stellar_sdk_1.xdr.ScVal.scvVoid()),
+        entry('predicate', stellar_sdk_1.xdr.ScVal.scvBytes(args.predicateBytes)),
+        entry('predicate_hash', stellar_sdk_1.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 stellar_sdk_1.Account(args.sourceAccount, args.sequence);
+    return new stellar_sdk_1.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 = stellar_sdk_1.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 = (0, node_crypto_1.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 = stellar_sdk_1.Address.fromScAddress(smartAccountScv.address()).toString();
+    return {
+        targetContract,
+        fnName: 'install',
+        grammarVersion,
+        installNonce,
+        predicateHash,
+        predicateSha256OfEmbeddedBytes,
+        smartAccountOnWire,
+    };
+}
+// 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-cjs/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-cjs/install/oz-auth.js

@@ -0,0 +1,114 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delegatedSigner = void 0;
+exports.signaturePayload = signaturePayload;
+exports.authDigest = authDigest;
+exports.authPayload = authPayload;
+exports.delegatedSignerEntry = delegatedSignerEntry;
+exports.accountEntry = accountEntry;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const sym = (s) => stellar_sdk_1.xdr.ScVal.scvSymbol(s);
+const u32 = (n) => stellar_sdk_1.xdr.ScVal.scvU32(n);
+const vec = (i) => stellar_sdk_1.xdr.ScVal.scvVec(i);
+const bytes = (b) => stellar_sdk_1.xdr.ScVal.scvBytes(b);
+function struct(fields) {
+    return stellar_sdk_1.xdr.ScVal.scvMap(Object.keys(fields)
+        .sort()
+        .map((k) => new stellar_sdk_1.xdr.ScMapEntry({ key: sym(k), val: fields[k] })));
+}
+/** `Signer::Delegated(addr)`. */
+const delegatedSigner = (a) => vec([sym('Delegated'), new stellar_sdk_1.Address(a).toScVal()]);
+exports.delegatedSigner = delegatedSigner;
+/** The standard Soroban authorization preimage hash for one entry. */
+function signaturePayload(networkPassphrase, nonce, signatureExpirationLedger, invocation) {
+    const preimage = stellar_sdk_1.xdr.HashIdPreimage.envelopeTypeSorobanAuthorization(new stellar_sdk_1.xdr.HashIdPreimageSorobanAuthorization({
+        networkId: (0, stellar_sdk_1.hash)(Buffer.from(networkPassphrase)),
+        nonce,
+        signatureExpirationLedger,
+        invocation,
+    }));
+    return (0, stellar_sdk_1.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.
+ */
+function authDigest(payload, contextRuleIds) {
+    const idsXdr = vec(contextRuleIds.map(u32)).toXDR();
+    return (0, stellar_sdk_1.hash)(Buffer.concat([payload, idsXdr]));
+}
+/** `AuthPayload { signers, context_rule_ids }` - the account's "signature". */
+function authPayload(signerAddresses, contextRuleIds, signatureFor) {
+    return struct({
+        signers: stellar_sdk_1.xdr.ScVal.scvMap(signerAddresses
+            .map((a) => new stellar_sdk_1.xdr.ScMapEntry({ key: (0, exports.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.
+ */
+function delegatedSignerEntry(accountId, digest) {
+    return new stellar_sdk_1.xdr.SorobanAuthorizationEntry({
+        credentials: stellar_sdk_1.xdr.SorobanCredentials.sorobanCredentialsSourceAccount(),
+        rootInvocation: new stellar_sdk_1.xdr.SorobanAuthorizedInvocation({
+            function: stellar_sdk_1.xdr.SorobanAuthorizedFunction.sorobanAuthorizedFunctionTypeContractFn(new stellar_sdk_1.xdr.InvokeContractArgs({
+                contractAddress: new stellar_sdk_1.Address(accountId).toScAddress(),
+                functionName: '__check_auth',
+                args: [bytes(digest)],
+            })),
+            subInvocations: [],
+        }),
+    });
+}
+/** Rebuild the account's entry with the AuthPayload in the signature slot. */
+function accountEntry(original, signatureExpirationLedger, payload) {
+    const creds = original.credentials().address();
+    return new stellar_sdk_1.xdr.SorobanAuthorizationEntry({
+        credentials: stellar_sdk_1.xdr.SorobanCredentials.sorobanCredentialsAddress(new stellar_sdk_1.xdr.SorobanAddressCredentials({
+            address: creds.address(),
+            nonce: creds.nonce(),
+            signatureExpirationLedger,
+            signature: payload,
+        })),
+        rootInvocation: original.rootInvocation(),
+    });
+}

package/dist-cjs/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-cjs/run/index.js

@@ -225,9 +225,9 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "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",