web3ql-client 1.2.0

package/dist/src/table-client.js

@@ -0,0 +1,292 @@
+/**
+ * @file   table-client.ts
+ * @notice Base encrypted table client.
+ *
+ * This class wraps a Web3QL table contract proxy and handles ALL
+ * encryption/decryption client-side.  The chain only ever sees:
+ *   • ciphertext blobs (AES-equivalent via NaCl secretbox)
+ *   • per-user encrypted key blobs   (NaCl box)
+ *
+ * Plaintext and symmetric keys never leave this class.
+ *
+ * Usage pattern:
+ * ─────────────────────────────────────────────────────────────
+ *   const client = new EncryptedTableClient(tableAddress, signer, keypair);
+ *
+ *   // Write — encrypts automatically
+ *   await client.write(1n, JSON.stringify({ name: 'Alice' }));
+ *
+ *   // Read — decrypts automatically
+ *   const data = await client.read(1n);         // '{"name":"Alice"}'
+ *
+ *   // Share with Bob (needs Bob registered in registry)
+ *   await client.share(1n, bobAddress, Role.VIEWER, registry);
+ *
+ *   // Revoke
+ *   await client.revoke(1n, bobAddress);
+ */
+import { ethers } from 'ethers';
+import { generateSymmetricKey, encryptData, decryptData, encryptKeyForSelf, encryptKeyForRecipient, decryptKeyForSelf, decryptKeyFromSender, } from './crypto.js';
+// ─────────────────────────────────────────────────────────────
+//  Types
+// ─────────────────────────────────────────────────────────────
+export var Role;
+(function (Role) {
+    Role[Role["VIEWER"] = 1] = "VIEWER";
+    Role[Role["EDITOR"] = 2] = "EDITOR";
+})(Role || (Role = {}));
+// ─────────────────────────────────────────────────────────────
+//  Minimal ABI — functions shared by all Web3QL table contracts
+// ─────────────────────────────────────────────────────────────
+const TABLE_ABI = [
+    // core
+    'function write(bytes32 key, bytes calldata ciphertext, bytes calldata encryptedKey) external',
+    'function read(bytes32 key) external view returns (bytes memory ciphertext, bool deleted, uint256 version, uint256 updatedAt, address owner)',
+    'function update(bytes32 key, bytes calldata ciphertext, bytes calldata encryptedKey) external',
+    'function deleteRecord(bytes32 key) external',
+    // key management
+    'function getMyEncryptedKey(bytes32 key) external view returns (bytes memory)',
+    // access control
+    'function grantAccess(bytes32 key, address user, uint8 role, bytes calldata encryptedKeyForUser) external',
+    'function revokeAccess(bytes32 key, address user) external',
+    // views
+    'function recordExists(bytes32 key) external view returns (bool)',
+    'function recordOwner(bytes32 key) external view returns (address)',
+    'function collaboratorCount(bytes32 key) external view returns (uint8)',
+    'function getCollaborators(bytes32 key) external view returns (address[] memory)',
+    'function getRole(bytes32 resource, address user) external view returns (uint8)',
+    // owner record enumeration
+    'function ownerRecordCount(address addr) external view returns (uint256)',
+    'function getOwnerRecords(address addr, uint256 start, uint256 limit) external view returns (bytes32[] memory)',
+    'function getActiveOwnerRecords(address addr, uint256 start, uint256 limit) external view returns (bytes32[] memory)',
+    // table metadata
+    'function tableName() external view returns (string memory)',
+];
+// ─────────────────────────────────────────────────────────────
+//  EncryptedTableClient
+// ─────────────────────────────────────────────────────────────
+export class EncryptedTableClient {
+    tableAddress;
+    contract;
+    signer;
+    /** The caller's X25519 keypair — private key STAYS in memory only. */
+    keypair;
+    /** Shorthand for casting contract to any so strict index checks don't block calls. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    get c() { return this.contract; }
+    constructor(tableAddress, signer, keypair, abi = TABLE_ABI) {
+        this.tableAddress = tableAddress;
+        this.signer = signer;
+        this.keypair = keypair;
+        this.contract = new ethers.Contract(tableAddress, abi, signer);
+    }
+    // ── Key derivation ─────────────────────────────────────────
+    /**
+     * Derive the bytes32 on-chain record key from a table name + primary key.
+     * Canonical scheme: keccak256(abi.encodePacked(tableName, id))
+     * Matches the Solidity generator and connector — all three layers are aligned.
+     */
+    deriveKey(tableName, id) {
+        return ethers.solidityPackedKeccak256(['string', 'uint256'], [tableName, id]);
+    }
+    // ── Write ──────────────────────────────────────────────────
+    /**
+     * Encrypt `plaintext` and store it as a new record.
+     * The symmetric key is encrypted for the caller (owner).
+     *
+     * @param key        bytes32 record key (use deriveKey or pass directly).
+     * @param plaintext  Any data you want to store — string or raw bytes.
+     */
+    async writeRaw(key, plaintext) {
+        const data = toBytes(plaintext);
+        const symKey = generateSymmetricKey();
+        const ciphertext = encryptData(data, symKey);
+        const encryptedKey = encryptKeyForSelf(symKey, this.keypair);
+        const tx = await this.c.write(key, ciphertext, encryptedKey);
+        return tx.wait();
+    }
+    /**
+     * Encrypt `plaintext` for self — returns the raw ciphertext and
+     * encrypted symmetric key bytes WITHOUT submitting any transaction.
+     *
+     * Used by Model.relatedCreate() to hand the encrypted bytes to a
+     * RelationWire contract that will call table.write() on behalf of
+     * the user within an atomic transaction.
+     */
+    async encryptForSelf(plaintext) {
+        const data = toBytes(plaintext);
+        const symKey = generateSymmetricKey();
+        const ciphertext = encryptData(data, symKey);
+        const encryptedKey = encryptKeyForSelf(symKey, this.keypair);
+        return { ciphertext, encryptedKey };
+    }
+    // ── Read ───────────────────────────────────────────────────
+    /**
+     * Read and decrypt a record.
+     * Returns the plaintext as a UTF-8 string.
+     * Throws if the record is deleted, doesn't exist, or you lack access.
+     */
+    async readPlaintext(key) {
+        return new TextDecoder().decode(await this.readBytes(key));
+    }
+    /**
+     * Read and decrypt a record — returns raw bytes.
+     */
+    async readBytes(key) {
+        const raw = await this.readRaw(key);
+        const encKey = await this.getMyEncryptedKey(key);
+        const symKey = decryptKeyForSelf(encKey, this.keypair);
+        return decryptData(raw.ciphertext, symKey);
+    }
+    /**
+     * Get the raw (still-encrypted) record from chain.
+     */
+    async readRaw(key) {
+        const [ciphertext, deleted, version, updatedAt, owner] = await this.c.read(key);
+        if (deleted)
+            throw new Error(`EncryptedTableClient: record ${key} is deleted`);
+        return {
+            ciphertext: toUint8Array(ciphertext),
+            deleted,
+            version,
+            updatedAt,
+            owner,
+        };
+    }
+    // ── Update ─────────────────────────────────────────────────
+    /**
+     * Update an existing record with new plaintext.
+     * Re-encrypts with a FRESH symmetric key — old key copies are NOT
+     * automatically re-shared.  Call reshareAfterUpdate() afterwards
+     * if collaborators need access to the updated version.
+     */
+    async updateRaw(key, plaintext) {
+        const data = toBytes(plaintext);
+        const symKey = generateSymmetricKey();
+        const ciphertext = encryptData(data, symKey);
+        const encryptedKey = encryptKeyForSelf(symKey, this.keypair);
+        const tx = await this.c.update(key, ciphertext, encryptedKey);
+        return tx.wait();
+    }
+    // ── Delete ─────────────────────────────────────────────────
+    /**
+     * Delete a record.  The contract scrubs ALL collaborator key copies
+     * on-chain.  Ciphertext remains but is permanently unreadable by
+     * anyone (the symmetric key is gone).
+     */
+    async deleteRecord(key) {
+        const tx = await this.c.deleteRecord(key);
+        return tx.wait();
+    }
+    // ── Sharing ────────────────────────────────────────────────
+    /**
+     * Share a record with another user.
+     *
+     * Flow:
+     *   1. Fetch caller's encrypted key from chain
+     *   2. Decrypt to recover the symmetric key (requires caller's privkey)
+     *   3. Fetch recipient's X25519 public key from the registry
+     *   4. Re-encrypt the symmetric key for the recipient
+     *   5. Call grantAccess on-chain with the new encrypted key copy
+     *
+     * @param key       bytes32 record key
+     * @param recipient Address to share with
+     * @param role      Role.VIEWER or Role.EDITOR
+     * @param registry  PublicKeyRegistryClient to look up recipient's pubkey
+     */
+    async share(key, recipient, role, registry) {
+        // 1. Get our own encrypted key copy from chain
+        const myEncKey = await this.getMyEncryptedKey(key);
+        // 2. Decrypt to get the plain symmetric key
+        const symKey = decryptKeyForSelf(myEncKey, this.keypair);
+        // 3. Look up recipient's public key from registry
+        const recipientPubKey = await registry.getPublicKey(recipient);
+        // 4. Re-encrypt the symmetric key for the recipient
+        const recipientEncKey = encryptKeyForRecipient(symKey, recipientPubKey, this.keypair.privateKey);
+        // 5. Grant access on-chain
+        const tx = await this.c.grantAccess(key, recipient, role, recipientEncKey);
+        return tx.wait();
+    }
+    /**
+     * Revoke a user's access.  Their encrypted key copy is scrubbed
+     * on-chain — they can no longer decrypt the record.
+     * (They may have decrypted and cached it locally — that is a
+     *  client-side concern, not something the chain can prevent.)
+     */
+    async revoke(key, user) {
+        const tx = await this.c.revokeAccess(key, user);
+        return tx.wait();
+    }
+    /**
+     * After updating a record (which rotates the key), re-share with
+     * all current collaborators so they can decrypt the new ciphertext.
+     *
+     * @param key            bytes32 record key
+     * @param collaborators  List of addresses to re-share with
+     * @param roles          Role for each address (parallel array)
+     * @param registry       PublicKeyRegistryClient
+     */
+    async reshareAfterUpdate(key, collaborators, roles, registry) {
+        if (collaborators.length !== roles.length) {
+            throw new Error('reshareAfterUpdate: collaborators and roles arrays must be same length');
+        }
+        for (let i = 0; i < collaborators.length; i++) {
+            await this.share(key, collaborators[i], roles[i], registry);
+        }
+    }
+    // ── Key helpers ────────────────────────────────────────────
+    /** Fetch this caller's encrypted key blob from chain (still encrypted). */
+    async getMyEncryptedKey(key) {
+        const hex = await this.c.getMyEncryptedKey(key);
+        return ethers.getBytes(hex);
+    }
+    /**
+     * Decrypt a symmetric key blob that was encrypted by a known sender
+     * (use when you are a collaborator, not the owner — the sender's
+     *  public key must be passed explicitly).
+     */
+    decryptSharedKey(encryptedKey, senderPublicKey) {
+        return decryptKeyFromSender(encryptedKey, senderPublicKey, this.keypair.privateKey);
+    }
+    // ── Views ──────────────────────────────────────────────────
+    async exists(key) {
+        return this.c.recordExists(key);
+    }
+    async owner(key) {
+        return this.c.recordOwner(key);
+    }
+    async collaboratorCount(key) {
+        return Number(await this.c.collaboratorCount(key));
+    }
+    /** List bytes32 record keys owned by `addr` (paginated).
+     *  Prefers getActiveOwnerRecords (skips deleted) when available;
+     *  falls back to getOwnerRecords for older contract versions.
+     */
+    async listOwnerRecords(addr, start = 0n, limit = 50n) {
+        try {
+            return await this.c.getActiveOwnerRecords(addr, start, limit);
+        }
+        catch {
+            // Older contract without getActiveOwnerRecords — fall back
+            return this.c.getOwnerRecords(addr, start, limit);
+        }
+    }
+    /** Total number of records written by `addr` (including deleted). */
+    async ownerRecordCount(addr) {
+        return this.c.ownerRecordCount(addr);
+    }
+}
+// ─────────────────────────────────────────────────────────────
+//  Helpers
+// ─────────────────────────────────────────────────────────────
+function toBytes(data) {
+    if (typeof data === 'string')
+        return new TextEncoder().encode(data);
+    return data;
+}
+function toUint8Array(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    return ethers.getBytes(value); // hex string
+}
+//# sourceMappingURL=table-client.js.map

package/dist/src/table-client.js.map

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

package/dist/src/typed-table.d.ts

@@ -0,0 +1,159 @@
+/**
+ * @file   typed-table.ts
+ * @notice High-level Prisma-style API for Web3QL encrypted tables.
+ *
+ * v1.1 upgrades:
+ *   • Optional SchemaDefinition support — auto validates, encodes, and decodes
+ *     fields using the extended type system (TIMESTAMP, UUID, ENUM, DECIMAL, etc.)
+ *   • NOT NULL + DEFAULT enforcement on write
+ *   • findMany with full query builder support: where/orderBy/limit/select/distinct
+ *   • findAll — convenience method (fetches + decrypts all records in batches)
+ *   • aggregate — COUNT/SUM/AVG/MIN/MAX over filtered decrypted records
+ *   • seed — bulk insert an array of records
+ *
+ * Usage (basic, schema-less — identical to v1.0):
+ * ─────────────────────────────────────────────────────────────
+ *   const users = new TypedTableClient<User>('users', db.table('0xTABLE'))
+ *   await users.create(1n, { id: 1n, name: 'Alice' })
+ *   const alice = await users.findUnique(1n)
+ *
+ * Usage (with schema for validation + type coercion):
+ * ─────────────────────────────────────────────────────────────
+ *   const schema: SchemaDefinition = [
+ *     { name: 'id',        type: 'INT',       primaryKey: true },
+ *     { name: 'name',      type: 'TEXT',       notNull: true },
+ *     { name: 'email',     type: 'TEXT',       notNull: true },
+ *     { name: 'createdAt', type: 'TIMESTAMP',  default: () => new Date() },
+ *     { name: 'role',      type: 'ENUM',       enumValues: ['user','admin'], default: 'user' },
+ *   ]
+ *   const users = new TypedTableClient<User>('users', db.table('0xADDR'), schema)
+ *
+ *   // findMany with query builder
+ *   const admins = await users.findMany(ownerAddr, {
+ *     where:   [['role', 'eq', 'admin']],
+ *     orderBy: [['createdAt', 'desc']],
+ *     limit:   20,
+ *     select:  ['id', 'name', 'email'],
+ *   })
+ * ─────────────────────────────────────────────────────────────
+ */
+import { ethers } from 'ethers';
+import type { EncryptedTableClient } from './table-client.js';
+import { SchemaDefinition } from './types.js';
+import { WhereOperator, SortDirection, AggregateOptions, AggregateResult } from './query.js';
+export type { SchemaDefinition } from './types.js';
+/** A single WHERE clause expressed as a tuple. */
+export type WhereTuple = [field: string, op: 'isNull' | 'isNotNull'] | [field: string, op: 'in' | 'notIn', values: unknown[]] | [field: string, op: 'between', range: [unknown, unknown]] | [field: string, op: WhereOperator, value: unknown];
+export interface FindManyOptions {
+    /**
+     * Starting index into the owner's record list when fetching from chain.
+     * Applied BEFORE client-side filtering — increase if paginating large tables.
+     * Default: 0.
+     */
+    chainOffset?: bigint;
+    /**
+     * Maximum records to fetch from chain per page.
+     * Default: 200 (raised from v1.0's 50 to allow client-side filtering).
+     */
+    chainLimit?: bigint;
+    /** WHERE conditions — ANDed together. Applied after decrypt. */
+    where?: WhereTuple[];
+    /** Sort order — applied after filtering. */
+    orderBy?: [field: string, dir?: SortDirection][];
+    /** Max records returned after filtering (client-side LIMIT). */
+    limit?: number;
+    /** Skip N records after filtering (client-side OFFSET). */
+    offset?: number;
+    /** Return only these fields. */
+    select?: string[];
+    /** Deduplicate on this field value. */
+    distinct?: string;
+}
+export interface RecordWithId<T> {
+    /**
+     * The uint256 primary key cannot be recovered from the on-chain bytes32 key alone
+     * (it is a keccak256 hash). This field is always `0n` when records are fetched via
+     * `findMany()`. Store the primary key inside your data payload and read it from
+     * `record.data.id` instead.
+     */
+    id: bigint;
+    /** Decrypted, typed record data. */
+    data: T;
+    /** bytes32 on-chain key (hex string). */
+    recordKey: string;
+}
+export declare class TypedTableClient<T extends Record<string, unknown>> {
+    private tableName;
+    private inner;
+    private schema?;
+    /**
+     * @param tableName  Must match the name used in the SQL schema and createTable().
+     * @param inner      An EncryptedTableClient from DatabaseClient.table(address).
+     * @param schema     Optional field descriptors — enables validation, type coercion,
+     *                   NOT NULL enforcement, and DEFAULT values.
+     */
+    constructor(tableName: string, inner: EncryptedTableClient, schema?: SchemaDefinition);
+    /** Derive the canonical bytes32 on-chain key for a given primary key id. */
+    key(id: bigint): string;
+    private encode;
+    private decode;
+    /**
+     * Validate, encode, encrypt, and store a new record.
+     * Throws if a non-deleted record with the same id already exists.
+     */
+    create(id: bigint, data: T): Promise<ethers.TransactionReceipt>;
+    /**
+     * Bulk-insert an array of records. Each record must include the primary key field.
+     * Records are written sequentially — fails on first error.
+     */
+    seed(rows: {
+        id: bigint;
+        data: T;
+    }[]): Promise<ethers.TransactionReceipt[]>;
+    /**
+     * Read and decrypt a single record by primary key.
+     * Returns `null` if the record does not exist or has been deleted.
+     */
+    findUnique(id: bigint): Promise<T | null>;
+    /**
+     * List and decrypt all records owned by `ownerAddress`, with optional
+     * client-side filtering, sorting, pagination, and projection.
+     *
+     * ⚠  Records are decrypted client-side. Use `chainLimit` to constrain
+     *    chain reads on large tables. For production scale, use the relay-
+     *    maintained index endpoint (v1.2) instead.
+     */
+    findMany(ownerAddress: string, options?: FindManyOptions): Promise<RecordWithId<Partial<T>>[]>;
+    /**
+     * Convenience: fetch and decrypt ALL records the wallet owns (no chain limit).
+     * Useful for small tables or full exports. Decrypts in parallel batches of 20.
+     */
+    findAll(ownerAddress: string): Promise<RecordWithId<T>[]>;
+    /**
+     * Aggregate over owner's records: COUNT, SUM, AVG, MIN, MAX, GROUP BY.
+     *
+     * @example
+     *   await users.aggregate(ownerAddress, { count: '*', groupBy: 'role' })
+     *   // => [{ group: 'admin', count: 3 }, { group: 'user', count: 47 }]
+     */
+    aggregate(ownerAddress: string, opts: AggregateOptions, where?: WhereTuple[], chainLimit?: bigint): Promise<AggregateResult[]>;
+    /**
+     * Fetch existing data, merge with `patch`, re-encrypt, and update on-chain.
+     */
+    update(id: bigint, patch: Partial<T>): Promise<ethers.TransactionReceipt>;
+    /**
+     * Replace a record's data entirely (no merge).
+     * More gas-efficient when you have the full new payload ready.
+     */
+    replace(id: bigint, data: T): Promise<ethers.TransactionReceipt>;
+    /**
+     * Soft-delete a record. The symmetric key is scrubbed for all collaborators.
+     * Only the record owner can call this.
+     */
+    remove(id: bigint): Promise<ethers.TransactionReceipt>;
+    /** Total number of records ever written by `ownerAddress` (including deleted). */
+    count(ownerAddress: string): Promise<bigint>;
+    /** True if a live (non-deleted) record exists for the given id. */
+    exists(id: bigint): Promise<boolean>;
+}
+//# sourceMappingURL=typed-table.d.ts.map

package/dist/src/typed-table.d.ts.map

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