@crediolabs/policy-synth 0.3.1 → 0.4.0

package/src/run/index.ts

@@ -20,7 +20,9 @@
 import { createHash } from 'node:crypto'
 import { rpc } from '@stellar/stellar-sdk'
 import {
+  declarePredicate,
   type ErrorCode,
+  encodePredicate,
   type Network,
   type PredicateNode,
   type ProposedPolicy,
@@ -31,6 +33,11 @@ import {
   type ToolError,
   type ToolResponse,
 } from '../index.ts'
+import {
+  type AuthorityOverlap,
+  findAuthorityOverlaps,
+  type ObservedRule,
+} from '../install/authority-overlap.ts'
 import {
   type BuildInstallPolicyResult,
   type BuildRevokePolicyResult,
@@ -40,8 +47,10 @@ import {
   rpcClientFromServer,
 } from '../install/build-install-policy.ts'
 import { getInterpreterInfo } from '../install/get-interpreter-info.ts'
+import { decodePredicate } from '../predicate/decode.ts'
 import { type EvalContext, evaluate, generateCases } from '../simulate/index.ts'
 import {
+  DeclarePolicyInputSchema,
   type GetInterpreterInfoInput,
   GetInterpreterInfoInputSchema,
   type InstallPolicyInput,
@@ -64,6 +73,7 @@ import {
 } from './schemas.ts'
 
 export type {
+  DeclarePolicyInput,
   GetInterpreterInfoInput,
   InstallPolicyInput,
   RecordTransactionInput,
@@ -78,6 +88,7 @@ export type {
 // truth - MCP tool shapes are derived from them.
 export {
   ComposeUserResponsesSchema,
+  DeclarePolicyInputSchema,
   GetInterpreterInfoInputSchema,
   InstallPolicyInputSchema,
   InterpreterOptionsSchema,
@@ -107,6 +118,7 @@ export type RunVerifyPolicyInput = VerifyPolicyInput
 type RunToolName =
   | 'record_transaction'
   | 'synthesize_policy'
+  | 'declare_policy'
   | 'simulate_policy'
   | 'verify_policy'
   | 'install_policy'
@@ -119,6 +131,7 @@ type RunToolName =
 const TOOL_ERROR_CODE: Record<RunToolName, ErrorCode> = {
   record_transaction: 'RECORDING_FAILED',
   synthesize_policy: 'SYNTHESIS_ERROR',
+  declare_policy: 'SYNTHESIS_ERROR',
   simulate_policy: 'SIMULATION_ERROR',
   verify_policy: 'VERIFICATION_FAILED',
   install_policy: 'INSTALL_BUILD_FAILED',
@@ -203,7 +216,7 @@ export async function runSynthesizePolicy(raw: unknown): Promise<
 
 export async function runInstallPolicy(
   raw: unknown
-): Promise<ToolResponse<BuildInstallPolicyResult>> {
+): Promise<ToolResponse<BuildInstallPolicyResult & { authorityScan: AuthorityOverlap[] | null }>> {
   const parsed = InstallPolicyInputSchema.safeParse(raw)
   if (!parsed.success) {
     return { ok: false, error: validationError('install_policy', parsed.error.issues) }
@@ -254,7 +267,28 @@ export async function runInstallPolicy(
       rpc: rpcClient,
       ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
     })
-    return { ok: true, data: result }
+    // Cross-rule scan, when the caller supplied what else is on the account.
+    // ABSENT is reported as `null` rather than an empty list: "we did not
+    // look" and "we looked and found nothing" are different answers, and
+    // collapsing them would let a caller read silence as safety.
+    const authorityScan =
+      input.existingRules === undefined
+        ? null
+        : findAuthorityOverlaps({
+            intended: {
+              // `add_context_rule` gets its id FROM the account, so there is
+              // no existing rule this install replaces. A sentinel no real id
+              // can equal keeps every observed rule in scope.
+              ruleId: -1,
+              contextType: input.rule.contextRuleType,
+              signers: input.rule.signers,
+              predicate: decodePredicate(encodedPredicate),
+            },
+            // The schema types `predicate` loosely (it is the shared
+            // PredicateNodeSchema); the shape is already validated.
+            existing: input.existingRules as ObservedRule[],
+          })
+    return { ok: true, data: { ...result, authorityScan } }
   } catch (e) {
     return toolFailure('install_policy', e)
   }
@@ -384,6 +418,49 @@ export function runSimulatePolicy(raw: unknown): ToolResponse<{
   }
 }
 
+/** `declare_policy` body - the DECLARATIVE front-end.
+ *
+ *  `synthesize_policy` infers a predicate from a transaction that happened;
+ *  this takes the constraint stated outright. No RPC, no decoding and no
+ *  parseConfidence, so nothing here can be refused for a contract the registry
+ *  does not recognise - which is most of the point of having it.
+ *
+ *  The returned `warnings` are load-bearing, not decoration. An argument index
+ *  the caller did not supply is DEFAULTED to the SEP-41 position, and a bound
+ *  on the wrong argument constrains something the caller did not mean without
+ *  ever announcing itself, so a caller that ignores warnings can install a
+ *  predicate that reads correctly and binds nothing. */
+export function runDeclarePolicy(raw: unknown): ToolResponse<{
+  predicate: PredicateNode
+  encodedPredicate: string
+  predicateHash: string
+  warnings: string[]
+}> {
+  const parsed = DeclarePolicyInputSchema.safeParse(raw)
+  if (!parsed.success) {
+    return { ok: false, error: validationError('declare_policy', parsed.error.issues) }
+  }
+  try {
+    // Rebuilt field-by-field rather than passed through: the schema's
+    // optionals are `T | undefined` and `PolicyDeclaration`'s are absent-or-T,
+    // which `exactOptionalPropertyTypes` treats as different.
+    const d = parsed.data
+    const { predicate, warnings } = declarePredicate({
+      fn: d.fn,
+      ...(d.contract !== undefined ? { contract: d.contract } : {}),
+      ...(d.maxAmount !== undefined ? { maxAmount: d.maxAmount } : {}),
+      ...(d.amountArgIndex !== undefined ? { amountArgIndex: d.amountArgIndex } : {}),
+      ...(d.recipients !== undefined ? { recipients: d.recipients } : {}),
+      ...(d.recipientArgIndex !== undefined ? { recipientArgIndex: d.recipientArgIndex } : {}),
+      ...(d.allowZeroCap !== undefined ? { allowZeroCap: d.allowZeroCap } : {}),
+    })
+    const { encodedPredicate, predicateHash } = encodePredicate(predicate)
+    return { ok: true, data: { predicate, encodedPredicate, predicateHash, warnings } }
+  } catch (e) {
+    return toolFailure('declare_policy', e)
+  }
+}
+
 /** `verify_policy` body - the permit case plus a generated deny case per
  *  dimension.
  *

package/src/run/schemas.ts

@@ -281,6 +281,29 @@ export type VerifyPolicyInput = z.infer<typeof VerifyPolicyInputSchema>
 const MAX_SIGNERS_PER_RULE = 15
 const MAX_POLICIES_PER_RULE = 5
 
+const SignerDraftSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('delegated'), address: z.string() }),
+  z.object({ kind: z.literal('external'), verifier: z.string(), keyBytes: z.string() }),
+])
+
+const ContextTypeSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('default') }),
+  z.object({ kind: z.literal('call_contract'), contract: z.string() }),
+  z.object({ kind: z.literal('create_contract'), wasmHash: z.string() }),
+])
+
+/** A rule ALREADY on the account, as the caller observed it. Supplying these
+ *  turns on the cross-rule authority scan: a signer belonging to several rules
+ *  picks which one applies, so a predicate only constrains a key when the
+ *  policed rule is the only rule that key is on. */
+export const ObservedRuleSchema = z.object({
+  id: z.number().int().nonnegative(),
+  contextType: ContextTypeSchema,
+  signers: z.array(SignerDraftSchema),
+  policyAddresses: z.array(z.string()),
+  predicate: PredicateNodeSchema.optional(),
+})
+
 const ContextRuleDraftSchema = z
   .object({
     contextRuleType: z.discriminatedUnion('kind', [
@@ -391,8 +414,42 @@ 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}$/
 
+// ===== declare_policy =====
+//
+// The declarative front-end: the constraint stated outright, with no
+// transaction to decode. Deliberately NOT a revival of the removed
+// `MandateSpec` - that carried a rolling `spendingLimit` the interpreter
+// cannot evaluate and an `approvalThreshold` needing OZ primitives nobody
+// deployed. Only fields grammar 3 can actually enforce appear here.
+export const DeclarePolicyInputSchema = z
+  .object({
+    fn: z.string().min(1, 'fn must name the method to pin'),
+    contract: z
+      .string()
+      .regex(STELLAR_CONTRACT_ADDRESS, 'contract must be a Stellar contract address (C...)')
+      .optional(),
+    /** Smallest unit, unsigned decimal STRING - an i128 is wider than
+     *  Number.MAX_SAFE_INTEGER, so a number here would silently round. */
+    maxAmount: z
+      .string()
+      .regex(/^[0-9]+$/, 'maxAmount must be an unsigned integer in the smallest unit')
+      .optional(),
+    amountArgIndex: z.number().int().nonnegative().max(U32_MAX).optional(),
+    recipients: z.array(z.string()).min(1, 'recipients must not be empty').optional(),
+    recipientArgIndex: z.number().int().nonnegative().max(U32_MAX).optional(),
+    allowZeroCap: z.boolean().optional(),
+  })
+  .strict()
+export type DeclarePolicyInput = z.infer<typeof DeclarePolicyInputSchema>
+
 export const InstallPolicyInputSchema = z
   .object({
+    /** Rules already on the account. Supplying them turns on the cross-rule
+     *  authority scan, which reports every existing rule a signer of this
+     *  install could name INSTEAD - including an unpoliced one, against which
+     *  the predicate never runs. Absent means the scan is skipped, and the
+     *  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()

package/src/synth/declare.ts

@@ -0,0 +1,157 @@
+// src/synth/declare.ts - build a predicate from a DECLARED constraint.
+//
+// The second synthesis front-end, beside `synthesizeFromRecording`. That one
+// infers a predicate from a transaction that happened; this one takes the
+// constraint the user states outright. No transaction, no decoding, no
+// inference, no RPC: the same declaration always lowers to a byte-identical
+// predicate.
+//
+// This is the surviving half of the removed `MandateSpec`. Two of that type's
+// five fields lowered to things that do not exist - `spendingLimit` became a
+// `window_spent` compare the interpreter cannot evaluate (it is handed one
+// call and keeps no state), and `approvalThreshold` needed OZ built-in policy
+// contracts that were never deployed. Both are deliberately absent here, and
+// the per-call `maxAmount` bound below is the honest replacement for the
+// first: it constrains the amount in THIS call rather than implying a rolling
+// total nothing tracks.
+//
+// What a declaration can say maps one-to-one onto grammar 3:
+//   fn         -> eq(call_fn, literal_symbol)
+//   contract   -> eq(call_contract, literal_address)
+//   maxAmount  -> lte(call_arg(i), literal_i128)
+//   recipients -> in(call_arg(j), [literal_address, ...])
+
+import type { ToolError } from '../errors.ts'
+import type { PredicateLeaf, PredicateNode } from '../types.ts'
+import { isStellarAddress } from './address.ts'
+
+/** Argument positions of the SEP-41 `transfer(from, to, amount)` shape. A
+ *  declaration that names a different method almost certainly has different
+ *  positions, which is why using either default emits a warning naming the
+ *  index it assumed - a bound on the wrong argument constrains something the
+ *  user did not mean and fails silently. */
+const SEP41_RECIPIENT_ARG = 1
+const SEP41_AMOUNT_ARG = 2
+
+export interface PolicyDeclaration {
+  /** Method to pin. Required: a predicate with no selector leaf constrains
+   *  nothing and the contract refuses it at install. */
+  fn: string
+  /** Contract to pin, already resolved to a `C...` address. */
+  contract?: string
+  /** Upper bound on the call's amount argument, in the token's SMALLEST
+   *  unit as an unsigned decimal string (25 XLM = "250000000"). */
+  maxAmount?: string
+  /** Which argument carries the amount. Defaults to the SEP-41 position. */
+  amountArgIndex?: number
+  /** Recipient allowlist. */
+  recipients?: string[]
+  /** Which argument carries the recipient. Defaults to the SEP-41 position. */
+  recipientArgIndex?: number
+  /** A cap of "0" denies every call, so it is refused unless asked for
+   *  explicitly. A rule that permits nothing is a plausible thing to want and
+   *  an implausible thing to want by accident. */
+  allowZeroCap?: boolean
+}
+
+export interface DeclaredPredicate {
+  predicate: PredicateNode
+  /** Assumptions the caller should check. Never empty when an argument index
+   *  was defaulted rather than supplied. */
+  warnings: string[]
+}
+
+/** Lower a declared constraint to a grammar-3 predicate. Pure and total:
+ *  the same declaration always produces the same predicate. */
+export function declarePredicate(d: PolicyDeclaration): DeclaredPredicate {
+  if (!d.fn || d.fn.trim() === '') {
+    throw declareError('SYNTHESIS_ERROR', 'a declaration needs `fn`: the method to pin')
+  }
+  const warnings: string[] = []
+  const children: PredicateNode[] = [
+    { op: 'eq', left: { kind: 'call_fn' }, right: { kind: 'literal_symbol', value: d.fn } },
+  ]
+
+  if (d.contract !== undefined) {
+    if (!isStellarAddress(d.contract) || !d.contract.startsWith('C')) {
+      throw declareError(
+        'SYNTHESIS_ERROR',
+        `contract must be a Stellar contract address (C...), got ${d.contract}`
+      )
+    }
+    children.push({
+      op: 'eq',
+      left: { kind: 'call_contract' },
+      right: { kind: 'literal_address', value: d.contract },
+    })
+  }
+
+  if (d.recipients !== undefined) {
+    if (d.recipients.length === 0) {
+      throw declareError(
+        'SYNTHESIS_ERROR',
+        'recipients was supplied but empty; an empty `in` haystack is refused at decode. Omit it to leave recipients unconstrained.'
+      )
+    }
+    for (const r of d.recipients) {
+      if (!isStellarAddress(r)) {
+        throw declareError('SYNTHESIS_ERROR', `recipient is not a Stellar address: ${r}`)
+      }
+    }
+    const idx = d.recipientArgIndex ?? SEP41_RECIPIENT_ARG
+    if (d.recipientArgIndex === undefined) {
+      warnings.push(
+        `recipient allowlist bound to call_arg(${idx}), the SEP-41 \`transfer\` position. If \`${d.fn}\` carries the recipient elsewhere this constrains the wrong argument - pass recipientArgIndex.`
+      )
+    }
+    children.push({
+      op: 'in',
+      needle: { kind: 'call_arg', index: idx },
+      haystack: d.recipients.map((value): PredicateLeaf => ({ kind: 'literal_address', value })),
+    })
+  }
+
+  if (d.maxAmount !== undefined) {
+    if (!/^[0-9]+$/.test(d.maxAmount)) {
+      throw declareError(
+        'SYNTHESIS_ERROR',
+        `maxAmount must be an unsigned integer in the token's smallest unit, got "${d.maxAmount}" (25 XLM = "250000000")`
+      )
+    }
+    if (d.maxAmount === '0' && d.allowZeroCap !== true) {
+      throw declareError(
+        'SYNTHESIS_ERROR',
+        'maxAmount "0" denies every call: no amount satisfies the bound. Set allowZeroCap to declare that deliberately.'
+      )
+    }
+    const idx = d.amountArgIndex ?? SEP41_AMOUNT_ARG
+    if (d.amountArgIndex === undefined) {
+      warnings.push(
+        `amount cap bound to call_arg(${idx}), the SEP-41 \`transfer\` position. If \`${d.fn}\` carries the amount elsewhere this caps the wrong argument - pass amountArgIndex.`
+      )
+    }
+    children.push({
+      op: 'lte',
+      left: { kind: 'call_arg', index: idx },
+      right: { kind: 'literal_i128', value: d.maxAmount },
+    })
+  }
+
+  // A single conjunct is emitted bare. `and` with one child encodes to
+  // different bytes than the child alone, and the extra node buys nothing.
+  const predicate: PredicateNode =
+    children.length === 1 ? (children[0] as PredicateNode) : { op: 'and', children }
+  return { predicate, warnings }
+}
+
+function declareError(code: ToolError['code'], message: string): ToolError {
+  const err = new Error(message) as Error & {
+    code: ToolError['code']
+    severity: string
+    retryable: boolean
+  }
+  err.code = code
+  err.severity = 'error'
+  err.retryable = false
+  throw err
+}

package/src/synth/index.ts

@@ -9,6 +9,11 @@ export {
   type ComposeResult,
   composeFromRecording,
 } from './compose-from-recording.ts'
+export {
+  type DeclaredPredicate,
+  declarePredicate,
+  type PolicyDeclaration,
+} from './declare.ts'
 export { type IntentFacts, lower } from './lower.ts'
 export {
   type DecideScopeOptions,