@crediolabs/policy-synth 0.1.12 → 0.1.13

package/src/run/schemas.ts

@@ -246,6 +246,332 @@ export const SynthesizePolicyInputSchema = z.discriminatedUnion('source', [
 ])
 export type SynthesizePolicyInput = z.infer<typeof SynthesizePolicyInputSchema>
 
+// ===== PredicateNode / PredicateLeaf =====
+//
+// Hand-written zod mirrors of the predicate grammar in types.ts:132-180.
+// Recursive (`and`/`or`/`not` nest), so the schemas use the same
+// `z.lazy` + explicit `z.ZodType<unknown>` annotation that ScValSchema
+// already uses - without the annotation TS's circular type inference
+// breaks the recursive reference. i128-shaped numerics (`num`, `den`)
+// are decimal STRINGS, never JS numbers, matching the on-chain i128
+// convention used everywhere else in this file. The grammar is the
+// single source of truth (types.ts); a drift test in this package
+// asserts the two stay in step.
+
+/** PredicateLeaf mirrors the core `PredicateLeaf` union. Every variant
+ *  is a `kind` discriminator; literals carry their primitive value inline.
+ *  `literal_vec.elements` is recursive (a vec may contain literals that
+ *  themselves nest) so the leaf schema is lazily self-referential. */
+export const PredicateLeafSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.object({ kind: z.literal('call_contract') }),
+    z.object({ kind: z.literal('call_fn') }),
+    z.object({ kind: z.literal('call_arg'), index: z.number().int().nonnegative() }),
+    z.object({ kind: z.literal('call_arg_len'), index: z.number().int().nonnegative() }),
+    z.object({
+      kind: z.literal('call_arg_field'),
+      index: z.number().int().nonnegative(),
+      element: z.number().int().nonnegative(),
+      field: z.string(),
+    }),
+    // num/den are i128 on chain; JSON numbers lose precision past 2^53,
+    // so the wire is a decimal string. The contract refuses `den == 0` and
+    // `num <= 0` / `den <= 0` at install (types.ts:162-163 + the install
+    // gate); mirroring that bound here closes the gap where simulate /
+    // verify green-light a policy the install gate will reject. The
+    // positive-only regex is the cheapest unambiguous check.
+    z.object({
+      kind: z.literal('call_arg_scaled'),
+      index: z.number().int().nonnegative(),
+      num: z.string().regex(/^[1-9][0-9]*$/),
+      den: z.string().regex(/^[1-9][0-9]*$/),
+    }),
+    z.object({ kind: z.literal('amount'), token: z.string() }),
+    z.object({
+      kind: z.literal('window_spent'),
+      token: z.string(),
+      windowSeconds: z.number().int().positive(),
+    }),
+    z.object({ kind: z.literal('now') }),
+    z.object({ kind: z.literal('valid_until') }),
+    z.object({
+      kind: z.literal('invocation_count_in_window'),
+      windowSecs: z.number().int().positive(),
+    }),
+    z.object({ kind: z.literal('oracle_price'), asset: z.string() }),
+    z.object({
+      kind: z.literal('oracle_threshold'),
+      value: z.string().regex(/^-?[0-9]+$/),
+      decimals: z.number().int().nonnegative(),
+    }),
+    z.object({ kind: z.literal('literal_address'), value: z.string() }),
+    z.object({ kind: z.literal('literal_i128'), value: z.string().regex(/^-?[0-9]+$/) }),
+    z.object({ kind: z.literal('literal_symbol'), value: z.string() }),
+    // `literal_u32` is u32 on chain. A negative value would wrap, and a
+    // value above U32_MAX would be refused at the encode boundary
+    // anyway. Bound at the schema so the wire cannot carry a value the
+    // contract will reject.
+    z.object({
+      kind: z.literal('literal_u32'),
+      value: z.number().int().nonnegative().max(U32_MAX),
+    }),
+    z.object({ kind: z.literal('literal_u64'), value: z.string().regex(/^[0-9]+$/) }),
+    // `literal_bytes` is hex on chain. `Buffer.from(value, 'hex')` silently
+    // drops non-hex chars AND yields an empty buffer when the whole input
+    // is non-hex - so a user passing 'zzzz' would get a predicate that
+    // compares against empty bytes instead of being rejected. The
+    // strict even-length hex regex closes that gap at the boundary.
+    z.object({
+      kind: z.literal('literal_bytes'),
+      value: z
+        .string()
+        .regex(/^[0-9a-fA-F]*$/)
+        .refine((v) => v.length % 2 === 0, 'must be even-length hex'),
+    }),
+    // elements are themselves PredicateLeaf; lazy to break the cycle.
+    z.object({ kind: z.literal('literal_vec'), elements: z.array(PredicateLeafSchema) }),
+  ])
+)
+
+/** PredicateNode mirrors the core `PredicateNode` union. Recursive through
+ *  `and`/`or`/`not`; the lazy + annotation pattern keeps the recursion
+ *  type-safe. */
+export const PredicateNodeSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.object({ op: z.literal('and'), children: z.array(PredicateNodeSchema) }),
+    z.object({ op: z.literal('or'), children: z.array(PredicateNodeSchema) }),
+    z.object({ op: z.literal('not'), child: PredicateNodeSchema }),
+    z.object({
+      op: z.literal('eq'),
+      left: PredicateLeafSchema,
+      right: PredicateLeafSchema,
+    }),
+    z.object({
+      op: z.enum(['lt', 'lte', 'gt', 'gte']),
+      left: PredicateLeafSchema,
+      right: PredicateLeafSchema,
+    }),
+    z.object({
+      op: z.literal('in'),
+      needle: PredicateLeafSchema,
+      haystack: z.array(PredicateLeafSchema),
+    }),
+  ])
+)
+
+// ===== simulate_policy / verify_policy =====
+//
+// The oracle fixture shape mirrors `SimulateOptions` / `VerifyOptions`
+// in packages/policy-synth/src/verify/{simulate,verify}.ts - the same
+// sorted set of error enum values is used by both engines. u32
+// `validUntilLedger` is bounded at the boundary so a hand-crafted
+// payload cannot leak a u32 overflow into the engine's permit context.
+
+/** Oracle price fixture - mirror of the entry type in `SimulateOptions` /
+ *  `VerifyOptions`. Discriminated by presence of `error` vs `price`. */
+export const OraclePriceFixtureSchema = z.union([
+  z.object({
+    price: z.string().regex(/^[0-9]+$/),
+    timestampSeconds: z.number().int().nonnegative(),
+  }),
+  z.object({
+    error: z.enum(['stale', 'missing', 'deviation', 'paused', 'decimals', 'fingerprint']),
+  }),
+])
+
+export const SimulatePolicyInputSchema = z.object({
+  // simulatePolicy accepts a null predicate (OZ-only policy); verifyPolicy
+  // does not. The asymmetry is mirrored at the schema boundary.
+  predicate: PredicateNodeSchema.nullable(),
+  permitTx: RecordedTransactionSchema,
+  validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+  oraclePricesByAsset: z.record(z.string(), OraclePriceFixtureSchema).optional(),
+})
+export type SimulatePolicyInput = z.infer<typeof SimulatePolicyInputSchema>
+
+export const VerifyPolicyInputSchema = z.object({
+  // verifyPolicy requires a non-null predicate; the engine refuses
+  // `null` outright. The schema mirrors that contract.
+  predicate: PredicateNodeSchema,
+  permitTx: RecordedTransactionSchema,
+  validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+  oraclePricesByAsset: z.record(z.string(), OraclePriceFixtureSchema).optional(),
+})
+export type VerifyPolicyInput = z.infer<typeof VerifyPolicyInputSchema>
+
+// ===== install_policy / revoke_policy / get_interpreter_info =====
+//
+// The install/revoke pair drives the OZ smart-account admin flow. Both surface
+// unsigned Soroban transaction XDRs (base64) and the tool body NEVER signs:
+// the wallet signature IS the user-confirmation step. See `run/index.ts` for
+// the rationale (no `action_id` two-call pair; the MCP server is stateless).
+//
+// `get_interpreter_info` is a read-only fingerprint lookup. It returns the
+// pinned address + grammar version + wasm hash AND, when requested, runs an
+// optional `grammar_version()` RPC call to check whether the deployed contract
+// matches the pin. A mismatch is worth MORE than a fabricated audit field.
+//
+// All three input schemas live BELOW the MandateSpecSchemaForRule declaration
+// so the const reference there is not in the temporal dead zone (no JS hoisting
+// for `const`).
+
+/** Minimal rule-draft schema for the install input. Mirrors ContextRuleDraft
+ *  from the core (`types.ts`); we keep this hand-rolled + flat rather than
+ *  importing the recursive discriminated union because the wire shape is
+ *  fixed (the user supplies one rule, not a nested AST). Declared BEFORE
+ *  InstallPolicyInputSchema below so the const reference there is not in
+ *  the temporal dead zone (no JS hoisting for `const`). */
+const MAX_SIGNERS_PER_RULE = 15
+const MAX_POLICIES_PER_RULE = 5
+
+const MandateSpecSchemaForRule = z
+  .object({
+    contextRuleType: 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() }),
+    ]),
+    name: z.string().min(1),
+    validUntilLedger: z.number().int().positive().max(U32_MAX).nullable(),
+    signers: z
+      .array(
+        z.discriminatedUnion('kind', [
+          z.object({ kind: z.literal('delegated'), address: z.string() }),
+          z.object({
+            kind: z.literal('external'),
+            verifier: z.string(),
+            keyBytes: z.string(),
+          }),
+        ])
+      )
+      .max(MAX_SIGNERS_PER_RULE),
+    policies: z
+      .array(
+        z.discriminatedUnion('kind', [
+          z.object({
+            kind: z.literal('interpreter'),
+            interpreterAddress: z.string(),
+            predicateBlobBase64: z.string().min(1),
+          }),
+          z.object({
+            kind: z.literal('oz_builtin'),
+            primitive: z.object({
+              primitive: z.enum(['spending_limit', 'simple_threshold', 'weighted_threshold']),
+              params: z.record(z.unknown()),
+            }),
+            instanceAddress: z.string(),
+          }),
+        ])
+      )
+      .max(MAX_POLICIES_PER_RULE),
+  })
+  .passthrough()
+  .refine(
+    (v) => !(v.signers.length === 0 && v.policies.length === 0),
+    'a rule with no signers and no policies is refused at install (NoSignersAndPolicies)'
+  )
+
+// install/revoke/get_info schemas live HERE (after the helper) so the const
+// reference resolves at module init. They are the new tools on top of the
+// existing four.
+
+/** Pinned interpreter address (testnet). Mirrors DEPLOYMENTS.md:156-157.
+ *  Single source for the MCP layer; do not embed elsewhere. */
+export const PINNED_INTERPRETER_TESTNET_ADDRESS =
+  'CDR4NLV22STCXFGZPNKDQTEANWLF7LZ6AJLY6B7CLJXKHDZGYJWIOKGP'
+
+/** Pinned interpreter wasm sha256 (hex). Mirrors DEPLOYMENTS.md:156-157. */
+export const PINNED_INTERPRETER_WASM_SHA256 =
+  '6e6c13d93e197aa380303a42cd120f5ddb080dd36ef2a343ee1dbd04ca52a443'
+
+/** The grammar version the interpreter enforces (matches SELF_VERSION in
+ *  packages/policy-interpreter/src/version.rs). */
+export const PINNED_INTERPRETER_GRAMMAR_VERSION = 1
+
+/** Default Soroban RPC for the install / revoke / info tools. The recorder
+ *  keeps its own copy in record/rpc.ts because it hands back a fetcher rather
+ *  than a Server; the two are deliberately different surfaces, so this is
+ *  pinned beside the addresses it is used with rather than shared. */
+export const TESTNET_RPC_URL = 'https://soroban-testnet.stellar.org'
+
+/** Soroban `valid_until` window (ledgers) added to the latest ledger when
+ *  building the auth entry. ~25 minutes at 5s/ledger. */
+export const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 300
+
+/** Stellar network passphrases. Pinned here so the XDR envelope uses the
+ *  matching passphrase when the wallet signs (a mismatch yields invalid
+ *  hashes). */
+export const NETWORK_PASSPHRASES: Record<Network, string> = {
+  testnet: 'Test SDF Network ; September 2015',
+  mainnet: 'Public Global Stellar Network ; September 2015',
+}
+
+export const InstallPolicyInputSchema = z
+  .object({
+    /** The smart account contract address (C...) that will receive the rule. */
+    smartAccount: z.string(),
+    /** The signer that authorises the install (G... wallet). Used only for
+     *  sequence number + auth nonce simulation; never persisted, never signed. */
+    sourceAccount: z.string(),
+    /** The proposed rule draft. Mirrors the core `ContextRuleDraft` shape. */
+    rule: MandateSpecSchemaForRule,
+    /** Per-rule install nonce; 1 for a fresh install. */
+    installNonce: z.number().int().positive(),
+    /** Optional RPC URL override. Defaults to the public testnet endpoint
+     *  (`TESTNET_RPC_URL`); the override is refused unless
+     *  `allowUnpinnedRpcUrl: true`, because the auth nonce and
+     *  rootInvocation in the response come from whichever RPC answered. */
+    rpcUrl: z.string().url().optional(),
+    /** Opt-in to using a non-pinned RPC URL. Without this flag the tool
+     *  refuses any `rpcUrl` other than `TESTNET_RPC_URL` because the
+     *  caller's auth-digest binds to whatever the RPC returned. */
+    allowUnpinnedRpcUrl: z.boolean().optional(),
+    /** Opt-in to pointing the rule's interpreter policy at any address
+     *  other than the pinned testnet interpreter. Default-deny: a caller
+     *  that controls the interpreter can permit everything. */
+    allowUnpinnedInterpreter: z.boolean().optional(),
+    /** Base fee in stroops; defaults to BASE_FEE (100). */
+    baseFee: z.number().int().positive().optional(),
+  })
+  .refine((v) => Boolean(v.smartAccount) && Boolean(v.sourceAccount), {
+    message: 'smartAccount and sourceAccount are required',
+  })
+export type InstallPolicyInput = z.infer<typeof InstallPolicyInputSchema>
+
+export const RevokePolicyInputSchema = z
+  .object({
+    /** The smart account contract address (C...). */
+    smartAccount: z.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.string(),
+    /** The rule id to remove from the smart account + interpreter. */
+    ruleId: z.number().int().nonnegative(),
+    /** Optional RPC URL override; same pin as install. */
+    rpcUrl: z.string().url().optional(),
+    /** Opt-in to using a non-pinned RPC URL. Same semantics as install. */
+    allowUnpinnedRpcUrl: z.boolean().optional(),
+    /** Base fee in stroops; defaults to BASE_FEE (100). */
+    baseFee: z.number().int().positive().optional(),
+  })
+  .refine((v) => Boolean(v.smartAccount) && Boolean(v.sourceAccount), {
+    message: 'smartAccount and sourceAccount are required',
+  })
+export type RevokePolicyInput = z.infer<typeof RevokePolicyInputSchema>
+
+export const GetInterpreterInfoInputSchema = z.object({
+  /** Network to query. The pin differs per network; defaults to testnet. */
+  network: NetworkSchema.optional(),
+  /** When true, perform an optional live `grammar_version()` RPC call to
+   *  verify the deployed contract matches the pin. */
+  verifyLive: z.boolean().optional(),
+  /** Optional RPC URL override. */
+  rpcUrl: z.string().url().optional(),
+})
+export type GetInterpreterInfoInput = z.infer<typeof GetInterpreterInfoInputSchema>
+
 // ===== Error envelope (canonical) =====
 //
 // Mirrors ToolError from packages/policy-synth/src/errors.ts. We use a