@prktsol/prkt 1.0.0 → 1.0.1

package/dist/onchain/policyGuardProgram.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePolicyGuardProgramId = resolvePolicyGuardProgramId;
+exports.createSessionId = createSessionId;
+exports.getPolicyStateSpace = getPolicyStateSpace;
+exports.findPolicyPda = findPolicyPda;
+exports.findVaultPda = findVaultPda;
+exports.findSessionPda = findSessionPda;
+exports.buildInitializePolicyInstruction = buildInitializePolicyInstruction;
+exports.buildSetKillSwitchInstruction = buildSetKillSwitchInstruction;
+exports.buildOpenSessionInstruction = buildOpenSessionInstruction;
+exports.buildCloseSessionInstruction = buildCloseSessionInstruction;
+exports.buildManagedTransferInstructions = buildManagedTransferInstructions;
+exports.encodeManagedTransferPayload = encodeManagedTransferPayload;
+exports.deriveTransferIntentHash = deriveTransferIntentHash;
+const crypto_1 = require("crypto");
+const web3_js_1 = require("@solana/web3.js");
+const env_1 = require("../config/env");
+const DEFAULT_POLICY_GUARD_PROGRAM_ID = new web3_js_1.PublicKey("3sUkfLW4jtwSQFgdtWyEj8FPedtvKfXSB1J16PMUZhMG");
+const POLICY_SEED = Buffer.from("policy", "utf8");
+const SESSION_SEED = Buffer.from("session", "utf8");
+const VAULT_SEED = Buffer.from("vault", "utf8");
+const EXECUTE_TRANSFER_OPCODE = 4;
+const EXECUTE_TRANSFER_PAYLOAD_SIZE = 160;
+const POLICY_STATE_HEADER_SIZE = 100;
+function resolvePolicyGuardProgramId(programId) {
+    if (programId) {
+        return programId;
+    }
+    const configured = (0, env_1.getOnchainPolicyGuardProgramId)();
+    return configured ? new web3_js_1.PublicKey(configured) : DEFAULT_POLICY_GUARD_PROGRAM_ID;
+}
+function createSessionId(seed) {
+    if (!seed) {
+        return (0, crypto_1.randomBytes)(32);
+    }
+    const source = typeof seed === "string" ? Buffer.from(seed, "utf8") : Buffer.from(seed);
+    return (0, crypto_1.createHash)("sha256").update(source).digest();
+}
+function getPolicyStateSpace(input) {
+    const allowedPrograms = input.allowedPrograms ?? [];
+    const allowedRecipients = input.allowedRecipients ?? [];
+    return POLICY_STATE_HEADER_SIZE + (allowedPrograms.length + allowedRecipients.length) * 32;
+}
+function findPolicyPda(owner, programId) {
+    return web3_js_1.PublicKey.findProgramAddressSync([POLICY_SEED, owner.toBuffer()], resolvePolicyGuardProgramId(programId));
+}
+function findVaultPda(policyPda, programId) {
+    return web3_js_1.PublicKey.findProgramAddressSync([VAULT_SEED, policyPda.toBuffer()], resolvePolicyGuardProgramId(programId));
+}
+function findSessionPda(policyPda, sessionId, programId) {
+    return web3_js_1.PublicKey.findProgramAddressSync([SESSION_SEED, policyPda.toBuffer(), toFixedBuffer(sessionId, 32)], resolvePolicyGuardProgramId(programId));
+}
+function buildInitializePolicyInstruction(input) {
+    const programId = resolvePolicyGuardProgramId(input.programId);
+    const allowedPrograms = input.allowedPrograms ?? [];
+    const allowedRecipients = input.allowedRecipients ?? [];
+    const [policyPda] = findPolicyPda(input.owner, programId);
+    const [vaultPda] = findVaultPda(policyPda, programId);
+    const data = Buffer.concat([
+        Buffer.from([0]),
+        encodeU32(input.sessionTtlMinutes),
+        encodeU64(input.dailySpendLimitLamports),
+        input.verifier.toBuffer(),
+        encodePubkeyArray(allowedPrograms),
+        encodePubkeyArray(allowedRecipients)
+    ]);
+    return {
+        instruction: new web3_js_1.TransactionInstruction({
+            programId,
+            keys: [
+                { pubkey: input.owner, isSigner: true, isWritable: true },
+                { pubkey: policyPda, isSigner: false, isWritable: true },
+                { pubkey: vaultPda, isSigner: false, isWritable: true },
+                { pubkey: web3_js_1.SystemProgram.programId, isSigner: false, isWritable: false }
+            ],
+            data
+        }),
+        policyPda,
+        vaultPda
+    };
+}
+function buildSetKillSwitchInstruction(input) {
+    const programId = resolvePolicyGuardProgramId(input.programId);
+    const [policyPda] = findPolicyPda(input.owner, programId);
+    return {
+        instruction: new web3_js_1.TransactionInstruction({
+            programId,
+            keys: [
+                { pubkey: input.owner, isSigner: true, isWritable: false },
+                { pubkey: policyPda, isSigner: false, isWritable: true }
+            ],
+            data: Buffer.from([1, input.active ? 1 : 0])
+        }),
+        policyPda
+    };
+}
+function buildOpenSessionInstruction(input) {
+    const programId = resolvePolicyGuardProgramId(input.programId);
+    const [policyPda] = findPolicyPda(input.owner, programId);
+    const [sessionPda] = findSessionPda(policyPda, input.sessionId, programId);
+    return {
+        instruction: new web3_js_1.TransactionInstruction({
+            programId,
+            keys: [
+                { pubkey: input.owner, isSigner: true, isWritable: true },
+                { pubkey: policyPda, isSigner: false, isWritable: false },
+                { pubkey: sessionPda, isSigner: false, isWritable: true },
+                { pubkey: web3_js_1.SystemProgram.programId, isSigner: false, isWritable: false }
+            ],
+            data: Buffer.concat([Buffer.from([2]), toFixedBuffer(input.sessionId, 32)])
+        }),
+        policyPda,
+        sessionPda
+    };
+}
+function buildCloseSessionInstruction(input) {
+    const programId = resolvePolicyGuardProgramId(input.programId);
+    const [policyPda] = findPolicyPda(input.owner, programId);
+    const [sessionPda] = findSessionPda(policyPda, input.sessionId, programId);
+    return {
+        instruction: new web3_js_1.TransactionInstruction({
+            programId,
+            keys: [
+                { pubkey: input.owner, isSigner: true, isWritable: false },
+                { pubkey: policyPda, isSigner: false, isWritable: false },
+                { pubkey: sessionPda, isSigner: false, isWritable: true }
+            ],
+            data: Buffer.concat([Buffer.from([3]), toFixedBuffer(input.sessionId, 32)])
+        }),
+        policyPda,
+        sessionPda
+    };
+}
+function buildManagedTransferInstructions(input) {
+    const programId = resolvePolicyGuardProgramId(input.programId);
+    const signer = normalizeSigner(input.signer);
+    const [policyPda] = findPolicyPda(input.policyOwner, programId);
+    const [vaultPda] = findVaultPda(policyPda, programId);
+    const [sessionPda] = findSessionPda(policyPda, input.sessionId, programId);
+    const payload = encodeManagedTransferPayload({
+        amountLamports: input.amountLamports,
+        expiresAtUnix: input.expiresAtUnix,
+        intentHash: Buffer.from(input.intentHash ?? deriveTransferIntentHash(input)),
+        nonce: input.nonce,
+        recipient: input.recipient,
+        sessionId: Buffer.from(input.sessionId),
+        targetProgram: input.targetProgram ?? programId,
+        timestampUnix: input.timestampUnix ?? Math.floor(Date.now() / 1000)
+    });
+    return {
+        ed25519Instruction: web3_js_1.Ed25519Program.createInstructionWithPrivateKey({
+            privateKey: signer.secretKey,
+            message: payload
+        }),
+        payload,
+        policyPda,
+        programInstruction: new web3_js_1.TransactionInstruction({
+            programId,
+            keys: [
+                { pubkey: policyPda, isSigner: false, isWritable: true },
+                { pubkey: vaultPda, isSigner: false, isWritable: true },
+                { pubkey: sessionPda, isSigner: false, isWritable: true },
+                { pubkey: input.recipient, isSigner: false, isWritable: true },
+                { pubkey: web3_js_1.SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false }
+            ],
+            data: Buffer.concat([Buffer.from([EXECUTE_TRANSFER_OPCODE]), payload])
+        }),
+        sessionPda,
+        vaultPda
+    };
+}
+function encodeManagedTransferPayload(input) {
+    const sessionId = toFixedBuffer(input.sessionId, 32);
+    const intentHash = toFixedBuffer(input.intentHash, 32);
+    const payload = Buffer.alloc(EXECUTE_TRANSFER_PAYLOAD_SIZE);
+    let offset = 0;
+    sessionId.copy(payload, offset);
+    offset += 32;
+    encodeU64(input.nonce).copy(payload, offset);
+    offset += 8;
+    encodeU64(input.amountLamports).copy(payload, offset);
+    offset += 8;
+    encodeI64(input.timestampUnix).copy(payload, offset);
+    offset += 8;
+    encodeI64(input.expiresAtUnix).copy(payload, offset);
+    offset += 8;
+    input.targetProgram.toBuffer().copy(payload, offset);
+    offset += 32;
+    input.recipient.toBuffer().copy(payload, offset);
+    offset += 32;
+    intentHash.copy(payload, offset);
+    return payload;
+}
+function deriveTransferIntentHash(input) {
+    const hash = (0, crypto_1.createHash)("sha256");
+    hash.update(toFixedBuffer(input.sessionId, 32));
+    hash.update(encodeU64(input.nonce));
+    hash.update(encodeU64(input.amountLamports));
+    hash.update(input.recipient.toBuffer());
+    hash.update((input.targetProgram ?? DEFAULT_POLICY_GUARD_PROGRAM_ID).toBuffer());
+    return hash.digest();
+}
+function normalizeSigner(input) {
+    if (input instanceof web3_js_1.Keypair) {
+        return input;
+    }
+    if (input.length === 64) {
+        return web3_js_1.Keypair.fromSecretKey(input);
+    }
+    if (input.length === 32) {
+        return web3_js_1.Keypair.fromSeed(input);
+    }
+    throw new Error("Signer must be a Keypair, 32-byte seed, or 64-byte secret key.");
+}
+function toFixedBuffer(value, expectedLength) {
+    const buffer = Buffer.from(value);
+    if (buffer.length !== expectedLength) {
+        throw new Error(`Expected ${expectedLength} bytes but received ${buffer.length}.`);
+    }
+    return buffer;
+}
+function encodePubkeyArray(values) {
+    return Buffer.concat([
+        encodeU16(values.length),
+        ...values.map((value) => value.toBuffer())
+    ]);
+}
+function encodeU16(value) {
+    const out = Buffer.alloc(2);
+    out.writeUInt16LE(value, 0);
+    return out;
+}
+function encodeU32(value) {
+    const out = Buffer.alloc(4);
+    out.writeUInt32LE(value, 0);
+    return out;
+}
+function encodeU64(value) {
+    const out = Buffer.alloc(8);
+    out.writeBigUInt64LE(value, 0);
+    return out;
+}
+function encodeI64(value) {
+    const out = Buffer.alloc(8);
+    out.writeBigInt64LE(BigInt(value), 0);
+    return out;
+}

package/dist/policy/PolicyGuard.d.ts

@@ -0,0 +1,13 @@
+import { type VersionedTransaction } from "@solana/web3.js";
+import type { PolicyConstraints } from "../types/policy";
+export declare class PolicyGuard {
+    private readonly policy;
+    constructor(policy: PolicyConstraints);
+    validate(transaction: VersionedTransaction): void;
+    private ensureEmergencyOverrideInactive;
+    private ensureSessionActive;
+    private ensureProgramAllowed;
+    private tryDecodeSpend;
+    private ensureInstructionShapeAllowed;
+    private detectBlockedSpendVector;
+}

package/dist/policy/emergencyLock.d.ts

@@ -0,0 +1,4 @@
+export declare function getEmergencyLockStatus(): {
+    locked: boolean;
+    reason: string | null;
+};

package/dist/policy/engine/PolicyEngine.d.ts

@@ -0,0 +1,28 @@
+import { type VersionedTransaction } from "@solana/web3.js";
+import type { PolicyConfig, SecurityAuditEntry, TxInspectionContext, TxInspectionResult } from "../types/policy";
+import { ethers } from "ethers";
+export declare class PolicyEngine {
+    private readonly policyConfig;
+    private readonly sessionStart;
+    private txCountSession;
+    private readonly perDayCounts;
+    private readonly auditLog;
+    private lastResetTimestamp;
+    private spentTodaySol;
+    constructor(policyConfig: PolicyConfig);
+    inspect(transaction: VersionedTransaction, context?: TxInspectionContext): TxInspectionResult;
+    inspectEvm(transaction: ethers.TransactionRequest): TxInspectionResult;
+    recordBroadcast(signature: string, amountSol?: number): void;
+    getAuditTrail(): SecurityAuditEntry[];
+    getSessionAgeMs(): number;
+    getPolicyConfig(): PolicyConfig;
+    getSpentToday(): number;
+    recordSpend(amountSol: number): void;
+    resetDailySpend(): void;
+    private tryDecodeSpend;
+    private detectBlockedSpendVector;
+    private isKnownNonSpendInstruction;
+    private maybeResetDailySpend;
+    private getUtcDayKey;
+    private lamportsToSol;
+}

package/dist/policy/engine/PolicyEngine.js

@@ -11,6 +11,8 @@ class PolicyEngine {
     txCountSession = 0;
     perDayCounts = new Map();
     auditLog = [];
+    lastResetTimestamp = Date.now();
+    spentTodaySol = 0;
     constructor(policyConfig) {
         this.policyConfig = policyConfig;
     }
@@ -23,6 +25,7 @@ class PolicyEngine {
         const mintsSeen = new Set();
         let hasUncheckedSplSpend = false;
         const now = Date.now();
+        this.maybeResetDailySpend(now);
         const emergencyStatus = (0, emergencyLock_1.getEmergencyLockStatus)();
         if (emergencyStatus.locked) {
             reasons.push(emergencyStatus.reason ?? "Human-in-the-loop Override engaged.");
@@ -83,6 +86,10 @@ class PolicyEngine {
         if (totalSolSpendLamports > BigInt(this.policyConfig.limits.maxSolPerTxLamports)) {
             reasons.push("max SOL per transaction exceeded");
         }
+        if (this.getSpentToday() + this.lamportsToSol(totalSolSpendLamports) >
+            this.lamportsToSol(BigInt(this.policyConfig.limits.maxSolPerTxLamports))) {
+            reasons.push("DAILY_LIMIT_EXCEEDED");
+        }
         if (totalSplSpendRaw > this.policyConfig.limits.maxSplPerTxRawAmount) {
             reasons.push("max SPL per transaction exceeded");
         }
@@ -104,6 +111,7 @@ class PolicyEngine {
         const allowed = reasons.length === 0;
         const result = {
             allowed,
+            reason: reasons[0],
             reasons,
             details: {
                 totalSolSpendLamports,
@@ -120,10 +128,69 @@ class PolicyEngine {
         });
         return result;
     }
-    recordBroadcast(signature) {
+    inspectEvm(transaction) {
+        const reasons = [];
+        const now = Date.now();
+        this.maybeResetDailySpend(now);
+        const emergencyStatus = (0, emergencyLock_1.getEmergencyLockStatus)();
+        if (emergencyStatus.locked) {
+            reasons.push(emergencyStatus.reason ?? "Human-in-the-loop Override engaged.");
+        }
+        const sessionExpiry = Date.parse(this.policyConfig.sessionExpiresAtIso8601);
+        if (Number.isNaN(sessionExpiry) || now > sessionExpiry) {
+            reasons.push("session expired");
+        }
+        const dayKey = new Date(now).toISOString().slice(0, 10);
+        const todaysCount = this.perDayCounts.get(dayKey) ?? 0;
+        if (this.txCountSession >= this.policyConfig.limits.maxTransactionsPerSession) {
+            reasons.push("max transactions per session exceeded");
+        }
+        if (todaysCount >= this.policyConfig.limits.maxTransactionsPerDay) {
+            reasons.push("max transactions per day exceeded");
+        }
+        // EVM contract address allowlist (analogous to program allowlist)
+        const toAddress = transaction.to?.toString().toLowerCase();
+        const allowedProgramsLower = this.policyConfig.rules.allowedProgramIds.map(id => id.toLowerCase());
+        if (toAddress && !allowedProgramsLower.includes(toAddress)) {
+            reasons.push(`EVM contract not allowed: ${toAddress}`);
+            if (!this.policyConfig.rules.allowOpaqueProgramIds?.map(id => id.toLowerCase()).includes(toAddress) && !this.policyConfig.rules.denyUnknownInstructionsByDefault) {
+                // allow
+            }
+        }
+        // Aggregate spend limit applies to EVM too (approximate 1 ETH = X SOL if needed, or raw values for test)
+        if (transaction.value && BigInt(transaction.value.toString()) > BigInt(this.policyConfig.limits.maxSolPerTxLamports)) {
+            reasons.push("max spend per transaction exceeded");
+        }
+        if (this.getSpentToday() + this.lamportsToSol(BigInt(transaction.value?.toString() || "0")) >
+            this.lamportsToSol(BigInt(this.policyConfig.limits.maxSolPerTxLamports))) {
+            reasons.push("DAILY_LIMIT_EXCEEDED");
+        }
+        const allowed = reasons.length === 0;
+        const result = {
+            allowed,
+            reason: reasons[0],
+            reasons,
+            details: {
+                totalSolSpendLamports: BigInt(transaction.value?.toString() || "0"),
+                totalSplSpendRaw: 0n,
+                programsSeen: toAddress ? [toAddress] : [],
+                mintsSeen: []
+            }
+        };
+        this.auditLog.push({
+            agentId: this.policyConfig.agentId,
+            timestampIso8601: new Date().toISOString(),
+            decision: allowed ? "allow" : "deny",
+            reason: allowed ? "policy checks passed" : reasons.join("; ")
+        });
+        return result;
+    }
+    recordBroadcast(signature, amountSol = 0) {
+        this.maybeResetDailySpend();
         this.txCountSession += 1;
         const dayKey = new Date().toISOString().slice(0, 10);
         this.perDayCounts.set(dayKey, (this.perDayCounts.get(dayKey) ?? 0) + 1);
+        this.recordSpend(amountSol);
         this.auditLog.push({
             agentId: this.policyConfig.agentId,
             timestampIso8601: new Date().toISOString(),
@@ -138,6 +205,34 @@ class PolicyEngine {
     getSessionAgeMs() {
         return Date.now() - this.sessionStart;
     }
+    getPolicyConfig() {
+        return {
+            ...this.policyConfig,
+            limits: {
+                ...this.policyConfig.limits
+            },
+            rules: {
+                ...this.policyConfig.rules,
+                allowOpaqueProgramIds: [...(this.policyConfig.rules.allowOpaqueProgramIds ?? [])],
+                allowedCloseAccountDestinations: [...(this.policyConfig.rules.allowedCloseAccountDestinations ?? [])],
+                allowedMintAddresses: [...this.policyConfig.rules.allowedMintAddresses],
+                allowedProgramIds: [...this.policyConfig.rules.allowedProgramIds],
+                allowedTransferDestinations: [...(this.policyConfig.rules.allowedTransferDestinations ?? [])]
+            }
+        };
+    }
+    getSpentToday() {
+        this.maybeResetDailySpend();
+        return this.spentTodaySol;
+    }
+    recordSpend(amountSol) {
+        this.maybeResetDailySpend();
+        this.spentTodaySol += amountSol;
+    }
+    resetDailySpend() {
+        this.spentTodaySol = 0;
+        this.lastResetTimestamp = Date.now();
+    }
     tryDecodeSpend(instruction) {
         if (instruction.programId.equals(web3_js_1.SystemProgram.programId)) {
             try {
@@ -233,5 +328,18 @@ class PolicyEngine {
             programId === programs_1.MEMO_PROGRAM_ID.toBase58() ||
             (this.policyConfig.rules.allowOpaqueProgramIds?.includes(programId) ?? false));
     }
+    maybeResetDailySpend(now = Date.now()) {
+        if (this.getUtcDayKey(this.lastResetTimestamp) === this.getUtcDayKey(now)) {
+            return;
+        }
+        this.spentTodaySol = 0;
+        this.lastResetTimestamp = now;
+    }
+    getUtcDayKey(timestamp) {
+        return new Date(timestamp).toISOString().slice(0, 10);
+    }
+    lamportsToSol(amountLamports) {
+        return Number(amountLamports) / 1_000_000_000;
+    }
 }
 exports.PolicyEngine = PolicyEngine;

package/dist/policy/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class SecurityViolationError extends Error {
+    constructor(message: string);
+}

package/dist/policy/index.d.ts

@@ -0,0 +1,3 @@
+export { PolicyEngine } from "./engine/PolicyEngine";
+export { SandboxExecutor, type SandboxExecutionResult } from "./sandbox/SandboxExecutor";
+export type { ApprovalCallback, ApprovalMode, PolicyConfig, PolicyLimits, PolicyRules, SecurityAuditEntry, TxInspectionContext, TxInspectionResult } from "./types/policy";

package/dist/policy/sandbox/SandboxExecutor.d.ts

@@ -0,0 +1,44 @@
+import { type TransactionConfirmationStrategy, VersionedTransaction } from "@solana/web3.js";
+import { TransactionService } from "../../core/transactions/TransactionService";
+import { PolicyEngine } from "../engine/PolicyEngine";
+import type { ApprovalCallback, TxInspectionContext, TxInspectionResult } from "../types/policy";
+import { PolicyProof } from "../../zk/PolicyCircuit";
+import { Keypair } from "@solana/web3.js";
+import { ethers } from "ethers";
+export type SandboxExecutionResult = {
+    inspection: TxInspectionResult;
+    signature: string | null;
+    simulationLogs: string[] | null;
+    zkProof?: PolicyProof;
+};
+export declare class SandboxExecutor {
+    private readonly policyEngine;
+    private readonly transactionService;
+    private readonly approvalMode;
+    private readonly approvalCallback?;
+    private readonly auditLogManager;
+    private readonly proofAnchor;
+    private readonly useCompression;
+    private readonly useZkProofs;
+    constructor(policyEngine: PolicyEngine, transactionService: TransactionService, approvalMode: "sandbox" | "live", approvalCallback?: ApprovalCallback | undefined);
+    executePreparedTransaction(input: {
+        confirmationStrategy?: TransactionConfirmationStrategy | string;
+        solanaKeypair?: Keypair;
+        transaction: VersionedTransaction;
+        inspectionContext?: TxInspectionContext;
+    }): Promise<SandboxExecutionResult>;
+    executePreparedEvmTransaction(input: {
+        solanaKeypair?: Keypair;
+        transaction: ethers.TransactionRequest;
+        address: string;
+        inspectionContext?: TxInspectionContext;
+    }): Promise<{
+        signature: string | null;
+        allowed: boolean;
+        reason?: string;
+        zkProof?: PolicyProof;
+    }>;
+    private resolveProofSigner;
+    private serializeEvmTransaction;
+    private buildProofState;
+}