@usesigil/kit 0.1.0

package/dist/shield.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Shield — Kit-native Client-Side Policy Enforcement (Defense-in-Depth)
+ *
+ * Wraps instruction signing with spending limits, rate limits,
+ * program allowlists, and custom checks.
+ *
+ * IMPORTANT: Shield is a CLIENT-SIDE advisory layer, NOT a security boundary.
+ * The on-chain program (validate_and_authorize + finalize_session) provides the
+ * hard enforcement of spending caps, permissions, and protocol allowlists.
+ * Shield reduces blast radius by catching violations before signing, but callers
+ * CAN bypass Shield by using the underlying TransactionSigner directly.
+ * This is by design — Shield prevents accidents, on-chain prevents catastrophe.
+ *
+ * State (spending counters, velocity limits) is in-memory and resets on process
+ * restart. Use syncFromOnChain() to re-sync with the authoritative on-chain state.
+ */
+import type { Address, Rpc, SolanaRpcApi, TransactionSigner } from "@solana/kit";
+import { type InspectableInstruction, type InstructionAnalysis } from "./inspector.js";
+import { type ShieldPolicies, type ResolvedPolicies } from "./policies.js";
+import type { AltCache } from "./alt-loader.js";
+import { type ResolvedVaultState } from "./state-resolver.js";
+import { type Network } from "./types.js";
+export interface PolicyViolation {
+    rule: string;
+    message: string;
+    suggestion?: string;
+}
+export declare class ShieldDeniedError extends Error {
+    readonly violations: PolicyViolation[];
+    code?: number;
+    constructor(violations: PolicyViolation[], code?: number);
+}
+export interface ShieldCheckResult {
+    allowed: boolean;
+    violations: PolicyViolation[];
+    /** Non-fatal warnings (e.g., ALT index out of bounds during analysis). */
+    warnings?: string[];
+}
+export interface SpendingSummary {
+    tokens: Array<{
+        mint: Address;
+        symbol?: string;
+        spent: bigint;
+        limit: bigint;
+        remaining: bigint;
+        windowMs: number;
+    }>;
+    rateLimit: {
+        count: number;
+        limit: number;
+        remaining: number;
+        windowMs: number;
+    };
+    isPaused: boolean;
+    /** On-chain spending state. Undefined when not synced. */
+    onChain?: {
+        globalSpent24h: bigint;
+        globalCap: bigint;
+        globalRemaining: bigint;
+        agentSpent24h: bigint | null;
+        agentCap: bigint | null;
+        agentRemaining: bigint | null;
+        maxTransactionUsd: bigint;
+        localAdditions: bigint;
+        syncedAt: bigint;
+    };
+}
+interface SpendEntry {
+    mint: string;
+    amount: bigint;
+    timestamp: number;
+}
+interface TxEntry {
+    timestamp: number;
+}
+interface Checkpoint {
+    spendEntries: SpendEntry[];
+    txEntries: TxEntry[];
+    resolvedState: ResolvedVaultState | null;
+    localUsdAdditions: bigint;
+    network: Network | null;
+    enforceUsed: boolean;
+}
+export declare class ShieldState {
+    private spendEntries;
+    private txEntries;
+    private _resolvedState;
+    private _localUsdAdditions;
+    private _network;
+    private _enforceUsed;
+    getSpendInWindow(mint: string, windowMs: number): bigint;
+    getTotalSpendInWindow(windowMs: number): bigint;
+    getTransactionCountInWindow(windowMs: number): number;
+    recordSpend(mint: string, amount: bigint): void;
+    recordTransaction(): void;
+    /** Prune stale entries when arrays exceed threshold. */
+    private prune;
+    /** Sync spending baseline from on-chain state. Resets local additions. */
+    syncFromOnChain(state: ResolvedVaultState, network?: Network): void;
+    /** Record local USD spend (optimistic addition on top of on-chain baseline). */
+    recordUsdSpend(amount: bigint): void;
+    /** Effective 24h global spend: on-chain baseline + local additions. */
+    getEffectiveGlobalSpent24h(): bigint;
+    /** Effective 24h remaining against on-chain cap. Returns null if not synced. */
+    getEffectiveGlobalRemaining(): bigint | null;
+    /** Resolved on-chain state, or null if never synced. */
+    get resolvedState(): ResolvedVaultState | null;
+    /** Local USD additions since last sync. */
+    get localUsdAdditions(): bigint;
+    /** Network configured during sync. Null if never synced with network. */
+    get network(): Network | null;
+    /** Effective 24h agent spend: on-chain baseline + local additions. Null if no agent budget. */
+    getEffectiveAgentSpent24h(): bigint | null;
+    /** Effective 24h remaining against agent cap. Null if no agent budget or not synced. */
+    getEffectiveAgentRemaining(): bigint | null;
+    /** S-7: Whether enforce() has been called on this state. */
+    get enforceUsed(): boolean;
+    /** S-7: Mark that enforce() was used. */
+    markEnforceUsed(): void;
+    checkpoint(): Checkpoint;
+    rollback(cp: Checkpoint): void;
+    reset(): void;
+}
+/**
+ * Evaluate a set of instructions against resolved policies.
+ * When state has on-chain sync, also checks vault/agent caps (requires network).
+ */
+export declare function evaluateInstructions(instructions: InspectableInstruction[], signerAddress: Address, resolved: ResolvedPolicies, state: ShieldState, network?: Network): {
+    violations: PolicyViolation[];
+    analysis: InstructionAnalysis;
+};
+export interface ShieldOptions {
+    onDenied?: (error: ShieldDeniedError) => void;
+    onApproved?: () => void;
+    onPolicyUpdate?: (policies: ShieldPolicies) => void;
+    onPause?: () => void;
+    onResume?: () => void;
+    /** Enable on-chain spending baseline sync via StateResolver. */
+    onChainSync?: {
+        rpc: Rpc<SolanaRpcApi>;
+        vaultAddress: Address;
+        agentAddress: Address;
+        network: Network;
+    };
+    /** S-2: Warn when resolved state is older than this many seconds (default: 300). */
+    stalenessWarnThresholdSec?: number;
+}
+export interface ShieldedContext {
+    /** Check instructions against policies without recording */
+    check(instructions: InspectableInstruction[], signerAddress: Address): ShieldCheckResult;
+    /** Check and record — throws ShieldDeniedError if denied */
+    enforce(instructions: InspectableInstruction[], signerAddress: Address): void;
+    /** Current resolved policies */
+    readonly resolvedPolicies: ResolvedPolicies;
+    /** Whether enforcement is paused */
+    readonly isPaused: boolean;
+    /** Update policies */
+    updatePolicies(policies: ShieldPolicies): void;
+    /** Reset spending state */
+    resetState(): void;
+    /** Pause enforcement */
+    pause(): void;
+    /** Resume enforcement */
+    resume(): void;
+    /** Get spending summary */
+    getSpendingSummary(): SpendingSummary;
+    /** Sync spending state from on-chain SpendTracker via StateResolver.
+     *  Requires onChainSync config in ShieldOptions.
+     *  Updates baseline and resets local additions. */
+    sync(): Promise<void>;
+    /** Whether on-chain sync is configured. */
+    readonly hasOnChainSync: boolean;
+    /** Internal state (for testing) */
+    readonly state: ShieldState;
+}
+/**
+ * Create a Kit-native shield context for client-side policy enforcement.
+ *
+ * Unlike the web3.js shield() which wraps wallet signing,
+ * this works at the instruction level:
+ * - check() validates instructions without side effects
+ * - enforce() validates and records, throwing on violation
+ */
+export declare function shield(policies?: ShieldPolicies, options?: ShieldOptions): ShieldedContext;
+/**
+ * Options for the 5-property pre-sign gate.
+ */
+export interface ShieldedSignerOptions {
+    /** Property 3: RPC for fail-closed simulation. */
+    rpc?: Rpc<SolanaRpcApi>;
+    /** Property 5: Session binding context. */
+    sessionContext?: {
+        sessionPda: Address;
+        expirySlot: bigint;
+    };
+    /** Skip simulation (testing only). */
+    skipSimulation?: boolean;
+    /** Property 2: Velocity ceiling thresholds. */
+    velocityThresholds?: {
+        maxTxPerHour?: number;
+        maxUsdPerHour?: bigint;
+    };
+    /** AltCache for resolving ALT-compressed accounts in compiled transactions.
+     *  Populated during compose, read synchronously during sign. */
+    altCache?: AltCache;
+    /** S-4: Session binding severity. 'hard' throws on incomplete binding, 'soft' warns. Default: 'hard'. */
+    sessionBindingSeverity?: "soft" | "hard";
+}
+/**
+ * Create a TransactionSigner that enforces a 5-property pre-sign gate.
+ *
+ * Intercepts every signing call and runs:
+ *   1. Intent-TX correspondence (SOFT — logs warning)
+ *   2. Velocity ceiling (HARD — throws)
+ *   3. Simulation liveness (HARD — throws)
+ *   4. Instruction allowlist via ShieldedContext (HARD — throws)
+ *   5. Session binding (SOFT — logs warning)
+ *
+ * On pass, delegates to the baseSigner. On HARD fail, throws ShieldDeniedError.
+ *
+ * @param baseSigner - The underlying TransactionSigner to delegate to
+ * @param shieldCtx - ShieldedContext providing policy evaluation and state
+ * @param options - Optional configuration for each property
+ */
+export declare function createShieldedSigner(baseSigner: TransactionSigner, shieldCtx: ShieldedContext, options?: ShieldedSignerOptions): TransactionSigner;
+/**
+ * Extract InspectableInstruction[] from a compiled transaction object.
+ * Resolves program addresses from staticAccounts[programAddressIndex].
+ * When ALTs are used, resolves ALT-compressed account indices via AltCache.
+ *
+ * Exported as _extractInstructionsFromCompiled for direct testing.
+ */
+export declare function _extractInstructionsFromCompiled(tx: any, altCache?: AltCache, warnings?: string[]): InspectableInstruction[];
+export {};
+//# sourceMappingURL=shield.d.ts.map

package/dist/shield.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shield.d.ts","sourceRoot":"","sources":["../src/shield.ts"],"names":[],"mappings":"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"}