@crediolabs/policy-synth 0.3.0 → 0.4.0

package/dist/ir/types.d.ts

@@ -1,71 +0,0 @@
-/** Comparison operator. Mirrors NEAR-V2 `CompOp`. */
-export type IRCompOp = 'eq' | 'lte';
-/** Boolean combinator. Mirrors NEAR-V2 `LogicOp`. */
-export type IRLogic = 'and';
-/** Scalar value type. The subset the predicate grammar has a literal for. */
-export type IRScalarType = 'address' | 'i128' | 'u32' | 'symbol';
-/** WHERE in the authorized call a value is read. NEAR-V2 selectors first, OZ
- *  extensions after (an adapter that cannot express an extension flags it). */
-export type IRSelector = {
-    kind: 'arg';
-    argIndex: number;
-    scalarType: IRScalarType;
-} | {
-    kind: 'arg_len';
-    argIndex: number;
-} | {
-    kind: 'arg_field';
-    argIndex: number;
-    element: number;
-    field: string;
-    scalarType: IRScalarType;
-};
-/** A single comparison leaf. `value` is a decimal/hex string (i128-safe;
- *  never a JS number). */
-export interface IRCompare {
-    selector: IRSelector;
-    operator: IRCompOp;
-    value: string;
-}
-/** Condition tree. NEAR-V2 guard/constraint are flat And/Or; the IR allows
- *  nesting + `not` + `in` + `eq_seq` so the same IR can later lower to the OZ
- *  predicate DSL. Week-1 adapters only lower the flat supported subset and flag
- *  the rest. */
-export type IRCondition = {
-    op: 'and';
-    children: IRCondition[];
-} | {
-    op: 'compare';
-    compare: IRCompare;
-} | {
-    op: 'in';
-    selector: IRSelector;
-    values: string[];
-}
-/** Exact ordered sequence equality. The IR-level selector value MUST EQUAL
- *  `values` as an ORDERED sequence (e.g. a swap hop `path`). `in` is pure
- *  set membership and cannot express order; `eq_seq` is the construct that
- *  does. Adapters that cannot express an exact ordered vector (OZ built-ins)
- *  flag this as `uncovered` rather than silently dropping it. */
- | {
-    op: 'eq_seq';
-    selector: IRSelector;
-    values: string[];
-};
-export interface IRPolicyRule {
-    /** NEAR-V2 scope filter; each field optional (absent = wildcard). */
-    scope: {
-        contract?: string;
-        method?: string;
-    };
-    /** NEAR-V2 constraint (AND; reject the transaction when any fails). */
-    constraints: IRCondition[];
-    /** OZ context-rule expiry, by ledger sequence - the only clock the OZ
-     *  account model exposes to a rule. */
-    expiry?: {
-        validUntilLedger?: number;
-    };
-}
-export interface PolicyIR {
-    rules: IRPolicyRule[];
-}

package/dist/ir/types.js

@@ -1,9 +0,0 @@
-// src/ir/types.ts - the PolicyIR ("Policy Tree").
-//
-// `PolicyIR` is the custody-agnostic "Policy Tree" hub (the diagram's Policy
-// Tree) that every CustodyAdapter compiles FROM. It generalizes the NEAR-V2
-// policy schema (roles / scope filter / guard / constraint / comparison leaves /
-// default behaviour) into one chain-neutral shape and extends it with the
-// single IR can serve every backend. NEAR-V2 has no stateful spend window,
-// below and are only lowered by adapters that declare support for them.
-export {};

package/dist/mandate/index.d.ts

@@ -1,2 +0,0 @@
-export { mandateToPolicyIR } from './to-ir.ts';
-export type { MandateSpec } from './types.ts';

package/dist/mandate/index.js

@@ -1,2 +0,0 @@
-// src/mandate/index.ts - re-export the Mandate source.
-export { mandateToPolicyIR } from "./to-ir.js";

package/dist/mandate/to-ir.d.ts

@@ -1,3 +0,0 @@
-import type { PolicyIR } from '../ir/types.ts';
-import type { MandateSpec } from './types.ts';
-export declare function mandateToPolicyIR(spec: MandateSpec): PolicyIR;

package/dist/mandate/to-ir.js

@@ -1,60 +0,0 @@
-// src/mandate/to-ir.ts - deterministic lowering of a MandateSpec to a PolicyIR.
-//
-// `mandateToPolicyIR` is pure and total: the same spec always lowers to a
-// byte-identical PolicyIR. No decoding, no inference, no clock. Each mandate
-// field maps to exactly one IR construct:
-//   contract/method  -> rule.scope
-//   spendingLimit    -> a `window_spent(token,window) <= limit` compare
-//   approvalThreshold-> rule.approval.threshold
-//   recipients       -> an `in` condition on the recipient arg (flagged as not
-//                       covered by the OZ adapter; that is expected)
-//   expiry           -> rule.expiry
-// The top-level default is `deny_all` (OZ context rules are deny-by-default).
-/** Arg index the recipient allowlist constrains. Pinned to the SEP-41
- *  `transfer(from, to, amount)` convention where `to` is arg 1. This condition
- *  is flagged as not covered by the OZ adapter (no built-in primitive expresses
- *  an arg allowlist), so the index only needs to be deterministic in week-1. */
-const RECIPIENT_ARG_INDEX = 1;
-export function mandateToPolicyIR(spec) {
-    const scope = { contract: spec.contract };
-    if (spec.method !== undefined)
-        scope.method = spec.method;
-    const constraints = [];
-    if (spec.spendingLimit) {
-        constraints.push({
-            op: 'compare',
-            compare: {
-                selector: {
-                    kind: 'window_spent',
-                    token: spec.spendingLimit.token,
-                    windowSeconds: spec.spendingLimit.windowSeconds,
-                },
-                operator: 'lte',
-                value: spec.spendingLimit.limit,
-            },
-        });
-    }
-    if (spec.recipients && spec.recipients.length > 0) {
-        const selector = {
-            kind: 'arg',
-            argIndex: RECIPIENT_ARG_INDEX,
-            scalarType: 'address',
-        };
-        constraints.push({ op: 'in', selector, values: [...spec.recipients] });
-    }
-    const rule = { roles: [], scope, constraints };
-    if (spec.approvalThreshold !== undefined) {
-        rule.approval = { kind: 'threshold', threshold: spec.approvalThreshold };
-    }
-    if (spec.expiry) {
-        const expiry = {};
-        if (spec.expiry.validUntilLedger !== undefined) {
-            expiry.validUntilLedger = spec.expiry.validUntilLedger;
-        }
-        if (spec.expiry.validUntilUnixSeconds !== undefined) {
-            expiry.validUntilUnixSeconds = spec.expiry.validUntilUnixSeconds;
-        }
-        rule.expiry = expiry;
-    }
-    return { chain: spec.chain, defaultBehavior: 'deny_all', rules: [rule] };
-}

package/dist/mandate/types.d.ts

@@ -1,20 +0,0 @@
-export interface MandateSpec {
-    chain: 'stellar';
-    contract: string;
-    method?: string;
-    /** -> OZ `spending_limit` primitive. `limit` is an i128 decimal string. */
-    spendingLimit?: {
-        token: string;
-        limit: string;
-        windowSeconds: number;
-    };
-    /** -> OZ `simple_threshold` / `weighted_threshold` primitive. */
-    approvalThreshold?: number;
-    /** Recipient allowlist -> an `in` arg condition (not covered by an OZ built-in). */
-    recipients?: string[];
-    /** -> OZ context-rule expiry. */
-    expiry?: {
-        validUntilLedger?: number;
-        validUntilUnixSeconds?: number;
-    };
-}

package/dist/mandate/types.js

@@ -1,8 +0,0 @@
-// src/mandate/types.ts - the deterministic Mandate source.
-//
-// A MandateSpec is a declarative policy statement: "this account may call this
-// contract, spending at most L per window, requiring M approvals, to these
-// recipients, until this expiry". It carries NO transaction to decode, NO
-// parseConfidence, and NO inference - it lowers deterministically to a
-// PolicyIR. It is the clean end-to-end demo path, co-equal with the recorder.
-export {};

package/dist/seams/index.d.ts

@@ -1 +0,0 @@
-export type { ChainDecoder, CompileResult, CustodyAdapter, CustodyCapabilities, CustodyMode, PolicySource, SimulationResult, } from './types.ts';

package/dist/seams/index.js

@@ -1,2 +0,0 @@
-// src/seams/index.ts - re-export the three custody-seam contracts.
-export {};

package/dist/seams/types.d.ts

@@ -1,64 +0,0 @@
-import type { ToolResponse } from '../errors.ts';
-import type { PolicyIR } from '../ir/types.ts';
-import type { Network, ProposedPolicy, RecordedTransaction, ScVal } from '../types.ts';
-/** INPUT: something that produces a normalized RecordedTransaction. */
-export interface PolicySource {
-    readonly name: string;
-    capture(input: {
-        hash?: string;
-        xdr?: string;
-        network: Network;
-    }): Promise<ToolResponse<RecordedTransaction>>;
-}
-/** DECODE: chain-specific call data -> the normalized facts the synth reasons
- *  over. */
-export interface ChainDecoder {
-    readonly chain: 'stellar' | 'evm';
-    decodeInvocation(tx: RecordedTransaction): {
-        contract: string;
-        method: string;
-        args: ScVal[];
-    };
-}
-/** OZ = enforce; `log_only` is reserved for shadow mode (out of scope). */
-export type CustodyMode = 'enforce' | 'log_only';
-/** What a backend can express. A construct needing a false flag is flagged
- *  `uncovered` by the adapter, never silently dropped. */
-export interface CustodyCapabilities {
-    supportsSpendWindow: boolean;
-    supportsTimeExpiry: boolean;
-    supportsThreshold: boolean;
-    supportsGeneralPredicate: boolean;
-}
-/** The result of compiling a PolicyIR for one backend. */
-export interface CompileResult {
-    /** false => some IR construct this backend cannot express (see `uncovered`). */
-    covered: boolean;
-    /** Human-readable list of unsupported constructs. */
-    uncovered: string[];
-    /** The backend-native installable policy, assembled when a rule lowered. */
-    proposed?: ProposedPolicy;
-}
-/** Result of a simulate() dry-run. `ts-model` is the off-chain TS evaluator.
- *  Real permit/deny semantics wiring is a later phase; week-1 returns a
- *  clearly-marked stub (empty `evaluations`, `permitted: null`). */
-export interface SimulationResult {
-    backend: 'ts-model';
-    /** Whether the permit tx would be allowed; null until real semantics land. */
-    permitted: boolean | null;
-    /** Per-construct evaluation trace; empty placeholder in this slice. */
-    evaluations: unknown[];
-    /** Diagnostics; marks the stub explicitly. */
-    notes: string[];
-}
-/** OUTPUT: compile a PolicyIR to a backend-specific installable policy. */
-export interface CustodyAdapter {
-    readonly name: string;
-    readonly mode: CustodyMode;
-    capabilities(): CustodyCapabilities;
-    compile(ir: PolicyIR): CompileResult;
-    /** Phase-03 wiring; a clearly-marked stub in week-1. */
-    simulate(ir: PolicyIR, permitTx: RecordedTransaction): SimulationResult;
-    /** Canonical JSON of the IR (portability / audit). */
-    export(ir: PolicyIR): string;
-}

package/dist/seams/types.js

@@ -1,11 +0,0 @@
-// src/seams/types.ts - the three custody seams (contracts, not implementations).
-//
-// The synthesizer is decoupled from its edges by three seams:
-//   - PolicySource  (INPUT):  produces a normalized RecordedTransaction. The
-//                             recorder is the reference source; a MandateSpec
-//                             lowering is a second, deterministic source.
-//   - ChainDecoder  (DECODE): chain-specific call data -> normalized facts.
-//   - CustodyAdapter (OUTPUT): compile a PolicyIR to a backend-native policy +
-//                             verify/export it (OZ is the first adapter).
-// These are INTERFACES only. Implementations live in their own modules.
-export {};

package/dist/synth/deny-cases.d.ts

@@ -1,28 +0,0 @@
-import type { PredicateNode, ScVal } from '../types.ts';
-import type { EvalContext } from './evaluate.ts';
-export interface DenyCase {
-    dimension: string;
-    ctx: EvalContext;
-    /** Canonical reason the Rust interpreter returns for this dimension.
-     *  Optional: when set, `runHarness` asserts the TS evaluator emits this
-     *  exact string, so a future TS/Rust reason divergence fails CI. When
-     *  absent the case is only checked on the boolean decision. */
-    expectedReason?: string;
-}
-export interface GeneratedCases {
-    permit: EvalContext;
-    denies: DenyCase[];
-}
-declare const OVERPERMISSIVE_DIMENSIONS: readonly ["argument_reorder"];
-export { OVERPERMISSIVE_DIMENSIONS };
-/** Build deterministic model-evaluated alternatives without mutating the intended call.
- *
- * @param predicate   - the synthesized predicate
- * @param permitCtx  - EvalContext for the intended (permitted) call
- * @param dimensions - optional whitelist of dimension names to emit; when omitted
- *                    all known dimensions (including over-permissiveness mutations)
- *                    are emitted. */
-export declare function generateCases(predicate: PredicateNode, permitCtx: EvalContext, dimensions?: string[]): GeneratedCases;
-/** Deep-copy an ScVal so a mutation cannot alias the recorded call.
- *  Exported so the permit-context builder shares this one implementation. */
-export declare function cloneScVal(value: ScVal, depth?: number): ScVal;

package/dist/synth/deny-cases.js

@@ -1,212 +0,0 @@
-import { MAX_SCVAL_CLONE_DEPTH } from "../types.js";
-// Deterministic XLM/USDC adjacency fixture; the shared registry can replace this boundary later.
-const OVERPERMISSIVE_DIMENSIONS = ['argument_reorder'];
-export { OVERPERMISSIVE_DIMENSIONS };
-/** Build deterministic model-evaluated alternatives without mutating the intended call.
- *
- * @param predicate   - the synthesized predicate
- * @param permitCtx  - EvalContext for the intended (permitted) call
- * @param dimensions - optional whitelist of dimension names to emit; when omitted
- *                    all known dimensions (including over-permissiveness mutations)
- *                    are emitted. */
-export function generateCases(predicate, permitCtx, dimensions) {
-    const facts = inspectPredicate(predicate);
-    const denies = [];
-    // arg_bound: set a constrained arg to an opaque ScVal.
-    // The reason depends on the predicate shape:
-    //   - an `eq(call_arg[i], literal)` denies with ARG_MISMATCH
-    //   - an `in(call_arg[i], [literals])` denies with NOT_IN_ALLOWLIST
-    // Both are correct in the TS evaluator; the reason is predicate-dependent
-    // so we cannot pin a single canonical reason here.
-    const argumentConstraints = [];
-    for (const comparison of facts.comparisons) {
-        if (comparison.op === 'eq' &&
-            comparison.left.kind === 'call_arg' &&
-            comparison.right.kind !== 'literal_vec') {
-            argumentConstraints.push({ index: comparison.left.index });
-        }
-    }
-    for (const membership of facts.memberships) {
-        if (membership.needle.kind === 'call_arg') {
-            argumentConstraints.push({ index: membership.needle.index });
-        }
-    }
-    for (const constraint of argumentConstraints) {
-        const ctx = cloneContext(permitCtx);
-        ctx.args[constraint.index] = { type: 'other', value: 'deny-case-opaque-argument' };
-        denies.push({ dimension: 'arg_bound', ctx });
-    }
-    // soroswap_allowed_path: replace a bound vec arg with a different vector.
-    // Still valid for eq comparisons on literal_vec leaves.
-    for (const comparison of facts.comparisons) {
-        if (comparison.op !== 'eq' ||
-            comparison.left.kind !== 'call_arg' ||
-            comparison.right.kind !== 'literal_vec') {
-            continue;
-        }
-        const ctx = cloneContext(permitCtx);
-        ctx.args[comparison.left.index] = differentVector(ctx.args[comparison.left.index]);
-        denies.push({ dimension: 'soroswap_allowed_path', ctx });
-    }
-    // argument_reorder: swap first two address args.
-    // Skipped when dimensions filter is active so the synth pipeline can emit a policy;
-    // the over-permissiveness harness then tests this mutation as a FINDING.
-    const constrainedArgIndices = new Set();
-    for (const comparison of facts.comparisons) {
-        if (comparison.left.kind === 'call_arg')
-            constrainedArgIndices.add(comparison.left.index);
-    }
-    for (const membership of facts.memberships) {
-        if (membership.needle.kind === 'call_arg')
-            constrainedArgIndices.add(membership.needle.index);
-    }
-    const hasConstrainedArg = constrainedArgIndices.size > 0;
-    if ((!dimensions || dimensions.includes('argument_reorder')) &&
-        hasConstrainedArg &&
-        permitCtx.args.length >= 2 &&
-        permitCtx.args[0]?.type === 'address' &&
-        permitCtx.args[1]?.type === 'address' &&
-        permitCtx.args[0].value !==
-            permitCtx.args[1].value) {
-        const ctx = cloneContext(permitCtx);
-        // Guard above guarantees args[0] and args[1] exist and are address-typed.
-        const a0 = ctx.args[0];
-        const a1 = ctx.args[1];
-        ctx.args[0] = a1;
-        ctx.args[1] = a0;
-        denies.push({ dimension: 'argument_reorder', ctx });
-    }
-    // map_field_flip: flip a bound map field to a different valid value of
-    // the same type. OPT-IN only, never ORIGINAL.
-    // Targets each `call_arg_field` leaf and produces a ctx whose vec element
-    // has a different value of the recorded field. ---
-    if (!dimensions || dimensions.includes('map_field_flip')) {
-        for (const comparison of facts.comparisons) {
-            const sel = comparison.left;
-            if (sel.kind !== 'call_arg_field')
-                continue;
-            const arg = permitCtx.args[sel.index];
-            if (arg?.type !== 'vec')
-                continue;
-            const element = arg.value[sel.element];
-            if (element?.type !== 'map' || !Array.isArray(element.value))
-                continue;
-            const entry = element.value.find((e) => e.key === sel.field);
-            if (!entry)
-                continue;
-            const flipped = flipFieldValue(entry.val);
-            if (flipped === null)
-                continue;
-            const ctx = cloneContext(permitCtx);
-            const clonedVec = arg.value.map(cloneScVal);
-            const clonedElement = clonedVec[sel.element];
-            if (clonedElement?.type !== 'map' || !Array.isArray(clonedElement.value))
-                continue;
-            clonedElement.value = clonedElement.value.map((e) => e.key === sel.field ? { key: e.key, val: flipped } : e);
-            clonedVec[sel.element] = clonedElement;
-            ctx.args[sel.index] = { type: 'vec', value: clonedVec };
-            denies.push({ dimension: 'map_field_flip', ctx });
-        }
-    }
-    // vec_append: append a new element to a bound vec. OPT-IN only, never ORIGINAL.
-    // Targets every `call_arg_len` leaf; without the length pin a caller can
-    // append an extra element to defeat per-element binds. ---
-    if (!dimensions || dimensions.includes('vec_append')) {
-        for (const comparison of facts.comparisons) {
-            const sel = comparison.left;
-            if (sel.kind !== 'call_arg_len')
-                continue;
-            const arg = permitCtx.args[sel.index];
-            if (arg?.type !== 'vec')
-                continue;
-            const ctx = cloneContext(permitCtx);
-            ctx.args[sel.index] = {
-                type: 'vec',
-                value: [...arg.value, { type: 'other', value: 'deny-case-vec-append' }],
-            };
-            denies.push({ dimension: 'vec_append', ctx });
-        }
-    }
-    return { permit: cloneContext(permitCtx), denies };
-}
-function inspectPredicate(predicate) {
-    const facts = { comparisons: [], memberships: [] };
-    visit(predicate, facts);
-    return facts;
-}
-function visit(node, facts) {
-    switch (node.op) {
-        case 'and':
-            for (const child of node.children)
-                visit(child, facts);
-            return;
-        case 'in':
-            facts.memberships.push(node);
-            return;
-        case 'eq':
-        case 'lte':
-            facts.comparisons.push(node);
-    }
-}
-function differentVector(actual) {
-    if (actual?.type !== 'vec')
-        return { type: 'vec', value: [] };
-    if (actual.value.length === 0) {
-        return { type: 'vec', value: [{ type: 'other', value: 'deny-case-extra-hop' }] };
-    }
-    if (actual.value.length > 1) {
-        const reversed = actual.value.map(cloneScVal).reverse();
-        if (JSON.stringify(reversed) !== JSON.stringify(actual.value)) {
-            return { type: 'vec', value: reversed };
-        }
-    }
-    const value = actual.value.map(cloneScVal);
-    value[0] = { type: 'other', value: 'deny-case-different-hop' };
-    return { type: 'vec', value };
-}
-function cloneContext(ctx) {
-    return {
-        contract: ctx.contract,
-        fn: ctx.fn,
-        args: ctx.args.map(cloneScVal),
-    };
-}
-/** Deep-copy an ScVal so a mutation cannot alias the recorded call.
- *  Exported so the permit-context builder shares this one implementation. */
-export function cloneScVal(value, depth = 0) {
-    if (value.type === 'vec') {
-        if (depth >= MAX_SCVAL_CLONE_DEPTH) {
-            throw cloneDepthError(value);
-        }
-        return { type: 'vec', value: value.value.map((v) => cloneScVal(v, depth + 1)) };
-    }
-    return { ...value };
-}
-function cloneDepthError(value) {
-    const err = new Error(`ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`);
-    err.code = 'SYNTHESIS_ERROR';
-    err.severity = 'error';
-    err.retryable = false;
-    err.depthContext = value.type;
-    throw err;
-}
-/** Build a value of the SAME ScVal type that differs from the recorded one,
- *  used by the `map_field_flip` mutation to defeat a per-element pin without
- *  changing the wire type. Returns null when the ScVal type has no obvious
- *  different value (e.g. opaque/other). */
-function flipFieldValue(val) {
-    switch (val.type) {
-        case 'address': {
-            const a = 'GBFKRGJYZXLTDEI36ZCQEIM225NMOCR2VDBOIHJTXJ54FEFFVL2FKALE';
-            const b = 'GD6XSMQJ47EHHJOWXQOND5YDVZC37JWZJHYHBKE6QJFSLLJ5KQXM5QS5';
-            return { type: 'address', value: val.value === a ? b : a };
-        }
-        case 'i128':
-        case 'u32':
-            return { type: val.type, value: String(BigInt(val.value) + 1n) };
-        case 'symbol':
-            return { type: 'symbol', value: `${val.value}x` };
-        default:
-            return null;
-    }
-}

package/dist/synth/evaluate.d.ts

@@ -1,18 +0,0 @@
-import type { PredicateNode, ScVal } from '../types.ts';
-export interface EvalContext {
-    /** Contract the interpreter is asked to enforce against. */
-    contract: string;
-    /** Function name on that contract. */
-    fn: string;
-    /** Decoded `ScVal[]` of the top-level authorized call. */
-    args: ScVal[];
-}
-export type EvalResult = {
-    permit: true;
-} | {
-    permit: false;
-    reason: string;
-};
-/** Evaluate a `PredicateNode` against the candidate call described by `ctx`.
- *  Pure function. Returns `{ permit: true }` or `{ permit: false; reason }`. */
-export declare function evaluate(predicate: PredicateNode, ctx: EvalContext): EvalResult;