@agentdock/crypto 0.0.1

package/README.md

@@ -0,0 +1,146 @@
+# @agentdock/crypto
+
+> E2E 加密模块 — AES-256-GCM + Ed25519 + NaCl Box/SecretBox，浏览器与 Node.js 22+ 通用。
+
+## 概述
+
+crypto 包实现 AgentDock 的端到端加密。**所有敏感数据在离开用户设备前加密，服务端永远看不到明文**。
+
+支持两种运行环境：
+
+- **浏览器**：Web Crypto API（AES-GCM、HKDF、HMAC）
+- **Node.js 22+**：同样走 Web Crypto API（`globalThis.crypto.subtle`）
+- **tweetnacl**：NaCl Box / SecretBox（跨平台兼容）
+
+## 在架构中的位置
+
+```
+wire → crypto → sdk → web
+wire → crypto → daemon
+```
+
+依赖 wire 的类型定义，被 sdk/daemon/web 使用。
+
+## 模块结构
+
+```
+src/
+├── aes.ts       # AES-256-GCM 加密/解密（Web Crypto API）
+├── auth.ts      # Ed25519 认证挑战（签名/验签）
+├── box.ts       # NaCl Box 非对称加密（密钥交付）
+├── secretbox.ts # NaCl SecretBox 对称加密（legacy 兼容）
+├── content.ts   # Content keypair 派生（从密钥树推导 Box 密钥对）
+├── keys.ts      # 密钥派生树（HKDF-SHA512 分层派生）
+├── hmac.ts      # HMAC-SHA512（消息认证码）
+├── encoding.ts  # Base64 / Base64URL 编解码
+├── random.ts    # 安全随机数生成
+└── index.ts     # Barrel exports
+```
+
+## API 参考
+
+### AES-256-GCM (aes.ts)
+
+```typescript
+import { encryptAesGcm, decryptAesGcm } from '@agentdock/crypto';
+
+// 加密：返回 { c: base64(iv + ciphertext + tag), n: base64(nonce) }
+const bundle = await encryptAesGcm(data: Uint8Array, key: Uint8Array);
+
+// 解密：返回原始明文 Uint8Array
+const plaintext = await decryptAesGcm(bundle, key);
+```
+
+Bundle 格式：`iv(12 bytes) + ciphertext + tag(16 bytes)`，整体 Base64 编码。
+
+### Ed25519 认证 (auth.ts)
+
+```typescript
+import { authChallenge, verifyChallenge } from '@agentdock/crypto';
+
+// 从 seed 生成 Ed25519 密钥对 + 签名挑战
+const result = await authChallenge(seed: Uint8Array);
+// { publicKey, secretKey, challenge, signature }
+
+// 验证签名
+const valid = await verifyChallenge(challenge, signature, publicKey);
+```
+
+**注意**：直接使用 seed 作为 Ed25519 种子，不做额外 deriveKey（与 Happy 对齐，见 L23）。
+
+### NaCl Box (box.ts)
+
+```typescript
+import { encryptBox, decryptBox, boxPublicKeyFromSecretKey } from '@agentdock/crypto';
+
+// 非对称加密（发送方用接收方公钥加密）
+const bundle = encryptBox(data: Uint8Array, recipientPublicKey: Uint8Array);
+
+// 解密（接收方用自己的私钥 + 发送方公钥解密）
+const plaintext = decryptBox(bundle, secretKey: Uint8Array);
+
+// 从 X25519 私钥推导公钥
+const publicKey = boxPublicKeyFromSecretKey(secretKey);
+```
+
+### NaCl SecretBox (secretbox.ts)
+
+```typescript
+import { encryptSecretBox, decryptSecretBox } from '@agentdock/crypto';
+
+// 对称加密（legacy 兼容）
+const bundle = encryptSecretBox(data: Uint8Array, secret: Uint8Array);
+const plaintext = decryptSecretBox(bundle, secret);
+```
+
+### 密钥派生树 (keys.ts)
+
+```typescript
+import { deriveSecretKeyTreeRoot, deriveSecretKeyTreeChild, deriveKey } from '@agentdock/crypto';
+
+// 从根密钥 + 标签派生子密钥
+const root = await deriveSecretKeyTreeRoot(masterSecret, 'Happy EnCoder');
+const child = await deriveSecretKeyTreeChild(root, 'content');
+
+// 底层：HKDF-SHA512 派生
+const key = await deriveKey(secret, label, segments);
+```
+
+### Content Keypair (content.ts)
+
+```typescript
+import { deriveContentKeyPair } from '@agentdock/crypto';
+
+// 'Happy EnCoder' + ['content'] + SHA-512[0:32] → NaCl Box keypair
+const { publicKey, secretKey } = await deriveContentKeyPair(secret);
+```
+
+### HMAC-SHA512 (hmac.ts)
+
+```typescript
+import { hmacSha512 } from '@agentdock/crypto';
+const mac = await hmacSha512(key, data);
+```
+
+### 编码 (encoding.ts)
+
+```typescript
+import { encodeBase64, decodeBase64, encodeBase64Url, decodeBase64Url } from '@agentdock/crypto';
+```
+
+## 开发
+
+```bash
+# 运行测试（111 tests）
+pnpm --filter @agentdock/crypto test
+
+# 覆盖率（目标 95%+）
+pnpm --filter @agentdock/crypto test:coverage
+```
+
+## 设计决策
+
+- **Web Crypto API 优先**：AES-GCM、HKDF、HMAC 全走 `crypto.subtle`，不引入额外依赖
+- **tweetnacl 用于 NaCl**：Box/SecretBox 使用 tweetnacl，因为 Web Crypto 不支持 X25519 Box
+- **密钥派生路径与 Happy 完全一致**：确保两端互操作（L23 教训）
+- **TypeScript `as BufferSource` 断言**：TS 5.7 的 Uint8Array 类型不兼容 Web Crypto（L7 教训）

package/dist/aes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * AES-256-GCM encryption and decryption using the Web Crypto API.
+ *
+ * Bundle format (compatible with Happy protocol):
+ *   version (1 byte) | nonce (12 bytes) | ciphertext + authTag
+ *
+ * - version: always 0 for this implementation
+ * - nonce: 12-byte IV for AES-GCM
+ * - ciphertext + authTag: Web Crypto API returns these concatenated
+ *   (authTag is the last 16 bytes)
+ *
+ * Data is JSON-serialized before encryption and JSON-parsed after decryption.
+ */
+/**
+ * Encrypt arbitrary JSON-serializable data with AES-256-GCM.
+ *
+ * @param data - Any JSON-serializable value.
+ * @param key  - 32-byte (256-bit) encryption key.
+ * @returns Encrypted bundle as Uint8Array.
+ * @throws If the key is not exactly 32 bytes.
+ */
+export declare function encryptAesGcm(data: unknown, key: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decrypt an AES-256-GCM bundle back to the original data.
+ *
+ * @param bundle - Encrypted bundle produced by `encryptAesGcm`.
+ * @param key    - 32-byte (256-bit) decryption key (must match encryption key).
+ * @returns The decrypted data, or `null` if decryption fails.
+ * @throws If the key is not exactly 32 bytes.
+ */
+export declare function decryptAesGcm(bundle: Uint8Array, key: Uint8Array): Promise<unknown | null>;
+//# sourceMappingURL=aes.d.ts.map

package/dist/aes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aes.d.ts","sourceRoot":"","sources":["../src/aes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAmBH;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAqBvF;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CA+BhG"}

package/dist/aes.js

@@ -0,0 +1,95 @@
+/**
+ * AES-256-GCM encryption and decryption using the Web Crypto API.
+ *
+ * Bundle format (compatible with Happy protocol):
+ *   version (1 byte) | nonce (12 bytes) | ciphertext + authTag
+ *
+ * - version: always 0 for this implementation
+ * - nonce: 12-byte IV for AES-GCM
+ * - ciphertext + authTag: Web Crypto API returns these concatenated
+ *   (authTag is the last 16 bytes)
+ *
+ * Data is JSON-serialized before encryption and JSON-parsed after decryption.
+ */
+import { getRandomBytes } from './random.js';
+/** Current bundle format version. */
+const BUNDLE_VERSION = 0;
+/** AES-GCM nonce size in bytes. */
+const NONCE_SIZE = 12;
+/** AES-GCM authentication tag size in bytes. */
+const AUTH_TAG_SIZE = 16;
+/** Minimum bundle size: version(1) + nonce(12) + authTag(16). */
+const MIN_BUNDLE_SIZE = 1 + NONCE_SIZE + AUTH_TAG_SIZE;
+/** Required AES-256 key size in bytes. */
+const KEY_SIZE = 32;
+/**
+ * Encrypt arbitrary JSON-serializable data with AES-256-GCM.
+ *
+ * @param data - Any JSON-serializable value.
+ * @param key  - 32-byte (256-bit) encryption key.
+ * @returns Encrypted bundle as Uint8Array.
+ * @throws If the key is not exactly 32 bytes.
+ */
+export async function encryptAesGcm(data, key) {
+    assertKeySize(key);
+    const plaintext = new TextEncoder().encode(JSON.stringify(data));
+    const nonce = getRandomBytes(NONCE_SIZE);
+    const cryptoKey = await importKey(key, ['encrypt']);
+    const encrypted = await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv: nonce }, cryptoKey, plaintext);
+    // Build bundle: version + nonce + (ciphertext + authTag)
+    const encryptedBytes = new Uint8Array(encrypted);
+    const bundle = new Uint8Array(1 + NONCE_SIZE + encryptedBytes.length);
+    bundle[0] = BUNDLE_VERSION;
+    bundle.set(nonce, 1);
+    bundle.set(encryptedBytes, 1 + NONCE_SIZE);
+    return bundle;
+}
+/**
+ * Decrypt an AES-256-GCM bundle back to the original data.
+ *
+ * @param bundle - Encrypted bundle produced by `encryptAesGcm`.
+ * @param key    - 32-byte (256-bit) decryption key (must match encryption key).
+ * @returns The decrypted data, or `null` if decryption fails.
+ * @throws If the key is not exactly 32 bytes.
+ */
+export async function decryptAesGcm(bundle, key) {
+    assertKeySize(key);
+    // Validate minimum bundle size
+    if (bundle.length < MIN_BUNDLE_SIZE) {
+        return null;
+    }
+    // Validate version
+    if (bundle[0] !== BUNDLE_VERSION) {
+        return null;
+    }
+    // Extract nonce and ciphertext+authTag
+    const nonce = bundle.slice(1, 1 + NONCE_SIZE);
+    const ciphertextWithTag = bundle.slice(1 + NONCE_SIZE);
+    try {
+        const cryptoKey = await importKey(key, ['decrypt']);
+        const decrypted = await globalThis.crypto.subtle.decrypt({ name: 'AES-GCM', iv: nonce }, cryptoKey, ciphertextWithTag);
+        const json = new TextDecoder().decode(decrypted);
+        return JSON.parse(json);
+    }
+    catch {
+        // Decryption or JSON parsing failed -- return null per contract
+        return null;
+    }
+}
+/**
+ * Import a raw key for AES-GCM operations.
+ */
+async function importKey(key, usages) {
+    return globalThis.crypto.subtle.importKey('raw', key, 'AES-GCM', false, [
+        ...usages,
+    ]);
+}
+/**
+ * Assert that a key is exactly 32 bytes (AES-256).
+ */
+function assertKeySize(key) {
+    if (key.length !== KEY_SIZE) {
+        throw new Error(`AES-256-GCM requires a 32-byte key, got ${key.length} bytes`);
+    }
+}
+//# sourceMappingURL=aes.js.map

package/dist/aes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aes.js","sourceRoot":"","sources":["../src/aes.ts"],"names":[],"mappings":"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"}

package/dist/auth.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Ed25519 authentication challenge — aligned with Happy.
+ *
+ * Uses tweetnacl for Ed25519 signing/verification, which works in
+ * ALL contexts (including non-secure HTTP). The raw 32-byte seed is
+ * used directly as the Ed25519 private key seed, WITHOUT any extra
+ * key derivation step, matching Happy's tweetnacl.sign.keyPair.fromSeed().
+ *
+ * Previous implementation used Web Crypto API (crypto.subtle) which
+ * requires a secure context (HTTPS or localhost). This broke mobile
+ * PWA access over LAN (http://192.168.x.x).
+ */
+/**
+ * Result of an authentication challenge.
+ * All fields are immutable Uint8Array instances.
+ */
+export type AuthChallengeResult = {
+    readonly challenge: Uint8Array;
+    readonly publicKey: Uint8Array;
+    readonly signature: Uint8Array;
+};
+/**
+ * Generate an authentication challenge signed with an Ed25519 key
+ * derived from the given seed.
+ *
+ * The seed is used directly as the Ed25519 private key seed (no extra
+ * key derivation), matching Happy's tweetnacl.sign.keyPair.fromSeed().
+ *
+ * @param seed - 32-byte seed for deterministic Ed25519 key pair
+ * @returns Challenge result with random nonce, public key, and signature
+ */
+export declare function authChallenge(seed: Uint8Array): Promise<AuthChallengeResult>;
+/**
+ * Sign an externally-provided challenge nonce with an Ed25519 key
+ * derived from the given seed. Used for server-driven auth flows
+ * where the server issues the nonce.
+ *
+ * @param nonce - Challenge nonce provided by the server
+ * @param seed - 32-byte seed for deterministic Ed25519 key pair
+ * @returns Public key and signature over the nonce
+ */
+export declare function signChallenge(nonce: Uint8Array, seed: Uint8Array): Promise<{
+    readonly publicKey: Uint8Array;
+    readonly signature: Uint8Array;
+}>;
+/**
+ * Verify an authentication challenge signature.
+ *
+ * @param challenge - The challenge nonce
+ * @param publicKey - The 32-byte Ed25519 public key
+ * @param signature - The 64-byte Ed25519 signature
+ * @returns true if the signature is valid
+ */
+export declare function verifyChallenge(challenge: Uint8Array, publicKey: Uint8Array, signature: Uint8Array): Promise<boolean>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;CAChC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAclF;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC;IAAE,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAA;CAAE,CAAC,CAQ7E;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,UAAU,EACrB,SAAS,EAAE,UAAU,EACrB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,OAAO,CAAC,CAMlB"}

package/dist/auth.js

@@ -0,0 +1,69 @@
+/**
+ * Ed25519 authentication challenge — aligned with Happy.
+ *
+ * Uses tweetnacl for Ed25519 signing/verification, which works in
+ * ALL contexts (including non-secure HTTP). The raw 32-byte seed is
+ * used directly as the Ed25519 private key seed, WITHOUT any extra
+ * key derivation step, matching Happy's tweetnacl.sign.keyPair.fromSeed().
+ *
+ * Previous implementation used Web Crypto API (crypto.subtle) which
+ * requires a secure context (HTTPS or localhost). This broke mobile
+ * PWA access over LAN (http://192.168.x.x).
+ */
+import nacl from 'tweetnacl';
+/**
+ * Generate an authentication challenge signed with an Ed25519 key
+ * derived from the given seed.
+ *
+ * The seed is used directly as the Ed25519 private key seed (no extra
+ * key derivation), matching Happy's tweetnacl.sign.keyPair.fromSeed().
+ *
+ * @param seed - 32-byte seed for deterministic Ed25519 key pair
+ * @returns Challenge result with random nonce, public key, and signature
+ */
+export async function authChallenge(seed) {
+    const keyPair = nacl.sign.keyPair.fromSeed(seed);
+    // Generate random 32-byte challenge
+    const challenge = nacl.randomBytes(32);
+    // Sign the challenge
+    const signature = nacl.sign.detached(challenge, keyPair.secretKey);
+    return {
+        challenge,
+        publicKey: keyPair.publicKey,
+        signature,
+    };
+}
+/**
+ * Sign an externally-provided challenge nonce with an Ed25519 key
+ * derived from the given seed. Used for server-driven auth flows
+ * where the server issues the nonce.
+ *
+ * @param nonce - Challenge nonce provided by the server
+ * @param seed - 32-byte seed for deterministic Ed25519 key pair
+ * @returns Public key and signature over the nonce
+ */
+export async function signChallenge(nonce, seed) {
+    const keyPair = nacl.sign.keyPair.fromSeed(seed);
+    const signature = nacl.sign.detached(nonce, keyPair.secretKey);
+    return {
+        publicKey: keyPair.publicKey,
+        signature,
+    };
+}
+/**
+ * Verify an authentication challenge signature.
+ *
+ * @param challenge - The challenge nonce
+ * @param publicKey - The 32-byte Ed25519 public key
+ * @param signature - The 64-byte Ed25519 signature
+ * @returns true if the signature is valid
+ */
+export async function verifyChallenge(challenge, publicKey, signature) {
+    try {
+        return nacl.sign.detached.verify(challenge, signature, publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAY7B;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAgB;IAClD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEjD,oCAAoC;IACpC,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAEvC,qBAAqB;IACrB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAEnE,OAAO;QACL,SAAS;QACT,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,SAAS;KACV,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAiB,EACjB,IAAgB;IAEhB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAE/D,OAAO;QACL,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,SAAS;KACV,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,SAAqB,EACrB,SAAqB,EACrB,SAAqB;IAErB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/box.d.ts

@@ -0,0 +1,50 @@
+/**
+ * NaCl Box encryption — aligned with Happy.
+ *
+ * Ephemeral X25519 Diffie-Hellman key agreement + authenticated encryption.
+ * Used for encrypting data for a specific recipient (key delivery).
+ *
+ * Bundle format: ephemeral_pubkey(32) + nonce(24) + ciphertext
+ */
+/**
+ * Encrypt data for a recipient's public key using NaCl Box.
+ *
+ * Generates an ephemeral keypair, performs DH key agreement,
+ * and encrypts with authenticated encryption (XSalsa20-Poly1305).
+ *
+ * @param data - Plaintext data to encrypt
+ * @param recipientPublicKey - 32-byte X25519 public key of the recipient
+ * @returns Bundle: ephemeral_pubkey(32) + nonce(24) + ciphertext
+ */
+export declare function encryptBox(data: Uint8Array, recipientPublicKey: Uint8Array): Uint8Array;
+/**
+ * Decrypt a NaCl Box bundle using the recipient's secret key.
+ *
+ * @param bundle - Bundle: ephemeral_pubkey(32) + nonce(24) + ciphertext
+ * @param recipientSecretKey - 32-byte X25519 secret key
+ * @returns Decrypted plaintext, or null if decryption fails
+ */
+export declare function decryptBox(bundle: Uint8Array, recipientSecretKey: Uint8Array): Uint8Array | null;
+/** X25519 keypair for NaCl Box operations. */
+export interface BoxKeyPair {
+    readonly publicKey: Uint8Array;
+    readonly secretKey: Uint8Array;
+}
+/**
+ * Generate a random X25519 keypair for NaCl Box operations.
+ *
+ * @returns BoxKeyPair with 32-byte publicKey and secretKey
+ */
+export declare function generateBoxKeyPair(): BoxKeyPair;
+/**
+ * Derive a NaCl Box public key from a secret key.
+ *
+ * NOTE: This matches libsodium's behavior — tweetnacl requires the
+ * secret key to already be the hashed form. For seed-based derivation,
+ * use deriveContentKeyPair() instead.
+ *
+ * @param secretKey - 32-byte X25519 secret key
+ * @returns 32-byte X25519 public key
+ */
+export declare function boxPublicKeyFromSecretKey(secretKey: Uint8Array): Uint8Array;
+//# sourceMappingURL=box.d.ts.map

package/dist/box.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"box.d.ts","sourceRoot":"","sources":["../src/box.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,kBAAkB,EAAE,UAAU,GAAG,UAAU,CAWvF;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,kBAAkB,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAShG;AAED,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,UAAU,CAM/C;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,CAE3E"}

package/dist/box.js

@@ -0,0 +1,73 @@
+/**
+ * NaCl Box encryption — aligned with Happy.
+ *
+ * Ephemeral X25519 Diffie-Hellman key agreement + authenticated encryption.
+ * Used for encrypting data for a specific recipient (key delivery).
+ *
+ * Bundle format: ephemeral_pubkey(32) + nonce(24) + ciphertext
+ */
+import nacl from 'tweetnacl';
+import { getRandomBytes } from './random.js';
+/**
+ * Encrypt data for a recipient's public key using NaCl Box.
+ *
+ * Generates an ephemeral keypair, performs DH key agreement,
+ * and encrypts with authenticated encryption (XSalsa20-Poly1305).
+ *
+ * @param data - Plaintext data to encrypt
+ * @param recipientPublicKey - 32-byte X25519 public key of the recipient
+ * @returns Bundle: ephemeral_pubkey(32) + nonce(24) + ciphertext
+ */
+export function encryptBox(data, recipientPublicKey) {
+    const ephemeralKeyPair = nacl.box.keyPair();
+    const nonce = getRandomBytes(nacl.box.nonceLength);
+    const encrypted = nacl.box(data, nonce, recipientPublicKey, ephemeralKeyPair.secretKey);
+    // Bundle: ephemeral pubkey(32) + nonce(24) + ciphertext
+    const result = new Uint8Array(32 + 24 + encrypted.length);
+    result.set(ephemeralKeyPair.publicKey, 0);
+    result.set(nonce, 32);
+    result.set(encrypted, 56);
+    return result;
+}
+/**
+ * Decrypt a NaCl Box bundle using the recipient's secret key.
+ *
+ * @param bundle - Bundle: ephemeral_pubkey(32) + nonce(24) + ciphertext
+ * @param recipientSecretKey - 32-byte X25519 secret key
+ * @returns Decrypted plaintext, or null if decryption fails
+ */
+export function decryptBox(bundle, recipientSecretKey) {
+    if (bundle.length < 32 + 24)
+        return null;
+    const ephemeralPublicKey = bundle.slice(0, 32);
+    const nonce = bundle.slice(32, 56);
+    const ciphertext = bundle.slice(56);
+    const decrypted = nacl.box.open(ciphertext, nonce, ephemeralPublicKey, recipientSecretKey);
+    return decrypted ? new Uint8Array(decrypted) : null;
+}
+/**
+ * Generate a random X25519 keypair for NaCl Box operations.
+ *
+ * @returns BoxKeyPair with 32-byte publicKey and secretKey
+ */
+export function generateBoxKeyPair() {
+    const kp = nacl.box.keyPair();
+    return {
+        publicKey: new Uint8Array(kp.publicKey),
+        secretKey: new Uint8Array(kp.secretKey),
+    };
+}
+/**
+ * Derive a NaCl Box public key from a secret key.
+ *
+ * NOTE: This matches libsodium's behavior — tweetnacl requires the
+ * secret key to already be the hashed form. For seed-based derivation,
+ * use deriveContentKeyPair() instead.
+ *
+ * @param secretKey - 32-byte X25519 secret key
+ * @returns 32-byte X25519 public key
+ */
+export function boxPublicKeyFromSecretKey(secretKey) {
+    return new Uint8Array(nacl.box.keyPair.fromSecretKey(secretKey).publicKey);
+}
+//# sourceMappingURL=box.js.map

package/dist/box.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"box.js","sourceRoot":"","sources":["../src/box.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,IAAgB,EAAE,kBAA8B;IACzE,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IAC5C,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAExF,wDAAwD;IACxD,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAC1D,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAC1C,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACtB,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,MAAkB,EAAE,kBAA8B;IAC3E,IAAI,MAAM,CAAC,MAAM,GAAG,EAAE,GAAG,EAAE;QAAE,OAAO,IAAI,CAAC;IAEzC,MAAM,kBAAkB,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACnC,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAEpC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,CAAC,CAAC;IAC3F,OAAO,SAAS,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACtD,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IAC9B,OAAO;QACL,SAAS,EAAE,IAAI,UAAU,CAAC,EAAE,CAAC,SAAS,CAAC;QACvC,SAAS,EAAE,IAAI,UAAU,CAAC,EAAE,CAAC,SAAS,CAAC;KACxC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAAqB;IAC7D,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC;AAC7E,CAAC"}

package/dist/content.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Content keypair derivation — aligned with Happy.
+ *
+ * Derives an X25519 NaCl Box keypair from a secret using the key tree.
+ * Usage string: 'Happy EnCoder', path: ['content'].
+ *
+ * The derived seed is SHA-512 hashed and the first 32 bytes become the
+ * Box secret key, matching libsodium's crypto_box_seed_keypair behavior.
+ */
+/**
+ * Derive a NaCl Box keypair for content encryption.
+ *
+ * Follows Happy's deriveContentKeyPair():
+ * 1. deriveKey(secret, 'Happy EnCoder', ['content']) → 32-byte seed
+ * 2. SHA-512(seed)[0:32] → box secret key (matching libsodium)
+ * 3. tweetnacl.box.keyPair.fromSecretKey(boxSecretKey) → keypair
+ *
+ * Since we use Web Crypto (no node:crypto), we approximate SHA-512
+ * using HMAC-SHA512 with the seed as both key and data, then take
+ * the first 32 bytes. This produces a deterministic 32-byte output
+ * for a given seed, matching the intent of SHA-512(seed)[0:32].
+ *
+ * @param secret - Master secret for key derivation
+ * @returns NaCl Box keypair { publicKey, secretKey }
+ */
+export declare function deriveContentKeyPair(secret: Uint8Array): Promise<{
+    readonly publicKey: Uint8Array;
+    readonly secretKey: Uint8Array;
+}>;
+//# sourceMappingURL=content.d.ts.map

package/dist/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC;IAAE,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAA;CAAE,CAAC,CAa7E"}

package/dist/content.js

@@ -0,0 +1,40 @@
+/**
+ * Content keypair derivation — aligned with Happy.
+ *
+ * Derives an X25519 NaCl Box keypair from a secret using the key tree.
+ * Usage string: 'Happy EnCoder', path: ['content'].
+ *
+ * The derived seed is SHA-512 hashed and the first 32 bytes become the
+ * Box secret key, matching libsodium's crypto_box_seed_keypair behavior.
+ */
+import nacl from 'tweetnacl';
+import { deriveKey } from './keys.js';
+/**
+ * Derive a NaCl Box keypair for content encryption.
+ *
+ * Follows Happy's deriveContentKeyPair():
+ * 1. deriveKey(secret, 'Happy EnCoder', ['content']) → 32-byte seed
+ * 2. SHA-512(seed)[0:32] → box secret key (matching libsodium)
+ * 3. tweetnacl.box.keyPair.fromSecretKey(boxSecretKey) → keypair
+ *
+ * Since we use Web Crypto (no node:crypto), we approximate SHA-512
+ * using HMAC-SHA512 with the seed as both key and data, then take
+ * the first 32 bytes. This produces a deterministic 32-byte output
+ * for a given seed, matching the intent of SHA-512(seed)[0:32].
+ *
+ * @param secret - Master secret for key derivation
+ * @returns NaCl Box keypair { publicKey, secretKey }
+ */
+export async function deriveContentKeyPair(secret) {
+    const seed = await deriveKey(secret, 'Happy EnCoder', ['content']);
+    // Match libsodium: crypto_box_seed_keypair does SHA-512(seed)[0:32]
+    // We use Web Crypto SHA-512 directly
+    const hashBuffer = await crypto.subtle.digest('SHA-512', seed);
+    const boxSecretKey = new Uint8Array(hashBuffer).slice(0, 32);
+    const keyPair = nacl.box.keyPair.fromSecretKey(boxSecretKey);
+    return {
+        publicKey: new Uint8Array(keyPair.publicKey),
+        secretKey: new Uint8Array(keyPair.secretKey),
+    };
+}
+//# sourceMappingURL=content.js.map

package/dist/content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAkB;IAElB,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAEnE,oEAAoE;IACpE,qCAAqC;IACrC,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAoB,CAAC,CAAC;IAC/E,MAAM,YAAY,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAE7D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;IAC7D,OAAO;QACL,SAAS,EAAE,IAAI,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC;QAC5C,SAAS,EAAE,IAAI,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC;KAC7C,CAAC;AACJ,CAAC"}

package/dist/encoding.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Base64 and Base64URL encoding/decoding utilities.
+ *
+ * Uses browser-compatible APIs (no Node.js Buffer dependency).
+ * Works in both browser and Node.js 22+ environments.
+ */
+/**
+ * Encode a Uint8Array to a standard Base64 string.
+ */
+export declare function encodeBase64(buffer: Uint8Array): string;
+/**
+ * Decode a standard Base64 string to a Uint8Array.
+ */
+export declare function decodeBase64(base64: string): Uint8Array;
+/**
+ * Encode a Uint8Array to a Base64URL string (no padding).
+ *
+ * Base64URL replaces `+` with `-`, `/` with `_`, and strips `=` padding.
+ */
+export declare function encodeBase64Url(buffer: Uint8Array): string;
+/**
+ * Decode a Base64URL string to a Uint8Array.
+ */
+export declare function decodeBase64Url(base64url: string): Uint8Array;
+//# sourceMappingURL=encoding.d.ts.map

package/dist/encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../src/encoding.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CASvD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CASvD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAG1D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAU7D"}