@optimystic/quereus-plugin-crypto 0.2.0

package/README.md

@@ -0,0 +1,279 @@
+# @optimystic/quereus-plugin-crypto
+
+Quereus plugin providing cryptographic functions for SQL queries with base64url encoding by default.
+
+## Features
+
+- **Hash Functions**: SHA-256, SHA-512, BLAKE3 hashing with base64url output
+- **Hash Modulo**: Fixed-size hash values (16-bit, 32-bit, etc.) for sharding and partitioning
+- **Random Bytes**: Generate cryptographically secure random bytes (default: 256 bits)
+- **Signature Functions**: secp256k1, P-256, Ed25519 signing with base64url encoding
+- **Verification Functions**: Signature verification for all supported curves
+- **Key Generation**: Generate and derive cryptographic keys
+- **Multiple Encodings**: Support for base64url, base64, hex, utf8, and raw bytes
+
+## Installation
+
+```bash
+npm install @optimystic/quereus-plugin-crypto
+```
+
+## Usage
+
+### As a Quereus Plugin
+
+```typescript
+import { Database } from '@quereus/quereus';
+import { loadPlugin } from '@quereus/quereus/util/plugin-loader.js';
+
+const db = new Database();
+await loadPlugin('npm:@optimystic/quereus-plugin-crypto', db);
+```
+
+### Direct Import (for JavaScript/TypeScript code)
+
+All cryptographic functions are also exported directly so you can use the same implementations in your JavaScript code:
+
+```typescript
+import {
+  digest,
+  hashMod,
+  randomBytes,
+  sign,
+  verify,
+  generatePrivateKey,
+  getPublicKey
+} from '@optimystic/quereus-plugin-crypto';
+
+// Hash data (base64url by default)
+const hash = digest('hello world', 'sha256', 'utf8', 'base64url');
+
+// Get a 16-bit hash for sharding
+const shard = hashMod('user@example.com', 16, 'sha256', 'utf8');
+
+// Generate random bytes (256 bits by default)
+const nonce = randomBytes(256, 'base64url');
+const salt = randomBytes(128, 'hex');
+
+// Generate keys
+const privateKey = generatePrivateKey('secp256k1', 'base64url');
+const publicKey = getPublicKey(privateKey, 'secp256k1', 'base64url', 'base64url');
+
+// Sign and verify
+const signature = sign(hash, privateKey, 'secp256k1', 'base64url', 'base64url', 'base64url');
+const isValid = verify(hash, signature, publicKey, 'secp256k1', 'base64url', 'base64url', 'base64url');
+```
+
+## SQL Functions
+
+All SQL functions use **base64url encoding by default** for inputs and outputs. This is URL-safe and SQL-friendly.
+
+### digest(data, algorithm?, inputEncoding?, outputEncoding?)
+
+Hash data using SHA-256 (default), SHA-512, or BLAKE3.
+
+```sql
+-- Hash base64url data (default)
+SELECT digest('aGVsbG8gd29ybGQ') as hash;
+
+-- Hash UTF-8 text
+SELECT digest('hello world', 'sha256', 'utf8', 'base64url') as hash;
+
+-- Hash with SHA-512
+SELECT digest('data', 'sha512', 'utf8', 'base64url') as sha512_hash;
+
+-- Hash with BLAKE3, output as hex
+SELECT digest('data', 'blake3', 'utf8', 'hex') as blake3_hex;
+```
+
+### hash_mod(data, bits, algorithm?, inputEncoding?)
+
+Hash data and return modulo 2^bits for fixed-size hash values.
+
+```sql
+-- Get 16-bit hash (0-65535) for sharding
+SELECT hash_mod('user@example.com', 16, 'sha256', 'utf8') as shard_id;
+
+-- Get 32-bit hash
+SELECT hash_mod('session_token', 32, 'sha256', 'utf8') as hash32;
+
+-- Use with base64url input
+SELECT hash_mod('aGVsbG8', 16) as hash16;
+```
+
+### random_bytes(bits?, encoding?)
+
+Generate cryptographically secure random bytes.
+
+```sql
+-- Generate 256 bits (32 bytes) of random data (default)
+SELECT random_bytes() as nonce;
+
+-- Generate 128 bits as hex
+SELECT random_bytes(128, 'hex') as salt;
+
+-- Generate 512 bits as base64url
+SELECT random_bytes(512, 'base64url') as token;
+
+-- Generate 64 bits for a random ID
+SELECT random_bytes(64) as random_id;
+```
+
+### sign(data, privateKey, curve?, inputEncoding?, keyEncoding?, outputEncoding?)
+
+Sign data using secp256k1 (default), P-256, or Ed25519.
+
+```sql
+-- Sign with secp256k1 (Bitcoin/Ethereum)
+SELECT sign('aGVsbG8', 'cHJpdmF0ZUtleQ') as signature;
+
+-- Sign UTF-8 text
+SELECT sign('hello', 'cHJpdmF0ZUtleQ', 'secp256k1', 'utf8') as signature;
+
+-- Sign with P-256 (NIST)
+SELECT sign('data', 'cHJpdmF0ZUtleQ', 'p256', 'utf8') as p256_sig;
+
+-- Sign with Ed25519
+SELECT sign('message', 'cHJpdmF0ZUtleQ', 'ed25519', 'utf8') as ed25519_sig;
+```
+
+### verify(data, signature, publicKey, curve?, inputEncoding?, sigEncoding?, keyEncoding?)
+
+Verify signatures. Returns 1 for valid, 0 for invalid.
+
+```sql
+-- Verify secp256k1 signature
+SELECT verify('aGVsbG8', 'c2lnbmF0dXJl', 'cHVibGljS2V5') as is_valid;
+
+-- Verify UTF-8 text signature
+SELECT verify('hello', 'c2lnbmF0dXJl', 'cHVibGljS2V5', 'secp256k1', 'utf8') as is_valid;
+
+-- Verify P-256 signature
+SELECT verify('data', 'c2lnbmF0dXJl', 'cHVibGljS2V5', 'p256', 'utf8') as is_valid;
+```
+
+## Supported Algorithms
+
+### Hash Algorithms
+- `sha256` - SHA-256 (default) - 256-bit secure hash
+- `sha512` - SHA-512 - 512-bit secure hash
+- `blake3` - BLAKE3 - Fast, secure, parallel hash
+
+### Elliptic Curves
+- `secp256k1` - Bitcoin/Ethereum curve (default)
+- `p256` - NIST P-256 curve (secp256r1)
+- `ed25519` - Edwards curve for EdDSA
+
+### Encoding Formats
+- `base64url` - URL-safe base64 without padding (default)
+- `base64` - Standard base64 encoding
+- `hex` - Hexadecimal encoding
+- `utf8` - UTF-8 text encoding
+- `bytes` - Raw Uint8Array (JavaScript only)
+
+## Why base64url?
+
+Base64url is the default encoding because it's:
+- **URL-safe**: No `+`, `/`, or `=` characters
+- **SQL-friendly**: No special characters that need escaping
+- **Compact**: More efficient than hex (33% smaller)
+- **Standard**: Defined in RFC 4648
+
+## Complete Example
+
+```typescript
+import { Database } from '@quereus/quereus';
+import { loadPlugin } from '@quereus/quereus/util/plugin-loader.js';
+import {
+  digest,
+  randomBytes,
+  sign,
+  verify,
+  generatePrivateKey,
+  getPublicKey
+} from '@optimystic/quereus-plugin-crypto';
+
+// Load plugin
+const db = new Database();
+await loadPlugin('npm:@optimystic/quereus-plugin-crypto', db);
+
+// Use in SQL
+db.exec(`
+  CREATE TABLE users (
+    id INTEGER PRIMARY KEY,
+    email TEXT,
+    shard_id INTEGER AS (hash_mod(email, 16, 'sha256', 'utf8')),
+    nonce TEXT DEFAULT (random_bytes(256))
+  );
+
+  INSERT INTO users (id, email) VALUES (1, 'alice@example.com');
+
+  SELECT id, email, shard_id, nonce FROM users;
+`);
+
+// Use in JavaScript
+const privateKey = generatePrivateKey('secp256k1', 'base64url');
+const publicKey = getPublicKey(privateKey);
+
+const message = 'Hello, World!';
+const hash = digest(message, 'sha256', 'utf8', 'base64url');
+const signature = sign(hash, privateKey);
+const isValid = verify(hash, signature, publicKey);
+
+console.log('Valid signature:', isValid); // true
+
+// Generate random nonce
+const nonce = randomBytes(256, 'base64url');
+console.log('Random nonce:', nonce);
+```
+
+## JavaScript API Reference
+
+### digest(data, algorithm?, inputEncoding?, outputEncoding?)
+Hash data using SHA-256, SHA-512, or BLAKE3.
+- **Returns**: Hash as string (or Uint8Array if encoding is 'bytes')
+
+### hashMod(data, bits, algorithm?, inputEncoding?)
+Hash data and return modulo 2^bits for fixed-size hash values.
+- **Returns**: Number between 0 and 2^bits - 1
+
+### randomBytes(bits?, encoding?)
+Generate cryptographically secure random bytes.
+- **Default**: 256 bits, base64url encoding
+- **Returns**: Random bytes as string (or Uint8Array if encoding is 'bytes')
+
+### sign(data, privateKey, curve?, inputEncoding?, keyEncoding?, outputEncoding?)
+Sign data using ECC (secp256k1, P-256, or Ed25519).
+- **Returns**: Signature as string (or Uint8Array if encoding is 'bytes')
+
+### verify(data, signature, publicKey, curve?, inputEncoding?, sigEncoding?, keyEncoding?)
+Verify an ECC signature.
+- **Returns**: Boolean (true if valid, false if invalid)
+
+### generatePrivateKey(curve?, encoding?)
+Generate a random private key for the specified curve.
+- **Returns**: Private key as string (or Uint8Array if encoding is 'bytes')
+
+### getPublicKey(privateKey, curve?, keyEncoding?, outputEncoding?)
+Derive the public key from a private key.
+- **Returns**: Public key as string (or Uint8Array if encoding is 'bytes')
+
+## Security Notes
+
+- All cryptographic operations use audited libraries (@noble/*)
+- Private keys should be handled securely and never exposed
+- Random number generation uses platform CSPRNG (crypto.getRandomValues)
+- Signatures use deterministic k-generation (RFC 6979)
+- All algorithms provide industry-standard security levels
+
+## React Native Compatibility
+
+These functions are fully compatible with React Native and don't require any native modules. They use:
+- `@noble/curves` for elliptic curve operations
+- `@noble/hashes` for hashing
+- `crypto.getRandomValues()` for secure randomness (polyfill required for React Native)
+
+## License
+
+MIT
+

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+/**
+ * Cryptographic Functions for Quereus
+ *
+ * Idiomatic ES module exports with base64url as default encoding.
+ * All functions accept and return base64url strings by default for SQL compatibility.
+ */
+type HashAlgorithm$1 = 'sha256' | 'sha512' | 'blake3';
+type CurveType$2 = 'secp256k1' | 'p256' | 'ed25519';
+type Encoding = 'base64url' | 'base64' | 'hex' | 'utf8' | 'bytes';
+/**
+ * Compute hash digest of input data
+ *
+ * @param data - Data to hash (base64url string or Uint8Array)
+ * @param algorithm - Hash algorithm (default: 'sha256')
+ * @param inputEncoding - Encoding of input string (default: 'base64url')
+ * @param outputEncoding - Encoding of output (default: 'base64url')
+ * @returns Hash digest in specified encoding
+ *
+ * @example
+ * ```typescript
+ * // Hash UTF-8 text, output as base64url
+ * const hash = digest('hello world', 'sha256', 'utf8');
+ *
+ * // Hash base64url data with SHA-512
+ * const hash2 = digest('SGVsbG8', 'sha512');
+ *
+ * // Get raw bytes
+ * const bytes = digest('data', 'blake3', 'utf8', 'bytes');
+ * ```
+ */
+declare function digest(data: string | Uint8Array, algorithm?: HashAlgorithm$1, inputEncoding?: Encoding, outputEncoding?: Encoding): string | Uint8Array;
+/**
+ * Hash data and return modulo of specified bit length
+ * Useful for generating fixed-size hash values (e.g., 16-bit, 32-bit)
+ *
+ * @param data - Data to hash
+ * @param bits - Number of bits for the result (e.g., 16 for 16-bit hash)
+ * @param algorithm - Hash algorithm (default: 'sha256')
+ * @param inputEncoding - Encoding of input string (default: 'base64url')
+ * @returns Integer hash value modulo 2^bits
+ *
+ * @example
+ * ```typescript
+ * // Get 16-bit hash (0-65535)
+ * const hash16 = hashMod('hello', 16, 'sha256', 'utf8');
+ *
+ * // Get 32-bit hash
+ * const hash32 = hashMod('world', 32, 'sha256', 'utf8');
+ * ```
+ */
+declare function hashMod(data: string | Uint8Array, bits: number, algorithm?: HashAlgorithm$1, inputEncoding?: Encoding): number;
+/**
+ * Sign data with a private key
+ *
+ * @param data - Data to sign (typically a hash)
+ * @param privateKey - Private key (base64url string or Uint8Array)
+ * @param curve - Elliptic curve (default: 'secp256k1')
+ * @param inputEncoding - Encoding of data input (default: 'base64url')
+ * @param keyEncoding - Encoding of private key (default: 'base64url')
+ * @param outputEncoding - Encoding of signature output (default: 'base64url')
+ * @returns Signature in specified encoding
+ *
+ * @example
+ * ```typescript
+ * // Sign a hash with secp256k1
+ * const sig = sign(hashData, privateKey);
+ *
+ * // Sign with Ed25519
+ * const sig2 = sign(hashData, privateKey, 'ed25519');
+ * ```
+ */
+declare function sign(data: string | Uint8Array, privateKey: string | Uint8Array, curve?: CurveType$2, inputEncoding?: Encoding, keyEncoding?: Encoding, outputEncoding?: Encoding): string | Uint8Array;
+/**
+ * Verify a signature
+ *
+ * @param data - Data that was signed
+ * @param signature - Signature to verify
+ * @param publicKey - Public key
+ * @param curve - Elliptic curve (default: 'secp256k1')
+ * @param inputEncoding - Encoding of data input (default: 'base64url')
+ * @param sigEncoding - Encoding of signature (default: 'base64url')
+ * @param keyEncoding - Encoding of public key (default: 'base64url')
+ * @returns true if signature is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Verify a signature
+ * const isValid = verify(hashData, signature, publicKey);
+ *
+ * // Verify with Ed25519
+ * const isValid2 = verify(hashData, signature, publicKey, 'ed25519');
+ * ```
+ */
+declare function verify(data: string | Uint8Array, signature: string | Uint8Array, publicKey: string | Uint8Array, curve?: CurveType$2, inputEncoding?: Encoding, sigEncoding?: Encoding, keyEncoding?: Encoding): boolean;
+/**
+ * Generate cryptographically secure random bytes
+ *
+ * @param bits - Number of bits to generate (default: 256)
+ * @param encoding - Output encoding (default: 'base64url')
+ * @returns Random bytes in the specified encoding
+ */
+declare function randomBytes(bits?: number, encoding?: Encoding): string | Uint8Array;
+/**
+ * Generate a random private key
+ */
+declare function generatePrivateKey(curve?: CurveType$2, encoding?: Encoding): string | Uint8Array;
+/**
+ * Get public key from private key
+ */
+declare function getPublicKey(privateKey: string | Uint8Array, curve?: CurveType$2, keyEncoding?: Encoding, outputEncoding?: Encoding): string | Uint8Array;
+
+/**
+ * Digest Function for Quereus
+ *
+ * Computes the hash of all arguments combined.
+ * Uses SHA-256 from @noble/hashes for portable implementation.
+ * Compatible with React Native and all JS environments.
+ */
+/**
+ * Hash algorithm options
+ */
+type HashAlgorithm = 'sha256' | 'sha512' | 'blake3';
+/**
+ * Input type for digest function - can be string, Uint8Array, or number
+ */
+type DigestInput$1 = string | Uint8Array | number | boolean | null | undefined;
+/**
+ * Options for the digest function
+ */
+interface DigestOptions {
+    /** Hash algorithm to use (default: sha256) */
+    algorithm?: HashAlgorithm;
+    /** Output format (default: uint8array) */
+    output?: 'uint8array' | 'hex';
+}
+/**
+ * Computes the hash of all arguments
+ *
+ * @param {...DigestInput} args - Variable number of arguments to hash
+ * @returns {Uint8Array} The computed hash as a Uint8Array
+ *
+ * @example
+ * ```typescript
+ * // Hash a string
+ * const hash1 = Digest('hello world');
+ *
+ * // Hash multiple arguments
+ * const hash2 = Digest('user:', 123, 'session');
+ *
+ * // Hash with specific algorithm
+ * const hash3 = Digest.withOptions({ algorithm: 'sha512' })('data1', 'data2');
+ *
+ * // Get hex output
+ * const hexHash = Digest.withOptions({ output: 'hex' })('hello');
+ * ```
+ */
+declare function Digest(...args: DigestInput$1[]): Uint8Array;
+declare namespace Digest {
+    var withOptions: (options: DigestOptions) => (...args: DigestInput$1[]) => string | Uint8Array<ArrayBufferLike>;
+    var sha256: (...args: DigestInput$1[]) => Uint8Array;
+    var sha512: (...args: DigestInput$1[]) => Uint8Array;
+    var blake3: (...args: DigestInput$1[]) => Uint8Array;
+    var hex: (...args: DigestInput$1[]) => string;
+    var sha256Hex: (...args: DigestInput$1[]) => string;
+    var sha512Hex: (...args: DigestInput$1[]) => string;
+    var blake3Hex: (...args: DigestInput$1[]) => string;
+}
+
+/**
+ * Sign Function for Quereus
+ *
+ * Returns the signature for the given payload using an ECC private key.
+ * Uses secp256k1 from @noble/curves for portable implementation.
+ * Compatible with React Native and all JS environments.
+ */
+/**
+ * Supported elliptic curve types
+ */
+type CurveType$1 = 'secp256k1' | 'p256' | 'ed25519';
+/**
+ * Private key input - can be Uint8Array, hex string, or bigint
+ */
+type PrivateKeyInput = Uint8Array | string | bigint;
+/**
+ * Digest input - can be Uint8Array or hex string
+ */
+type DigestInput = Uint8Array | string;
+/**
+ * Signature output format options
+ */
+type SignatureFormat = 'uint8array' | 'hex' | 'compact' | 'der';
+/**
+ * Options for the Sign function
+ */
+interface SignOptions {
+    /** Elliptic curve to use (default: secp256k1) */
+    curve?: CurveType$1;
+    /** Output format for signature (default: uint8array) */
+    format?: SignatureFormat;
+    /** Additional entropy for signatures (hedged signatures) */
+    extraEntropy?: boolean | Uint8Array;
+    /** Use low-S canonical signatures (default: true) */
+    lowS?: boolean;
+}
+/**
+ * Sign a digest using the specified private key and curve
+ *
+ * @param {DigestInput} digest - The digest/hash to sign
+ * @param {PrivateKeyInput} privateKey - The private key to use for signing
+ * @param {SignOptions} [options] - Optional signing parameters
+ * @returns {Uint8Array | string} The signature in the requested format
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with secp256k1
+ * const digest = new Uint8Array(32).fill(1); // Your hash here
+ * const privateKey = 'a'.repeat(64); // Your private key hex
+ * const signature = Sign(digest, privateKey);
+ *
+ * // With specific curve and format
+ * const sig = Sign(digest, privateKey, {
+ *   curve: 'p256',
+ *   format: 'hex'
+ * });
+ *
+ * // With hedged signatures for extra security
+ * const hedgedSig = Sign(digest, privateKey, {
+ *   extraEntropy: true
+ * });
+ * ```
+ */
+declare function Sign(digest: DigestInput, privateKey: PrivateKeyInput, options?: SignOptions): Uint8Array | string;
+declare namespace Sign {
+    var secp256k1: (digest: DigestInput, privateKey: PrivateKeyInput, options?: Omit<SignOptions, "curve">) => string | Uint8Array<ArrayBufferLike>;
+    var p256: (digest: DigestInput, privateKey: PrivateKeyInput, options?: Omit<SignOptions, "curve">) => string | Uint8Array<ArrayBufferLike>;
+    var ed25519: (digest: DigestInput, privateKey: PrivateKeyInput, options?: Omit<SignOptions, "curve">) => string | Uint8Array<ArrayBufferLike>;
+    var generatePrivateKey: (curve?: CurveType$1) => Uint8Array;
+    var getPublicKey: (privateKey: PrivateKeyInput, curve?: CurveType$1) => Uint8Array;
+}
+
+/**
+ * SignatureValid Function for Quereus
+ *
+ * Returns true if the ECC signature is valid for the given digest and public key.
+ * Uses @noble/curves for portable implementation.
+ * Compatible with React Native and all JS environments.
+ */
+/**
+ * Supported elliptic curve types
+ */
+type CurveType = 'secp256k1' | 'p256' | 'ed25519';
+/**
+ * Input types that can be Uint8Array or hex string
+ */
+type BytesInput = Uint8Array | string;
+/**
+ * Options for signature verification
+ */
+interface VerifyOptions {
+    /** Elliptic curve to use (default: secp256k1) */
+    curve?: CurveType;
+    /** Signature format (default: auto-detect) */
+    signatureFormat?: 'compact' | 'der' | 'raw';
+    /** Allow malleable signatures (default: false for ECDSA, true for EdDSA) */
+    allowMalleableSignatures?: boolean;
+}
+/**
+ * Verify if an ECC signature is valid
+ *
+ * @param {BytesInput} digest - The digest/hash that was signed
+ * @param {BytesInput} signature - The signature to verify
+ * @param {BytesInput} publicKey - The public key to verify against
+ * @param {VerifyOptions} [options] - Optional verification parameters
+ * @returns {boolean} True if the signature is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with secp256k1
+ * const isValid = SignatureValid(digest, signature, publicKey);
+ *
+ * // With specific curve
+ * const isValid = SignatureValid(digest, signature, publicKey, {
+ *   curve: 'p256'
+ * });
+ *
+ * // With specific signature format
+ * const isValid = SignatureValid(digest, signature, publicKey, {
+ *   curve: 'secp256k1',
+ *   signatureFormat: 'der'
+ * });
+ *
+ * // Allow malleable signatures
+ * const isValid = SignatureValid(digest, signature, publicKey, {
+ *   allowMalleableSignatures: true
+ * });
+ * ```
+ */
+declare function SignatureValid(digest: BytesInput, signature: BytesInput, publicKey: BytesInput, options?: VerifyOptions): boolean;
+declare namespace SignatureValid {
+    var secp256k1: (digest: BytesInput, signature: BytesInput, publicKey: BytesInput, options?: Omit<VerifyOptions, "curve">) => boolean;
+    var p256: (digest: BytesInput, signature: BytesInput, publicKey: BytesInput, options?: Omit<VerifyOptions, "curve">) => boolean;
+    var ed25519: (digest: BytesInput, signature: BytesInput, publicKey: BytesInput, options?: Omit<VerifyOptions, "curve">) => boolean;
+    var batch: (verifications: Array<{
+        digest: BytesInput;
+        signature: BytesInput;
+        publicKey: BytesInput;
+        options?: VerifyOptions;
+    }>) => boolean[];
+    var detailed: (digest: BytesInput, signature: BytesInput, publicKey: BytesInput, options?: VerifyOptions) => {
+        valid: boolean;
+        curve: CurveType;
+        signatureFormat: string;
+        error?: string;
+    };
+}
+
+export { type BytesInput, type CurveType$2 as CurveType, Digest, type DigestInput$1 as DigestInput, type DigestOptions, type Encoding, type HashAlgorithm$1 as HashAlgorithm, type PrivateKeyInput, Sign, type SignOptions, SignatureValid, type VerifyOptions, digest, generatePrivateKey, getPublicKey, hashMod, randomBytes, sign, verify };