web3ql-client 1.2.0

package/dist/src/schema-manager.js

@@ -0,0 +1,259 @@
+/**
+ * @file   schema-manager.ts
+ * @notice Web3QL v1.2 — schema management: drop tables, rename, introspection.
+ *
+ * Schema is stored as ABI-encoded bytes in the database contract.
+ * This module provides:
+ *
+ *   1. SCHEMA INTROSPECTION  — decode raw schema bytes → FieldDescriptor[]
+ *   2. DROP TABLE            — bulk delete all owner records, then rename table to __dropped__
+ *   3. RENAME TABLE          — soft-rename via a meta record (contract doesn't support rename natively)
+ *   4. SCHEMA DIFF           — compare two schemas, produce a list of changes
+ *   5. SCHEMA VERSION        — read + write the schema version stored in a meta record
+ *
+ * Usage:
+ * ─────────────────────────────────────────────────────────────
+ *   const mgr = new SchemaManager(db, tableAddress, tableClient);
+ *
+ *   // Inspect a deployed table's schema
+ *   const fields = await mgr.introspect();
+ *
+ *   // Diff two versions
+ *   const changes = diffSchema(oldFields, newFields);
+ *
+ *   // Soft-drop: mark table as dropped + purge all owner records
+ *   await mgr.dropTable(ownerAddress);
+ *
+ *   // Soft-rename: store alias mapping in meta record
+ *   await mgr.renameTable('users', 'app_users');
+ * ─────────────────────────────────────────────────────────────
+ */
+import { ethers } from 'ethers';
+// ─────────────────────────────────────────────────────────────
+//  Schema introspection
+// ─────────────────────────────────────────────────────────────
+/**
+ * Minimal ABI type tags used in Web3QL schema encoding.
+ * Must stay in sync with protocol/compiler/generator.ts.
+ */
+const SOLIDITY_TO_FIELD_TYPE = {
+    'uint256': 'INT',
+    'int256': 'INT',
+    'int64': 'INT',
+    'uint64': 'UINT64',
+    'uint32': 'UINT32',
+    'uint16': 'UINT16',
+    'uint8': 'UINT8',
+    'string': 'TEXT',
+    'bool': 'BOOL',
+    'address': 'ADDRESS',
+    'bytes32': 'BYTES32',
+    'bytes': 'BYTES32',
+};
+/**
+ * Decode raw schema bytes from the contract into an array of FieldDescriptors.
+ *
+ * Web3QL encodes schema as ABI-encoded:
+ *   tuple(string name, string solidityType, bool primaryKey, bool notNull)[]
+ *
+ * This mirrors protocol/compiler/generator.ts compileSchema().
+ */
+export function decodeSchemaBytes(schemaBytes) {
+    try {
+        const bytes = typeof schemaBytes === 'string' ? ethers.getBytes(schemaBytes) : schemaBytes;
+        if (bytes.length === 0)
+            return [];
+        const abiCoder = ethers.AbiCoder.defaultAbiCoder();
+        const decoded = abiCoder.decode(['tuple(string name, string solidityType, bool primaryKey, bool notNull)[]'], bytes);
+        const fields = decoded[0];
+        return fields.map((f) => ({
+            name: f.name,
+            type: (SOLIDITY_TO_FIELD_TYPE[f.solidityType] ?? 'TEXT'),
+            primaryKey: f.primaryKey || undefined,
+            notNull: f.notNull || undefined,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Compute the diff between two schema versions.
+ * Returns an ordered list of changes from `from` → `to`.
+ */
+export function diffSchema(from, to) {
+    const changes = [];
+    const fromMap = new Map(from.map((f) => [f.name, f]));
+    const toMap = new Map(to.map((f) => [f.name, f]));
+    // Added or changed
+    for (const [name, toField] of toMap) {
+        const fromField = fromMap.get(name);
+        if (!fromField) {
+            changes.push({ type: 'added', column: name, newValue: toField.type });
+        }
+        else {
+            if (fromField.type !== toField.type) {
+                changes.push({ type: 'typeChanged', column: name, oldValue: fromField.type, newValue: toField.type });
+            }
+            if (Boolean(fromField.notNull) !== Boolean(toField.notNull)) {
+                changes.push({
+                    type: 'notNullChanged',
+                    column: name,
+                    oldValue: fromField.notNull ? 'NOT NULL' : 'NULLABLE',
+                    newValue: toField.notNull ? 'NOT NULL' : 'NULLABLE',
+                });
+            }
+        }
+    }
+    // Dropped
+    for (const name of fromMap.keys()) {
+        if (!toMap.has(name)) {
+            changes.push({ type: 'dropped', column: name });
+        }
+    }
+    return changes;
+}
+// ─────────────────────────────────────────────────────────────
+//  SchemaManager
+// ─────────────────────────────────────────────────────────────
+const DATABASE_INTROSPECT_ABI = [
+    'function getTableSchema(string calldata name) external view returns (bytes memory)',
+    'function getTable(string calldata name) external view returns (address)',
+    'function listTables() external view returns (string[] memory)',
+];
+export class SchemaManager {
+    db;
+    tableAddress;
+    tableClient;
+    dbContract;
+    constructor(db, tableAddress, tableClient, signer) {
+        this.db = db;
+        this.tableAddress = tableAddress;
+        this.tableClient = tableClient;
+        this.dbContract = new ethers.Contract(db.address, DATABASE_INTROSPECT_ABI, signer);
+    }
+    // ── Introspection ───────────────────────────────────────────
+    /**
+     * Read the schema bytes from the database contract and decode them
+     * into a usable FieldDescriptor array.
+     *
+     * @param tableName  The name used when the table was created.
+     */
+    async introspect(tableName) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const schemaBytes = await this.dbContract.getTableSchema(tableName);
+            return decodeSchemaBytes(schemaBytes);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * List all table names in this database.
+     */
+    async listTables() {
+        return this.db.listTables();
+    }
+    // ── Schema version tracking ─────────────────────────────────
+    /**
+     * Read the schema version stored in a meta record on-chain.
+     * Returns 0 if no version record has been written yet.
+     */
+    async getSchemaVersion(tableName) {
+        const versionKey = this.tableClient.deriveKey(`__schema_version__${tableName}`, 0n);
+        try {
+            const exists = await this.tableClient.exists(versionKey);
+            if (!exists)
+                return 0;
+            const json = await this.tableClient.readPlaintext(versionKey);
+            const { version } = JSON.parse(json);
+            return version;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Write (or update) the schema version meta record.
+     */
+    async setSchemaVersion(tableName, version) {
+        const versionKey = this.tableClient.deriveKey(`__schema_version__${tableName}`, 0n);
+        const payload = JSON.stringify({ version, updatedAt: Date.now() });
+        const exists = await this.tableClient.exists(versionKey);
+        if (exists) {
+            await this.tableClient.updateRaw(versionKey, payload);
+        }
+        else {
+            await this.tableClient.writeRaw(versionKey, payload);
+        }
+    }
+    // ── Soft-rename ─────────────────────────────────────────────
+    /**
+     * Store a name alias mapping in a meta record.
+     * Future `introspect()` calls should use the new name.
+     *
+     * ⚠  The contract still uses the old name internally. This is a
+     *    client-side alias only. To hard-rename, re-create the table.
+     */
+    async renameTable(oldName, newName) {
+        const renameKey = this.tableClient.deriveKey(`__rename__${oldName}`, 0n);
+        const payload = JSON.stringify({ from: oldName, to: newName, renamedAt: Date.now() });
+        const exists = await this.tableClient.exists(renameKey);
+        if (exists) {
+            await this.tableClient.updateRaw(renameKey, payload);
+        }
+        else {
+            await this.tableClient.writeRaw(renameKey, payload);
+        }
+    }
+    /** Check if a table has been soft-renamed. Returns the new name or null. */
+    async getRenamedTo(tableName) {
+        const renameKey = this.tableClient.deriveKey(`__rename__${tableName}`, 0n);
+        try {
+            const exists = await this.tableClient.exists(renameKey);
+            if (!exists)
+                return null;
+            const json = await this.tableClient.readPlaintext(renameKey);
+            const { to } = JSON.parse(json);
+            return to;
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── Soft-drop ───────────────────────────────────────────────
+    /**
+     * "Drop" a table by:
+     *   1. Deleting all owner records (batch, up to `maxRecords`).
+     *   2. Writing a __dropped__ meta record so the SDK knows to ignore it.
+     *
+     * ⚠  This is irreversible. The on-chain key->ciphertext mapping for
+     *    deleted records is permanently unreadable (symmetric key scrubbed).
+     *
+     * @param ownerAddress  Address whose records to delete.
+     * @param maxRecords    Safety cap. Default: 500. Increase for large tables.
+     */
+    async dropTable(ownerAddress, maxRecords = 500) {
+        const keys = await this.tableClient.listOwnerRecords(ownerAddress, 0n, BigInt(maxRecords));
+        let deleted = 0;
+        for (const key of keys) {
+            try {
+                await this.tableClient.deleteRecord(key);
+                deleted++;
+            }
+            catch { /* already deleted or no access — skip */ }
+        }
+        // Write tombstone
+        const tombstoneKey = this.tableClient.deriveKey(`__dropped__${this.tableAddress}`, 0n);
+        const payload = JSON.stringify({ droppedAt: Date.now(), ownerAddress });
+        await this.tableClient.writeRaw(tombstoneKey, payload);
+        return { deleted };
+    }
+    /** Check if a table has been soft-dropped. */
+    async isDropped() {
+        const tombstoneKey = this.tableClient.deriveKey(`__dropped__${this.tableAddress}`, 0n);
+        return this.tableClient.exists(tombstoneKey);
+    }
+}
+//# sourceMappingURL=schema-manager.js.map

package/dist/src/schema-manager.js.map

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

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

@@ -0,0 +1,156 @@
+/**
+ * @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 { EncryptionKeypair } from './crypto.js';
+import type { PublicKeyRegistryClient } from './registry.js';
+export declare enum Role {
+    VIEWER = 1,
+    EDITOR = 2
+}
+export interface RawRecord {
+    ciphertext: Uint8Array;
+    deleted: boolean;
+    version: bigint;
+    updatedAt: bigint;
+    owner: string;
+}
+export declare class EncryptedTableClient {
+    readonly tableAddress: string;
+    protected contract: ethers.Contract;
+    protected signer: ethers.Signer;
+    /** The caller's X25519 keypair — private key STAYS in memory only. */
+    private keypair;
+    /** Shorthand for casting contract to any so strict index checks don't block calls. */
+    private get c();
+    constructor(tableAddress: string, signer: ethers.Signer, keypair: EncryptionKeypair, abi?: readonly string[]);
+    /**
+     * 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: string, id: bigint): string;
+    /**
+     * 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.
+     */
+    writeRaw(key: string, plaintext: string | Uint8Array): Promise<ethers.TransactionReceipt>;
+    /**
+     * 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.
+     */
+    encryptForSelf(plaintext: string | Uint8Array): Promise<{
+        ciphertext: Uint8Array;
+        encryptedKey: Uint8Array;
+    }>;
+    /**
+     * 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.
+     */
+    readPlaintext(key: string): Promise<string>;
+    /**
+     * Read and decrypt a record — returns raw bytes.
+     */
+    readBytes(key: string): Promise<Uint8Array>;
+    /**
+     * Get the raw (still-encrypted) record from chain.
+     */
+    readRaw(key: string): Promise<RawRecord>;
+    /**
+     * 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.
+     */
+    updateRaw(key: string, plaintext: string | Uint8Array): Promise<ethers.TransactionReceipt>;
+    /**
+     * 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).
+     */
+    deleteRecord(key: string): Promise<ethers.TransactionReceipt>;
+    /**
+     * 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
+     */
+    share(key: string, recipient: string, role: Role, registry: PublicKeyRegistryClient): Promise<ethers.TransactionReceipt>;
+    /**
+     * 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.)
+     */
+    revoke(key: string, user: string): Promise<ethers.TransactionReceipt>;
+    /**
+     * 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
+     */
+    reshareAfterUpdate(key: string, collaborators: string[], roles: Role[], registry: PublicKeyRegistryClient): Promise<void>;
+    /** Fetch this caller's encrypted key blob from chain (still encrypted). */
+    getMyEncryptedKey(key: string): Promise<Uint8Array>;
+    /**
+     * 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: Uint8Array, senderPublicKey: Uint8Array): Uint8Array;
+    exists(key: string): Promise<boolean>;
+    owner(key: string): Promise<string>;
+    collaboratorCount(key: string): Promise<number>;
+    /** List bytes32 record keys owned by `addr` (paginated).
+     *  Prefers getActiveOwnerRecords (skips deleted) when available;
+     *  falls back to getOwnerRecords for older contract versions.
+     */
+    listOwnerRecords(addr: string, start?: bigint, limit?: bigint): Promise<string[]>;
+    /** Total number of records written by `addr` (including deleted). */
+    ownerRecordCount(addr: string): Promise<bigint>;
+}
+//# sourceMappingURL=table-client.d.ts.map

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

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