@crediolabs/policy-synth 0.2.0 → 0.3.1

package/dist/codegen/template.js

@@ -1,148 +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.
-/** 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) {
-    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) {
-    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, name) {
-    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/dist/install/authority-overlap.d.ts

@@ -1,134 +0,0 @@
-import type { PredicateNode, SignerDraft } from '../types.ts';
-/** Wildcard component of a `Selector`: the predicate does not pin this half. */
-export declare const ANY = "*";
-/** A (contract, function) pair a predicate may permit. `ANY` in either half
- *  means unconstrained, so `{contract: ANY, fn: ANY}` is "any call at all". */
-export interface Selector {
-    contract: string;
-    fn: string;
-}
-export type ContextType = {
-    kind: 'default';
-} | {
-    kind: 'call_contract';
-    address: string;
-} | {
-    kind: 'create_contract';
-    wasmHash: string;
-};
-/** How much we can say about a neighbouring rule.
- *  - `interpreter`: policed by our interpreter and the predicate was readable,
- *    so its authority is known exactly and it can be merged.
- *  - `foreign`: policed by some other contract. The address is visible, the
- *    semantics are not, so it must be reviewed by hand.
- *  - `unpoliced`: no policy at all. Whatever the rule's context type allows,
- *    its signers may do without constraint. */
-export type RuleClass = 'interpreter' | 'foreign' | 'unpoliced';
-export interface ObservedRule {
-    id: number;
-    contextType: ContextType;
-    signers: SignerDraft[];
-    /** Policy contract addresses attached to the rule, in OZ's order. */
-    policyAddresses: string[];
-    /** OZ's global registry ids for those policies, index-aligned with
-     *  `policyAddresses`. `remove_policy` takes the id, not the address, so
-     *  detaching a policy is impossible without them. */
-    policyIds?: number[];
-    /** Per-policy oracle bounds from the stored document, when it was
-     *  readable. A merge must re-install these or it silently widens them. */
-    oracleBounds?: {
-        maxStalenessSeconds?: number;
-        maxDeviationBps?: number;
-        maxCrossFeedDeviationBps?: number;
-    };
-    /** Decoded predicate. Present only when the rule is policed by our
-     *  interpreter AND the stored document was readable. */
-    predicate?: PredicateNode;
-}
-export interface IntendedInstall {
-    /** Rule the predicate is being installed onto. A re-install onto the same
-     *  id is a replacement, not an overlap, so this id is skipped. */
-    ruleId: number;
-    contextType: ContextType;
-    signers: SignerDraft[];
-    predicate: PredicateNode;
-}
-export type OverlapSeverity = 
-/** A neighbouring rule imposes no constraint at all on the shared calls. */
-'bypass'
-/** A neighbouring policy exists but we cannot read what it permits. */
- | 'unknown'
-/** Both rules are ours. The new rule will not restrict the shared calls,
- *  because the signer can name whichever rule is more permissive. */
- | 'not-restricting';
-export interface AuthorityOverlap {
-    ruleId: number;
-    ruleClass: RuleClass;
-    severity: OverlapSeverity;
-    /** Signers present in both rules. Overlap is only reachable by a signer who
-     *  can name both rules, so a rule sharing no signer is not a collision. */
-    sharedSigners: SignerDraft[];
-    /** The selectors both rules can serve. Non-empty by construction. */
-    sharedSelectors: Selector[];
-    /** True when the neighbour is ours and can therefore be replaced by the
-     *  conjunction of the two predicates. */
-    mergeable: boolean;
-    advice: string;
-}
-/** Canonical key for signer equality. Mirrors OZ's `Signer` enum: a delegated
- *  signer is its address, an external signer is the verifier plus the key
- *  bytes, since one verifier may hold many keys. */
-export declare function signerKey(s: SignerDraft): string;
-/** Intersection of two selector SETS: every compatible pairing survives. */
-export declare function intersectSelectors(a: Selector[], b: Selector[]): Selector[];
-/**
- * The set of `(contract, fn)` selectors a predicate may permit.
- *
- * This is a deliberate OVER-approximation: every call the predicate actually
- * permits is covered by some returned selector, and unrecognised structure
- * widens to the wildcard rather than narrowing. That direction is what makes
- * the emptiness test below sound. A call carries exactly one `(contract, fn)`,
- * so if two predicates' over-approximations do not intersect, no single call
- * can be routed to either of them and the rules provably cannot collide.
- *
- * `not` is treated as unconstrained. Complementing a selector set would need
- * the universe of addresses and function names, which is not available and
- * would not be sound to guess.
- */
-export declare function permittedSelectors(node: PredicateNode): Selector[];
-/** Selectors a context type admits, before the predicate narrows them. */
-export declare function selectorsForContextType(ct: ContextType): Selector[];
-/** What a rule can actually authorise: its context type narrowed by its
- *  predicate. An unpoliced or unreadable rule contributes no narrowing. */
-export declare function effectiveSelectors(rule: ObservedRule): Selector[];
-/**
- * Every existing rule that a signer of the intended install could name instead.
- *
- * A rule collides when it shares at least one signer AND at least one selector,
- * because both conditions are needed for the signer to have a choice. The rule
- * being installed onto is skipped: re-installing over it replaces its
- * predicate rather than adding a second source of authority.
- */
-export declare function findAuthorityOverlaps(args: {
-    intended: IntendedInstall;
-    existing: ObservedRule[];
-}): AuthorityOverlap[];
-export interface MergeResult {
-    ok: boolean;
-    predicate?: PredicateNode;
-    /** Set when `ok` is false. */
-    reason?: string;
-}
-/**
- * Conjunction of an existing predicate with a new one, for the tightening case.
- *
- * `and` children are flattened so repeated merges do not nest, which keeps the
- * encoded form closer to the byte cap.
- *
- * The guard matters more than the merge. `and` is only correct when the caller
- * means to tighten. Applied to two predicates that pin DIFFERENT selectors it
- * produces a predicate permitting nothing, which silently disables the policy
- * instead of restricting it. That case is refused, because the caller wanted
- * two capabilities and two rules already express that correctly.
- */
-export declare function mergeIntoAnd(existing: PredicateNode, incoming: PredicateNode): MergeResult;

package/dist/install/build-install-predicate.d.ts

@@ -1,96 +0,0 @@
-import { Contract } from '@stellar/stellar-sdk';
-import type { InstallRpcClient } from './build-install-policy.ts';
-/** Inputs for the install-predicate build. */
-export interface BuildInstallPredicateArgs {
-    /** The smart account contract address (C...). The interpreter hashes
-     *  this rule's `signers` at install; we fetch it via `get_context_rule`
-     *  on this address, not reconstruct it. */
-    smartAccount: string;
-    /** The signer that authorises the install (G... wallet). */
-    sourceAccount: string;
-    /** The rule id the account assigned in call 1. */
-    ruleId: number;
-    /** The interpreter contract address (C...). */
-    interpreterAddress: string;
-    /** Network passphrase - pins the hash the auth digest binds. */
-    networkPassphrase: string;
-    /** Already-encoded (base64) canonical ScVal of the predicate. */
-    encodedPredicate: string;
-    /** Hex sha256 of the canonical predicate XDR bytes. */
-    predicateHash: string;
-    /** Grammar version override; defaults to 1. */
-    grammarVersion?: number;
-    /** Base fee in stroops; defaults to BASE_FEE (100). */
-    baseFee?: number;
-    /** RPC client to use for the simulation pass; injected for tests. */
-    rpc: InstallRpcClient;
-    /** Ledger window (in ledgers) for the auth entry's `validUntil`. */
-    authValidUntilLedgers?: number;
-}
-/** Human-readable description of the install-predicate call, decoded FROM
- *  the built XDR (not from the input args). The wallet signature binds
- *  to bytes; the review card has to bind to the same bytes, so this is
- *  the only safe source.
- *
- *  `ruleId` is NOT decoded from the XDR - it lives inside
- *  `raw_context_rule`, which is passed through verbatim. Decoding it
- *  here would re-introduce the client-side reconstruction the file
- *  header warns against. The top-level `BuildInstallPredicateResult`
- *  echoes the caller-supplied rule id instead. */
-export interface InstallPredicateCallDescribes {
-    /** The interpreter that will hold the predicate. */
-    targetContract: string;
-    /** The fn name on the target (always `install` today). */
-    fnName: 'install';
-    /** Grammar version the interpreter enforces; read off the wire. */
-    grammarVersion: number;
-    /** Per-rule install nonce; read off the wire. */
-    installNonce: number;
-    /** Hex sha256 of the encoded predicate blob; read off the wire. */
-    predicateHash: string;
-    /** Hex sha256 of the predicate bytes embedded in the params map. The
-     *  two values MUST match; a difference is a wire tampering signal. */
-    predicateSha256OfEmbeddedBytes: string;
-    /** The smart account address encoded in args[2], read off the wire. */
-    smartAccountOnWire: string;
-}
-/** Output of the install-predicate build. The unsigned XDR is the
- *  wallet's input; the wallet signs it (single envelope signature) and
- *  submits. The auth tree matches install_policy: account entry
- *  carrying OZ's AuthPayload + a source-account delegated signer entry.
- *  Both are covered by the envelope signature. */
-export interface BuildInstallPredicateResult {
-    /** Unsigned Soroban transaction envelope, base64 XDR. */
-    unsignedXdr: string;
-    /** Smart account contract address (echo). */
-    smartAccount: string;
-    /** Source account (echo) - the address that signs the envelope. */
-    sourceAccount: string;
-    /** The interpreter contract address (echo). */
-    interpreterAddress: string;
-    /** The rule id the account assigned in call 1 (echo). */
-    ruleId: number;
-    /** The host-call target + fn name. */
-    call: {
-        contract: string;
-        fn: 'install';
-    };
-    /** The smart-account auth nonce (snapshot). */
-    authNonce: string;
-    /** The ledger sequence + window the auth entry expires at. */
-    authValidUntilLedger: number;
-    /** The captured rootInvocation for the smart-account entry. */
-    rootInvocationXdr: string;
-    /** Human-readable description of the install call, decoded FROM the
-     *  built unsigned XDR (not from the input args). The wallet signature
-     *  binds to bytes; the review card has to bind to the same bytes, so
-     *  this is the only safe source. */
-    describes: InstallPredicateCallDescribes;
-}
-/** Build the unsigned transaction envelope for
- *  `interpreter.install(params, raw_context_rule, smart_account)`. The
- *  output XDR is signed by the wallet, not by us. */
-export declare function buildInstallPredicateXdr(args: BuildInstallPredicateArgs): Promise<BuildInstallPredicateResult>;
-/** Re-export `Contract` so the run-layer does not need to import the
- *  SDK directly. Mirrors the build-install-policy.ts convention. */
-export { Contract };