@crediolabs/policy-synth 0.2.0 → 0.3.1

package/src/codegen/compile-gate.ts

@@ -1,167 +0,0 @@
-// src/codegen/compile-gate.ts - toolchain-gated `cargo check` for the
-// codegen escape hatch.
-//
-// The escape hatch ships as the `policy-builder escape-hatch` CLI subcommand
-// (a later phase). This gate is its safety net, NOT the happy path. Property:
-// generated Rust compiles against the pinned OZ crate; broken source returns
-// `COMPILE_GATE_FAILED` with `stderr`; an absent toolchain returns `SKIPPED`
-// (does NOT fail - we cannot make build tools a hard runtime requirement for
-// a TypeScript package).
-
-import { spawn } from 'node:child_process'
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-
-export type CompileGateResult =
-  | { code: 'COMPILE_OK' }
-  | { code: 'COMPILE_GATE_FAILED'; stderr: string }
-  | { code: 'SKIPPED'; reason: string }
-
-export interface CompileGateOpts {
-  /** Caller-controlled abort signal; aborting before toolchain probe resolves
-   *  the gate to `SKIPPED` rather than starting a cargo invocation. */
-  signal?: AbortSignal
-  /** Override the `cargo` binary (mostly for tests). */
-  cargoBin?: string
-  /** Override the target directory (mostly for tests). */
-  tempDir?: string
-}
-
-interface ToolchainProbe {
-  present: boolean
-  reason: string
-}
-
-/** Probe the host for the Rust toolchain the gate requires. We require BOTH
- *  `cargo` AND `stellar` (the Soroban CLI) because a real gate run invokes
- *  `stellar contract build`; absent either, the gate returns `SKIPPED`. */
-export async function hasRustToolchain(): Promise<boolean> {
-  const probe = await probeToolchain()
-  return probe.present
-}
-
-async function probeToolchain(): Promise<ToolchainProbe> {
-  const cargo = await which('cargo')
-  if (!cargo) return { present: false, reason: 'cargo not found on PATH' }
-  const stellar = await which('stellar')
-  if (!stellar) return { present: false, reason: 'stellar not found on PATH' }
-  return { present: true, reason: `${cargo} + ${stellar}` }
-}
-
-async function which(bin: string): Promise<string | null> {
-  try {
-    const out = await runProcess('sh', ['-c', `command -v ${bin}`], { capture: true })
-    const path = out.stdout.trim()
-    return path.length > 0 ? path : null
-  } catch {
-    return null
-  }
-}
-
-interface RunOpts {
-  capture?: boolean
-  signal?: AbortSignal
-}
-
-function runProcess(
-  cmd: string,
-  args: string[],
-  opts: RunOpts
-): Promise<{ stdout: string; stderr: string; code: number }> {
-  return new Promise((resolve, reject) => {
-    if (opts.signal?.aborted) {
-      reject(new Error('aborted'))
-      return
-    }
-    const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] })
-    let stdout = ''
-    let stderr = ''
-    child.stdout.on('data', (b: Buffer) => {
-      stdout += b.toString('utf8')
-    })
-    child.stderr.on('data', (b: Buffer) => {
-      stderr += b.toString('utf8')
-    })
-    const onAbort = () => {
-      child.kill('SIGTERM')
-      reject(new Error('aborted'))
-    }
-    opts.signal?.addEventListener('abort', onAbort, { once: true })
-    child.on('error', (e) => {
-      opts.signal?.removeEventListener('abort', onAbort)
-      reject(e)
-    })
-    child.on('close', (code) => {
-      opts.signal?.removeEventListener('abort', onAbort)
-      resolve({ stdout, stderr, code: code ?? -1 })
-    })
-  })
-}
-
-const CARGO_MANIFEST = `[package]
-name = "escape-hatch-gate"
-version = "0.0.0"
-edition = "2021"
-publish = false
-
-[lib]
-crate-type = ["cdylib"]
-# The gate writes the source beside the manifest rather than under src/, so
-# the path is stated. Without it cargo looks for src/lib.rs and fails to
-# parse the manifest before it ever compiles anything, which reads as a
-# broken generator rather than a broken scaffold.
-path = "lib.rs"
-
-[dependencies]
-soroban-sdk = "22"
-
-[workspace]
-`
-
-/** Compile-check a Rust source string against the pinned Soroban SDK.
- *
- *  - Toolchain absent -> `{ code: 'SKIPPED', reason }` (NOT a failure).
- *  - Toolchain present, source compiles -> `{ code: 'COMPILE_OK' }`.
- *  - Toolchain present, source broken -> `{ code: 'COMPILE_GATE_FAILED', stderr }`.
- *
- *  The gate writes the source to a temporary crate and runs `cargo check`
- *  against it; the crate is cleaned up whether or not compilation succeeds.
- *  The caller is expected to surface `COMPILE_GATE_FAILED.stderr` to the
- *  user (the LLM agent) so the user can iterate. */
-export async function compileCheck(
-  rustSource: string,
-  opts: CompileGateOpts = {}
-): Promise<CompileGateResult> {
-  if (opts.signal?.aborted) {
-    return { code: 'SKIPPED', reason: 'aborted before probe' }
-  }
-
-  const probe = await probeToolchain()
-  if (!probe.present) {
-    return { code: 'SKIPPED', reason: probe.reason }
-  }
-
-  let dir: string | null = null
-  try {
-    dir = await mkdtemp(join(opts.tempDir ?? tmpdir(), 'codegen-gate-'))
-    await writeFile(join(dir, 'Cargo.toml'), CARGO_MANIFEST)
-    await writeFile(join(dir, 'lib.rs'), rustSource)
-
-    const runOpts: RunOpts = opts.signal ? { signal: opts.signal } : {}
-    const result = await runProcess(
-      opts.cargoBin ?? 'cargo',
-      ['check', '--quiet', '--offline', '--manifest-path', join(dir, 'Cargo.toml')],
-      runOpts
-    ).catch((e: Error) => ({ stdout: '', stderr: e.message, code: -1 }))
-
-    if (result.code === 0) {
-      return { code: 'COMPILE_OK' }
-    }
-    return { code: 'COMPILE_GATE_FAILED', stderr: result.stderr || result.stdout }
-  } finally {
-    if (dir) {
-      await rm(dir, { recursive: true, force: true }).catch(() => {})
-    }
-  }
-}

package/src/codegen/index.ts

@@ -1,17 +0,0 @@
-// src/codegen/index.ts - re-export the codegen escape-hatch surface.
-//
-// The escape hatch is OUT of the audited happy path: the synthesiser never
-// calls `generateRust` itself; the CLI subcommand (a later phase) is the only
-// entry point. Keeping the surface in one file makes that boundary visible
-// in import statements.
-
-export {
-  type CompileGateOpts,
-  type CompileGateResult,
-  compileCheck,
-  hasRustToolchain,
-} from './compile-gate.ts'
-export {
-  type EscapeHatchSpec,
-  generateRust,
-} from './template.ts'

package/src/codegen/template.ts

@@ -1,165 +0,0 @@
-// src/codegen/template.ts - deterministic Rust source generator for the OZ
-// `Policy` escape-hatch skeleton.
-//
-// SUPERSEDED. The architecture this belongs to no longer exists. A deployed
-// policy involves exactly two contracts, the OZ smart account and one
-// immutable interpreter, and the synthesiser emits policy DATA rather than
-// code. Nothing on the synthesis path reaches this module, and no install can
-// produce a contract from it. When a constraint falls outside the grammar the
-// answer is to version the synthesiser and the interpreter together, not to
-// put unaudited Rust on chain per policy.
-//
-// Deleting it is a decision nobody has taken yet, not a dependency question.
-// `compile-gate.ts` takes a Rust string and knows nothing about this module,
-// and its tests compile a hardcoded fixture, so the gate keeps working either
-// way. What deleting this would remove is the only in-repo producer of policy
-// Rust for the gate to check. Do not read its presence as the product
-// generating contracts, and do not wire it into the synthesis path.
-//
-// What follows describes the abandoned design.
-//
-// This is the LAST-RESORT tool for constraints the v1 DSL cannot express. It
-// lives OUT of the audited happy-path surface; the synthesiser never emits it
-// automatically. It mirrors Zodiac Roles' `Custom` operator: a hand-written
-// (here: scaffolded) policy the operator assumes responsibility for.
-//
-// The skeleton carries five storage invariants the user MUST preserve when
-// filling in the predicate logic:
-//   1. `smart_account.require_auth()` is invoked INSIDE `enforce`.
-//   2. Storage is keyed by the composite `(smart_account, rule_id)`.
-//   3. Chain reads use `unwrap_or_default()` so a missing key is a permitted
-//      default, not a panic.
-//   4. Storage is `persistent()` (NOT `instance()`) so the policy survives
-//      contract instance lifecycle changes.
-//   5. `uninstall` removes the stored state.
-//
-// Determinism: same `(spec, name)` -> byte-identical output. No clock, no RNG,
-// no environment reads.
-
-/** A small typed description of one uncovered constraint the v1 DSL refused
- *  to express. The synthesiser surfaces these from `CompileResult.uncovered`
- *  and the codegen escape hatch wraps them into a hand-auditable skeleton. */
-export interface EscapeHatchSpec {
-  /** Address of the policy contract the skeleton is generated for. */
-  contract: string
-  /** The trait method the predicate lives inside (default: 'enforce'). */
-  fnName?: string
-  /** Human-readable description of each construct the DSL could not cover. */
-  uncovered: string[]
-}
-
-/** Format a name for use as a Rust identifier. The input is constrained by
- *  the caller (a kebab-case policy name + alphanumeric addresses); this is a
- *  belt-and-braces sanitiser that maps anything non-identifier to '_'. */
-function asRustIdent(s: string): string {
-  let out = ''
-  for (let i = 0; i < s.length; i++) {
-    const ch = s.charCodeAt(i)
-    const ok =
-      (ch >= 48 && ch <= 57) || // 0-9
-      (ch >= 65 && ch <= 90) || // A-Z
-      (ch >= 97 && ch <= 122) || // a-z
-      ch === 95 // _
-    out += ok ? s[i] : '_'
-  }
-  // Identifiers may not start with a digit.
-  if (out.length > 0 && out.charCodeAt(0) >= 48 && out.charCodeAt(0) <= 57) {
-    out = `_${out}`
-  }
-  return out || 'policy'
-}
-
-/** Render the `uncovered` list as a `//` comment block (one line per item). */
-function renderUncovered(uncovered: string[]): string {
-  if (uncovered.length === 0) {
-    return '    // (no specific uncovered constructs reported)'
-  }
-  return uncovered.map((line) => `    // - ${line}`).join('\n')
-}
-
-/** Generate a deterministic OZ `Policy` skeleton for an uncovered constraint.
- *
- *  The skeleton is NOT a finished policy; the user fills in the predicate
- *  logic in the marked TODO(user) holes and audits the result themselves.
- *
- *  Same `(spec, name)` always produces byte-identical output. */
-export function generateRust(spec: EscapeHatchSpec, name: string): string {
-  const _contract = spec.contract
-  const _fnName = spec.fnName ?? 'enforce'
-  const structName = asRustIdent(name)
-  const _dataKeyName = `${asRustIdent(name)}_data`
-  const uncoveredBlock = renderUncovered(spec.uncovered)
-
-  return `// Auto-generated by the OZ Policy Builder codegen escape hatch.
-// THIS OUTPUT IS THE USER'S TO COMPLETE AND AUDIT.
-// The synthesiser never emits it on the happy path; reach for it only when
-// a constraint cannot be expressed in the v1 DSL grammar (same shape as
-// Zodiac Roles' \`Custom\` operator).
-
-#![no_std]
-
-use soroban_sdk::{contract, contractimpl, contracttype, Address, Env, Vec};
-
-#[contracttype]
-pub enum DataKey {
-    /// Composite key \`(smart_account, rule_id)\` so multiple policies on
-    /// one smart account coexist without collision.
-    State(Address, u32),
-}
-
-#[contract]
-pub struct ${structName};
-
-#[contractimpl]
-impl ${structName} {
-    pub fn install(e: &Env, smart_account: Address, rule_id: u32) {
-        // TODO(user): initialise policy state for this (smart_account, rule_id).
-        // The skeleton leaves the stored value empty; the predicate body
-        // (in \`enforce\`) decides what to read.
-        e.storage().persistent().set(
-            &DataKey::State(smart_account.clone(), rule_id),
-            &(),
-        );
-    }
-
-    pub fn enforce(
-        e: &Env,
-        smart_account: Address,
-        rule_id: u32,
-        _signers: Vec<Address>,
-    ) {
-        // Invariant 1: authorise the smart account BEFORE any state read or
-        // predicate evaluation. Removing this call opens the policy to
-        // impersonation by any caller with a valid rule_id.
-        smart_account.require_auth();
-
-        // Invariant 2 + 4: read stored state through the composite key on
-        // \`persistent()\` storage. \`unwrap_or_default()\` (invariant 3)
-        // makes an empty key a permitted default rather than a panic.
-        let _state: () = e
-            .storage()
-            .persistent()
-            .get(&DataKey::State(smart_account.clone(), rule_id))
-            .unwrap_or_default();
-
-        // --- uncovered constraints the v1 DSL refused to express ---
-${uncoveredBlock}
-
-        // TODO(user): replace the placeholder below with the real predicate
-        // body. The recorded flow's \`(contract, fn_name, args)\` is the
-        // single authorised call \`Policy::enforce\` receives; match against
-        // \`e\` here.
-        let _ = (_state, &e);
-    }
-
-    pub fn uninstall(e: &Env, smart_account: Address, rule_id: u32) {
-        // Invariant 5: \`uninstall\` removes the stored state so a subsequent
-        // install starts from a clean slate (and the nonce returns to its
-        // post-uninstall value).
-        e.storage()
-            .persistent()
-            .remove(&DataKey::State(smart_account, rule_id));
-    }
-}
-`
-}

package/src/install/build-merge-policy.ts

@@ -1,219 +0,0 @@
-//! Transactions for the merge remedy.
-//!
-//! `plan-merge-policy.ts` decides WHAT should happen; this builds the XDR for
-//! the step the caller asked for. Two calls, in order, because OZ refuses to
-//! attach a policy that is already on the rule:
-//!
-//!   step 1 `detach`    -> `account.remove_policy(rule_id, policy_id)`
-//!   step 2 `reinstall` -> `account.add_policy(rule_id, interpreter, param)`
-//!
-//! The two cannot be emitted together. Simulating step 2 while the old
-//! attachment is still there hits `DuplicatePolicy`, so the second transaction
-//! is only buildable once the first has confirmed.
-//!
-//! Both calls route through the smart account and are authorised the same way
-//! as `revoke_policy`: against the deploy-time admin rule, with the recorded
-//! `rootInvocation` binding the auth payload to this exact rule and policy.
-//! Detaching runs our `uninstall`, which is master-gated, so the signer has to
-//! be a master of the rule either way.
-
-import {
-  Account,
-  Address,
-  BASE_FEE,
-  Operation,
-  rpc,
-  TransactionBuilder,
-  xdr,
-} from '@stellar/stellar-sdk'
-import { DEFAULT_GRAMMAR_VERSION, encodePolicyInstallParams } from './build-add-context-rule.ts'
-import type { InstallRpcClient } from './build-install-policy.ts'
-import {
-  accountEntry,
-  authDigest,
-  authPayload,
-  delegatedSignerEntry,
-  signaturePayload,
-} from './oz-auth.ts'
-import type { MergeStep } from './plan-merge-policy.ts'
-
-/** Matches the window the install and revoke builders use. */
-const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 100
-
-/**
- * The context rule the merge authorises AGAINST, which is not the rule being
- * merged.
- *
- * Both calls mutate the smart account itself, so they need the account's own
- * authorisation, and this builder asks rule 0 for it - the same assumption the
- * install and revoke builders make. OpenZeppelin does NOT enforce any
- * admin semantic for rule 0: it is simply the first rule the account's
- * constructor created, and OZ's reference account creates it as `Default`
- * covering every context.
- *
- * The assumption is therefore load-bearing and unverified at build time. If
- * rule 0 does not exist, does not cover `CallContract(<smart account>)`, or
- * does not list the source account as a signer, the transaction is built and
- * then fails when submitted, and the operator pays the fee for a transaction
- * that was never signable. Changing it is a wire-visible change: the id is
- * hashed into the auth digest.
- */
-export const ADMIN_CONTEXT_RULE_ID = 0
-
-export interface BuildMergePolicyArgs {
-  smartAccount: string
-  sourceAccount: string
-  networkPassphrase: string
-  ruleId: number
-  /** OZ registry id of the interpreter policy on this rule, from the plan. */
-  policyId: number
-  interpreterAddress: string
-  step: MergeStep
-  /** Only needed for `reinstall`: the merged predicate, already encoded. */
-  encodedPredicate?: string
-  predicateHash?: string
-  /** Nonce for the reinstall. Read from chain rather than assumed: a detach
-   *  whose uninstall panicked leaves the old nonce in place. */
-  installNonce?: number
-  /** Oracle bounds to carry over from the document being replaced. */
-  oracleParams?: {
-    maxStalenessSeconds?: number
-    maxDeviationBps?: number
-    maxCrossFeedDeviationBps?: number
-  }
-  rpc: InstallRpcClient
-  baseFee?: number
-  authValidUntilLedgers?: number
-}
-
-export interface BuildMergePolicyResult {
-  unsignedXdr: string
-  smartAccount: string
-  sourceAccount: string
-  step: MergeStep
-  call: { contract: string; fn: 'remove_policy' | 'add_policy'; ruleId: number }
-  authNonce: string
-  authValidUntilLedger: number
-  rootInvocationXdr: string
-}
-
-function hostFunctionFor(args: BuildMergePolicyArgs): xdr.HostFunction {
-  if (args.step === 'detach') {
-    return xdr.HostFunction.hostFunctionTypeInvokeContract(
-      new xdr.InvokeContractArgs({
-        contractAddress: new Address(args.smartAccount).toScAddress(),
-        functionName: 'remove_policy',
-        args: [xdr.ScVal.scvU32(args.ruleId), xdr.ScVal.scvU32(args.policyId)],
-      })
-    )
-  }
-
-  if (!args.encodedPredicate || !args.predicateHash) {
-    throw new Error('merge_policy: reinstall needs the merged predicate and its hash')
-  }
-  return xdr.HostFunction.hostFunctionTypeInvokeContract(
-    new xdr.InvokeContractArgs({
-      contractAddress: new Address(args.smartAccount).toScAddress(),
-      functionName: 'add_policy',
-      args: [
-        xdr.ScVal.scvU32(args.ruleId),
-        new Address(args.interpreterAddress).toScVal(),
-        // Same encoder as a fresh install: the field order is ABI-significant
-        // and it re-hashes the predicate to confirm the supplied hash.
-        encodePolicyInstallParams({
-          encodedPredicate: args.encodedPredicate,
-          predicateHash: args.predicateHash,
-          installNonce: args.installNonce ?? 1,
-          grammarVersion: DEFAULT_GRAMMAR_VERSION,
-          ...(args.oracleParams ? { oracleParams: args.oracleParams } : {}),
-        }),
-      ],
-    })
-  )
-}
-
-/**
- * Build the unsigned transaction for one step of the merge.
- *
- * The auth dance mirrors `buildRevokePolicyXdr`: simulate once to record the
- * account's auth entry, rebuild with the payload bound to that recorded
- * `rootInvocation`, then assemble. Binding to the recorded invocation rather
- * than to the input arguments is what makes the signature commit to the exact
- * rule and policy being changed.
- */
-export async function buildMergePolicyXdr(
-  args: BuildMergePolicyArgs
-): Promise<BuildMergePolicyResult> {
-  const fn = args.step === 'detach' ? 'remove_policy' : 'add_policy'
-  const source = await args.rpc.getAccount(args.sourceAccount)
-  const hostFunction = hostFunctionFor(args)
-  const makeOperation = (auth: xdr.SorobanAuthorizationEntry[] = []) =>
-    Operation.invokeHostFunction({ func: hostFunction, auth })
-  const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE
-
-  const buildTx = (op: xdr.Operation) =>
-    new TransactionBuilder(new Account(args.sourceAccount, source.sequenceNumber()), {
-      fee: baseFee,
-      networkPassphrase: args.networkPassphrase,
-    })
-      .addOperation(op)
-      .setTimeout(0)
-      .build()
-
-  const recorded = await args.rpc.simulateTransaction(buildTx(makeOperation()))
-  if (rpc.Api.isSimulationError(recorded)) {
-    // Short and stable, like the other builders: the SDK's full error carries
-    // host and URL detail that has no business in a user-facing message.
-    throw new Error(`merge_policy: ${fn} simulateTransaction failed`)
-  }
-  const original = (recorded.result?.auth ?? []).find(
-    (entry) =>
-      entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
-      Address.fromScAddress(entry.credentials().address().address()).toString() ===
-        args.smartAccount
-  )
-  if (!original) {
-    throw new Error(
-      `merge_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`
-    )
-  }
-
-  const validUntilLedger =
-    (await args.rpc.getLatestLedger()).sequence +
-    (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_UNTIL_LEDGERS)
-  const contextRuleIds = [ADMIN_CONTEXT_RULE_ID]
-  const digest = authDigest(
-    signaturePayload(
-      args.networkPassphrase,
-      original.credentials().address().nonce(),
-      validUntilLedger,
-      original.rootInvocation()
-    ),
-    contextRuleIds
-  )
-  const authEntries = [
-    accountEntry(
-      original,
-      validUntilLedger,
-      authPayload([args.sourceAccount], contextRuleIds, () => Buffer.alloc(0))
-    ),
-    ...contextRuleIds.map(() => delegatedSignerEntry(args.smartAccount, digest)),
-  ]
-  const txWithAuth = buildTx(makeOperation(authEntries))
-  const enforcing = await args.rpc.simulateTransaction(txWithAuth)
-  if (rpc.Api.isSimulationError(enforcing)) {
-    throw new Error(`merge_policy: ${fn} auth simulateTransaction failed`)
-  }
-  const finalTx = rpc.assembleTransaction(txWithAuth, enforcing).build()
-
-  return {
-    unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
-    smartAccount: args.smartAccount,
-    sourceAccount: args.sourceAccount,
-    step: args.step,
-    call: { contract: args.smartAccount, fn, ruleId: args.ruleId },
-    authNonce: original.credentials().address().nonce().toString(),
-    authValidUntilLedger: validUntilLedger,
-    rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
-  }
-}