@crediolabs/policy-synth 1.1.0 → 1.2.0

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

@@ -112,6 +112,21 @@ export interface InstallCallDescribes {
 export interface BuildInstallPolicyResult {
     /** Unsigned Soroban transaction envelope, base64 XDR. */
     unsignedXdr: string;
+    /** Length and SHA-256 of `unsignedXdr`, so a caller that has to move it can
+     *  prove it arrived whole.
+     *
+     *  This envelope runs to several thousand characters, and the only route
+     *  from a tool result onto disk is the caller re-emitting it. A truncated
+     *  copy is not obviously wrong - it fails later as
+     *  "failed to decode XDR: xdr value invalid", which reads like a malformed
+     *  transaction rather than a transport problem. Observed in practice: one of
+     *  two envelopes written in the same session lost its tail and its base64
+     *  length went from a multiple of four to `len % 4 == 3`.
+     *
+     *  Check both before signing. They are cheap, and they turn a silent,
+     *  fatal truncation into a retry. */
+    unsignedXdrLength: number;
+    unsignedXdrSha256: string;
     /** Smart account contract address (echo). */
     smartAccount: string;
     /** Source account (echo) - the address that must sign. */
@@ -168,6 +183,11 @@ export declare function buildRevokePolicyXdr(args: {
 }): Promise<BuildRevokePolicyResult>;
 export interface BuildRevokePolicyResult {
     unsignedXdr: string;
+    /** Same integrity pair as the install result, for the same reason: a revoke
+     *  envelope also has to reach a signer intact, and a truncated copy fails as
+     *  a malformed transaction rather than as a transport error. */
+    unsignedXdrLength: number;
+    unsignedXdrSha256: string;
     smartAccount: string;
     sourceAccount: string;
     call: {

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

@@ -62,6 +62,14 @@ export function rpcClientFromServer(server, networkPassphrase) {
         },
     };
 }
+/** `unsignedXdr` plus the length and digest that prove it arrived whole. */
+function xdrIntegrity(unsignedXdr) {
+    return {
+        unsignedXdr,
+        unsignedXdrLength: unsignedXdr.length,
+        unsignedXdrSha256: createHash('sha256').update(unsignedXdr, 'utf8').digest('hex'),
+    };
+}
 /** Build the unsigned transaction envelope for `account.add_context_rule(...)`.
  *  The output XDR is signed by the wallet, not by us. */
 export async function buildInstallPolicyXdr(args) {
@@ -90,7 +98,7 @@ export async function buildInstallPolicyXdr(args) {
     //    The human approval binds to the exact bytes the wallet will sign.
     const describes = decodeInstallCallDescribes(finalTx, args.installNonce);
     return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'add_context_rule' },
@@ -119,7 +127,7 @@ export async function buildRevokePolicyXdr(args) {
     // consumer supplies only the ordinary envelope signature.
     const { finalTx, original, validUntilLedger } = await buildAuthorisedSmartAccountTx(args, 'remove_context_rule', [xdr.ScVal.scvU32(args.ruleId)], 'revoke_policy');
     return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },

package/dist/run/index.d.ts

@@ -38,6 +38,20 @@ export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<
         predicateTree: PredicateNode | null;
     };
 }>;
+/** The refusal message for an install the cross-rule scan proves cannot bind,
+ *  or `undefined` when the install may proceed.
+ *
+ *  Only `bypass` refuses. That class means the neighbouring rule carries NO
+ *  policy, so a shared signer names it and the new predicate never runs - a
+ *  proof, from data already in hand, that the rule constrains nothing.
+ *  `unknown` (a neighbour policed by a contract this tool cannot decode) stays
+ *  advisory: it may well be tighter, and refusing on "cannot decode" would
+ *  block installs on a guess. A `null` scan is NOT CHECKED, which is not
+ *  evidence of a bypass and must not refuse on its own.
+ *
+ *  Separated from the tool body so the decision can be tested without a
+ *  network: the install it guards cannot be built without one. */
+export declare function authorityBypassRefusal(scan: AuthorityOverlap[] | null, allowAuthorityOverlap: boolean | undefined): string | undefined;
 export declare function runInstallPolicy(raw: unknown): Promise<ToolResponse<BuildInstallPolicyResult & {
     authorityScan: AuthorityOverlap[] | null;
 }>>;

package/dist/run/index.js

@@ -17,6 +17,7 @@
 // No business logic. No retries. No session state. The same call shape can
 // drive the CLI (which calls into the same core directly without MCP).
 import { createHash } from 'node:crypto';
+import { readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { rpc } from '@stellar/stellar-sdk';
 import { PLACEHOLDER_INTERPRETER_ADDRESS } from "../adapters/interpreter/adapter.js";
 import { declarePredicate, encodePredicate, recordTransaction, synthesizeFromRecording, } from "../index.js";
@@ -128,6 +129,28 @@ export async function runSynthesizePolicy(raw) {
         return toolFailure('synthesize_policy', e);
     }
 }
+/** The refusal message for an install the cross-rule scan proves cannot bind,
+ *  or `undefined` when the install may proceed.
+ *
+ *  Only `bypass` refuses. That class means the neighbouring rule carries NO
+ *  policy, so a shared signer names it and the new predicate never runs - a
+ *  proof, from data already in hand, that the rule constrains nothing.
+ *  `unknown` (a neighbour policed by a contract this tool cannot decode) stays
+ *  advisory: it may well be tighter, and refusing on "cannot decode" would
+ *  block installs on a guess. A `null` scan is NOT CHECKED, which is not
+ *  evidence of a bypass and must not refuse on its own.
+ *
+ *  Separated from the tool body so the decision can be tested without a
+ *  network: the install it guards cannot be built without one. */
+export function authorityBypassRefusal(scan, allowAuthorityOverlap) {
+    if (scan === null || allowAuthorityOverlap === true)
+        return undefined;
+    const proven = scan.filter((o) => o.severity === 'bypass');
+    if (proven.length === 0)
+        return undefined;
+    const ids = proven.map((o) => o.ruleId).join(', ');
+    return `install_policy: ${proven[0]?.advice ?? ''} This rule would install cleanly and constrain nothing, so it is refused (rule ${ids}); remove the shared signer from that rule, attach a policy to it, or set \`allowAuthorityOverlap: true\` to install anyway.`;
+}
 export async function runInstallPolicy(raw) {
     const parsed = InstallPolicyInputSchema.safeParse(raw);
     if (!parsed.success) {
@@ -330,7 +353,52 @@ export async function runInstallPolicy(raw) {
                 },
                 existing: observed,
             });
-        return { ok: true, data: { ...result, authorityScan } };
+        // A `bypass` overlap is not a warning, it is a proof that this rule cannot
+        // bind the key it names: the neighbour carries NO policy, so the signer
+        // names that rule instead and the predicate never runs. Returning `ok` with
+        // the finding buried in `authorityScan` puts the whole protection on the
+        // caller reading a field, and the caller here is usually an agent that
+        // checks whether the call succeeded. Refuse, and let the caller opt in.
+        //
+        // Only the provable class. `unknown` - a neighbour whose policy this tool
+        // cannot decode - stays advisory: it may well be tighter, and refusing on
+        // "cannot decode" would block installs on a guess.
+        const bypassRefusal = authorityBypassRefusal(authorityScan, input.allowAuthorityOverlap);
+        if (bypassRefusal !== undefined) {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: bypassRefusal,
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        // Write the envelope here when asked, so it never travels through the
+        // caller. `writtenTo` is what the caller should hand to a signer.
+        let writtenTo;
+        if (input.outPath !== undefined) {
+            // Write beside the target and rename, which is atomic within a
+            // filesystem. A plain write truncates first, so anything watching the
+            // directory - a signer picking up envelopes is the obvious case - can
+            // read a half-written file and report a malformed TRANSACTION. With a
+            // rename the path either does not exist or holds the whole envelope.
+            const staging = `${input.outPath}.partial`;
+            await writeFile(staging, result.unsignedXdr, 'utf8');
+            const readBack = await readFile(staging, 'utf8');
+            if (readBack !== result.unsignedXdr) {
+                await rm(staging, { force: true });
+                throw new Error(`outPath: wrote ${result.unsignedXdr.length} characters to ${input.outPath} but read back ${readBack.length}; the file was not persisted intact`);
+            }
+            await rename(staging, input.outPath);
+            writtenTo = input.outPath;
+        }
+        return {
+            ok: true,
+            data: { ...result, authorityScan, ...(writtenTo !== undefined ? { writtenTo } : {}) },
+        };
     }
     catch (e) {
         return toolFailure('install_policy', e);

package/dist/run/schemas.d.ts

@@ -2849,10 +2849,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         predicate?: unknown;
     }>, "many">>;
     /** The smart account contract address (C...) that will receive the rule. */
-    smartAccount: z.ZodString;
+    smartAccount: z.ZodEffects<z.ZodString, string, string>;
     /** The signer that authorises the install (G... wallet). Used only for
      *  sequence number + auth nonce simulation; never persisted, never signed. */
-    sourceAccount: z.ZodString;
+    sourceAccount: z.ZodEffects<z.ZodString, string, string>;
     /** Target network for the install. Selects which interpreter pin and
      *  which RPC URL are valid by default. Defaults to `testnet` so the
      *  pre-mainnet callers keep working: they were always pointing at
@@ -3366,6 +3366,17 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
      *  knows. Supply it only to re-install over an existing rule, where the
      *  interpreter wants `stored_nonce + 1`. */
     installNonce: z.ZodOptional<z.ZodNumber>;
+    /** Absolute path to write the unsigned envelope to.
+     *
+     *  The envelope runs to several thousand characters, and without this the
+     *  only route onto disk is the CALLER re-emitting it - through a model, a
+     *  shell argument, or both. That transport mangles it: observed in practice
+     *  as a file of the right length whose bytes no longer parse
+     *  ("xdr padding contains non-zero bytes"), and as silent truncation.
+     *  Writing it here takes the caller out of the transport entirely.
+     *
+     *  Opt-in: omitted, nothing is written and behaviour is unchanged. */
+    outPath: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
     /** Optional RPC URL override. Defaults to the pinned RPC for the
      *  selected `network` (testnet by default, mainnet when
      *  `network: 'mainnet'`); the override is refused unless
@@ -3411,6 +3422,18 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
      *  unaffected; only the case the synthesizer explicitly flagged is
      *  refused. */
     allowUnboundedAmount: z.ZodOptional<z.ZodBoolean>;
+    /** Opt-in to installing a rule that the cross-rule scan proves cannot bind.
+     *
+     *  An OZ account resolves a call against the rule the caller NAMES, so a
+     *  key on several rules gets the MAXIMUM authority over them, never the
+     *  intersection. A key that also sits on a rule with no policy is therefore
+     *  unconstrained: it names that rule and the new predicate never runs.
+     *
+     *  Default-deny, and only for the case the scan can PROVE - an unpoliced
+     *  neighbour sharing signers and selectors. A neighbour carrying a policy
+     *  this tool cannot decode stays advisory, because "cannot decode" is not
+     *  "proved unsafe" and refusing it would block installs on a guess. */
+    allowAuthorityOverlap: z.ZodOptional<z.ZodBoolean>;
     /** Opt-in to pointing the rule's interpreter policy at any address
      *  other than the pinned interpreter for the selected network.
      *  Default-deny: a caller that controls the interpreter can permit
@@ -3549,9 +3572,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }, {
@@ -3684,9 +3709,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }>, {
@@ -3819,9 +3846,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }, {
@@ -3954,9 +3983,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }>, {
@@ -4089,9 +4120,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }, {
@@ -4224,21 +4257,23 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }>;
 export type InstallPolicyInput = z.infer<typeof InstallPolicyInputSchema>;
 export declare const RevokePolicyInputSchema: z.ZodEffects<z.ZodObject<{
     /** The smart account contract address (C...). */
-    smartAccount: z.ZodString;
+    smartAccount: z.ZodEffects<z.ZodString, string, string>;
     /** The wallet that will sign the removal. The ACCOUNT decides whether it
      *  accepts that signer; this schema does not assert a rule it cannot
      *  verify, since the account's source is not in this repo. Proven on
      *  testnet: the account's deployer can revoke. */
-    sourceAccount: z.ZodString;
+    sourceAccount: z.ZodEffects<z.ZodString, string, string>;
     /** Target network for the revoke. Same `testnet`-default as install,
      *  so pre-mainnet callers keep working without an explicit flag. */
     network: z.ZodOptional<z.ZodEnum<["mainnet", "testnet"]>>;

package/dist/run/schemas.js

@@ -14,6 +14,7 @@
 // This module is the SINGLE source of truth for these shapes. The MCP package
 // imports them here so its tool-shape bindings stay in step; the CLI imports
 // them here so it can build the same args envelope the MCP transport builds.
+import { StrKey } from '@stellar/stellar-sdk';
 import { z } from 'zod';
 import { isStellarAddress } from "../synth/address.js";
 /** Soroban `valid_until` is a u32 ledger sequence; a value above this cannot be
@@ -471,6 +472,20 @@ export const NETWORK_PASSPHRASES = {
 // `sourceAccount` is the signing wallet (G...).
 const STELLAR_CONTRACT_ADDRESS = /^C[2-7A-Z]{55}$/;
 const STELLAR_ACCOUNT_ADDRESS = /^G[2-7A-Z]{55}$/;
+// The regexes above check SHAPE only. A wrong-but-well-formed address - the
+// classic case being one an agent reproduced from memory - passes them and then
+// fails the SDK's StrKey decoder deep inside the build, where the throw is
+// caught by the tool envelope and reported as a bare "invalid checksum" naming
+// no field. A caller holding several addresses then cannot tell which one is
+// wrong. Validating the checksum HERE keeps the field name attached.
+const contractAddress = (field) => z
+    .string()
+    .regex(STELLAR_CONTRACT_ADDRESS, `${field} must be a Stellar contract address (C...)`)
+    .refine(StrKey.isValidContract, `${field} is not a valid contract address: the checksum does not match, so this address does not exist`);
+const accountAddress = (field) => z
+    .string()
+    .regex(STELLAR_ACCOUNT_ADDRESS, `${field} must be a Stellar account address (G...)`)
+    .refine(StrKey.isValidEd25519PublicKey, `${field} is not a valid account address: the checksum does not match, so this address does not exist`);
 // ===== declare_policy =====
 //
 // The declarative front-end: the constraint stated outright, with no
@@ -532,14 +547,10 @@ export const InstallPolicyInputSchema = z
      *  result says so rather than reporting "no overlaps found". */
     existingRules: z.array(ObservedRuleSchema).optional(),
     /** The smart account contract address (C...) that will receive the rule. */
-    smartAccount: z
-        .string()
-        .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The signer that authorises the install (G... wallet). Used only for
      *  sequence number + auth nonce simulation; never persisted, never signed. */
-    sourceAccount: z
-        .string()
-        .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the install. Selects which interpreter pin and
      *  which RPC URL are valid by default. Defaults to `testnet` so the
      *  pre-mainnet callers keep working: they were always pointing at
@@ -612,6 +623,22 @@ export const InstallPolicyInputSchema = z
      *  knows. Supply it only to re-install over an existing rule, where the
      *  interpreter wants `stored_nonce + 1`. */
     installNonce: z.number().int().positive().optional(),
+    /** Absolute path to write the unsigned envelope to.
+     *
+     *  The envelope runs to several thousand characters, and without this the
+     *  only route onto disk is the CALLER re-emitting it - through a model, a
+     *  shell argument, or both. That transport mangles it: observed in practice
+     *  as a file of the right length whose bytes no longer parse
+     *  ("xdr padding contains non-zero bytes"), and as silent truncation.
+     *  Writing it here takes the caller out of the transport entirely.
+     *
+     *  Opt-in: omitted, nothing is written and behaviour is unchanged. */
+    outPath: z
+        .string()
+        .min(1)
+        .refine((p) => p.startsWith('/'), 'outPath must be an absolute path')
+        .refine((p) => !p.includes('\0'), 'outPath must not contain a null byte')
+        .optional(),
     /** Optional RPC URL override. Defaults to the pinned RPC for the
      *  selected `network` (testnet by default, mainnet when
      *  `network: 'mainnet'`); the override is refused unless
@@ -655,6 +682,18 @@ export const InstallPolicyInputSchema = z
      *  unaffected; only the case the synthesizer explicitly flagged is
      *  refused. */
     allowUnboundedAmount: z.boolean().optional(),
+    /** Opt-in to installing a rule that the cross-rule scan proves cannot bind.
+     *
+     *  An OZ account resolves a call against the rule the caller NAMES, so a
+     *  key on several rules gets the MAXIMUM authority over them, never the
+     *  intersection. A key that also sits on a rule with no policy is therefore
+     *  unconstrained: it names that rule and the new predicate never runs.
+     *
+     *  Default-deny, and only for the case the scan can PROVE - an unpoliced
+     *  neighbour sharing signers and selectors. A neighbour carrying a policy
+     *  this tool cannot decode stays advisory, because "cannot decode" is not
+     *  "proved unsafe" and refusing it would block installs on a guess. */
+    allowAuthorityOverlap: z.boolean().optional(),
     /** Opt-in to pointing the rule's interpreter policy at any address
      *  other than the pinned interpreter for the selected network.
      *  Default-deny: a caller that controls the interpreter can permit
@@ -673,16 +712,12 @@ export const InstallPolicyInputSchema = z
 export const RevokePolicyInputSchema = z
     .object({
     /** The smart account contract address (C...). */
-    smartAccount: z
-        .string()
-        .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The wallet that will sign the removal. The ACCOUNT decides whether it
      *  accepts that signer; this schema does not assert a rule it cannot
      *  verify, since the account's source is not in this repo. Proven on
      *  testnet: the account's deployer can revoke. */
-    sourceAccount: z
-        .string()
-        .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the revoke. Same `testnet`-default as install,
      *  so pre-mainnet callers keep working without an explicit flag. */
     network: NetworkSchema.optional(),

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

@@ -112,6 +112,21 @@ export interface InstallCallDescribes {
 export interface BuildInstallPolicyResult {
     /** Unsigned Soroban transaction envelope, base64 XDR. */
     unsignedXdr: string;
+    /** Length and SHA-256 of `unsignedXdr`, so a caller that has to move it can
+     *  prove it arrived whole.
+     *
+     *  This envelope runs to several thousand characters, and the only route
+     *  from a tool result onto disk is the caller re-emitting it. A truncated
+     *  copy is not obviously wrong - it fails later as
+     *  "failed to decode XDR: xdr value invalid", which reads like a malformed
+     *  transaction rather than a transport problem. Observed in practice: one of
+     *  two envelopes written in the same session lost its tail and its base64
+     *  length went from a multiple of four to `len % 4 == 3`.
+     *
+     *  Check both before signing. They are cheap, and they turn a silent,
+     *  fatal truncation into a retry. */
+    unsignedXdrLength: number;
+    unsignedXdrSha256: string;
     /** Smart account contract address (echo). */
     smartAccount: string;
     /** Source account (echo) - the address that must sign. */
@@ -168,6 +183,11 @@ export declare function buildRevokePolicyXdr(args: {
 }): Promise<BuildRevokePolicyResult>;
 export interface BuildRevokePolicyResult {
     unsignedXdr: string;
+    /** Same integrity pair as the install result, for the same reason: a revoke
+     *  envelope also has to reach a signer intact, and a truncated copy fails as
+     *  a malformed transaction rather than as a transport error. */
+    unsignedXdrLength: number;
+    unsignedXdrSha256: string;
     smartAccount: string;
     sourceAccount: string;
     call: {

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

@@ -68,6 +68,14 @@ function rpcClientFromServer(server, networkPassphrase) {
         },
     };
 }
+/** `unsignedXdr` plus the length and digest that prove it arrived whole. */
+function xdrIntegrity(unsignedXdr) {
+    return {
+        unsignedXdr,
+        unsignedXdrLength: unsignedXdr.length,
+        unsignedXdrSha256: (0, node_crypto_1.createHash)('sha256').update(unsignedXdr, 'utf8').digest('hex'),
+    };
+}
 /** Build the unsigned transaction envelope for `account.add_context_rule(...)`.
  *  The output XDR is signed by the wallet, not by us. */
 async function buildInstallPolicyXdr(args) {
@@ -96,7 +104,7 @@ async function buildInstallPolicyXdr(args) {
     //    The human approval binds to the exact bytes the wallet will sign.
     const describes = decodeInstallCallDescribes(finalTx, args.installNonce);
     return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'add_context_rule' },
@@ -125,7 +133,7 @@ async function buildRevokePolicyXdr(args) {
     // consumer supplies only the ordinary envelope signature.
     const { finalTx, original, validUntilLedger } = await buildAuthorisedSmartAccountTx(args, 'remove_context_rule', [stellar_sdk_1.xdr.ScVal.scvU32(args.ruleId)], 'revoke_policy');
     return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },

package/dist-cjs/run/index.d.ts

@@ -38,6 +38,20 @@ export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<
         predicateTree: PredicateNode | null;
     };
 }>;
+/** The refusal message for an install the cross-rule scan proves cannot bind,
+ *  or `undefined` when the install may proceed.
+ *
+ *  Only `bypass` refuses. That class means the neighbouring rule carries NO
+ *  policy, so a shared signer names it and the new predicate never runs - a
+ *  proof, from data already in hand, that the rule constrains nothing.
+ *  `unknown` (a neighbour policed by a contract this tool cannot decode) stays
+ *  advisory: it may well be tighter, and refusing on "cannot decode" would
+ *  block installs on a guess. A `null` scan is NOT CHECKED, which is not
+ *  evidence of a bypass and must not refuse on its own.
+ *
+ *  Separated from the tool body so the decision can be tested without a
+ *  network: the install it guards cannot be built without one. */
+export declare function authorityBypassRefusal(scan: AuthorityOverlap[] | null, allowAuthorityOverlap: boolean | undefined): string | undefined;
 export declare function runInstallPolicy(raw: unknown): Promise<ToolResponse<BuildInstallPolicyResult & {
     authorityScan: AuthorityOverlap[] | null;
 }>>;

package/dist-cjs/run/index.js

@@ -21,6 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolErrorSchema = exports.TESTNET_RPC_URL = exports.SynthesizePolicyInputSchema = exports.RPC_URL_BY_NETWORK = exports.RevokePolicyInputSchema = exports.RecordTransactionInputSchema = exports.RecordedTransactionSchema = exports.PredicateNodeSchema = exports.PredicateLeafSchema = exports.PINNED_OZ_POLICY_WASM_SHA256 = exports.PINNED_OZ_POLICY_ADDRESS_BY_NETWORK = exports.PINNED_INTERPRETER_WASM_SHA256 = exports.PINNED_INTERPRETER_TESTNET_ADDRESS = exports.PINNED_INTERPRETER_MAINNET_ADDRESS = exports.PINNED_INTERPRETER_GRAMMAR_VERSION = exports.PINNED_INTERPRETER_ADDRESS_BY_NETWORK = exports.NetworkSchema = exports.MAINNET_RPC_URL = exports.InterpreterOptionsSchema = exports.InstallPolicyInputSchema = exports.GetInterpreterInfoInputSchema = exports.DeclarePolicyInputSchema = exports.ComposeUserResponsesSchema = void 0;
 exports.runRecordTransaction = runRecordTransaction;
 exports.runSynthesizePolicy = runSynthesizePolicy;
+exports.authorityBypassRefusal = authorityBypassRefusal;
 exports.runInstallPolicy = runInstallPolicy;
 exports.runRevokePolicy = runRevokePolicy;
 exports.contextTypeForPredicate = contextTypeForPredicate;
@@ -30,6 +31,7 @@ exports.runVerifyPolicy = runVerifyPolicy;
 exports.runGetInterpreterInfo = runGetInterpreterInfo;
 exports.caughtError = caughtError;
 const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const adapter_ts_1 = require("../adapters/interpreter/adapter.js");
 const index_ts_1 = require("../index.js");
@@ -164,6 +166,28 @@ async function runSynthesizePolicy(raw) {
         return toolFailure('synthesize_policy', e);
     }
 }
+/** The refusal message for an install the cross-rule scan proves cannot bind,
+ *  or `undefined` when the install may proceed.
+ *
+ *  Only `bypass` refuses. That class means the neighbouring rule carries NO
+ *  policy, so a shared signer names it and the new predicate never runs - a
+ *  proof, from data already in hand, that the rule constrains nothing.
+ *  `unknown` (a neighbour policed by a contract this tool cannot decode) stays
+ *  advisory: it may well be tighter, and refusing on "cannot decode" would
+ *  block installs on a guess. A `null` scan is NOT CHECKED, which is not
+ *  evidence of a bypass and must not refuse on its own.
+ *
+ *  Separated from the tool body so the decision can be tested without a
+ *  network: the install it guards cannot be built without one. */
+function authorityBypassRefusal(scan, allowAuthorityOverlap) {
+    if (scan === null || allowAuthorityOverlap === true)
+        return undefined;
+    const proven = scan.filter((o) => o.severity === 'bypass');
+    if (proven.length === 0)
+        return undefined;
+    const ids = proven.map((o) => o.ruleId).join(', ');
+    return `install_policy: ${proven[0]?.advice ?? ''} This rule would install cleanly and constrain nothing, so it is refused (rule ${ids}); remove the shared signer from that rule, attach a policy to it, or set \`allowAuthorityOverlap: true\` to install anyway.`;
+}
 async function runInstallPolicy(raw) {
     const parsed = schemas_ts_1.InstallPolicyInputSchema.safeParse(raw);
     if (!parsed.success) {
@@ -366,7 +390,52 @@ async function runInstallPolicy(raw) {
                 },
                 existing: observed,
             });
-        return { ok: true, data: { ...result, authorityScan } };
+        // A `bypass` overlap is not a warning, it is a proof that this rule cannot
+        // bind the key it names: the neighbour carries NO policy, so the signer
+        // names that rule instead and the predicate never runs. Returning `ok` with
+        // the finding buried in `authorityScan` puts the whole protection on the
+        // caller reading a field, and the caller here is usually an agent that
+        // checks whether the call succeeded. Refuse, and let the caller opt in.
+        //
+        // Only the provable class. `unknown` - a neighbour whose policy this tool
+        // cannot decode - stays advisory: it may well be tighter, and refusing on
+        // "cannot decode" would block installs on a guess.
+        const bypassRefusal = authorityBypassRefusal(authorityScan, input.allowAuthorityOverlap);
+        if (bypassRefusal !== undefined) {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: bypassRefusal,
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        // Write the envelope here when asked, so it never travels through the
+        // caller. `writtenTo` is what the caller should hand to a signer.
+        let writtenTo;
+        if (input.outPath !== undefined) {
+            // Write beside the target and rename, which is atomic within a
+            // filesystem. A plain write truncates first, so anything watching the
+            // directory - a signer picking up envelopes is the obvious case - can
+            // read a half-written file and report a malformed TRANSACTION. With a
+            // rename the path either does not exist or holds the whole envelope.
+            const staging = `${input.outPath}.partial`;
+            await (0, promises_1.writeFile)(staging, result.unsignedXdr, 'utf8');
+            const readBack = await (0, promises_1.readFile)(staging, 'utf8');
+            if (readBack !== result.unsignedXdr) {
+                await (0, promises_1.rm)(staging, { force: true });
+                throw new Error(`outPath: wrote ${result.unsignedXdr.length} characters to ${input.outPath} but read back ${readBack.length}; the file was not persisted intact`);
+            }
+            await (0, promises_1.rename)(staging, input.outPath);
+            writtenTo = input.outPath;
+        }
+        return {
+            ok: true,
+            data: { ...result, authorityScan, ...(writtenTo !== undefined ? { writtenTo } : {}) },
+        };
     }
     catch (e) {
         return toolFailure('install_policy', e);

package/dist-cjs/run/schemas.d.ts

@@ -2849,10 +2849,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         predicate?: unknown;
     }>, "many">>;
     /** The smart account contract address (C...) that will receive the rule. */
-    smartAccount: z.ZodString;
+    smartAccount: z.ZodEffects<z.ZodString, string, string>;
     /** The signer that authorises the install (G... wallet). Used only for
      *  sequence number + auth nonce simulation; never persisted, never signed. */
-    sourceAccount: z.ZodString;
+    sourceAccount: z.ZodEffects<z.ZodString, string, string>;
     /** Target network for the install. Selects which interpreter pin and
      *  which RPC URL are valid by default. Defaults to `testnet` so the
      *  pre-mainnet callers keep working: they were always pointing at
@@ -3366,6 +3366,17 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
      *  knows. Supply it only to re-install over an existing rule, where the
      *  interpreter wants `stored_nonce + 1`. */
     installNonce: z.ZodOptional<z.ZodNumber>;
+    /** Absolute path to write the unsigned envelope to.
+     *
+     *  The envelope runs to several thousand characters, and without this the
+     *  only route onto disk is the CALLER re-emitting it - through a model, a
+     *  shell argument, or both. That transport mangles it: observed in practice
+     *  as a file of the right length whose bytes no longer parse
+     *  ("xdr padding contains non-zero bytes"), and as silent truncation.
+     *  Writing it here takes the caller out of the transport entirely.
+     *
+     *  Opt-in: omitted, nothing is written and behaviour is unchanged. */
+    outPath: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
     /** Optional RPC URL override. Defaults to the pinned RPC for the
      *  selected `network` (testnet by default, mainnet when
      *  `network: 'mainnet'`); the override is refused unless
@@ -3411,6 +3422,18 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
      *  unaffected; only the case the synthesizer explicitly flagged is
      *  refused. */
     allowUnboundedAmount: z.ZodOptional<z.ZodBoolean>;
+    /** Opt-in to installing a rule that the cross-rule scan proves cannot bind.
+     *
+     *  An OZ account resolves a call against the rule the caller NAMES, so a
+     *  key on several rules gets the MAXIMUM authority over them, never the
+     *  intersection. A key that also sits on a rule with no policy is therefore
+     *  unconstrained: it names that rule and the new predicate never runs.
+     *
+     *  Default-deny, and only for the case the scan can PROVE - an unpoliced
+     *  neighbour sharing signers and selectors. A neighbour carrying a policy
+     *  this tool cannot decode stays advisory, because "cannot decode" is not
+     *  "proved unsafe" and refusing it would block installs on a guess. */
+    allowAuthorityOverlap: z.ZodOptional<z.ZodBoolean>;
     /** Opt-in to pointing the rule's interpreter policy at any address
      *  other than the pinned interpreter for the selected network.
      *  Default-deny: a caller that controls the interpreter can permit
@@ -3549,9 +3572,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }, {
@@ -3684,9 +3709,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }>, {
@@ -3819,9 +3846,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }, {
@@ -3954,9 +3983,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }>, {
@@ -4089,9 +4120,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }, {
@@ -4224,21 +4257,23 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }>;
 export type InstallPolicyInput = z.infer<typeof InstallPolicyInputSchema>;
 export declare const RevokePolicyInputSchema: z.ZodEffects<z.ZodObject<{
     /** The smart account contract address (C...). */
-    smartAccount: z.ZodString;
+    smartAccount: z.ZodEffects<z.ZodString, string, string>;
     /** The wallet that will sign the removal. The ACCOUNT decides whether it
      *  accepts that signer; this schema does not assert a rule it cannot
      *  verify, since the account's source is not in this repo. Proven on
      *  testnet: the account's deployer can revoke. */
-    sourceAccount: z.ZodString;
+    sourceAccount: z.ZodEffects<z.ZodString, string, string>;
     /** Target network for the revoke. Same `testnet`-default as install,
      *  so pre-mainnet callers keep working without an explicit flag. */
     network: z.ZodOptional<z.ZodEnum<["mainnet", "testnet"]>>;

package/dist-cjs/run/schemas.js

@@ -17,6 +17,7 @@
 // them here so it can build the same args envelope the MCP transport builds.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolErrorSchema = exports.GetInterpreterInfoInputSchema = exports.RevokePolicyInputSchema = exports.InstallPolicyInputSchema = exports.DeclarePolicyInputSchema = exports.NETWORK_PASSPHRASES = exports.PINNED_OZ_POLICY_WASM_SHA256 = exports.PINNED_OZ_POLICY_ADDRESS_BY_NETWORK = exports.PINNED_OZ_STELLAR_CONTRACTS_TAG = exports.RPC_URL_BY_NETWORK = exports.PINNED_INTERPRETER_ADDRESS_BY_NETWORK = exports.MAINNET_RPC_URL = exports.TESTNET_RPC_URL = exports.PINNED_INTERPRETER_GRAMMAR_VERSION = exports.PINNED_INTERPRETER_WASM_SHA256 = exports.PINNED_INTERPRETER_MAINNET_ADDRESS = exports.PINNED_INTERPRETER_TESTNET_ADDRESS = exports.ObservedRuleSchema = exports.VerifyPolicyInputSchema = exports.SimulatePolicyInputSchema = exports.PredicateNodeSchema = exports.PredicateLeafSchema = exports.SynthesizePolicyInputSchema = exports.InterpreterOptionsSchema = exports.RecordTransactionInputSchema = exports.ComposeUserResponsesSchema = exports.RecordedTransactionSchema = exports.ParseConfidenceSchema = exports.OnChainEventSchema = exports.TokenMovementSchema = exports.ContractInvocationSchema = exports.ScValSchema = exports.NetworkSchema = void 0;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const zod_1 = require("zod");
 const address_ts_1 = require("../synth/address.js");
 /** Soroban `valid_until` is a u32 ledger sequence; a value above this cannot be
@@ -474,6 +475,20 @@ exports.NETWORK_PASSPHRASES = {
 // `sourceAccount` is the signing wallet (G...).
 const STELLAR_CONTRACT_ADDRESS = /^C[2-7A-Z]{55}$/;
 const STELLAR_ACCOUNT_ADDRESS = /^G[2-7A-Z]{55}$/;
+// The regexes above check SHAPE only. A wrong-but-well-formed address - the
+// classic case being one an agent reproduced from memory - passes them and then
+// fails the SDK's StrKey decoder deep inside the build, where the throw is
+// caught by the tool envelope and reported as a bare "invalid checksum" naming
+// no field. A caller holding several addresses then cannot tell which one is
+// wrong. Validating the checksum HERE keeps the field name attached.
+const contractAddress = (field) => zod_1.z
+    .string()
+    .regex(STELLAR_CONTRACT_ADDRESS, `${field} must be a Stellar contract address (C...)`)
+    .refine(stellar_sdk_1.StrKey.isValidContract, `${field} is not a valid contract address: the checksum does not match, so this address does not exist`);
+const accountAddress = (field) => zod_1.z
+    .string()
+    .regex(STELLAR_ACCOUNT_ADDRESS, `${field} must be a Stellar account address (G...)`)
+    .refine(stellar_sdk_1.StrKey.isValidEd25519PublicKey, `${field} is not a valid account address: the checksum does not match, so this address does not exist`);
 // ===== declare_policy =====
 //
 // The declarative front-end: the constraint stated outright, with no
@@ -535,14 +550,10 @@ exports.InstallPolicyInputSchema = zod_1.z
      *  result says so rather than reporting "no overlaps found". */
     existingRules: zod_1.z.array(exports.ObservedRuleSchema).optional(),
     /** The smart account contract address (C...) that will receive the rule. */
-    smartAccount: zod_1.z
-        .string()
-        .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The signer that authorises the install (G... wallet). Used only for
      *  sequence number + auth nonce simulation; never persisted, never signed. */
-    sourceAccount: zod_1.z
-        .string()
-        .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the install. Selects which interpreter pin and
      *  which RPC URL are valid by default. Defaults to `testnet` so the
      *  pre-mainnet callers keep working: they were always pointing at
@@ -615,6 +626,22 @@ exports.InstallPolicyInputSchema = zod_1.z
      *  knows. Supply it only to re-install over an existing rule, where the
      *  interpreter wants `stored_nonce + 1`. */
     installNonce: zod_1.z.number().int().positive().optional(),
+    /** Absolute path to write the unsigned envelope to.
+     *
+     *  The envelope runs to several thousand characters, and without this the
+     *  only route onto disk is the CALLER re-emitting it - through a model, a
+     *  shell argument, or both. That transport mangles it: observed in practice
+     *  as a file of the right length whose bytes no longer parse
+     *  ("xdr padding contains non-zero bytes"), and as silent truncation.
+     *  Writing it here takes the caller out of the transport entirely.
+     *
+     *  Opt-in: omitted, nothing is written and behaviour is unchanged. */
+    outPath: zod_1.z
+        .string()
+        .min(1)
+        .refine((p) => p.startsWith('/'), 'outPath must be an absolute path')
+        .refine((p) => !p.includes('\0'), 'outPath must not contain a null byte')
+        .optional(),
     /** Optional RPC URL override. Defaults to the pinned RPC for the
      *  selected `network` (testnet by default, mainnet when
      *  `network: 'mainnet'`); the override is refused unless
@@ -658,6 +685,18 @@ exports.InstallPolicyInputSchema = zod_1.z
      *  unaffected; only the case the synthesizer explicitly flagged is
      *  refused. */
     allowUnboundedAmount: zod_1.z.boolean().optional(),
+    /** Opt-in to installing a rule that the cross-rule scan proves cannot bind.
+     *
+     *  An OZ account resolves a call against the rule the caller NAMES, so a
+     *  key on several rules gets the MAXIMUM authority over them, never the
+     *  intersection. A key that also sits on a rule with no policy is therefore
+     *  unconstrained: it names that rule and the new predicate never runs.
+     *
+     *  Default-deny, and only for the case the scan can PROVE - an unpoliced
+     *  neighbour sharing signers and selectors. A neighbour carrying a policy
+     *  this tool cannot decode stays advisory, because "cannot decode" is not
+     *  "proved unsafe" and refusing it would block installs on a guess. */
+    allowAuthorityOverlap: zod_1.z.boolean().optional(),
     /** Opt-in to pointing the rule's interpreter policy at any address
      *  other than the pinned interpreter for the selected network.
      *  Default-deny: a caller that controls the interpreter can permit
@@ -676,16 +715,12 @@ exports.InstallPolicyInputSchema = zod_1.z
 exports.RevokePolicyInputSchema = zod_1.z
     .object({
     /** The smart account contract address (C...). */
-    smartAccount: zod_1.z
-        .string()
-        .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The wallet that will sign the removal. The ACCOUNT decides whether it
      *  accepts that signer; this schema does not assert a rule it cannot
      *  verify, since the account's source is not in this repo. Proven on
      *  testnet: the account's deployer can revoke. */
-    sourceAccount: zod_1.z
-        .string()
-        .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the revoke. Same `testnet`-default as install,
      *  so pre-mainnet callers keep working without an explicit flag. */
     network: exports.NetworkSchema.optional(),

package/package.json

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

@@ -182,12 +182,40 @@ export interface InstallCallDescribes {
   installNonce: number
 }
 
+/** `unsignedXdr` plus the length and digest that prove it arrived whole. */
+function xdrIntegrity(unsignedXdr: string): {
+  unsignedXdr: string
+  unsignedXdrLength: number
+  unsignedXdrSha256: string
+} {
+  return {
+    unsignedXdr,
+    unsignedXdrLength: unsignedXdr.length,
+    unsignedXdrSha256: createHash('sha256').update(unsignedXdr, 'utf8').digest('hex'),
+  }
+}
+
 /** Output of the install-policy build. The unsigned XDR is the wallet's
  *  input; the captured auth nonce + invocation root make the response
  *  self-describing for callers that want to inspect what they signed. */
 export interface BuildInstallPolicyResult {
   /** Unsigned Soroban transaction envelope, base64 XDR. */
   unsignedXdr: string
+  /** Length and SHA-256 of `unsignedXdr`, so a caller that has to move it can
+   *  prove it arrived whole.
+   *
+   *  This envelope runs to several thousand characters, and the only route
+   *  from a tool result onto disk is the caller re-emitting it. A truncated
+   *  copy is not obviously wrong - it fails later as
+   *  "failed to decode XDR: xdr value invalid", which reads like a malformed
+   *  transaction rather than a transport problem. Observed in practice: one of
+   *  two envelopes written in the same session lost its tail and its base64
+   *  length went from a multiple of four to `len % 4 == 3`.
+   *
+   *  Check both before signing. They are cheap, and they turn a silent,
+   *  fatal truncation into a retry. */
+  unsignedXdrLength: number
+  unsignedXdrSha256: string
   /** Smart account contract address (echo). */
   smartAccount: string
   /** Source account (echo) - the address that must sign. */
@@ -258,7 +286,7 @@ export async function buildInstallPolicyXdr(
   const describes = decodeInstallCallDescribes(finalTx, args.installNonce)
 
   return {
-    unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+    ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
     smartAccount: args.smartAccount,
     sourceAccount: args.sourceAccount,
     call: { contract: args.smartAccount, fn: 'add_context_rule' },
@@ -302,7 +330,7 @@ export async function buildRevokePolicyXdr(args: {
   )
 
   return {
-    unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+    ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
     smartAccount: args.smartAccount,
     sourceAccount: args.sourceAccount,
     call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },
@@ -314,6 +342,11 @@ export async function buildRevokePolicyXdr(args: {
 
 export interface BuildRevokePolicyResult {
   unsignedXdr: string
+  /** Same integrity pair as the install result, for the same reason: a revoke
+   *  envelope also has to reach a signer intact, and a truncated copy fails as
+   *  a malformed transaction rather than as a transport error. */
+  unsignedXdrLength: number
+  unsignedXdrSha256: string
   smartAccount: string
   sourceAccount: string
   call: { contract: string; fn: 'remove_context_rule'; ruleId: number }

package/src/run/index.ts

@@ -18,6 +18,7 @@
 // drive the CLI (which calls into the same core directly without MCP).
 
 import { createHash } from 'node:crypto'
+import { readFile, rename, rm, writeFile } from 'node:fs/promises'
 import { rpc } from '@stellar/stellar-sdk'
 import { PLACEHOLDER_INTERPRETER_ADDRESS } from '../adapters/interpreter/adapter.ts'
 import {
@@ -236,6 +237,30 @@ export async function runSynthesizePolicy(raw: unknown): Promise<
   }
 }
 
+/** The refusal message for an install the cross-rule scan proves cannot bind,
+ *  or `undefined` when the install may proceed.
+ *
+ *  Only `bypass` refuses. That class means the neighbouring rule carries NO
+ *  policy, so a shared signer names it and the new predicate never runs - a
+ *  proof, from data already in hand, that the rule constrains nothing.
+ *  `unknown` (a neighbour policed by a contract this tool cannot decode) stays
+ *  advisory: it may well be tighter, and refusing on "cannot decode" would
+ *  block installs on a guess. A `null` scan is NOT CHECKED, which is not
+ *  evidence of a bypass and must not refuse on its own.
+ *
+ *  Separated from the tool body so the decision can be tested without a
+ *  network: the install it guards cannot be built without one. */
+export function authorityBypassRefusal(
+  scan: AuthorityOverlap[] | null,
+  allowAuthorityOverlap: boolean | undefined
+): string | undefined {
+  if (scan === null || allowAuthorityOverlap === true) return undefined
+  const proven = scan.filter((o) => o.severity === 'bypass')
+  if (proven.length === 0) return undefined
+  const ids = proven.map((o) => o.ruleId).join(', ')
+  return `install_policy: ${proven[0]?.advice ?? ''} This rule would install cleanly and constrain nothing, so it is refused (rule ${ids}); remove the shared signer from that rule, attach a policy to it, or set \`allowAuthorityOverlap: true\` to install anyway.`
+}
+
 export async function runInstallPolicy(
   raw: unknown
 ): Promise<ToolResponse<BuildInstallPolicyResult & { authorityScan: AuthorityOverlap[] | null }>> {
@@ -453,7 +478,54 @@ export async function runInstallPolicy(
             },
             existing: observed,
           })
-    return { ok: true, data: { ...result, authorityScan } }
+    // A `bypass` overlap is not a warning, it is a proof that this rule cannot
+    // bind the key it names: the neighbour carries NO policy, so the signer
+    // names that rule instead and the predicate never runs. Returning `ok` with
+    // the finding buried in `authorityScan` puts the whole protection on the
+    // caller reading a field, and the caller here is usually an agent that
+    // checks whether the call succeeded. Refuse, and let the caller opt in.
+    //
+    // Only the provable class. `unknown` - a neighbour whose policy this tool
+    // cannot decode - stays advisory: it may well be tighter, and refusing on
+    // "cannot decode" would block installs on a guess.
+    const bypassRefusal = authorityBypassRefusal(authorityScan, input.allowAuthorityOverlap)
+    if (bypassRefusal !== undefined) {
+      return {
+        ok: false,
+        error: {
+          code: 'INSTALL_BUILD_FAILED',
+          message: bypassRefusal,
+          severity: 'error',
+          retryable: false,
+          remediation: { toolCall: { name: 'install_policy', args: {} } },
+        },
+      }
+    }
+    // Write the envelope here when asked, so it never travels through the
+    // caller. `writtenTo` is what the caller should hand to a signer.
+    let writtenTo: string | undefined
+    if (input.outPath !== undefined) {
+      // Write beside the target and rename, which is atomic within a
+      // filesystem. A plain write truncates first, so anything watching the
+      // directory - a signer picking up envelopes is the obvious case - can
+      // read a half-written file and report a malformed TRANSACTION. With a
+      // rename the path either does not exist or holds the whole envelope.
+      const staging = `${input.outPath}.partial`
+      await writeFile(staging, result.unsignedXdr, 'utf8')
+      const readBack = await readFile(staging, 'utf8')
+      if (readBack !== result.unsignedXdr) {
+        await rm(staging, { force: true })
+        throw new Error(
+          `outPath: wrote ${result.unsignedXdr.length} characters to ${input.outPath} but read back ${readBack.length}; the file was not persisted intact`
+        )
+      }
+      await rename(staging, input.outPath)
+      writtenTo = input.outPath
+    }
+    return {
+      ok: true,
+      data: { ...result, authorityScan, ...(writtenTo !== undefined ? { writtenTo } : {}) },
+    }
   } catch (e) {
     return toolFailure('install_policy', e)
   }

package/src/run/schemas.ts

@@ -15,6 +15,7 @@
 // imports them here so its tool-shape bindings stay in step; the CLI imports
 // them here so it can build the same args envelope the MCP transport builds.
 
+import { StrKey } from '@stellar/stellar-sdk'
 import { z } from 'zod'
 import { isStellarAddress } from '../synth/address.ts'
 
@@ -550,6 +551,29 @@ export const NETWORK_PASSPHRASES: Record<Network, string> = {
 const STELLAR_CONTRACT_ADDRESS = /^C[2-7A-Z]{55}$/
 const STELLAR_ACCOUNT_ADDRESS = /^G[2-7A-Z]{55}$/
 
+// The regexes above check SHAPE only. A wrong-but-well-formed address - the
+// classic case being one an agent reproduced from memory - passes them and then
+// fails the SDK's StrKey decoder deep inside the build, where the throw is
+// caught by the tool envelope and reported as a bare "invalid checksum" naming
+// no field. A caller holding several addresses then cannot tell which one is
+// wrong. Validating the checksum HERE keeps the field name attached.
+const contractAddress = (field: string) =>
+  z
+    .string()
+    .regex(STELLAR_CONTRACT_ADDRESS, `${field} must be a Stellar contract address (C...)`)
+    .refine(
+      StrKey.isValidContract,
+      `${field} is not a valid contract address: the checksum does not match, so this address does not exist`
+    )
+const accountAddress = (field: string) =>
+  z
+    .string()
+    .regex(STELLAR_ACCOUNT_ADDRESS, `${field} must be a Stellar account address (G...)`)
+    .refine(
+      StrKey.isValidEd25519PublicKey,
+      `${field} is not a valid account address: the checksum does not match, so this address does not exist`
+    )
+
 // ===== declare_policy =====
 //
 // The declarative front-end: the constraint stated outright, with no
@@ -613,14 +637,10 @@ export const InstallPolicyInputSchema = z
      *  result says so rather than reporting "no overlaps found". */
     existingRules: z.array(ObservedRuleSchema).optional(),
     /** The smart account contract address (C...) that will receive the rule. */
-    smartAccount: z
-      .string()
-      .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The signer that authorises the install (G... wallet). Used only for
      *  sequence number + auth nonce simulation; never persisted, never signed. */
-    sourceAccount: z
-      .string()
-      .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the install. Selects which interpreter pin and
      *  which RPC URL are valid by default. Defaults to `testnet` so the
      *  pre-mainnet callers keep working: they were always pointing at
@@ -693,6 +713,22 @@ export const InstallPolicyInputSchema = z
      *  knows. Supply it only to re-install over an existing rule, where the
      *  interpreter wants `stored_nonce + 1`. */
     installNonce: z.number().int().positive().optional(),
+    /** Absolute path to write the unsigned envelope to.
+     *
+     *  The envelope runs to several thousand characters, and without this the
+     *  only route onto disk is the CALLER re-emitting it - through a model, a
+     *  shell argument, or both. That transport mangles it: observed in practice
+     *  as a file of the right length whose bytes no longer parse
+     *  ("xdr padding contains non-zero bytes"), and as silent truncation.
+     *  Writing it here takes the caller out of the transport entirely.
+     *
+     *  Opt-in: omitted, nothing is written and behaviour is unchanged. */
+    outPath: z
+      .string()
+      .min(1)
+      .refine((p) => p.startsWith('/'), 'outPath must be an absolute path')
+      .refine((p) => !p.includes('\0'), 'outPath must not contain a null byte')
+      .optional(),
     /** Optional RPC URL override. Defaults to the pinned RPC for the
      *  selected `network` (testnet by default, mainnet when
      *  `network: 'mainnet'`); the override is refused unless
@@ -736,6 +772,18 @@ export const InstallPolicyInputSchema = z
      *  unaffected; only the case the synthesizer explicitly flagged is
      *  refused. */
     allowUnboundedAmount: z.boolean().optional(),
+    /** Opt-in to installing a rule that the cross-rule scan proves cannot bind.
+     *
+     *  An OZ account resolves a call against the rule the caller NAMES, so a
+     *  key on several rules gets the MAXIMUM authority over them, never the
+     *  intersection. A key that also sits on a rule with no policy is therefore
+     *  unconstrained: it names that rule and the new predicate never runs.
+     *
+     *  Default-deny, and only for the case the scan can PROVE - an unpoliced
+     *  neighbour sharing signers and selectors. A neighbour carrying a policy
+     *  this tool cannot decode stays advisory, because "cannot decode" is not
+     *  "proved unsafe" and refusing it would block installs on a guess. */
+    allowAuthorityOverlap: z.boolean().optional(),
     /** Opt-in to pointing the rule's interpreter policy at any address
      *  other than the pinned interpreter for the selected network.
      *  Default-deny: a caller that controls the interpreter can permit
@@ -760,16 +808,12 @@ export type InstallPolicyInput = z.infer<typeof InstallPolicyInputSchema>
 export const RevokePolicyInputSchema = z
   .object({
     /** The smart account contract address (C...). */
-    smartAccount: z
-      .string()
-      .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The wallet that will sign the removal. The ACCOUNT decides whether it
      *  accepts that signer; this schema does not assert a rule it cannot
      *  verify, since the account's source is not in this repo. Proven on
      *  testnet: the account's deployer can revoke. */
-    sourceAccount: z
-      .string()
-      .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the revoke. Same `testnet`-default as install,
      *  so pre-mainnet callers keep working without an explicit flag. */
     network: NetworkSchema.optional(),