SDK Reference

Core library functions for encryption, decryption, auth, and memory operations in the MNEMOS vault.

lib/crypto.ts

All encryption and decryption runs through this module using the browser's native WebCrypto API.

deriveKeyFromWallet

Derives a non-extractable AES-256-GCM key from a wallet signature. Call once per session and cache the result.

typescript

import { deriveKeyFromWallet } from "@/lib/crypto";
import { useSignMessage } from "wagmi";

const { signMessageAsync } = useSignMessage();
const key = await deriveKeyFromWallet(signMessageAsync);
// Returns: CryptoKey (non-extractable, AES-256-GCM)

encryptContent

Encrypts a plaintext string with the derived key. Generates a fresh 96-bit IV per call.

typescript

import { encryptContent } from "@/lib/crypto";

const ciphertext = await encryptContent("Meeting notes...", key);
// Returns: "base64url(iv).base64url(ciphertext)" string
// Safe to store on the server — no IV reuse, AEAD authenticated

decryptContent

Decrypts a ciphertext string produced by encryptContent. Throws if the key is wrong or the data was tampered with.

typescript

import { decryptContent } from "@/lib/crypto";

const plaintext = await decryptContent(memory.ciphertext, key);
// Returns: decrypted string
// Throws: DOMException if authentication fails (wrong key or tampered data)

lib/auth.ts

Wallet signature authentication for mutation endpoints.

buildAuthMessage

Constructs the canonical message to sign for API authentication.

typescript

import { buildAuthMessage } from "@/lib/auth";

const timestamp = Date.now();
const message = buildAuthMessage("create-memory", walletAddress, timestamp);
// Returns: "mnemos:create-memory:{walletAddress}:{timestamp}"

const signature = await signMessageAsync({ message });
// Include { walletAddress, timestamp, signature } in API request body

verifyAuth

Server-side: verifies a wallet signature and checks timestamp freshness (5-minute window).

typescript

import { verifyAuth } from "@/lib/auth";

// In an API route handler:
const { walletAddress, timestamp, signature } = await req.json();
const valid = await verifyAuth("create-memory", walletAddress, timestamp, signature);
if (!valid) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });

lib/neon.ts — memory helpers

Direct Neon Postgres helpers for memory CRUD. Used by API route handlers.

createMemory

typescript

import { createMemory } from "@/lib/neon";

const memory = await createMemory({
  walletAddress: "0x...",
  ciphertext: "base64url(iv).base64url(ct)",
  category: "context",
  tags: ["work", "meeting"],
  title: "AI-generated title",
  source: "vault",
});
// Returns: MemoryRecord

listMemories

typescript

import { listMemories } from "@/lib/neon";

const memories = await listMemories({
  walletAddress: "0x...",
  category: "decision",    // optional filter
  limit: 20,
  cursor: lastId,          // cursor-based pagination
});
// Returns: MemoryRecord[]

searchMemories

Semantic similarity search using Voyage AI embeddings stored in the embedding column.

typescript

import { searchMemories } from "@/lib/neon";

const results = await searchMemories({
  walletAddress: "0x...",
  query: "health patterns from last month",
  limit: 10,
});
// Returns: MemoryRecord[] sorted by cosine similarity

lib/vault-crypto.ts — shared vaults

ECDH P-256 key exchange utilities for shared vault operations.

generateEcdhKeyPair

typescript

import { generateEcdhKeyPair } from "@/lib/vault-crypto";

const { publicKey, privateKey } = await generateEcdhKeyPair();
// publicKey: SPKI base64url P-256 public key (stored on server, readable by anyone)
// privateKey: PKCS#8 P-256 private key (wrapped with wallet key before storing)

wrapVaultKeyForInvitee

typescript

import { wrapVaultKeyForInvitee } from "@/lib/vault-crypto";

const { wrappedVaultKey, ephemeralPubkey } = await wrapVaultKeyForInvitee(
  vaultKey,            // CryptoKey — the shared vault's symmetric key
  inviteePubkeySpki    // string — invitee's SPKI base64url public key
);
// Stored on VaultMember row — only invitee can unwrap using their private key

WalletCryptoProvider

React context provider that manages the wallet-derived crypto key for the vault UI. Wraps the entire vault with the key in context so all components can encrypt/decrypt without re-deriving.

typescript

// src/providers/WalletCryptoProvider.tsx
// Usage: wraps the vault dashboard
import { useCryptoKey } from "@/providers/WalletCryptoProvider";

const { cryptoKey, deriveKey, clearKey } = useCryptoKey();

// cryptoKey: CryptoKey | null — present after signing
// deriveKey(): prompts wallet signature → derives and caches key
// clearKey(): clears the cached key (used on disconnect)

TIP

The crypto key is held in a React ref — it is not stored in localStorage or anywhere persistent. Refreshing the page or disconnecting requires signing again.