@saw-protocol/keystore-env

A dynamic, structurally encrypted Environment Keystore for the SAW Protocol.

This module implements the IKeyStore interface by storing multiple Agent Wallets locally in a targeted .sawp_<extension> JSON file. This is highly suitable for local development or heavily secured server environments.

By passing an encryptionKey option, the Keystore seamlessly utilizes AES-256-GCM to ensure credentials never touch the disk in plain-text.

Installation

npm install @saw-protocol/keystore-env

Example Usage

1. Initializing and Utilizing the Keystore

import { EnvKeyStore } from "@saw-protocol/keystore-env";
import { Transaction, SystemProgram, PublicKey } from "@solana/web3.js";

// Initialize securely. This will read/write from `.sawp_devnet` securely
const keystore = new EnvKeyStore({
  extensionName: "devnet",
  storageDir: process.cwd(), // Default directory
  encryptionKey: "super_secret_aes_passphrase", // Enables AES-256-GCM serialization
});

const myAgentDID = "did:sol:agentX123";

// Create a new keypair tagged to this Agent
const newWalletAddress = await keystore.create(myAgentDID);
console.log("Generated Wallet Address:", newWalletAddress.toBase58());

// Or, import an existing Keypair securely into the .sawp file
// const importedAddress = await keystore.import(myAgentDID, myExistingSecretKeyUint8Array);

// Fetch all keys mapped to this agent
const wallets = await keystore.listWallets(myAgentDID);

// Construct a raw solana transaction
const tx = new Transaction().add(
  SystemProgram.transfer({
    fromPubkey: newWalletAddress,
    toPubkey: new PublicKey("..."),
    lamports: 1000000,
  }),
);

// Abstractly Sign without exposing the key material
const signedTx = await keystore.sign(newWalletAddress, tx);

2. Exporting Secrets

import { Keypair } from "@solana/web3.js";

const externalEncryptionKeypair = Keypair.generate();

// Securely wraps the target secret payload in AES utilizing a hash of the target encryptionKey
const bundle = await keystore.export(
  newWalletAddress,
  externalEncryptionKeypair.publicKey,
);

console.log("Algorithm:", bundle.algo);
console.log("Encrypted Payload:", bundle.data);