web3ql-client 1.2.0

package/src/crypto.ts

@@ -0,0 +1,239 @@
+/**
+ * @file   crypto.ts
+ * @notice Off-chain encryption layer for Web3QL.
+ *
+ * Security model:
+ * ─────────────────────────────────────────────────────────────
+ *  • One random 32-byte symmetric key is generated per record.
+ *  • Record data is encrypted with that key using NaCl secretbox
+ *    (XSalsa20-Poly1305, 256-bit key, 192-bit nonce, 128-bit MAC).
+ *  • The symmetric key is encrypted separately for each authorised
+ *    user using NaCl box (X25519-XSalsa20-Poly1305, ECDH key agreement).
+ *  • Only the encrypted blobs ever touch the chain — the symmetric key
+ *    and plaintext never leave the client device.
+ *
+ * Key derivation from Ethereum wallet:
+ * ─────────────────────────────────────────────────────────────
+ *  X25519 private key = SHA-256(Ethereum private key bytes)
+ *  X25519 public key  = scalar multiplication (computed by nacl)
+ *
+ *  This means no separate key management — the wallet IS the
+ *  encryption identity.  Losing the wallet private key = losing
+ *  access to encrypted records (same as losing any crypto key).
+ *
+ * Wire format (self-describing, no external framing needed):
+ * ─────────────────────────────────────────────────────────────
+ *  secretbox blob: [ 24-byte nonce | encrypted payload ]
+ *  box blob:       [ 24-byte nonce | encrypted payload ]
+ */
+
+import nacl           from 'tweetnacl';
+import { sha256 }     from '@noble/hashes/sha256';
+import { hexToBytes } from '@noble/hashes/utils';
+import type { Signer } from 'ethers';
+
+// ─────────────────────────────────────────────────────────────
+//  Types
+// ─────────────────────────────────────────────────────────────
+
+export interface EncryptionKeypair {
+  /** X25519 public key — safe to publish on-chain */
+  publicKey  : Uint8Array; // 32 bytes
+  /** X25519 private key — never leaves the client */
+  privateKey : Uint8Array; // 32 bytes
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Keypair derivation
+// ─────────────────────────────────────────────────────────────
+
+/** Message signed by the wallet to derive the X25519 keypair.
+ *  Must be identical to the constant in cloud/lib/browser-crypto.ts so
+ *  browser and SDK produce the same keypair for the same wallet.
+ */
+export const KEY_DERIVATION_MESSAGE = 'Web3QL encryption key derivation v1';
+
+/**
+ * Derive an X25519 keypair from an ethers Signer by signing a fixed
+ * derivation message.  Because Ethereum personal_sign (RFC 6979) is
+ * deterministic, the same wallet always produces the same keypair.
+ *
+ * ✅ Use this when both SDK and browser clients need to share the same
+ *    encryption identity — the resulting pubkey matches what the browser
+ *    derives via `deriveKeypairFromSignature` in browser-crypto.ts.
+ *
+ * @param signer  Any ethers v6 Signer (e.g. `new ethers.Wallet(privKey)`).
+ */
+export async function deriveKeypairFromWallet(
+  signer: Signer,
+): Promise<EncryptionKeypair> {
+  const sig     = await signer.signMessage(KEY_DERIVATION_MESSAGE);
+  const sigHex  = sig.startsWith('0x') ? sig.slice(2) : sig;
+  const seed    = sha256(hexToBytes(sigHex));
+  const kp      = nacl.box.keyPair.fromSecretKey(seed);
+  return { publicKey: kp.publicKey, privateKey: kp.secretKey };
+}
+
+/**
+ * Derive an X25519 encryption keypair from an Ethereum private key.
+ *
+ * @deprecated Prefer `deriveKeypairFromWallet(signer)` — it produces a
+ *   keypair that is compatible with the Web3QL browser Explorer and any
+ *   other client that uses wallet-signature derivation.  Raw-private-key
+ *   derivation generates a DIFFERENT keypair, so records written with this
+ *   function cannot be decrypted in the browser (and vice-versa).
+ *
+ * @param ethPrivateKey  Hex string, with or without "0x" prefix.
+ */
+export function deriveKeypair(ethPrivateKey: string): EncryptionKeypair {
+  const stripped = ethPrivateKey.startsWith('0x')
+    ? ethPrivateKey.slice(2)
+    : ethPrivateKey;
+  const seed = sha256(hexToBytes(stripped));
+  const kp   = nacl.box.keyPair.fromSecretKey(seed);
+  return { publicKey: kp.publicKey, privateKey: kp.secretKey };
+}
+
+/**
+ * Derive ONLY the public key (useful when you only have a signed
+ * message and want to register — not when you have the private key).
+ * Exposed for completeness; normally call deriveKeypair() directly.
+ */
+export function publicKeyFromPrivate(ethPrivateKey: string): Uint8Array {
+  return deriveKeypair(ethPrivateKey).publicKey;
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Symmetric encryption (record data)
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Generate a random 32-byte symmetric key for a new record.
+ * Call this once per write — never reuse across records.
+ */
+export function generateSymmetricKey(): Uint8Array {
+  return nacl.randomBytes(nacl.secretbox.keyLength); // 32 bytes
+}
+
+/**
+ * Encrypt plaintext with a symmetric key.
+ * Wire format: [ 24-byte nonce | MAC+ciphertext ]
+ */
+export function encryptData(
+  plaintext    : Uint8Array,
+  symmetricKey : Uint8Array,
+): Uint8Array {
+  const nonce     = nacl.randomBytes(nacl.secretbox.nonceLength);
+  const encrypted = nacl.secretbox(plaintext, nonce, symmetricKey);
+  if (!encrypted) throw new Error('encryptData: nacl.secretbox returned null');
+  return concat(nonce, encrypted);
+}
+
+/**
+ * Decrypt a secretbox blob (nonce||ciphertext) with a symmetric key.
+ * Throws if the MAC check fails (data tampered or wrong key).
+ */
+export function decryptData(
+  blob         : Uint8Array,
+  symmetricKey : Uint8Array,
+): Uint8Array {
+  const nonce      = blob.subarray(0, nacl.secretbox.nonceLength);
+  const ciphertext = blob.subarray(nacl.secretbox.nonceLength);
+  const plaintext  = nacl.secretbox.open(ciphertext, nonce, symmetricKey);
+  if (!plaintext) throw new Error('decryptData: authentication failed — wrong key or tampered data');
+  return plaintext;
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Asymmetric key wrapping (per-recipient symmetric key copies)
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Encrypt a symmetric key for a specific recipient.
+ *
+ * The caller (sharer) needs their own X25519 private key and the
+ * recipient's X25519 public key (registered on-chain in PublicKeyRegistry).
+ *
+ * Wire format: [ 24-byte nonce | MAC+ciphertext ]
+ */
+export function encryptKeyForRecipient(
+  symmetricKey       : Uint8Array,
+  recipientPublicKey : Uint8Array,
+  senderPrivateKey   : Uint8Array,
+): Uint8Array {
+  const nonce     = nacl.randomBytes(nacl.box.nonceLength);
+  const encrypted = nacl.box(symmetricKey, nonce, recipientPublicKey, senderPrivateKey);
+  if (!encrypted) throw new Error('encryptKeyForRecipient: nacl.box returned null');
+  return concat(nonce, encrypted);
+}
+
+/**
+ * Decrypt a symmetric key that was encrypted for us.
+ * Throws if authentication fails.
+ */
+export function decryptKeyFromSender(
+  blob              : Uint8Array,
+  senderPublicKey   : Uint8Array,
+  recipientPrivKey  : Uint8Array,
+): Uint8Array {
+  const nonce      = blob.subarray(0, nacl.box.nonceLength);
+  const ciphertext = blob.subarray(nacl.box.nonceLength);
+  const key        = nacl.box.open(ciphertext, nonce, senderPublicKey, recipientPrivKey);
+  if (!key) throw new Error('decryptKeyFromSender: authentication failed — wrong key or tampered data');
+  return key;
+}
+
+/**
+ * Encrypt the symmetric key to yourself — used on the initial write
+ * so the owner can always recover their own key.
+ */
+export function encryptKeyForSelf(
+  symmetricKey : Uint8Array,
+  keypair      : EncryptionKeypair,
+): Uint8Array {
+  return encryptKeyForRecipient(symmetricKey, keypair.publicKey, keypair.privateKey);
+}
+
+/**
+ * Decrypt a symmetric key that was encrypted to yourself.
+ */
+export function decryptKeyForSelf(
+  blob    : Uint8Array,
+  keypair : EncryptionKeypair,
+): Uint8Array {
+  return decryptKeyFromSender(blob, keypair.publicKey, keypair.privateKey);
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Encode/decode public key for on-chain storage (bytes32)
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Encode a 32-byte X25519 public key as a 0x-prefixed hex string
+ * suitable for passing to PublicKeyRegistry.register().
+ */
+export function publicKeyToHex(pubKey: Uint8Array): string {
+  if (pubKey.length !== 32) throw new Error('publicKeyToHex: expected 32 bytes');
+  return '0x' + Buffer.from(pubKey).toString('hex');
+}
+
+/**
+ * Decode a 0x-prefixed hex bytes32 from the registry back to Uint8Array.
+ */
+export function hexToPublicKey(hex: string): Uint8Array {
+  const stripped = hex.startsWith('0x') ? hex.slice(2) : hex;
+  const bytes    = hexToBytes(stripped);
+  if (bytes.length !== 32) throw new Error('hexToPublicKey: expected 32 hex bytes');
+  return bytes;
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Utility
+// ─────────────────────────────────────────────────────────────
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}

package/src/factory-client.ts

@@ -0,0 +1,237 @@
+/**
+ * @file   factory-client.ts
+ * @notice High-level client for the Web3QL Factory + Database contracts.
+ *
+ * Entry point for every Web3QL app:
+ * ─────────────────────────────────────────────────────────────
+ *   const web3ql = new Web3QLClient(factoryAddress, signer, keypair, registryAddress);
+ *
+ *   // Register your public key once (one-time, ~40k gas)
+ *   await web3ql.register();
+ *
+ *   // Create a personal database (or get existing)
+ *   const db = await web3ql.getOrCreateDatabase();
+ *
+ *   // Create a table
+ *   const tableAddr = await db.createTable('users', schemaBytes);
+ *
+ *   // Get an encrypted client for that table
+ *   const users = db.table(tableAddr);
+ *
+ *   // Write (auto-encrypts)
+ *   await users.writeRaw(users.deriveKey('users', 1n), '{"name":"Alice"}');
+ */
+
+import { ethers }                               from 'ethers';
+import { EncryptedTableClient }                 from './table-client.js';
+import { PublicKeyRegistryClient }              from './registry.js';
+import type { EncryptionKeypair }               from './crypto.js';
+
+// ─────────────────────────────────────────────────────────────
+//  ABIs
+// ─────────────────────────────────────────────────────────────
+
+const FACTORY_ABI = [
+  'function createDatabase(string calldata name) external returns (address)',
+  'function getUserDatabases(address user) external view returns (address[] memory)',
+  'function databaseImplementation() external view returns (address)',
+  'function tableImplementation() external view returns (address)',
+  'function databaseCount() external view returns (uint256)',
+  'function removeDatabase(address db) external',
+  'event DatabaseCreated(address indexed owner, address indexed db, uint256 indexed index)',
+  'event DatabaseRemoved(address indexed owner, address indexed db)',
+] as const;
+
+const DATABASE_ABI = [
+  'function createTable(string calldata name, bytes calldata schemaBytes) external returns (address)',
+  'function getTable(string calldata name) external view returns (address)',
+  'function listTables() external view returns (string[] memory)',
+  'event TableCreated(string name, address indexed tableContract, address indexed owner)',
+] as const;
+
+// ─────────────────────────────────────────────────────────────
+//  DatabaseClient
+// ─────────────────────────────────────────────────────────────
+
+export class DatabaseClient {
+  readonly address : string;
+  private contract : ethers.Contract;
+  private signer   : ethers.Signer;
+  private keypair  : EncryptionKeypair;
+
+  constructor(
+    address  : string,
+    signer   : ethers.Signer,
+    keypair  : EncryptionKeypair,
+  ) {
+    this.address  = address;
+    this.signer   = signer;
+    this.keypair  = keypair;
+    this.contract = new ethers.Contract(address, DATABASE_ABI, signer);
+  }
+
+  /**
+   * Create a new encrypted table inside this database.
+   * @param name        Human-readable table name (matches your schema).
+   * @param schemaBytes ABI-encoded schema from @web3ql/compiler's compileSchema().
+   * @returns           Address of the deployed table proxy.
+   */
+  async createTable(name: string, schemaBytes: string): Promise<string> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const tx      = await (this.contract as any).createTable(name, schemaBytes) as { wait(): Promise<ethers.TransactionReceipt> };
+    const receipt = await tx.wait();
+
+    const iface = new ethers.Interface(DATABASE_ABI);
+    for (const log of receipt.logs) {
+      try {
+        const parsed = iface.parseLog(log);
+        if (parsed?.name === 'TableCreated') {
+          return parsed.args['tableContract'] as string;
+        }
+      } catch { /* skip non-matching logs */ }
+    }
+    throw new Error('DatabaseClient.createTable: TableCreated event not found in logs');
+  }
+
+  /**
+   * Get the address of an existing table by name.
+   * Returns ethers.ZeroAddress if not found.
+   */
+  async getTable(name: string): Promise<string> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (this.contract as any).getTable(name) as Promise<string>;
+  }
+
+  /**
+   * List all table names in this database.
+   */
+  async listTables(): Promise<string[]> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (this.contract as any).listTables() as Promise<string[]>;
+  }
+
+  /**
+   * Drop (remove from registry) a table by name.
+   * Records inside the table are NOT purged by this call — they remain
+   * as unreachable ciphertext. Use SchemaManager.dropTable() first to
+   * bulk-delete records if you want storage refunds.
+   */
+  async dropTable(name: string): Promise<ethers.TransactionReceipt> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const tx = await (this.contract as any).dropTable(name) as { wait(): Promise<ethers.TransactionReceipt> };
+    return tx.wait();
+  }
+
+  /**
+   * Get an EncryptedTableClient for a specific table address.
+   * Use this after createTable() or getTable() to read/write records.
+   */
+  table(tableAddress: string): EncryptedTableClient {
+    return new EncryptedTableClient(tableAddress, this.signer, this.keypair);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+//  Web3QLClient  (top-level entry point)
+// ─────────────────────────────────────────────────────────────
+
+export class Web3QLClient {
+  private factory  : ethers.Contract;
+  private signer   : ethers.Signer;
+  private keypair  : EncryptionKeypair;
+  readonly registry: PublicKeyRegistryClient;
+
+  constructor(
+    factoryAddress   : string,
+    signer           : ethers.Signer,
+    keypair          : EncryptionKeypair,
+    registryAddress  : string,
+  ) {
+    this.signer   = signer;
+    this.keypair  = keypair;
+    this.factory  = new ethers.Contract(factoryAddress, FACTORY_ABI, signer);
+    this.registry = new PublicKeyRegistryClient(registryAddress, signer);
+  }
+
+  /**
+   * Register the caller's encryption public key on-chain.
+   * Must be called once per address before anyone can share records
+   * with that address.  Safe to call again — will overwrite.
+   */
+  async register(): Promise<ethers.TransactionReceipt> {
+    return this.registry.register(this.keypair);
+  }
+
+  /**
+   * Check if an address has registered its public key.
+   */
+  async isRegistered(address: string): Promise<boolean> {
+    return this.registry.hasKey(address);
+  }
+
+  /**
+   * Create a new personal database for the calling wallet.
+   * Most users only ever need one database — use getOrCreateDatabase().
+   * @param name  Human-readable label stored immutably on-chain.
+   */
+  async createDatabase(name: string = ''): Promise<DatabaseClient> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const tx      = await (this.factory as any).createDatabase(name) as { wait(): Promise<ethers.TransactionReceipt> };
+    const receipt = await tx.wait();
+
+    const iface = new ethers.Interface(FACTORY_ABI);
+    for (const log of receipt.logs) {
+      try {
+        const parsed = iface.parseLog(log);
+        if (parsed?.name === 'DatabaseCreated') {
+          return new DatabaseClient(
+            parsed.args['db'] as string,
+            this.signer,
+            this.keypair,
+          );
+        }
+      } catch { /* skip */ }
+    }
+    throw new Error('Web3QLClient.createDatabase: DatabaseCreated event not found');
+  }
+
+  /**
+   * Get all database proxies owned by a user.
+   */
+  async getDatabases(owner?: string): Promise<string[]> {
+    const addr = owner ?? await this.signer.getAddress();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (this.factory as any).getUserDatabases(addr) as Promise<string[]>;
+  }
+
+  /**
+   * Return the first existing database for the caller, or create one
+   * if none exists.  Idempotent — safe to call on every app startup.
+   * @param name  Passed to createDatabase() only when a new one is created.
+   */
+  async getOrCreateDatabase(name: string = ''): Promise<DatabaseClient> {
+    const dbs = await this.getDatabases();
+    if (dbs.length > 0) {
+      return new DatabaseClient(dbs[0]!, this.signer, this.keypair);
+    }
+    return this.createDatabase(name);
+  }
+
+  /**
+   * Wrap an already-known database address (e.g. loaded from config).
+   */
+  database(address: string): DatabaseClient {
+    return new DatabaseClient(address, this.signer, this.keypair);
+  }
+
+  /**
+   * Remove a database from the factory’s registry.
+   * The proxy contract is NOT destroyed — it remains on-chain.
+   * After calling this it will no longer appear in getDatabases().
+   */
+  async removeDatabase(dbAddress: string): Promise<ethers.TransactionReceipt> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const tx = await (this.factory as any).removeDatabase(dbAddress) as { wait(): Promise<ethers.TransactionReceipt> };
+    return tx.wait();
+  }
+}