@crediolabs/policy-synth 0.1.13 → 0.1.14

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

@@ -19,6 +19,7 @@
 import { createHash } from 'node:crypto';
 import { Address, BASE_FEE, Contract, Keypair, Operation, rpc, scValToBigInt, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
 import { buildAddContextRuleArgs, DEFAULT_GRAMMAR_VERSION } from "./build-add-context-rule.js";
+import { accountEntry, authDigest, authPayload, delegatedSignerEntry, signaturePayload, } from "./oz-auth.js";
 /** Convert a real rpc.Server into the InstallRpcClient surface. The
  *  `getContractVersion` lookup uses `simulateTransaction` against
  *  `contract.call('grammar_version')` and decodes the returned u32.
@@ -83,31 +84,28 @@ export async function buildInstallPolicyXdr(args) {
         ...(args.oracleParams ? { oracleParams: args.oracleParams } : {}),
         ...(args.grammarVersion !== undefined ? { grammarVersion: args.grammarVersion } : {}),
     });
-    // 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 = []) => Operation.invokeHostFunction({ func: hostFunction, auth });
     const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE;
-    const tx = buildUnsignedTx({
+    const buildTx = (op) => 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 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
@@ -121,14 +119,32 @@ export async function buildInstallPolicyXdr(args) {
     if (!original) {
         throw new Error(`install_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
     }
-    // 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' },
@@ -157,25 +173,21 @@ export async function buildInstallPolicyXdr(args) {
  *  be guessing at a contract it cannot read, and the chain is the authority. */
 export async function buildRevokePolicyXdr(args) {
     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 = []) => Operation.invokeHostFunction({ func: hostFunction, auth });
     const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE;
-    const tx = buildUnsignedTx({
+    const buildTx = (op) => buildUnsignedTx({
         sourceAccount: args.sourceAccount,
         sequence: source.sequenceNumber(),
         fee: baseFee,
         networkPassphrase: args.networkPassphrase,
         op,
     });
-    const recorded = await args.rpc.simulateTransaction(tx);
+    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
@@ -189,8 +201,27 @@ export async function buildRevokePolicyXdr(args) {
     if (!original) {
         throw new Error(`revoke_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
     }
+    // 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 },
@@ -200,7 +231,7 @@ export async function buildRevokePolicyXdr(args) {
     };
 }
 /** ~25 minutes at 5s/ledger. */
-const DEFAULT_AUTH_VALID_LEDGERS = 300;
+const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 300;
 // ---- internals ----
 /** Adapter: turn the install-policy wire `PolicyRef` shape into the core
  *  `PolicyRef` shape `buildAddContextRuleArgs` expects. Keeps the wire
@@ -238,20 +269,24 @@ function buildUnsignedTx(args) {
     // its signature, and broadcasts. We do NOT sign here.
     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
  *  install has no interpreter policy (no `install_nonce` to read); the
  *  caller already knows it. */
-function decodeInstallCallDescribes(tx, op, expectedInstallNonce) {
+function decodeInstallCallDescribes(tx, expectedInstallNonce) {
+    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');
     }
     const invokeArgs = hostFn.invokeContract();
@@ -404,10 +439,6 @@ function decodeInstallCallDescribes(tx, op, expectedInstallNonce) {
     // `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/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-cjs/install/build-install-policy.js

@@ -27,6 +27,7 @@ const stellar_sdk_1 = require("@stellar/stellar-sdk");
 Object.defineProperty(exports, "Contract", { enumerable: true, get: function () { return stellar_sdk_1.Contract; } });
 const build_add_context_rule_ts_1 = require("./build-add-context-rule.js");
 Object.defineProperty(exports, "DEFAULT_GRAMMAR_VERSION", { enumerable: true, get: function () { return build_add_context_rule_ts_1.DEFAULT_GRAMMAR_VERSION; } });
+const oz_auth_ts_1 = require("./oz-auth.js");
 /** Convert a real rpc.Server into the InstallRpcClient surface. The
  *  `getContractVersion` lookup uses `simulateTransaction` against
  *  `contract.call('grammar_version')` and decodes the returned u32.
@@ -91,31 +92,28 @@ async function buildInstallPolicyXdr(args) {
         ...(args.oracleParams ? { oracleParams: args.oracleParams } : {}),
         ...(args.grammarVersion !== undefined ? { grammarVersion: args.grammarVersion } : {}),
     });
-    // 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 = stellar_sdk_1.Operation.invokeHostFunction({
-        func: stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
-            contractAddress: new stellar_sdk_1.Address(args.smartAccount).toScAddress(),
-            functionName: 'add_context_rule',
-            args: [...callArgs],
-        })),
-        auth: [],
-    });
+    const hostFunction = stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
+        contractAddress: new stellar_sdk_1.Address(args.smartAccount).toScAddress(),
+        functionName: 'add_context_rule',
+        args: [...callArgs],
+    }));
+    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 tx = buildUnsignedTx({
+    const buildTx = (op) => 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 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 (stellar_sdk_1.rpc.Api.isSimulationError(recorded)) {
         // Short, stable reason. The full `simulateTransaction` error (which
         // carries host + URL detail) stays in the SDK's own logs - never
@@ -129,14 +127,32 @@ async function buildInstallPolicyXdr(args) {
     if (!original) {
         throw new Error(`install_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
     }
-    // 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 = (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)),
+    ];
+    // 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 (stellar_sdk_1.rpc.Api.isSimulationError(enforcing)) {
+        throw new Error('install_policy: auth simulateTransaction failed');
+    }
+    const finalTx = stellar_sdk_1.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' },
@@ -165,25 +181,21 @@ async function buildInstallPolicyXdr(args) {
  *  be guessing at a contract it cannot read, and the chain is the authority. */
 async function buildRevokePolicyXdr(args) {
     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 = stellar_sdk_1.Operation.invokeHostFunction({
-        func: stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
-            contractAddress: new stellar_sdk_1.Address(args.smartAccount).toScAddress(),
-            functionName: 'remove_context_rule',
-            args: [stellar_sdk_1.xdr.ScVal.scvU32(args.ruleId)],
-        })),
-        auth: [],
-    });
+    const hostFunction = stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
+        contractAddress: new stellar_sdk_1.Address(args.smartAccount).toScAddress(),
+        functionName: 'remove_context_rule',
+        args: [stellar_sdk_1.xdr.ScVal.scvU32(args.ruleId)],
+    }));
+    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 tx = buildUnsignedTx({
+    const buildTx = (op) => buildUnsignedTx({
         sourceAccount: args.sourceAccount,
         sequence: source.sequenceNumber(),
         fee: baseFee,
         networkPassphrase: args.networkPassphrase,
         op,
     });
-    const recorded = await args.rpc.simulateTransaction(tx);
+    const recorded = await args.rpc.simulateTransaction(buildTx(makeOperation()));
     if (stellar_sdk_1.rpc.Api.isSimulationError(recorded)) {
         // Short, stable reason. The full `simulateTransaction` error (which
         // carries host + URL detail) stays in the SDK's own logs - never
@@ -197,8 +209,27 @@ async function buildRevokePolicyXdr(args) {
     if (!original) {
         throw new Error(`revoke_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
     }
+    // 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 = (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)),
+    ];
+    const txWithAuth = buildTx(makeOperation(authEntries));
+    const enforcing = await args.rpc.simulateTransaction(txWithAuth);
+    if (stellar_sdk_1.rpc.Api.isSimulationError(enforcing)) {
+        throw new Error('revoke_policy: auth simulateTransaction failed');
+    }
+    const finalTx = stellar_sdk_1.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 },
@@ -208,7 +239,7 @@ async function buildRevokePolicyXdr(args) {
     };
 }
 /** ~25 minutes at 5s/ledger. */
-const DEFAULT_AUTH_VALID_LEDGERS = 300;
+const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 300;
 // ---- internals ----
 /** Adapter: turn the install-policy wire `PolicyRef` shape into the core
  *  `PolicyRef` shape `buildAddContextRuleArgs` expects. Keeps the wire
@@ -246,20 +277,24 @@ function buildUnsignedTx(args) {
     // its signature, and broadcasts. We do NOT sign here.
     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
  *  install has no interpreter policy (no `install_nonce` to read); the
  *  caller already knows it. */
-function decodeInstallCallDescribes(tx, op, expectedInstallNonce) {
+function decodeInstallCallDescribes(tx, expectedInstallNonce) {
+    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');
     }
     const invokeArgs = hostFn.invokeContract();
@@ -412,10 +447,6 @@ function decodeInstallCallDescribes(tx, op, expectedInstallNonce) {
     // `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/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/package.json

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

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

@@ -31,6 +31,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
@@ -265,36 +272,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,15 +318,48 @@ 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' },
@@ -360,30 +397,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 +436,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 +491,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 +542,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 +554,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 +732,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(),
+  })
+}