@crediolabs/policy-synth 1.1.1 → 1.2.0

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

@@ -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,9 +4257,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;
 }>;

package/dist/run/schemas.js

@@ -623,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
@@ -666,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

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

@@ -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,9 +4257,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;
 }>;

package/dist-cjs/run/schemas.js

@@ -626,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
@@ -669,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

package/package.json

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

@@ -713,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
@@ -756,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