@nice-code/util 0.5.5 → 0.6.1

package/README.md

@@ -1,6 +1,6 @@
 # @nice-code/util
 
-Typed storage adapters for browser, Cloudflare Durable Objects, and in-memory use.
+Typed storage adapters (browser, Cloudflare Durable Objects, in-memory) and WebCrypto utilities (Ed25519 signing, X25519 key exchange, AES-GCM encryption).
 
 ## Install
 
@@ -12,140 +12,232 @@ bun add @nice-code/util
 
 ## Typed storage
 
-`createTypedStorage` wraps a `StorageAdapter` and adds full TypeScript key and value inference based on a schema type parameter.
+`ITypedStorage<T>` gives you fully typed, async, key-prefixed storage over any backend.
 
 ```ts
 import { createTypedWebLocalStorage } from "@nice-code/util";
 
-// Define the shape of your storage
 interface IAppStorage {
   user_id: string;
   theme: "light" | "dark";
-  last_seen: number;
+  recent_searches: string[];
 }
 
-const storage = createTypedWebLocalStorage<IAppStorage>(localStorage, "app:");
+const storage = createTypedWebLocalStorage<IAppStorage>({
+  localStorage,
+  keyPrefix: "app:",
+});
 
 // All keys autocomplete; values are typed
 await storage.setJson("theme", "dark");
-const theme = await storage.getJson("theme");      // "light" | "dark" | undefined
+const theme = await storage.getJson("theme"); // "light" | "dark" | undefined
 const userId = await storage.getJsonOrDef("user_id", "guest"); // string
-await storage.removeItem("last_seen");
-```
 
-All methods are async and key-prefixed if a prefix is provided.
-
----
+// Read-modify-write in one call
+await storage.updateJsonWithDef("recent_searches", [], (cur) => [...cur, "query"]);
 
-## Available adapters
+await storage.removeItem("theme");
+await storage.clearAll(); // removes only keys this storage has written
+```
 
-### Browser — `localStorage` / `sessionStorage`
+### Adapters
 
 ```ts
 import {
   createTypedWebLocalStorage,
   createTypedWebSessionStorage,
+  createDurableObjectTypedStorage,
+  createTypedMemoryStorage_string,
+  createTypedMemoryStorage_json,
 } from "@nice-code/util";
 
-const local = createTypedWebLocalStorage<IAppStorage>(localStorage, "prefix:");
-const session = createTypedWebSessionStorage<IAppStorage>(sessionStorage);
-```
+// Browser
+const local = createTypedWebLocalStorage<IAppStorage>({ localStorage, keyPrefix: "app:" });
+const session = createTypedWebSessionStorage<IAppStorage>({ sessionStorage });
 
-### Cloudflare Durable Objects
+// Cloudflare Durable Objects (inside a DO class)
+const doStorage = createDurableObjectTypedStorage<IDOStorage>({
+  durableObjectStorage: ctx.storage,
+  keyPrefix: "do:",
+});
 
-```ts
-import { createDurableObjectTypedStorage } from "@nice-code/util";
+// In-memory (testing / SSR) — string-serialized or JSON-native
+const mem = createTypedMemoryStorage_string<IAppStorage>();
+const memJson = createTypedMemoryStorage_json<IAppStorage>();
+
+// Share state between instances by passing the same Map
+const shared = new Map<string, string>();
+const a = createTypedMemoryStorage_string<IAppStorage>({ memoryStorageMap: shared });
+const b = createTypedMemoryStorage_string<IAppStorage>({ memoryStorageMap: shared });
+```
 
-// Inside a Durable Object class
-export class MyDO {
-  private storage: ITypedStorage<IDOStorage>;
+### `ITypedStorage<T>` interface
 
-  constructor(state: DurableObjectState) {
-    this.storage = createDurableObjectTypedStorage<IDOStorage>(state.storage, "do:");
-  }
+```ts
+interface ITypedStorage<T extends Record<string, any>> {
+  getJson<K>(key: K): Promise<T[K] | undefined>;
+  getJsonOrDef<K>(key: K, defVal: T[K]): Promise<T[K]>;
+  setJson<K>(key: K, val: T[K]): Promise<void>;
+  updateJson<K>(key: K, updater: (cur: T[K] | undefined) => T[K]): Promise<void>;
+  updateJsonWithDef<K>(key: K, defVal: T[K], updater: (cur: T[K]) => T[K]): Promise<void>;
+  removeItem<K>(key: K): Promise<void>;
+  clearAll(): Promise<void>;
 }
 ```
 
-### In-memory (testing / SSR)
+### Custom backend
+
+Implement the methods interface to wrap any storage (Redis, KV, …):
 
 ```ts
 import {
-  createTypedMemoryStorage_string,
-  createTypedMemoryStorage_json,
+  createTypedStorage,
+  EStorageAdapterType,
+  StorageAdapter,
+  type IStorageAdapterMethods_String,
 } from "@nice-code/util";
 
-// String-serialized (like localStorage)
-const store = createTypedMemoryStorage_string<IAppStorage>();
-
-// JSON-native (no serialization overhead)
-const jsonStore = createTypedMemoryStorage_json<IAppStorage>();
+const redisMethods: IStorageAdapterMethods_String = {
+  type: EStorageAdapterType.string,
+  getItem: async (key) => redis.get(key),
+  setItem: async (key, value) => { await redis.set(key, value); },
+  removeItem: async (key) => { await redis.del(key); },
+};
 
-// Pass in your own Map to share state between instances
-const shared = new Map<string, string>();
-const a = createTypedMemoryStorage_string<IAppStorage>(shared);
-const b = createTypedMemoryStorage_string<IAppStorage>(shared);
+const storage = createTypedStorage<IMySchema>({
+  storageAdapter: new StorageAdapter({ methods: redisMethods, keyPrefix: "app:" }),
+});
 ```
 
+The lower-level `StorageAdapter` can also be used directly (untyped keys), including
+`createJsonGetterSetter<T>(key)` for a single-key `{ get, set }` pair.
+
 ---
 
-## `ITypedStorage<T>` interface
+## Crypto
+
+WebCrypto-based helpers — work in browsers, Workers / Durable Objects, Bun, and Node.
+
+### Ed25519 — sign & verify
 
 ```ts
-interface ITypedStorage<T extends Record<string, any>> {
-  getJson<K extends keyof T & string>(key: K): Promise<T[K] | undefined>;
-  getJsonOrDef<K extends keyof T & string>(key: K, defVal: T[K]): Promise<T[K]>;
-  setJson<K extends keyof T & string>(key: K, val: T[K]): Promise<void>;
-  removeItem<K extends keyof T & string>(key: K): Promise<void>;
-}
+import {
+  generateEd25519KeyPair,
+  importEd25519Key,
+  serializeEd25519Key_Raw,
+  signTextDataWithKeyEd25519,
+  verifyWithKeyEd25519,
+} from "@nice-code/util";
+import { base64 } from "@scure/base";
+
+const keyPair = await generateEd25519KeyPair();
+
+// Sign
+const signature = await signTextDataWithKeyEd25519("challenge-text", keyPair.privateKey);
+const signatureBase64 = base64.encode(signature);
+
+// Serialize the public key for transport — "ed25519::raw_base64::<data>"
+const { prefixed } = await serializeEd25519Key_Raw(keyPair.publicKey);
+
+// Other side: import + verify
+const publicKey = await importEd25519Key.public.fromFormattedString.extractable(prefixed);
+const isValid = await verifyWithKeyEd25519({
+  challenge: "challenge-text",
+  signatureBase64,
+  publicKey,
+});
 ```
 
----
+Keys serialize to self-describing prefixed strings (`<algo>::<format>::<data>`), so a stored or
+transported key always knows how to re-import itself. Private keys serialize via
+`serializeEd25519Key_Jwk` / `serializeX25519Key_Jwk`; public keys via the `_Raw` variants.
 
-## `StorageAdapter` — low-level
+### X25519 + AES-GCM — shared-key encryption
 
-Use `StorageAdapter` directly when you need a getter/setter pair or want to build a custom typed storage on top.
+Derive a shared AES-GCM key from two X25519 key pairs (ECDH + HKDF), then encrypt/decrypt:
 
 ```ts
-import { StorageAdapter } from "@nice-code/util";
-import { createMemoryStorageMethods_string } from "@nice-code/util";
+import {
+  generateX25519KeyPair,
+  createAesGcmKeyFromX25519Keys,
+  encryptTextDataWithAesGcmKey,
+  decryptTextDataWithAesGcmKey,
+} from "@nice-code/util";
 
-const adapter = new StorageAdapter({
-  methods: createMemoryStorageMethods_string(),
-  keyPrefix: "myapp:",
+const alice = await generateX25519KeyPair();
+const bob = await generateX25519KeyPair();
+
+// Both sides derive the same key from their private + the other's public key
+const aliceKey = await createAesGcmKeyFromX25519Keys({
+  internalX25519PrivateKey: alice.privateKey,
+  externalX25519PublicKey: bob.publicKey,
+  saltString: "optional-session-salt",
+  infoString: "optional-context",
+});
+const bobKey = await createAesGcmKeyFromX25519Keys({
+  internalX25519PrivateKey: bob.privateKey,
+  externalX25519PublicKey: alice.publicKey,
+  saltString: "optional-session-salt",
+  infoString: "optional-context",
 });
 
-await adapter.setJson("token", { value: "abc", exp: 9999 });
-const token = await adapter.getJson<{ value: string; exp: number }>("token");
-const safe = await adapter.getJsonOrDef("token", { value: "", exp: 0 });
+const payload = await encryptTextDataWithAesGcmKey({
+  aesGcmKey: aliceKey,
+  dataToEncrypt: "secret message",
+}); // { nonce, ciphertext } — both base64
 
-// Convenient getter/setter pair for a single key
-const { get, set } = adapter.createJsonGetterSetter<string>("theme");
-await set("dark");
-const theme = await get(); // string | undefined
+const plaintext = await decryptTextDataWithAesGcmKey({
+  aesGcmKey: bobKey,
+  dataToDecrypt: payload,
+});
 ```
 
----
+### `ClientCryptoKeyLink` — full client-to-client crypto
 
-## Custom adapter
-
-Implement `TStorageAdapterMethods` to wrap any storage backend:
+High-level class managing a local identity (Ed25519 verify pair + X25519 exchange pair) and links
+to other clients, with optional persistence through any `StorageAdapter`.
 
 ```ts
-import type { IStorageAdapterMethods_String } from "@nice-code/util";
-import { EStorageAdapterType } from "@nice-code/util";
+import { ClientCryptoKeyLink, createMemoryStorageAdapter_json } from "@nice-code/util";
 
-const redisMethods: IStorageAdapterMethods_String = {
-  type: EStorageAdapterType.string,
-  getItem: async (key) => redis.get(key),
-  setItem: async (key, value) => { await redis.set(key, value); },
-  removeItem: async (key) => { await redis.del(key); },
-};
+const link = new ClientCryptoKeyLink({
+  storageAdapter: createMemoryStorageAdapter_json(), // optional — omit for in-memory only
+});
+await link.initialize();
+
+// Share these with the other side (serialized prefixed strings)
+const { verifyPublicKey, exchangePublicKey } = await link.getLocalPublicKeys();
+
+// Register the other side's keys
+await link.linkClient({
+  linkedClientId: "client::partner-1",
+  verifyPublicKey: theirVerifyKey,
+  exchangePublicKey: theirExchangeKey,
+  // Optionally fold both verify keys into key derivation, so a
+  // tampered relayed key makes the first decryption fail:
+  bindVerifyKeysIntoDerivation: true,
+});
+// linkClientAndStore(...) persists the link across reloads
 
-const storage = createTypedStorage<IMySchema>({
-  storageAdapter: new StorageAdapter({ methods: redisMethods, keyPrefix: "app:" }),
+// Sign + encrypt for the linked client (shared key derived & cached automatically)
+const { encryptedData, signatureBase64 } = await link.signAndEncryptDataForLinkedClient({
+  linkedClientId: "client::partner-1",
+  dataToEncrypt: "hello",
 });
+
+// Other side: decrypt + verify in one call
+const { data, isValid } = await otherLink.decryptAndVerifyDataFromLinkedClient({
+  linkedClientId: "client::me",
+  dataToDecrypt: encryptedData,
+  signatureBase64,
+});
+
+// Also: signChallenge, verifyChallengeFromLinkedClient, encryptDataForLinkedClient,
+// decryptDataFromLinkedClient, unlinkClient, unlinkAllClients, reset
 ```
 
+> Crypto helpers require the `@scure/base` peer dependency.
+
 ---
 
 ## TypeScript utilities