@saw-protocol/policy 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @saw-protocol/policy
+
+The standard execution Policy Engine for the SAWP Protocol.
+
+This module acts as the protocol's firewall. It implements `IPolicyEngine` and ensures agents never exceed financial constraints, communicate with untrusted programs, or violate delegated bounds before constructing blockchain transactions.
+
+## Installation
+
+```bash
+npm install @saw-protocol/policy
+```
+
+## Example Usage
+
+```typescript
+import { CorePolicyEngine } from "@saw-protocol/policy";
+import { PublicKey } from "@solana/web3.js";
+import { TransactionIntent } from "@saw-protocol/core";
+import { v4 as uuidv4 } from "uuid";
+
+const mockStorage: IStorageProvider<any> = {
+  get: async (key: string) => null,
+  set: async (key: string, value: any) => {},
+  delete: async (key: string) => {},
+};
+
+const engine = new CorePolicyEngine(mockStorage);
+const walletPubkey = new PublicKey("..."); // Target wallet address
+
+// Add foundational safety boundaries
+await engine.addRule(walletPubkey, {
+  type: "SpendLimit",
+  maxSOLPerTx: 0.1, // Never allow a transaction intent above 0.1 SOL
+  maxSOLPerDay: 1.0,
+});
+
+await engine.addRule(walletPubkey, {
+  type: "ProgramAllowList",
+  allowedProgramIds: [new PublicKey("JUP6LkbZbjS1jKKwapdH67yIeU1B...")], // Only Jupyter Swaps
+});
+
+// A malicious Agent tries to request a transfer of 5 SOL to an unknown program
+const badIntent: TransactionIntent = {
+  id: uuidv4(),
+  agentId: "did:sol:someAgent",
+  walletAddress: walletPubkey,
+  action: {
+    type: "transfer",
+    estimatedValue: 5.0, // Instantly stopped by SpendLimit
+    params: {},
+  },
+  reasoning: "Attempting to drain funds",
+  signature: "...",
+  timestamp: Date.now(),
+};
+
+// Evaluate the structural intent. Does NOT communicate with the chain.
+const evaluation = await engine.evaluate(badIntent, mockWalletObj, {
+  network: "devnet",
+  currentBalance: 10,
+});
+
+console.log(evaluation.allowed); // false
+console.log(evaluation.reason); // "Policy Denied: Estimated value 5 exceeds per-tx limit of 0.1"
+```

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { IPolicyEngine, EvaluationContext, EvaluationResult, TransactionIntent, AgentWallet, DelegationToken, PolicyRule, PolicySet, IStorageProvider } from '@saw-protocol/core';
+import { PublicKey } from '@solana/web3.js';
+/**
+ * The standard rule-based Policy Engine implementation for the SAWP Protocol.
+ * Evaluates intents against a dynamically managed set of strict `PolicySet` rules.
+ */
+export declare class CorePolicyEngine implements IPolicyEngine {
+    private _store?;
+    private _walletPolicies;
+    private _rateLimitState;
+    private _dailySpendState;
+    constructor(store?: IStorageProvider);
+    /** Gets or initializes a policy set for a wallet */
+    private _getOrCreatePolicySet;
+    private _getOrInitDailySpend;
+    private _getOrInitRateLimit;
+    private _evaluateRule;
+    /** Mutates in-memory spend/rate trackers after a successful transaction */
+    private _recordSpend;
+    evaluate(intent: TransactionIntent, wallet: AgentWallet, context: EvaluationContext): Promise<EvaluationResult>;
+    evaluateDelegation(token: DelegationToken, intent: TransactionIntent): Promise<EvaluationResult>;
+    addRule(walletAddress: PublicKey, rule: PolicyRule): Promise<void>;
+    removeRule(walletAddress: PublicKey, ruleId: string): Promise<void>;
+    listRules(walletAddress: PublicKey): Promise<PolicySet>;
+    simulate(intent: TransactionIntent, wallet: AgentWallet): Promise<EvaluationResult>;
+}

package/dist/index.js

@@ -0,0 +1,373 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CorePolicyEngine = void 0;
+const uuid_1 = require("uuid");
+/**
+ * The standard rule-based Policy Engine implementation for the SAWP Protocol.
+ * Evaluates intents against a dynamically managed set of strict `PolicySet` rules.
+ */
+class CorePolicyEngine {
+    _store;
+    _walletPolicies = new Map();
+    // In-memory rate-limit and daily-spend trackers (not persisted for performance)
+    _rateLimitState = new Map();
+    _dailySpendState = new Map();
+    constructor(store) {
+        this._store = store;
+    }
+    /** Gets or initializes a policy set for a wallet */
+    async _getOrCreatePolicySet(walletAddress) {
+        const key = `policy:${walletAddress.toBase58()}`;
+        // Check external store first
+        if (this._store) {
+            const stored = await this._store.get(key);
+            if (stored)
+                return stored;
+        }
+        // Check in-memory fallback
+        const memKey = walletAddress.toBase58();
+        if (this._walletPolicies.has(memKey)) {
+            return this._walletPolicies.get(memKey);
+        }
+        // Create default — defaultAction 'allow' so wallets work out of the box.
+        // Developers add rules to tighten as needed.
+        const newPolicy = {
+            id: (0, uuid_1.v4)(),
+            rules: [],
+            defaultAction: 'allow',
+            createdAt: Date.now(),
+            updatedAt: Date.now()
+        };
+        if (this._store) {
+            await this._store.set(key, newPolicy);
+        }
+        else {
+            this._walletPolicies.set(memKey, newPolicy);
+        }
+        return newPolicy;
+    }
+    _getOrInitDailySpend(walletKey) {
+        const now = Date.now();
+        const startOfDay = new Date();
+        startOfDay.setUTCHours(0, 0, 0, 0);
+        const dayStart = startOfDay.getTime();
+        const existing = this._dailySpendState.get(walletKey);
+        if (existing && existing.dayStart === dayStart)
+            return existing;
+        // New day — reset
+        const fresh = { dayStart, totalSOL: 0, perMint: {} };
+        this._dailySpendState.set(walletKey, fresh);
+        return fresh;
+    }
+    _getOrInitRateLimit(walletKey) {
+        const now = Date.now();
+        const existing = this._rateLimitState.get(walletKey);
+        if (existing && now - existing.windowStart < 60_000)
+            return existing;
+        // New minute window
+        const fresh = { windowStart: now, count: 0 };
+        this._rateLimitState.set(walletKey, fresh);
+        return fresh;
+    }
+    _evaluateRule(rule, intent, wallet, context) {
+        const walletKey = wallet.address.toBase58();
+        switch (rule.type) {
+            case 'SpendLimit': {
+                if (intent.action.estimatedValue > rule.maxSOLPerTx) {
+                    return {
+                        passed: false,
+                        reason: `Value ${intent.action.estimatedValue} SOL exceeds per-tx limit of ${rule.maxSOLPerTx} SOL`
+                    };
+                }
+                // Enforce daily limit from in-memory tracker
+                const daily = this._getOrInitDailySpend(walletKey);
+                if (daily.totalSOL + intent.action.estimatedValue > rule.maxSOLPerDay) {
+                    return {
+                        passed: false,
+                        reason: `Daily spend would reach ${(daily.totalSOL + intent.action.estimatedValue).toFixed(4)} SOL, limit is ${rule.maxSOLPerDay} SOL`
+                    };
+                }
+                return { passed: true };
+            }
+            case 'TokenSpendLimit': {
+                const mintKey = rule.mint.toBase58();
+                const amount = Number(intent.action.params?.amount || 0);
+                if (amount > rule.maxPerTx) {
+                    return {
+                        passed: false,
+                        reason: `Token amount ${amount} exceeds per-tx limit of ${rule.maxPerTx} for mint ${mintKey}`
+                    };
+                }
+                const daily = this._getOrInitDailySpend(walletKey);
+                const mintSpent = daily.perMint[mintKey] || 0;
+                if (mintSpent + amount > rule.maxPerDay) {
+                    return {
+                        passed: false,
+                        reason: `Daily token spend would reach ${mintSpent + amount}, limit is ${rule.maxPerDay} for mint ${mintKey}`
+                    };
+                }
+                return { passed: true };
+            }
+            case 'ProgramAllowList':
+                if (intent.action.programId &&
+                    !rule.allowedProgramIds.some(p => p.toBase58() === intent.action.programId?.toBase58())) {
+                    return {
+                        passed: false,
+                        reason: `Program ${intent.action.programId.toBase58()} is not in the ProgramAllowList`
+                    };
+                }
+                return { passed: true };
+            case 'ProgramDenyList':
+                if (intent.action.programId &&
+                    rule.blockedProgramIds.some(p => p.toBase58() === intent.action.programId?.toBase58())) {
+                    return {
+                        passed: false,
+                        reason: `Program ${intent.action.programId.toBase58()} is blocked by ProgramDenyList`
+                    };
+                }
+                return { passed: true };
+            case 'Network':
+                if (!rule.allowedNetworks.includes(context.network)) {
+                    return {
+                        passed: false,
+                        reason: `Network '${context.network}' is not in the allowed list [${rule.allowedNetworks.join(', ')}]`
+                    };
+                }
+                return { passed: true };
+            case 'TimeWindow': {
+                const [startHour, endHour] = rule.allowedHoursUTC;
+                const currentHour = new Date().getUTCHours();
+                const inWindow = startHour <= endHour
+                    ? currentHour >= startHour && currentHour < endHour
+                    : currentHour >= startHour || currentHour < endHour; // overnight window
+                if (!inWindow) {
+                    return {
+                        passed: false,
+                        reason: `Current UTC hour ${currentHour} is outside allowed window [${startHour}–${endHour}]`
+                    };
+                }
+                return { passed: true };
+            }
+            case 'RateLimit': {
+                const rl = this._getOrInitRateLimit(walletKey);
+                if (rl.count >= rule.maxTransactionsPerMinute) {
+                    return {
+                        passed: false,
+                        reason: `Rate limit exceeded: ${rl.count}/${rule.maxTransactionsPerMinute} transactions in the current minute window`
+                    };
+                }
+                return { passed: true };
+            }
+            case 'RequireApproval':
+                if (intent.action.estimatedValue > rule.aboveSOLValue) {
+                    // Check if a delegation from the approver is present
+                    if (!intent.delegation || intent.delegation.grantor !== rule.approverAgentId) {
+                        return {
+                            passed: false,
+                            reason: `Transaction value ${intent.action.estimatedValue} SOL exceeds ${rule.aboveSOLValue} SOL and requires approval from ${rule.approverAgentId}`
+                        };
+                    }
+                }
+                return { passed: true };
+            case 'DelegationScope':
+                if (rule.mustBeWithinDelegation && !intent.delegation) {
+                    return {
+                        passed: false,
+                        reason: `This wallet requires a delegation token for all operations`
+                    };
+                }
+                return { passed: true };
+            default:
+                return {
+                    passed: false,
+                    reason: `Unknown policy rule type: ${rule.type} — denied for safety`
+                };
+        }
+    }
+    /** Mutates in-memory spend/rate trackers after a successful transaction */
+    _recordSpend(walletKey, intent) {
+        const daily = this._getOrInitDailySpend(walletKey);
+        daily.totalSOL += intent.action.estimatedValue;
+        // Track per-mint spend for splTransfer and any token actions that carry a mint param
+        if (intent.action.params?.mint) {
+            const mintKey = intent.action.params.mint || 'unknown';
+            daily.perMint[mintKey] = (daily.perMint[mintKey] || 0) + Number(intent.action.params?.amount || 0);
+        }
+        const rl = this._getOrInitRateLimit(walletKey);
+        rl.count += 1;
+    }
+    async evaluate(intent, wallet, context) {
+        let policySet;
+        if (this._store) {
+            policySet = await this._store.get(`policy:${wallet.address.toBase58()}`);
+        }
+        else {
+            policySet = this._walletPolicies.get(wallet.address.toBase58());
+        }
+        // Fall back to the agent wallet's embedded setup
+        policySet = policySet || wallet.policySet;
+        if (!policySet || policySet.rules.length === 0) {
+            return {
+                allowed: policySet?.defaultAction === 'allow',
+                failedRules: [],
+                passedRules: [],
+                reason: policySet?.defaultAction === 'allow'
+                    ? 'No rules defined — allowed by default policy'
+                    : 'No rules defined — denied by default policy',
+                conditions: []
+            };
+        }
+        const failedRules = [];
+        const passedRules = [];
+        for (const rule of policySet.rules) {
+            const { passed, reason } = this._evaluateRule(rule, intent, wallet, context);
+            if (!passed) {
+                failedRules.push(rule);
+                return {
+                    allowed: false,
+                    failedRules,
+                    passedRules,
+                    reason: `Policy Denied: ${reason}`,
+                    conditions: []
+                };
+            }
+            else {
+                passedRules.push(rule);
+            }
+        }
+        // All rules passed — record spend for rate-limit and daily trackers
+        this._recordSpend(wallet.address.toBase58(), intent);
+        return {
+            allowed: true,
+            failedRules,
+            passedRules,
+            reason: 'All policy rules passed.',
+            conditions: []
+        };
+    }
+    async evaluateDelegation(token, intent) {
+        const context = { network: 'unknown', currentBalance: 0 };
+        const passedRules = [];
+        const failedRules = [];
+        // Check expiry
+        if (Date.now() > token.validUntil) {
+            return {
+                allowed: false,
+                failedRules: [],
+                passedRules: [],
+                reason: `Delegation token has expired`,
+                conditions: []
+            };
+        }
+        // Check uses remaining
+        if (token.usesRemaining !== 'unlimited' && token.usesRemaining <= 0) {
+            return {
+                allowed: false,
+                failedRules: [],
+                passedRules: [],
+                reason: `Delegation token has no uses remaining`,
+                conditions: []
+            };
+        }
+        // Evaluate scope rules
+        const mockWallet = { address: token.walletAddress, policySet: token.scope };
+        for (const rule of token.scope.rules) {
+            const { passed, reason } = this._evaluateRule(rule, intent, mockWallet, context);
+            if (!passed) {
+                return {
+                    allowed: false,
+                    failedRules: [rule],
+                    passedRules: [],
+                    reason: `Delegation scope exceeded: ${reason}`,
+                    conditions: []
+                };
+            }
+            passedRules.push(rule);
+        }
+        return {
+            allowed: true,
+            failedRules: [],
+            passedRules,
+            reason: 'Action is within authorized delegation scope',
+            conditions: []
+        };
+    }
+    async addRule(walletAddress, rule) {
+        const policy = await this._getOrCreatePolicySet(walletAddress);
+        // Auto-assign an ID if the rule doesn't have one
+        if (!rule.id) {
+            rule.id = (0, uuid_1.v4)();
+        }
+        policy.rules.push(rule);
+        policy.updatedAt = Date.now();
+        if (this._store) {
+            await this._store.set(`policy:${walletAddress.toBase58()}`, policy);
+        }
+        else {
+            this._walletPolicies.set(walletAddress.toBase58(), policy);
+        }
+    }
+    async removeRule(walletAddress, ruleId) {
+        const policy = await this._getOrCreatePolicySet(walletAddress);
+        const before = policy.rules.length;
+        policy.rules = policy.rules.filter(r => r.id !== ruleId);
+        if (policy.rules.length === before) {
+            console.warn(`[Policy] removeRule: No rule with id '${ruleId}' found for wallet ${walletAddress.toBase58()}`);
+        }
+        policy.updatedAt = Date.now();
+        if (this._store) {
+            await this._store.set(`policy:${walletAddress.toBase58()}`, policy);
+        }
+        else {
+            this._walletPolicies.set(walletAddress.toBase58(), policy);
+        }
+    }
+    async listRules(walletAddress) {
+        return await this._getOrCreatePolicySet(walletAddress);
+    }
+    async simulate(intent, wallet) {
+        // Simulate acts identically to evaluate but does NOT mutate spend trackers
+        const context = { network: 'simulate', currentBalance: 0 };
+        let policySet;
+        if (this._store) {
+            policySet = await this._store.get(`policy:${wallet.address.toBase58()}`);
+        }
+        else {
+            policySet = this._walletPolicies.get(wallet.address.toBase58());
+        }
+        policySet = policySet || wallet.policySet;
+        if (!policySet || policySet.rules.length === 0) {
+            return {
+                allowed: policySet?.defaultAction === 'allow',
+                failedRules: [],
+                passedRules: [],
+                reason: 'Simulated: no rules defined',
+                conditions: []
+            };
+        }
+        const failedRules = [];
+        const passedRules = [];
+        for (const rule of policySet.rules) {
+            const { passed, reason } = this._evaluateRule(rule, intent, wallet, context);
+            if (!passed) {
+                failedRules.push(rule);
+                return {
+                    allowed: false,
+                    failedRules,
+                    passedRules,
+                    reason: `Simulated — Policy Denied: ${reason}`,
+                    conditions: []
+                };
+            }
+            passedRules.push(rule);
+        }
+        return {
+            allowed: true,
+            failedRules,
+            passedRules,
+            reason: 'Simulated — all rules would pass.',
+            conditions: []
+        };
+    }
+}
+exports.CorePolicyEngine = CorePolicyEngine;

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@saw-protocol/policy",
+  "version": "0.1.0",
+  "description": "Default Policy Engine implementation for the SAW Protocol",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "@saw-protocol/core": "*",
+    "@solana/web3.js": "^1.91.1",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/uuid": "^9.0.8",
+    "typescript": "^5.4.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/timileyindev/sawp.git"
+  },
+  "license": "ISC"
+}

package/src/index.ts

@@ -0,0 +1,448 @@
+import { 
+  IPolicyEngine, 
+  EvaluationContext, 
+  EvaluationResult, 
+  TransactionIntent, 
+  AgentWallet, 
+  DelegationToken, 
+  PolicyRule, 
+  PolicySet,
+  IStorageProvider
+} from '@saw-protocol/core';
+import { PublicKey } from '@solana/web3.js';
+import { v4 as uuidv4 } from 'uuid';
+
+// Per-wallet in-memory rate limit tracker (resets each minute window)
+interface RateLimitState {
+  windowStart: number;
+  count: number;
+}
+
+// Per-wallet in-memory daily spend tracker
+interface DailySpendState {
+  dayStart: number; // UTC midnight timestamp
+  totalSOL: number;
+  perMint: Record<string, number>;
+}
+
+/**
+ * The standard rule-based Policy Engine implementation for the SAWP Protocol.
+ * Evaluates intents against a dynamically managed set of strict `PolicySet` rules.
+ */
+export class CorePolicyEngine implements IPolicyEngine {
+  private _store?: IStorageProvider;
+  private _walletPolicies = new Map<string, PolicySet>();
+  // In-memory rate-limit and daily-spend trackers (not persisted for performance)
+  private _rateLimitState = new Map<string, RateLimitState>();
+  private _dailySpendState = new Map<string, DailySpendState>();
+
+  constructor(store?: IStorageProvider) {
+    this._store = store;
+  }
+
+  /** Gets or initializes a policy set for a wallet */
+  private async _getOrCreatePolicySet(walletAddress: PublicKey): Promise<PolicySet> {
+    const key = `policy:${walletAddress.toBase58()}`;
+    
+    // Check external store first
+    if (this._store) {
+      const stored = await this._store.get<PolicySet>(key);
+      if (stored) return stored;
+    }
+
+    // Check in-memory fallback
+    const memKey = walletAddress.toBase58();
+    if (this._walletPolicies.has(memKey)) {
+      return this._walletPolicies.get(memKey)!;
+    }
+
+    // Create default — defaultAction 'allow' so wallets work out of the box.
+    // Developers add rules to tighten as needed.
+    const newPolicy: PolicySet = {
+      id: uuidv4(),
+      rules: [],
+      defaultAction: 'allow',
+      createdAt: Date.now(),
+      updatedAt: Date.now()
+    };
+    
+    if (this._store) {
+      await this._store.set(key, newPolicy);
+    } else {
+      this._walletPolicies.set(memKey, newPolicy);
+    }
+    
+    return newPolicy;
+  }
+
+  private _getOrInitDailySpend(walletKey: string): DailySpendState {
+    const now = Date.now();
+    const startOfDay = new Date();
+    startOfDay.setUTCHours(0, 0, 0, 0);
+    const dayStart = startOfDay.getTime();
+
+    const existing = this._dailySpendState.get(walletKey);
+    if (existing && existing.dayStart === dayStart) return existing;
+
+    // New day — reset
+    const fresh: DailySpendState = { dayStart, totalSOL: 0, perMint: {} };
+    this._dailySpendState.set(walletKey, fresh);
+    return fresh;
+  }
+
+  private _getOrInitRateLimit(walletKey: string): RateLimitState {
+    const now = Date.now();
+    const existing = this._rateLimitState.get(walletKey);
+    if (existing && now - existing.windowStart < 60_000) return existing;
+
+    // New minute window
+    const fresh: RateLimitState = { windowStart: now, count: 0 };
+    this._rateLimitState.set(walletKey, fresh);
+    return fresh;
+  }
+
+  private _evaluateRule(
+    rule: PolicyRule,
+    intent: TransactionIntent,
+    wallet: AgentWallet,
+    context: EvaluationContext
+  ): { passed: boolean; reason?: string } {
+    const walletKey = wallet.address.toBase58();
+
+    switch (rule.type) {
+      case 'SpendLimit': {
+        if (intent.action.estimatedValue > rule.maxSOLPerTx) {
+          return {
+            passed: false,
+            reason: `Value ${intent.action.estimatedValue} SOL exceeds per-tx limit of ${rule.maxSOLPerTx} SOL`
+          };
+        }
+        // Enforce daily limit from in-memory tracker
+        const daily = this._getOrInitDailySpend(walletKey);
+        if (daily.totalSOL + intent.action.estimatedValue > rule.maxSOLPerDay) {
+          return {
+            passed: false,
+            reason: `Daily spend would reach ${(daily.totalSOL + intent.action.estimatedValue).toFixed(4)} SOL, limit is ${rule.maxSOLPerDay} SOL`
+          };
+        }
+        return { passed: true };
+      }
+
+      case 'TokenSpendLimit': {
+        const mintKey = rule.mint.toBase58();
+        const amount = Number(intent.action.params?.amount || 0);
+        if (amount > rule.maxPerTx) {
+          return {
+            passed: false,
+            reason: `Token amount ${amount} exceeds per-tx limit of ${rule.maxPerTx} for mint ${mintKey}`
+          };
+        }
+        const daily = this._getOrInitDailySpend(walletKey);
+        const mintSpent = daily.perMint[mintKey] || 0;
+        if (mintSpent + amount > rule.maxPerDay) {
+          return {
+            passed: false,
+            reason: `Daily token spend would reach ${mintSpent + amount}, limit is ${rule.maxPerDay} for mint ${mintKey}`
+          };
+        }
+        return { passed: true };
+      }
+
+      case 'ProgramAllowList':
+        if (
+          intent.action.programId &&
+          !rule.allowedProgramIds.some(p => p.toBase58() === intent.action.programId?.toBase58())
+        ) {
+          return {
+            passed: false,
+            reason: `Program ${intent.action.programId.toBase58()} is not in the ProgramAllowList`
+          };
+        }
+        return { passed: true };
+
+      case 'ProgramDenyList':
+        if (
+          intent.action.programId &&
+          rule.blockedProgramIds.some(p => p.toBase58() === intent.action.programId?.toBase58())
+        ) {
+          return {
+            passed: false,
+            reason: `Program ${intent.action.programId.toBase58()} is blocked by ProgramDenyList`
+          };
+        }
+        return { passed: true };
+
+      case 'Network':
+        if (!rule.allowedNetworks.includes(context.network as 'devnet' | 'mainnet')) {
+          return {
+            passed: false,
+            reason: `Network '${context.network}' is not in the allowed list [${rule.allowedNetworks.join(', ')}]`
+          };
+        }
+        return { passed: true };
+
+      case 'TimeWindow': {
+        const [startHour, endHour] = rule.allowedHoursUTC;
+        const currentHour = new Date().getUTCHours();
+        const inWindow =
+          startHour <= endHour
+            ? currentHour >= startHour && currentHour < endHour
+            : currentHour >= startHour || currentHour < endHour; // overnight window
+        if (!inWindow) {
+          return {
+            passed: false,
+            reason: `Current UTC hour ${currentHour} is outside allowed window [${startHour}–${endHour}]`
+          };
+        }
+        return { passed: true };
+      }
+
+      case 'RateLimit': {
+        const rl = this._getOrInitRateLimit(walletKey);
+        if (rl.count >= rule.maxTransactionsPerMinute) {
+          return {
+            passed: false,
+            reason: `Rate limit exceeded: ${rl.count}/${rule.maxTransactionsPerMinute} transactions in the current minute window`
+          };
+        }
+        return { passed: true };
+      }
+
+      case 'RequireApproval':
+        if (intent.action.estimatedValue > rule.aboveSOLValue) {
+          // Check if a delegation from the approver is present
+          if (!intent.delegation || intent.delegation.grantor !== rule.approverAgentId) {
+            return {
+              passed: false,
+              reason: `Transaction value ${intent.action.estimatedValue} SOL exceeds ${rule.aboveSOLValue} SOL and requires approval from ${rule.approverAgentId}`
+            };
+          }
+        }
+        return { passed: true };
+
+      case 'DelegationScope':
+        if (rule.mustBeWithinDelegation && !intent.delegation) {
+          return {
+            passed: false,
+            reason: `This wallet requires a delegation token for all operations`
+          };
+        }
+        return { passed: true };
+
+      default:
+        return {
+          passed: false,
+          reason: `Unknown policy rule type: ${(rule as any).type} — denied for safety`
+        };
+    }
+  }
+
+  /** Mutates in-memory spend/rate trackers after a successful transaction */
+  private _recordSpend(walletKey: string, intent: TransactionIntent): void {
+    const daily = this._getOrInitDailySpend(walletKey);
+    daily.totalSOL += intent.action.estimatedValue;
+
+    // Track per-mint spend for splTransfer and any token actions that carry a mint param
+    if (intent.action.params?.mint) {
+      const mintKey = (intent.action.params.mint as string) || 'unknown';
+      daily.perMint[mintKey] = (daily.perMint[mintKey] || 0) + Number(intent.action.params?.amount || 0);
+    }
+
+    const rl = this._getOrInitRateLimit(walletKey);
+    rl.count += 1;
+  }
+
+  async evaluate(intent: TransactionIntent, wallet: AgentWallet, context: EvaluationContext): Promise<EvaluationResult> {
+    let policySet: PolicySet | undefined | null;
+
+    if (this._store) {
+      policySet = await this._store.get<PolicySet>(`policy:${wallet.address.toBase58()}`);
+    } else {
+      policySet = this._walletPolicies.get(wallet.address.toBase58());
+    }
+
+    // Fall back to the agent wallet's embedded setup
+    policySet = policySet || wallet.policySet;
+
+    if (!policySet || policySet.rules.length === 0) {
+      return {
+        allowed: policySet?.defaultAction === 'allow',
+        failedRules: [],
+        passedRules: [],
+        reason: policySet?.defaultAction === 'allow'
+          ? 'No rules defined — allowed by default policy'
+          : 'No rules defined — denied by default policy',
+        conditions: []
+      };
+    }
+
+    const failedRules: PolicyRule[] = [];
+    const passedRules: PolicyRule[] = [];
+
+    for (const rule of policySet.rules) {
+      const { passed, reason } = this._evaluateRule(rule, intent, wallet, context);
+
+      if (!passed) {
+        failedRules.push(rule);
+        return {
+          allowed: false,
+          failedRules,
+          passedRules,
+          reason: `Policy Denied: ${reason}`,
+          conditions: []
+        };
+      } else {
+        passedRules.push(rule);
+      }
+    }
+
+    // All rules passed — record spend for rate-limit and daily trackers
+    this._recordSpend(wallet.address.toBase58(), intent);
+
+    return {
+      allowed: true,
+      failedRules,
+      passedRules,
+      reason: 'All policy rules passed.',
+      conditions: []
+    };
+  }
+
+  async evaluateDelegation(token: DelegationToken, intent: TransactionIntent): Promise<EvaluationResult> {
+    const context: EvaluationContext = { network: 'unknown', currentBalance: 0 };
+    const passedRules: PolicyRule[] = [];
+    const failedRules: PolicyRule[] = [];
+
+    // Check expiry
+    if (Date.now() > token.validUntil) {
+      return {
+        allowed: false,
+        failedRules: [],
+        passedRules: [],
+        reason: `Delegation token has expired`,
+        conditions: []
+      };
+    }
+
+    // Check uses remaining
+    if (token.usesRemaining !== 'unlimited' && token.usesRemaining <= 0) {
+      return {
+        allowed: false,
+        failedRules: [],
+        passedRules: [],
+        reason: `Delegation token has no uses remaining`,
+        conditions: []
+      };
+    }
+
+    // Evaluate scope rules
+    const mockWallet = { address: token.walletAddress, policySet: token.scope } as any;
+    for (const rule of token.scope.rules) {
+      const { passed, reason } = this._evaluateRule(rule, intent, mockWallet, context);
+      if (!passed) {
+        return {
+          allowed: false,
+          failedRules: [rule],
+          passedRules: [],
+          reason: `Delegation scope exceeded: ${reason}`,
+          conditions: []
+        };
+      }
+      passedRules.push(rule);
+    }
+
+    return {
+      allowed: true,
+      failedRules: [],
+      passedRules,
+      reason: 'Action is within authorized delegation scope',
+      conditions: []
+    };
+  }
+
+  async addRule(walletAddress: PublicKey, rule: PolicyRule): Promise<void> {
+    const policy = await this._getOrCreatePolicySet(walletAddress);
+    // Auto-assign an ID if the rule doesn't have one
+    if (!(rule as any).id) {
+      (rule as any).id = uuidv4();
+    }
+    policy.rules.push(rule);
+    policy.updatedAt = Date.now();
+    
+    if (this._store) {
+      await this._store.set(`policy:${walletAddress.toBase58()}`, policy);
+    } else {
+      this._walletPolicies.set(walletAddress.toBase58(), policy);
+    }
+  }
+
+  async removeRule(walletAddress: PublicKey, ruleId: string): Promise<void> {
+    const policy = await this._getOrCreatePolicySet(walletAddress);
+    const before = policy.rules.length;
+    policy.rules = policy.rules.filter(r => (r as any).id !== ruleId);
+    if (policy.rules.length === before) {
+      console.warn(`[Policy] removeRule: No rule with id '${ruleId}' found for wallet ${walletAddress.toBase58()}`);
+    }
+    policy.updatedAt = Date.now();
+    
+    if (this._store) {
+      await this._store.set(`policy:${walletAddress.toBase58()}`, policy);
+    } else {
+      this._walletPolicies.set(walletAddress.toBase58(), policy);
+    }
+  }
+
+  async listRules(walletAddress: PublicKey): Promise<PolicySet> {
+    return await this._getOrCreatePolicySet(walletAddress);
+  }
+
+  async simulate(intent: TransactionIntent, wallet: AgentWallet): Promise<EvaluationResult> {
+    // Simulate acts identically to evaluate but does NOT mutate spend trackers
+    const context: EvaluationContext = { network: 'simulate', currentBalance: 0 };
+    let policySet: PolicySet | undefined | null;
+
+    if (this._store) {
+      policySet = await this._store.get<PolicySet>(`policy:${wallet.address.toBase58()}`);
+    } else {
+      policySet = this._walletPolicies.get(wallet.address.toBase58());
+    }
+
+    policySet = policySet || wallet.policySet;
+
+    if (!policySet || policySet.rules.length === 0) {
+      return {
+        allowed: policySet?.defaultAction === 'allow',
+        failedRules: [],
+        passedRules: [],
+        reason: 'Simulated: no rules defined',
+        conditions: []
+      };
+    }
+
+    const failedRules: PolicyRule[] = [];
+    const passedRules: PolicyRule[] = [];
+
+    for (const rule of policySet.rules) {
+      const { passed, reason } = this._evaluateRule(rule, intent, wallet, context);
+      if (!passed) {
+        failedRules.push(rule);
+        return {
+          allowed: false,
+          failedRules,
+          passedRules,
+          reason: `Simulated — Policy Denied: ${reason}`,
+          conditions: []
+        };
+      }
+      passedRules.push(rule);
+    }
+
+    return {
+      allowed: true,
+      failedRules,
+      passedRules,
+      reason: 'Simulated — all rules would pass.',
+      conditions: []
+    };
+  }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}