@optimystic/quereus-plugin-crypto 0.2.0

package/src/digest.ts

@@ -0,0 +1,173 @@
+/**
+ * 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.
+ */
+
+import { sha256 } from '@noble/hashes/sha2';
+import { sha512 } from '@noble/hashes/sha2';
+import { blake3 } from '@noble/hashes/blake3';
+import { concatBytes, utf8ToBytes } from '@noble/hashes/utils';
+
+/**
+ * Hash algorithm options
+ */
+export type HashAlgorithm = 'sha256' | 'sha512' | 'blake3';
+
+/**
+ * Input type for digest function - can be string, Uint8Array, or number
+ */
+export type DigestInput = string | Uint8Array | number | boolean | null | undefined;
+
+/**
+ * Options for the digest function
+ */
+export interface DigestOptions {
+  /** Hash algorithm to use (default: sha256) */
+  algorithm?: HashAlgorithm;
+  /** Output format (default: uint8array) */
+  output?: 'uint8array' | 'hex';
+}
+
+/**
+ * Convert various input types to Uint8Array for hashing
+ */
+function inputToBytes(input: DigestInput): Uint8Array {
+  if (input === null || input === undefined) {
+    return new Uint8Array(0);
+  }
+
+  if (typeof input === 'string') {
+    return utf8ToBytes(input);
+  }
+
+  if (input instanceof Uint8Array) {
+    return input;
+  }
+
+  if (typeof input === 'number') {
+    // Convert number to 8-byte big-endian representation
+    const buffer = new ArrayBuffer(8);
+    const view = new DataView(buffer);
+    view.setFloat64(0, input, false); // big-endian
+    return new Uint8Array(buffer);
+  }
+
+  if (typeof input === 'boolean') {
+    return new Uint8Array([input ? 1 : 0]);
+  }
+
+  // Fallback: convert to string then to bytes
+  return utf8ToBytes(String(input));
+}
+
+/**
+ * Get hash function based on algorithm
+ */
+function getHashFunction(algorithm: HashAlgorithm): (data: Uint8Array) => Uint8Array {
+  switch (algorithm) {
+    case 'sha256':
+      return sha256;
+    case 'sha512':
+      return sha512;
+    case 'blake3':
+      return blake3;
+    default:
+      throw new Error(`Unsupported hash algorithm: ${algorithm}`);
+  }
+}
+
+/**
+ * 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');
+ * ```
+ */
+export function Digest(...args: DigestInput[]): Uint8Array {
+  return DigestWithOptions({ algorithm: 'sha256', output: 'uint8array' }, ...args) as Uint8Array;
+}
+
+/**
+ * Digest function with custom options
+ */
+export function DigestWithOptions(options: DigestOptions, ...args: DigestInput[]): Uint8Array | string {
+  const algorithm = options.algorithm || 'sha256';
+  const output = options.output || 'uint8array';
+
+  // Convert all arguments to bytes and concatenate
+  const byteArrays = args.map(inputToBytes);
+  const combined = concatBytes(...byteArrays);
+
+  // Hash the combined data
+  const hashFunction = getHashFunction(algorithm);
+  const hash = hashFunction(combined);
+
+  // Return in requested format
+  if (output === 'hex') {
+    return Array.from(hash)
+      .map(b => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  return hash;
+}
+
+/**
+ * Create a digest function with preset options
+ */
+Digest.withOptions = (options: DigestOptions) => {
+  return (...args: DigestInput[]) => DigestWithOptions(options, ...args);
+};
+
+/**
+ * Convenience functions for specific algorithms
+ */
+Digest.sha256 = (...args: DigestInput[]): Uint8Array => {
+  return DigestWithOptions({ algorithm: 'sha256' }, ...args) as Uint8Array;
+};
+
+Digest.sha512 = (...args: DigestInput[]): Uint8Array => {
+  return DigestWithOptions({ algorithm: 'sha512' }, ...args) as Uint8Array;
+};
+
+Digest.blake3 = (...args: DigestInput[]): Uint8Array => {
+  return DigestWithOptions({ algorithm: 'blake3' }, ...args) as Uint8Array;
+};
+
+/**
+ * Hex output variants
+ */
+Digest.hex = (...args: DigestInput[]): string => {
+  return DigestWithOptions({ algorithm: 'sha256', output: 'hex' }, ...args) as string;
+};
+
+Digest.sha256Hex = (...args: DigestInput[]): string => {
+  return DigestWithOptions({ algorithm: 'sha256', output: 'hex' }, ...args) as string;
+};
+
+Digest.sha512Hex = (...args: DigestInput[]): string => {
+  return DigestWithOptions({ algorithm: 'sha512', output: 'hex' }, ...args) as string;
+};
+
+Digest.blake3Hex = (...args: DigestInput[]): string => {
+  return DigestWithOptions({ algorithm: 'blake3', output: 'hex' }, ...args) as string;
+};
+
+export default Digest;

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Quereus Crypto Functions Plugin
+ *
+ * Provides cryptographic functions for SQL queries and ES modules:
+ * - digest: Hash functions (SHA-256, SHA-512, BLAKE3) with base64url encoding
+ * - sign: ECC signature generation (secp256k1, P-256, Ed25519)
+ * - verify: ECC signature verification
+ * - hashMod: Hash with modulo for fixed-size outputs
+ * - randomBytes: Generate cryptographically secure random bytes
+ *
+ * All functions use base64url encoding by default for SQL compatibility.
+ */
+
+// Export idiomatic lowercase functions (primary API)
+export {
+	digest,
+	sign,
+	verify,
+	hashMod,
+	randomBytes,
+	generatePrivateKey,
+	getPublicKey,
+	type HashAlgorithm,
+	type CurveType,
+	type Encoding,
+} from './crypto.js';
+
+// Legacy exports for backwards compatibility (if needed)
+export { Digest, type DigestInput, type DigestOptions } from './digest.js';
+export { Sign, type PrivateKeyInput, type SignOptions } from './sign.js';
+export { SignatureValid, type BytesInput, type VerifyOptions } from './signature-valid.js';
+
+

package/src/plugin.ts

@@ -0,0 +1,87 @@
+/**
+ * Quereus Plugin Entry Point for Crypto Functions
+ *
+ * This module provides the plugin registration following Quereus 0.4.5 format.
+ * All metadata is in package.json - no manifest export needed.
+ */
+
+import type { Database, FunctionFlags, SqlValue } from '@quereus/quereus';
+import { digest, sign, verify, hashMod, randomBytes } from './crypto.js';
+
+/**
+ * Plugin registration function
+ * This is called by Quereus when the plugin is loaded
+ */
+export default function register(_db: Database, _config: Record<string, SqlValue> = {}) {
+	// Register crypto functions with Quereus
+	const functions = [
+		{
+			schema: {
+				name: 'digest',
+				numArgs: -1, // Variable arguments: data, algorithm?, inputEncoding?, outputEncoding?
+				flags: 1 as FunctionFlags, // UTF8
+				returnType: { typeClass: 'scalar' as const, sqlType: 'TEXT' },
+				implementation: (...args: SqlValue[]) => {
+					const [data, algorithm = 'sha256', inputEncoding = 'base64url', outputEncoding = 'base64url'] = args;
+					return digest(data as string, algorithm as any, inputEncoding as any, outputEncoding as any);
+				},
+			},
+		},
+		{
+			schema: {
+				name: 'sign',
+				numArgs: -1, // Variable arguments: data, privateKey, curve?, inputEncoding?, keyEncoding?, outputEncoding?
+				flags: 1 as FunctionFlags,
+				returnType: { typeClass: 'scalar' as const, sqlType: 'TEXT' },
+				implementation: (...args: SqlValue[]) => {
+					const [data, privateKey, curve = 'secp256k1', inputEncoding = 'base64url', keyEncoding = 'base64url', outputEncoding = 'base64url'] = args;
+					return sign(data as string, privateKey as string, curve as any, inputEncoding as any, keyEncoding as any, outputEncoding as any);
+				},
+			},
+		},
+		{
+			schema: {
+				name: 'verify',
+				numArgs: -1, // Variable arguments: data, signature, publicKey, curve?, inputEncoding?, sigEncoding?, keyEncoding?
+				flags: 1 as FunctionFlags,
+				returnType: { typeClass: 'scalar' as const, sqlType: 'INTEGER' },
+				implementation: (...args: SqlValue[]) => {
+					const [data, signature, publicKey, curve = 'secp256k1', inputEncoding = 'base64url', sigEncoding = 'base64url', keyEncoding = 'base64url'] = args;
+					const result = verify(data as string, signature as string, publicKey as string, curve as any, inputEncoding as any, sigEncoding as any, keyEncoding as any);
+					return result ? 1 : 0;
+				},
+			},
+		},
+		{
+			schema: {
+				name: 'hash_mod',
+				numArgs: -1, // Variable arguments: data, bits, algorithm?, inputEncoding?
+				flags: 1 as FunctionFlags,
+				returnType: { typeClass: 'scalar' as const, sqlType: 'INTEGER' },
+				implementation: (...args: SqlValue[]) => {
+					const [data, bits, algorithm = 'sha256', inputEncoding = 'base64url'] = args;
+					return hashMod(data as string, bits as number, algorithm as any, inputEncoding as any);
+				},
+			},
+		},
+		{
+			schema: {
+				name: 'random_bytes',
+				numArgs: -1, // Variable arguments: bits?, encoding?
+				flags: 1 as FunctionFlags,
+				returnType: { typeClass: 'scalar' as const, sqlType: 'TEXT' },
+				implementation: (...args: SqlValue[]) => {
+					const [bits = 256, encoding = 'base64url'] = args;
+					return randomBytes(bits as number, encoding as any);
+				},
+			},
+		},
+	];
+
+	return {
+		functions,
+		vtables: [],
+		collations: [],
+	};
+}
+

package/src/sign.ts

@@ -0,0 +1,245 @@
+/**
+ * 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.
+ */
+
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { p256 } from '@noble/curves/nist';
+import { ed25519 } from '@noble/curves/ed25519';
+import { bytesToHex, hexToBytes } from '@noble/curves/abstract/utils';
+
+/**
+ * Supported elliptic curve types
+ */
+export type CurveType = 'secp256k1' | 'p256' | 'ed25519';
+
+/**
+ * Private key input - can be Uint8Array, hex string, or bigint
+ */
+export type PrivateKeyInput = Uint8Array | string | bigint;
+
+/**
+ * Digest input - can be Uint8Array or hex string
+ */
+export type DigestInput = Uint8Array | string;
+
+/**
+ * Signature output format options
+ */
+export type SignatureFormat = 'uint8array' | 'hex' | 'compact' | 'der';
+
+/**
+ * Options for the Sign function
+ */
+export interface SignOptions {
+  /** Elliptic curve to use (default: secp256k1) */
+  curve?: CurveType;
+  /** 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;
+}
+
+/**
+ * Normalize private key input to Uint8Array
+ */
+function normalizePrivateKey(privateKey: PrivateKeyInput): Uint8Array {
+  if (privateKey instanceof Uint8Array) {
+    return privateKey;
+  }
+
+  if (typeof privateKey === 'string') {
+    // Assume hex string
+    return hexToBytes(privateKey);
+  }
+
+  if (typeof privateKey === 'bigint') {
+    // Convert bigint to 32-byte array (for secp256k1/p256)
+    const hex = privateKey.toString(16).padStart(64, '0');
+    return hexToBytes(hex);
+  }
+
+  throw new Error('Invalid private key format');
+}
+
+/**
+ * Normalize digest input to Uint8Array
+ */
+function normalizeDigest(digest: DigestInput): Uint8Array {
+  if (digest instanceof Uint8Array) {
+    return digest;
+  }
+
+  if (typeof digest === 'string') {
+    return hexToBytes(digest);
+  }
+
+  throw new Error('Invalid digest format');
+}
+
+/**
+ * Format signature based on requested format
+ */
+function formatSignature(signature: any, format: SignatureFormat, curve: CurveType): Uint8Array | string {
+  switch (format) {
+    case 'uint8array':
+      if (curve === 'ed25519') {
+        return signature;
+      }
+      return signature.toCompactRawBytes();
+
+    case 'hex':
+      if (curve === 'ed25519') {
+        return bytesToHex(signature);
+      }
+      return signature.toCompactHex();
+
+    case 'compact':
+      if (curve === 'ed25519') {
+        return signature;
+      }
+      return signature.toCompactRawBytes();
+
+    case 'der':
+      if (curve === 'ed25519') {
+        throw new Error('DER format not supported for ed25519');
+      }
+      // Note: DER encoding would require additional implementation
+      // For now, fall back to compact
+      return signature.toCompactRawBytes();
+
+    default:
+      throw new Error(`Unsupported signature format: ${format}`);
+  }
+}
+
+/**
+ * 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
+ * });
+ * ```
+ */
+export function Sign(
+  digest: DigestInput,
+  privateKey: PrivateKeyInput,
+  options: SignOptions = {}
+): Uint8Array | string {
+  const {
+    curve = 'secp256k1',
+    format = 'uint8array',
+    extraEntropy = false,
+    lowS = true,
+  } = options;
+
+  const normalizedDigest = normalizeDigest(digest);
+  const normalizedPrivateKey = normalizePrivateKey(privateKey);
+
+  let signature: any;
+
+  switch (curve) {
+    case 'secp256k1': {
+      const signOptions: any = { lowS };
+      if (extraEntropy) {
+        signOptions.extraEntropy = extraEntropy;
+      }
+      signature = secp256k1.sign(normalizedDigest, normalizedPrivateKey, signOptions);
+      break;
+    }
+
+    case 'p256': {
+      const signOptions: any = { lowS };
+      if (extraEntropy) {
+        signOptions.extraEntropy = extraEntropy;
+      }
+      signature = p256.sign(normalizedDigest, normalizedPrivateKey, signOptions);
+      break;
+    }
+
+    case 'ed25519': {
+      signature = ed25519.sign(normalizedDigest, normalizedPrivateKey);
+      break;
+    }
+
+    default:
+      throw new Error(`Unsupported curve: ${curve}`);
+  }
+
+  return formatSignature(signature, format, curve);
+}
+
+/**
+ * Convenience functions for specific curves
+ */
+Sign.secp256k1 = (digest: DigestInput, privateKey: PrivateKeyInput, options: Omit<SignOptions, 'curve'> = {}) => {
+  return Sign(digest, privateKey, { ...options, curve: 'secp256k1' });
+};
+
+Sign.p256 = (digest: DigestInput, privateKey: PrivateKeyInput, options: Omit<SignOptions, 'curve'> = {}) => {
+  return Sign(digest, privateKey, { ...options, curve: 'p256' });
+};
+
+Sign.ed25519 = (digest: DigestInput, privateKey: PrivateKeyInput, options: Omit<SignOptions, 'curve'> = {}) => {
+  return Sign(digest, privateKey, { ...options, curve: 'ed25519' });
+};
+
+/**
+ * Generate a random private key for the specified curve
+ */
+Sign.generatePrivateKey = (curve: CurveType = 'secp256k1'): Uint8Array => {
+  switch (curve) {
+    case 'secp256k1':
+      return secp256k1.utils.randomPrivateKey();
+    case 'p256':
+      return p256.utils.randomPrivateKey();
+    case 'ed25519':
+      return ed25519.utils.randomPrivateKey();
+    default:
+      throw new Error(`Unsupported curve: ${curve}`);
+  }
+};
+
+/**
+ * Get the public key for a given private key and curve
+ */
+Sign.getPublicKey = (privateKey: PrivateKeyInput, curve: CurveType = 'secp256k1'): Uint8Array => {
+  const normalizedPrivateKey = normalizePrivateKey(privateKey);
+
+  switch (curve) {
+    case 'secp256k1':
+      return secp256k1.getPublicKey(normalizedPrivateKey);
+    case 'p256':
+      return p256.getPublicKey(normalizedPrivateKey);
+    case 'ed25519':
+      return ed25519.getPublicKey(normalizedPrivateKey);
+    default:
+      throw new Error(`Unsupported curve: ${curve}`);
+  }
+};
+
+export default Sign;