api-ape 3.0.1 → 4.1.0

package/client/README.md

@@ -1,14 +1,25 @@
 # 🦍 api-ape Client
 
-WebSocket client library with auto-reconnection and proxy-based API calls.
+![api-ape mascot](../assets/friend.jpg)
 
-## Files
+## Overview
 
-| File | Description |
-|------|-------------|
-| `index.js` | **Unified entry** — auto-initializing client with call buffering |
-| `browser.js` | Browser entry point — exposes `window.ape` |
-| `connectSocket.js` | WebSocket client with auto-reconnect, queuing, and JJS encoding |
+The client module provides the browser-side WebSocket client for api-ape. It enables seamless communication with api-ape servers through a proxy-based API that converts method calls like `api.users.list()` into WebSocket messages.
+
+**Key capabilities:**
+
+- **Proxy-based API** — Call server endpoints like local methods (`api.path.method(data)`)
+- **Auto-reconnection** — Automatically reconnects with exponential backoff on disconnection
+- **Call buffering** — Queues calls made before connection is established
+- **JSS encoding** — Supports Date, RegExp, Error, Set, Map, and undefined over the wire
+- **HTTP fallback** — Falls back to long-polling when WebSocket is blocked
+- **Binary transfers** — Transparent file upload/download handling
+- **Connection state** — Track connection status (offline, connecting, connected, disconnected)
+- **Pub/sub subscriptions** — Subscribe to channels and receive targeted updates
+
+The client works in both browser environments (via `<script>` tag) and bundled applications (React, Vue, etc.).
+
+> **Contributing?** See [`files.md`](./files.md) for directory structure and file descriptions.
 
 ## Usage
 
@@ -17,11 +28,14 @@ WebSocket client library with auto-reconnection and proxy-based API calls.
 ```html
 <script src="/api/ape.js"></script>
 <script>
-  // Call server functions
+  // Call server functions (RPC)
   api.hello('World').then(result => console.log(result))
-  
-  // Listen for broadcasts
-  api.on('message', ({ data }) => console.log(data))
+
+  // Subscribe to channels (pass a callback function)
+  const unsub = api.message(data => console.log(data))
+
+  // Unsubscribe when done
+  unsub()
 </script>
 ```
 
@@ -37,8 +51,13 @@ import api from 'api-ape'
 // Just use it! Calls are buffered until connected.
 api.users.list().then(users => console.log(users))
 
-// Listen for broadcasts
-api.on('message', ({ data }) => console.log(data))
+// Subscribe to channels (pass a callback function)
+const unsub = api.news.banking(data => {
+  console.log('Received:', data)
+})
+
+// Unsubscribe when done
+unsub()
 
 // Track connection state
 api.onConnectionChange((state) => {
@@ -53,6 +72,7 @@ api.onConnectionChange((state) => {
 - `disconnected` — Had connection, lost it
 - `connecting` — Actively connecting
 - `connected` — Ready to use
+- `closing` — Connection is closing
 
 **No async setup needed!** The client auto-initializes and buffers calls until connected.
 
@@ -61,7 +81,7 @@ api.onConnectionChange((state) => {
 - **Proxy-based API** — `ape.path.method(data)` converts to WebSocket calls
 - **Auto-reconnect** — Reconnects on disconnect with queued messages
 - **Promise-based** — All calls return promises with matched responses via queryId
-- **JJS encoding** — Supports Date, RegExp, Error, Set, Map, undefined over the wire
+- **JSS encoding** — Supports Date, RegExp, Error, Set, Map, undefined over the wire
 - **Request timeout** — Configurable timeout (default: 10s)
 
 ## File Transfers
@@ -95,6 +115,45 @@ await api.files.upload({
 
 Binary transfers use `/api/ape/data/:hash` endpoints with session verification.
 
+## Pub/Sub Subscriptions
+
+Subscribe to channels using the same chaining syntax as RPC calls. The key difference: **pass a callback function to subscribe, pass data to make an RPC call**.
+
+```js
+// RPC call - passing data
+await api.news.banking({ category: 'stocks' })  // Returns Promise<response>
+
+// Subscribe - passing a callback function
+const unsub = api.news.banking(data => {
+  console.log('Received:', data)
+})
+
+// Unsubscribe when done
+unsub()
+```
+
+### Chained Subscriptions
+
+```js
+// Subscribe to nested channels
+const unsub1 = api.stock.AAPL(data => {
+  console.log('AAPL:', data.price)
+})
+
+const unsub2 = api.health(data => {
+  console.log('Health update:', data)
+})
+
+// Clean up
+unsub1()
+unsub2()
+```
+
+**Behavior:**
+- On subscribe, you receive the last published message immediately (if any)
+- Subscriptions are automatically restored on reconnect
+- Subscriptions are automatically cleaned up on disconnect
+
 ## Security
 
 ### CSRF Protection

package/client/auth/crypto/aead.js

@@ -0,0 +1,214 @@
+/**
+ * @file AES-256-GCM AEAD encryption for browser
+ */
+'use strict';
+
+const {
+  CryptoError,
+  AES_KEY_LENGTH,
+  GCM_NONCE_LENGTH,
+  GCM_TAG_LENGTH,
+} = require('./constants');
+const {
+  isCryptoAvailable,
+  bufferToUint8Array,
+  stringToUint8Array,
+  randomBytes,
+} = require('./encoding');
+
+/**
+ * Import raw key for AES-GCM
+ * @param {Uint8Array} keyData - Key bytes
+ * @returns {Promise<CryptoKey>}
+ */
+async function importKey(keyData) {
+  return crypto.subtle.importKey('raw', keyData, { name: 'AES-GCM' }, false, [
+    'encrypt',
+    'decrypt',
+  ]);
+}
+
+/**
+ * Encrypt data using AES-256-GCM with AEAD
+ * @param {Uint8Array} key - 32-byte encryption key
+ * @param {Uint8Array|string} plaintext - Data to encrypt
+ * @param {Uint8Array|string} [aad] - Additional authenticated data
+ * @returns {Promise<Object>} Encrypted data components
+ */
+async function aeadEncrypt(key, plaintext, aad = '') {
+  if (!isCryptoAvailable()) {
+    const err = new Error('Web Crypto API not available');
+    err.code = CryptoError.CRYPTO_NOT_AVAILABLE;
+    throw err;
+  }
+
+  if (!(key instanceof Uint8Array) || key.length !== AES_KEY_LENGTH) {
+    const err = new Error(`Key must be a ${AES_KEY_LENGTH}-byte Uint8Array`);
+    err.code = CryptoError.INVALID_KEY_LENGTH;
+    throw err;
+  }
+
+  const plaintextArray =
+    typeof plaintext === 'string' ? stringToUint8Array(plaintext) : plaintext;
+  const aadArray =
+    typeof aad === 'string' ? stringToUint8Array(aad) : aad || new Uint8Array(0);
+
+  const nonce = randomBytes(GCM_NONCE_LENGTH);
+  const cryptoKey = await importKey(key);
+
+  const encryptedBuffer = await crypto.subtle.encrypt(
+    {
+      name: 'AES-GCM',
+      iv: nonce,
+      additionalData: aadArray,
+      tagLength: GCM_TAG_LENGTH * 8,
+    },
+    cryptoKey,
+    plaintextArray
+  );
+
+  const encrypted = bufferToUint8Array(encryptedBuffer);
+  const ciphertext = encrypted.slice(0, encrypted.length - GCM_TAG_LENGTH);
+  const tag = encrypted.slice(encrypted.length - GCM_TAG_LENGTH);
+
+  return { ciphertext, nonce, tag };
+}
+
+/**
+ * Decrypt data using AES-256-GCM with AEAD
+ * @param {Uint8Array} key - 32-byte decryption key
+ * @param {Uint8Array} ciphertext - Data to decrypt
+ * @param {Uint8Array} nonce - 12-byte nonce
+ * @param {Uint8Array} tag - 16-byte auth tag
+ * @param {Uint8Array|string} [aad] - Additional authenticated data
+ * @returns {Promise<Uint8Array>} Decrypted plaintext
+ */
+async function aeadDecrypt(key, ciphertext, nonce, tag, aad = '') {
+  if (!isCryptoAvailable()) {
+    const err = new Error('Web Crypto API not available');
+    err.code = CryptoError.CRYPTO_NOT_AVAILABLE;
+    throw err;
+  }
+
+  if (!(key instanceof Uint8Array) || key.length !== AES_KEY_LENGTH) {
+    const err = new Error(`Key must be a ${AES_KEY_LENGTH}-byte Uint8Array`);
+    err.code = CryptoError.INVALID_KEY_LENGTH;
+    throw err;
+  }
+
+  if (!(nonce instanceof Uint8Array) || nonce.length !== GCM_NONCE_LENGTH) {
+    const err = new Error(`Nonce must be a ${GCM_NONCE_LENGTH}-byte Uint8Array`);
+    err.code = CryptoError.INVALID_NONCE;
+    throw err;
+  }
+
+  if (!(tag instanceof Uint8Array) || tag.length !== GCM_TAG_LENGTH) {
+    const err = new Error(`Tag must be a ${GCM_TAG_LENGTH}-byte Uint8Array`);
+    err.code = CryptoError.INVALID_TAG;
+    throw err;
+  }
+
+  const aadArray =
+    typeof aad === 'string' ? stringToUint8Array(aad) : aad || new Uint8Array(0);
+
+  const combined = new Uint8Array(ciphertext.length + tag.length);
+  combined.set(ciphertext);
+  combined.set(tag, ciphertext.length);
+
+  const cryptoKey = await importKey(key);
+
+  try {
+    const decryptedBuffer = await crypto.subtle.decrypt(
+      {
+        name: 'AES-GCM',
+        iv: nonce,
+        additionalData: aadArray,
+        tagLength: GCM_TAG_LENGTH * 8,
+      },
+      cryptoKey,
+      combined
+    );
+
+    return bufferToUint8Array(decryptedBuffer);
+  } catch {
+    const err = new Error('Decryption failed: authentication tag mismatch');
+    err.code = CryptoError.DECRYPTION_FAILED;
+    throw err;
+  }
+}
+
+/**
+ * Pack encrypted data into single Uint8Array for storage
+ * Format: [nonce:12][tag:16][ciphertext:N]
+ * @param {Object} encrypted - Encrypted data components
+ * @param {Uint8Array} encrypted.ciphertext - The encrypted data
+ * @param {Uint8Array} encrypted.nonce - The nonce
+ * @param {Uint8Array} encrypted.tag - The auth tag
+ * @returns {Uint8Array}
+ */
+function packEncrypted(encrypted) {
+  const { ciphertext, nonce, tag } = encrypted;
+  const packed = new Uint8Array(nonce.length + tag.length + ciphertext.length);
+  packed.set(nonce);
+  packed.set(tag, nonce.length);
+  packed.set(ciphertext, nonce.length + tag.length);
+  return packed;
+}
+
+/**
+ * Unpack encrypted data from storage format
+ * @param {Uint8Array} packed - Packed encrypted data
+ * @returns {Object} Unpacked components
+ */
+function unpackEncrypted(packed) {
+  if (!(packed instanceof Uint8Array)) {
+    const err = new Error('Packed data must be a Uint8Array');
+    err.code = CryptoError.INVALID_CIPHERTEXT;
+    throw err;
+  }
+
+  const minLength = GCM_NONCE_LENGTH + GCM_TAG_LENGTH;
+  if (packed.length < minLength) {
+    const err = new Error(`Packed data too short: minimum ${minLength} bytes`);
+    err.code = CryptoError.INVALID_CIPHERTEXT;
+    throw err;
+  }
+
+  const nonce = packed.slice(0, GCM_NONCE_LENGTH);
+  const tag = packed.slice(GCM_NONCE_LENGTH, GCM_NONCE_LENGTH + GCM_TAG_LENGTH);
+  const ciphertext = packed.slice(GCM_NONCE_LENGTH + GCM_TAG_LENGTH);
+
+  return { ciphertext, nonce, tag };
+}
+
+/**
+ * Encrypt and pack in one step
+ * @param {Uint8Array} key - Encryption key
+ * @param {Uint8Array|string} plaintext - Data to encrypt
+ * @param {Uint8Array|string} [aad] - Additional authenticated data
+ * @returns {Promise<Uint8Array>}
+ */
+async function encryptAndPack(key, plaintext, aad = '') {
+  return packEncrypted(await aeadEncrypt(key, plaintext, aad));
+}
+
+/**
+ * Unpack and decrypt in one step
+ * @param {Uint8Array} key - Decryption key
+ * @param {Uint8Array} packed - Packed encrypted data
+ * @param {Uint8Array|string} [aad] - Additional authenticated data
+ * @returns {Promise<Uint8Array>}
+ */
+async function unpackAndDecrypt(key, packed, aad = '') {
+  const { ciphertext, nonce, tag } = unpackEncrypted(packed);
+  return aeadDecrypt(key, ciphertext, nonce, tag, aad);
+}
+
+module.exports = {
+  aeadEncrypt,
+  aeadDecrypt,
+  packEncrypted,
+  unpackEncrypted,
+  encryptAndPack,
+  unpackAndDecrypt,
+};

package/client/auth/crypto/constants.js

@@ -0,0 +1,32 @@
+/**
+ * @file Cryptographic constants and error codes
+ */
+'use strict';
+
+/**
+ * Error codes for crypto operations
+ * @enum {string}
+ */
+const CryptoError = {
+  DECRYPTION_FAILED: 'DECRYPTION_FAILED',
+  INVALID_KEY_LENGTH: 'INVALID_KEY_LENGTH',
+  INVALID_CIPHERTEXT: 'INVALID_CIPHERTEXT',
+  INVALID_NONCE: 'INVALID_NONCE',
+  INVALID_TAG: 'INVALID_TAG',
+  ARGON2_NOT_AVAILABLE: 'ARGON2_NOT_AVAILABLE',
+  KDF_FAILED: 'KDF_FAILED',
+  CRYPTO_NOT_AVAILABLE: 'CRYPTO_NOT_AVAILABLE',
+};
+
+const AES_KEY_LENGTH = 32; // 256 bits for AES-256-GCM
+const GCM_NONCE_LENGTH = 12; // 96 bits for GCM
+const GCM_TAG_LENGTH = 16; // 128 bits auth tag
+const PBKDF2_ITERATIONS = 600000; // OWASP recommended minimum
+
+module.exports = {
+  CryptoError,
+  AES_KEY_LENGTH,
+  GCM_NONCE_LENGTH,
+  GCM_TAG_LENGTH,
+  PBKDF2_ITERATIONS,
+};

package/client/auth/crypto/encoding.js

@@ -0,0 +1,104 @@
+/**
+ * @file Data encoding utilities for browser crypto
+ */
+'use strict';
+
+/**
+ * Check if Web Crypto API is available
+ * @returns {boolean}
+ */
+function isCryptoAvailable() {
+  return typeof crypto !== 'undefined' && crypto.subtle;
+}
+
+/**
+ * Convert ArrayBuffer to Uint8Array
+ * @param {ArrayBuffer} buffer - Buffer to convert
+ * @returns {Uint8Array}
+ */
+function bufferToUint8Array(buffer) {
+  return new Uint8Array(buffer);
+}
+
+/**
+ * Convert string to Uint8Array
+ * @param {string} str - String to convert
+ * @returns {Uint8Array}
+ */
+function stringToUint8Array(str) {
+  return new TextEncoder().encode(str);
+}
+
+/**
+ * Convert Uint8Array to string
+ * @param {Uint8Array} array - Array to convert
+ * @returns {string}
+ */
+function uint8ArrayToString(array) {
+  return new TextDecoder().decode(array);
+}
+
+/**
+ * Convert Uint8Array to base64
+ * @param {Uint8Array} array - Array to convert
+ * @returns {string}
+ */
+function uint8ArrayToBase64(array) {
+  let binary = '';
+  for (let i = 0; i < array.length; i++) {
+    binary += String.fromCharCode(array[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Convert base64 to Uint8Array
+ * @param {string} base64 - Base64 string to convert
+ * @returns {Uint8Array}
+ */
+function base64ToUint8Array(base64) {
+  const binary = atob(base64);
+  const array = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    array[i] = binary.charCodeAt(i);
+  }
+  return array;
+}
+
+/**
+ * Generate random bytes
+ * @param {number} length - Number of bytes
+ * @returns {Uint8Array}
+ */
+function randomBytes(length) {
+  const array = new Uint8Array(length);
+  crypto.getRandomValues(array);
+  return array;
+}
+
+/**
+ * Timing-safe comparison (best effort in browser)
+ * @param {Uint8Array} a - First array
+ * @param {Uint8Array} b - Second array
+ * @returns {boolean}
+ */
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a[i] ^ b[i];
+  }
+  return result === 0;
+}
+
+module.exports = {
+  isCryptoAvailable,
+  bufferToUint8Array,
+  stringToUint8Array,
+  uint8ArrayToString,
+  uint8ArrayToBase64,
+  base64ToUint8Array,
+  randomBytes,
+  timingSafeEqual,
+};

package/client/auth/crypto/files.md

@@ -0,0 +1,27 @@
+# Client Auth Crypto Module
+
+Browser-side cryptographic utilities using Web Crypto API.
+
+## Directory Structure
+
+```
+crypto/
+├── aead.js       - AES-GCM encryption/decryption
+├── constants.js  - Crypto constants and error codes
+├── encoding.js   - Base64/hex encoding utilities
+└── kdf.js        - Key derivation functions (PBKDF2)
+```
+
+## Files
+
+### `constants.js`
+Defines AES key lengths, nonce lengths, and error codes for crypto operations.
+
+### `encoding.js`
+Provides base64url and hex encoding/decoding utilities for browser environments.
+
+### `aead.js`
+AES-256-GCM authenticated encryption using Web Crypto API.
+
+### `kdf.js`
+PBKDF2 key derivation for encrypting shares client-side.