@crediolabs/policy-synth 0.5.2 → 0.5.4

package/dist/review-card/builder.js

@@ -107,12 +107,33 @@ function leftArgLabel(leaf) {
 }
 /** Render ONE constraint sentence for ONE interpreter predicate node. The
  *  shape of the output is pinned by Task 7b so the test suite can assert
- *  byte-for-byte equality. Returns `null` when the node is a structural
- *  boolean (`and`) - that is not a constraint leaf. */
+ *  byte-for-byte equality. Returns `null` only when a node's shape cannot be
+ *  rendered at all. */
 function renderConstraint(node) {
     switch (node.op) {
-        case 'and':
-            return null;
+        case 'and': {
+            // Reached ONLY when an `and` sits BENEATH an `or`: `walkPredicate`
+            // descends into a top-level `and` and never calls this on one.
+            //
+            // This used to return null, on the reasoning that `and` is structural
+            // rather than a constraint leaf. That is true for the walk path and
+            // false for this one, and the combination silently dropped real
+            // policies: `or(and, and)` is the natural shape of a policy with
+            // alternative permitted forms - one conjunction of pins per branch -
+            // so the `or` case below always saw null children and withheld the
+            // entire disjunction. `describePredicate` then returned an EMPTY list
+            // for a restrictive policy, which any caller renders as "no
+            // constraints".
+            //
+            // That inverts the very guard it was protecting: the `or` case
+            // withholds to avoid reading STRICTER than reality, but withholding
+            // the only line reads as UNRESTRICTED, which is far worse. Compose
+            // instead, and keep the withhold for genuinely unrenderable children.
+            const parts = node.children.map(renderConstraint);
+            if (parts.some((p) => p === null))
+                return null;
+            return parts.join(' and ');
+        }
         case 'or': {
             // One line for the whole disjunction. If any branch is a shape the
             // card cannot render, the entire line is withheld rather than shown

package/dist/synth/compose-from-recording.d.ts

@@ -20,6 +20,10 @@ export interface ComposeUserResponses {
 export interface ComposeOptions {
     network: Network;
     userResponses?: ComposeUserResponses;
+    /** The smart account this rule will be installed on, when known. Used only
+     *  to detect self-scope (see the warning below `scopeContract` is set) -
+     *  composition proceeds identically when this is omitted. */
+    smartAccountAddress?: string;
 }
 /** One composed rule: what the call must be scoped to, the constraints on it,
  *  and how long the resulting context rule lives. The constraints are already

package/dist/synth/compose-from-recording.js

@@ -2,9 +2,12 @@
 //
 // Fail-closed composition rules:
 //   - unknown top-level protocol (registry.identifyProtocol returns null) ->
-//     emit no constraint from the spend; scope is kept (contract + method) and
-//     every inferred bound surfaces as a descriptive warning. An unrecognised
-//     call never compiles to a permissive policy.
+//     no ABI means no argument can be singled out by role (recipient, spender,
+//     etc.), so a spend is never capped and no argument is guessed at; every
+//     address argument the call actually carries is pinned to its observed
+//     value instead (AC-33.19), and every other inferred bound surfaces as a
+//     descriptive warning. An unrecognised call never compiles to a
+//     permissive policy.
 //   - a spend cap is emitted ONLY when the caller supplies `limitAmount` AND
 //     the call carries an amount argument to bind it to. A single recorded
 //     spend does NOT authorise that amount on every call, so the observed
@@ -80,9 +83,8 @@ export function composeFromRecording(facts, scopeContract, topLevel, opts) {
         }
     }
     // Observed recipient allowlist (SEP-41) is a real, recorded constraint the
-    // interpreter adapter lowers to an `in` predicate. Unknown protocols emit
-    // nothing here. SoroSwap's swap recipient (arg[3]) is the source-of-truth for
-    // the swapRecipientAllowlist surface.
+    // interpreter adapter lowers to an `in` predicate. SoroSwap's swap recipient
+    // (arg[3]) is the source-of-truth for the swapRecipientAllowlist surface.
     if (topLevel && protocol !== null) {
         // A SoroSwap input-amount cap binds the caller's limitAmount to the swap's
         // input-amount argument ONLY when no outgoing spend was detected for the
@@ -93,6 +95,41 @@ export function composeFromRecording(facts, scopeContract, topLevel, opts) {
         const swapInputAmountCap = spendTokens.length === 0 ? limitAmount : undefined;
         appendProtocolSpecificConstraints(interpreterConstraints, warnings, ambiguities, facts, topLevel, protocol, opts.userResponses?.swapRecipientAllowlist, swapInputAmountCap);
     }
+    else if (topLevel && protocol === null) {
+        // Unrecognised protocol: there is no published ABI, so no argument can be
+        // singled out as THE recipient - guessing an index risks pinning the
+        // wrong value (false security) or a value that means something else
+        // entirely for a different contract sharing the same shape. What the
+        // recording DOES evidence, without any interpretation, is every address
+        // literally carried by the call. AC-33.19: a value the recording
+        // evidences is pinned by default, never left open because its semantic
+        // role is unrecognised - so every address argument is pinned to its
+        // observed value, not just the one a known ABI would call "to".
+        const addressArgIndexes = topLevel.args.flatMap((arg, i) => (arg.type === 'address' ? [i] : []));
+        if (addressArgIndexes.length > 0) {
+            for (const i of addressArgIndexes) {
+                const arg = topLevel.args[i];
+                if (arg?.type !== 'address')
+                    continue;
+                interpreterConstraints.push({
+                    op: 'in',
+                    needle: { kind: 'call_arg', index: i },
+                    haystack: [{ kind: 'literal_address', value: arg.value }],
+                });
+            }
+            warnings.push(`unrecognised protocol: every address argument observed in the call (index ${addressArgIndexes.join(', ')}) was pinned to its recorded value - the ABI is unknown, so no single argument could be identified as the recipient specifically; read this pin with less confidence than a recognised protocol's`);
+        }
+    }
+    // Self-scope: a rule whose scope targets the smart account that will hold
+    // it lets the account authorise calls against its own governance surface
+    // (e.g. a recorded batch_add_signer against the account itself). Such a
+    // rule installs cleanly and then denies every OTHER call with OZ error
+    // #3002, bricking the account. Detected only when the caller supplies
+    // smartAccountAddress; without it the composer has nothing to compare
+    // scopeContract against, so composition proceeds unchanged.
+    if (opts.smartAccountAddress !== undefined && scopeContract === opts.smartAccountAddress) {
+        warnings.push(`scope.contract (${scopeContract}) is the smart account's own address: a rule scoping ${topLevel?.fn ?? 'this call'} to the account that will hold it lets the account govern its own governance surface, and denies every other call with OZ error #3002 once installed`);
+    }
     // The interpreter adapter lowers `scope.method` into a `call_fn == <method>`
     // predicate leaf.
     const scope = { contract: scopeContract };

package/dist/synth/synthesize-from-recording.js

@@ -148,6 +148,9 @@ function synthesizeFromRecordingInner(tx, opts) {
     const composeOpts = {
         network: opts.network,
         ...(opts.userResponses !== undefined ? { userResponses: opts.userResponses } : {}),
+        ...(opts.interpreter?.smartAccountAddress !== undefined
+            ? { smartAccountAddress: opts.interpreter.smartAccountAddress }
+            : {}),
     };
     const composed = composeFromRecording(facts, scope.contract, topLevel, composeOpts);
     // --explain hook: capture the in-memory predicate tree + the real

package/dist-cjs/review-card/builder.js

@@ -111,12 +111,33 @@ function leftArgLabel(leaf) {
 }
 /** Render ONE constraint sentence for ONE interpreter predicate node. The
  *  shape of the output is pinned by Task 7b so the test suite can assert
- *  byte-for-byte equality. Returns `null` when the node is a structural
- *  boolean (`and`) - that is not a constraint leaf. */
+ *  byte-for-byte equality. Returns `null` only when a node's shape cannot be
+ *  rendered at all. */
 function renderConstraint(node) {
     switch (node.op) {
-        case 'and':
-            return null;
+        case 'and': {
+            // Reached ONLY when an `and` sits BENEATH an `or`: `walkPredicate`
+            // descends into a top-level `and` and never calls this on one.
+            //
+            // This used to return null, on the reasoning that `and` is structural
+            // rather than a constraint leaf. That is true for the walk path and
+            // false for this one, and the combination silently dropped real
+            // policies: `or(and, and)` is the natural shape of a policy with
+            // alternative permitted forms - one conjunction of pins per branch -
+            // so the `or` case below always saw null children and withheld the
+            // entire disjunction. `describePredicate` then returned an EMPTY list
+            // for a restrictive policy, which any caller renders as "no
+            // constraints".
+            //
+            // That inverts the very guard it was protecting: the `or` case
+            // withholds to avoid reading STRICTER than reality, but withholding
+            // the only line reads as UNRESTRICTED, which is far worse. Compose
+            // instead, and keep the withhold for genuinely unrenderable children.
+            const parts = node.children.map(renderConstraint);
+            if (parts.some((p) => p === null))
+                return null;
+            return parts.join(' and ');
+        }
         case 'or': {
             // One line for the whole disjunction. If any branch is a shape the
             // card cannot render, the entire line is withheld rather than shown

package/dist-cjs/synth/compose-from-recording.d.ts

@@ -20,6 +20,10 @@ export interface ComposeUserResponses {
 export interface ComposeOptions {
     network: Network;
     userResponses?: ComposeUserResponses;
+    /** The smart account this rule will be installed on, when known. Used only
+     *  to detect self-scope (see the warning below `scopeContract` is set) -
+     *  composition proceeds identically when this is omitted. */
+    smartAccountAddress?: string;
 }
 /** One composed rule: what the call must be scoped to, the constraints on it,
  *  and how long the resulting context rule lives. The constraints are already

package/dist-cjs/synth/compose-from-recording.js

@@ -3,9 +3,12 @@
 //
 // Fail-closed composition rules:
 //   - unknown top-level protocol (registry.identifyProtocol returns null) ->
-//     emit no constraint from the spend; scope is kept (contract + method) and
-//     every inferred bound surfaces as a descriptive warning. An unrecognised
-//     call never compiles to a permissive policy.
+//     no ABI means no argument can be singled out by role (recipient, spender,
+//     etc.), so a spend is never capped and no argument is guessed at; every
+//     address argument the call actually carries is pinned to its observed
+//     value instead (AC-33.19), and every other inferred bound surfaces as a
+//     descriptive warning. An unrecognised call never compiles to a
+//     permissive policy.
 //   - a spend cap is emitted ONLY when the caller supplies `limitAmount` AND
 //     the call carries an amount argument to bind it to. A single recorded
 //     spend does NOT authorise that amount on every call, so the observed
@@ -83,9 +86,8 @@ function composeFromRecording(facts, scopeContract, topLevel, opts) {
         }
     }
     // Observed recipient allowlist (SEP-41) is a real, recorded constraint the
-    // interpreter adapter lowers to an `in` predicate. Unknown protocols emit
-    // nothing here. SoroSwap's swap recipient (arg[3]) is the source-of-truth for
-    // the swapRecipientAllowlist surface.
+    // interpreter adapter lowers to an `in` predicate. SoroSwap's swap recipient
+    // (arg[3]) is the source-of-truth for the swapRecipientAllowlist surface.
     if (topLevel && protocol !== null) {
         // A SoroSwap input-amount cap binds the caller's limitAmount to the swap's
         // input-amount argument ONLY when no outgoing spend was detected for the
@@ -96,6 +98,41 @@ function composeFromRecording(facts, scopeContract, topLevel, opts) {
         const swapInputAmountCap = spendTokens.length === 0 ? limitAmount : undefined;
         appendProtocolSpecificConstraints(interpreterConstraints, warnings, ambiguities, facts, topLevel, protocol, opts.userResponses?.swapRecipientAllowlist, swapInputAmountCap);
     }
+    else if (topLevel && protocol === null) {
+        // Unrecognised protocol: there is no published ABI, so no argument can be
+        // singled out as THE recipient - guessing an index risks pinning the
+        // wrong value (false security) or a value that means something else
+        // entirely for a different contract sharing the same shape. What the
+        // recording DOES evidence, without any interpretation, is every address
+        // literally carried by the call. AC-33.19: a value the recording
+        // evidences is pinned by default, never left open because its semantic
+        // role is unrecognised - so every address argument is pinned to its
+        // observed value, not just the one a known ABI would call "to".
+        const addressArgIndexes = topLevel.args.flatMap((arg, i) => (arg.type === 'address' ? [i] : []));
+        if (addressArgIndexes.length > 0) {
+            for (const i of addressArgIndexes) {
+                const arg = topLevel.args[i];
+                if (arg?.type !== 'address')
+                    continue;
+                interpreterConstraints.push({
+                    op: 'in',
+                    needle: { kind: 'call_arg', index: i },
+                    haystack: [{ kind: 'literal_address', value: arg.value }],
+                });
+            }
+            warnings.push(`unrecognised protocol: every address argument observed in the call (index ${addressArgIndexes.join(', ')}) was pinned to its recorded value - the ABI is unknown, so no single argument could be identified as the recipient specifically; read this pin with less confidence than a recognised protocol's`);
+        }
+    }
+    // Self-scope: a rule whose scope targets the smart account that will hold
+    // it lets the account authorise calls against its own governance surface
+    // (e.g. a recorded batch_add_signer against the account itself). Such a
+    // rule installs cleanly and then denies every OTHER call with OZ error
+    // #3002, bricking the account. Detected only when the caller supplies
+    // smartAccountAddress; without it the composer has nothing to compare
+    // scopeContract against, so composition proceeds unchanged.
+    if (opts.smartAccountAddress !== undefined && scopeContract === opts.smartAccountAddress) {
+        warnings.push(`scope.contract (${scopeContract}) is the smart account's own address: a rule scoping ${topLevel?.fn ?? 'this call'} to the account that will hold it lets the account govern its own governance surface, and denies every other call with OZ error #3002 once installed`);
+    }
     // The interpreter adapter lowers `scope.method` into a `call_fn == <method>`
     // predicate leaf.
     const scope = { contract: scopeContract };

package/dist-cjs/synth/synthesize-from-recording.js

@@ -152,6 +152,9 @@ function synthesizeFromRecordingInner(tx, opts) {
     const composeOpts = {
         network: opts.network,
         ...(opts.userResponses !== undefined ? { userResponses: opts.userResponses } : {}),
+        ...(opts.interpreter?.smartAccountAddress !== undefined
+            ? { smartAccountAddress: opts.interpreter.smartAccountAddress }
+            : {}),
     };
     const composed = (0, compose_from_recording_ts_1.composeFromRecording)(facts, scope.contract, topLevel, composeOpts);
     // --explain hook: capture the in-memory predicate tree + the real

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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/review-card/builder.ts

@@ -134,12 +134,32 @@ function leftArgLabel(leaf: PredicateLeaf): string {
 
 /** Render ONE constraint sentence for ONE interpreter predicate node. The
  *  shape of the output is pinned by Task 7b so the test suite can assert
- *  byte-for-byte equality. Returns `null` when the node is a structural
- *  boolean (`and`) - that is not a constraint leaf. */
+ *  byte-for-byte equality. Returns `null` only when a node's shape cannot be
+ *  rendered at all. */
 function renderConstraint(node: PredicateNode): string | null {
   switch (node.op) {
-    case 'and':
-      return null
+    case 'and': {
+      // Reached ONLY when an `and` sits BENEATH an `or`: `walkPredicate`
+      // descends into a top-level `and` and never calls this on one.
+      //
+      // This used to return null, on the reasoning that `and` is structural
+      // rather than a constraint leaf. That is true for the walk path and
+      // false for this one, and the combination silently dropped real
+      // policies: `or(and, and)` is the natural shape of a policy with
+      // alternative permitted forms - one conjunction of pins per branch -
+      // so the `or` case below always saw null children and withheld the
+      // entire disjunction. `describePredicate` then returned an EMPTY list
+      // for a restrictive policy, which any caller renders as "no
+      // constraints".
+      //
+      // That inverts the very guard it was protecting: the `or` case
+      // withholds to avoid reading STRICTER than reality, but withholding
+      // the only line reads as UNRESTRICTED, which is far worse. Compose
+      // instead, and keep the withhold for genuinely unrenderable children.
+      const parts = node.children.map(renderConstraint)
+      if (parts.some((p) => p === null)) return null
+      return parts.join(' and ')
+    }
     case 'or': {
       // One line for the whole disjunction. If any branch is a shape the
       // card cannot render, the entire line is withheld rather than shown

package/src/synth/compose-from-recording.ts

@@ -2,9 +2,12 @@
 //
 // Fail-closed composition rules:
 //   - unknown top-level protocol (registry.identifyProtocol returns null) ->
-//     emit no constraint from the spend; scope is kept (contract + method) and
-//     every inferred bound surfaces as a descriptive warning. An unrecognised
-//     call never compiles to a permissive policy.
+//     no ABI means no argument can be singled out by role (recipient, spender,
+//     etc.), so a spend is never capped and no argument is guessed at; every
+//     address argument the call actually carries is pinned to its observed
+//     value instead (AC-33.19), and every other inferred bound surfaces as a
+//     descriptive warning. An unrecognised call never compiles to a
+//     permissive policy.
 //   - a spend cap is emitted ONLY when the caller supplies `limitAmount` AND
 //     the call carries an amount argument to bind it to. A single recorded
 //     spend does NOT authorise that amount on every call, so the observed
@@ -43,6 +46,10 @@ export interface ComposeUserResponses {
 export interface ComposeOptions {
   network: Network
   userResponses?: ComposeUserResponses
+  /** The smart account this rule will be installed on, when known. Used only
+   *  to detect self-scope (see the warning below `scopeContract` is set) -
+   *  composition proceeds identically when this is omitted. */
+  smartAccountAddress?: string
 }
 
 /** One composed rule: what the call must be scoped to, the constraints on it,
@@ -145,9 +152,8 @@ export function composeFromRecording(
   }
 
   // Observed recipient allowlist (SEP-41) is a real, recorded constraint the
-  // interpreter adapter lowers to an `in` predicate. Unknown protocols emit
-  // nothing here. SoroSwap's swap recipient (arg[3]) is the source-of-truth for
-  // the swapRecipientAllowlist surface.
+  // interpreter adapter lowers to an `in` predicate. SoroSwap's swap recipient
+  // (arg[3]) is the source-of-truth for the swapRecipientAllowlist surface.
   if (topLevel && protocol !== null) {
     // A SoroSwap input-amount cap binds the caller's limitAmount to the swap's
     // input-amount argument ONLY when no outgoing spend was detected for the
@@ -166,6 +172,44 @@ export function composeFromRecording(
       opts.userResponses?.swapRecipientAllowlist,
       swapInputAmountCap
     )
+  } else if (topLevel && protocol === null) {
+    // Unrecognised protocol: there is no published ABI, so no argument can be
+    // singled out as THE recipient - guessing an index risks pinning the
+    // wrong value (false security) or a value that means something else
+    // entirely for a different contract sharing the same shape. What the
+    // recording DOES evidence, without any interpretation, is every address
+    // literally carried by the call. AC-33.19: a value the recording
+    // evidences is pinned by default, never left open because its semantic
+    // role is unrecognised - so every address argument is pinned to its
+    // observed value, not just the one a known ABI would call "to".
+    const addressArgIndexes = topLevel.args.flatMap((arg, i) => (arg.type === 'address' ? [i] : []))
+    if (addressArgIndexes.length > 0) {
+      for (const i of addressArgIndexes) {
+        const arg = topLevel.args[i]
+        if (arg?.type !== 'address') continue
+        interpreterConstraints.push({
+          op: 'in',
+          needle: { kind: 'call_arg', index: i },
+          haystack: [{ kind: 'literal_address', value: arg.value }],
+        })
+      }
+      warnings.push(
+        `unrecognised protocol: every address argument observed in the call (index ${addressArgIndexes.join(', ')}) was pinned to its recorded value - the ABI is unknown, so no single argument could be identified as the recipient specifically; read this pin with less confidence than a recognised protocol's`
+      )
+    }
+  }
+
+  // Self-scope: a rule whose scope targets the smart account that will hold
+  // it lets the account authorise calls against its own governance surface
+  // (e.g. a recorded batch_add_signer against the account itself). Such a
+  // rule installs cleanly and then denies every OTHER call with OZ error
+  // #3002, bricking the account. Detected only when the caller supplies
+  // smartAccountAddress; without it the composer has nothing to compare
+  // scopeContract against, so composition proceeds unchanged.
+  if (opts.smartAccountAddress !== undefined && scopeContract === opts.smartAccountAddress) {
+    warnings.push(
+      `scope.contract (${scopeContract}) is the smart account's own address: a rule scoping ${topLevel?.fn ?? 'this call'} to the account that will hold it lets the account govern its own governance surface, and denies every other call with OZ error #3002 once installed`
+    )
   }
 
   // The interpreter adapter lowers `scope.method` into a `call_fn == <method>`

package/src/synth/synthesize-from-recording.ts

@@ -234,6 +234,9 @@ function synthesizeFromRecordingInner(
   const composeOpts: ComposeOptions = {
     network: opts.network,
     ...(opts.userResponses !== undefined ? { userResponses: opts.userResponses } : {}),
+    ...(opts.interpreter?.smartAccountAddress !== undefined
+      ? { smartAccountAddress: opts.interpreter.smartAccountAddress }
+      : {}),
   }
   const composed = composeFromRecording(facts, scope.contract, topLevel, composeOpts)