sietch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hans Rakotomanga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# sietch
+
+An offline-first database library with CRDT-based sync, post-quantum encryption,
+and a PostgreSQL/AGE/pgvector server backend. Inspired by GunJS and TopGun.
+
+## Features
+
+- **Offline-first** — full CRUD without network, automatic sync when online
+- **CRDT sync** — Yjs-powered conflict-free replication across peers and servers
+- **P2P networking** — libp2p transport with NAT traversal (Circuit Relay v2)
+- **Post-quantum encryption** — hybrid Ed25519+ML-DSA-44 signing, X25519+ML-KEM-768 key exchange
+- **Per-subtree ACL** — server-signed reference nodes with three tiers (open / policy / crypto)
+- **Graph + vector** — local Orama/graphology indexing, server-side AGE graph + pgvector search
+- **Transparent eviction** — two-tier (memory → disk → network), with pinning support
+- **Zero-config** — sensible defaults, `createStore()` works out of the box
+
+## Getting Started
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm tsc --noEmit
+```
+
+### Minimal Example
+
+```typescript
+import { createStore } from 'sietch';
+
+const db = await createStore();
+await db.put('greeting.msg', 'hello world');
+const result = await db.get('greeting.msg');
+console.log(result.value); // 'hello world'
+```
+
+## Architecture
+
+| Client Module | Purpose |
+|---|---|
+| Store | Public API facade |
+| Yjs Engine | CRDT engine (subdocument per subtree) |
+| ACL Module | Per-subtree access control |
+| Crypto Module | PQ hybrid signing, KEX, symmetric encryption |
+| Identity Module | Keypair lifecycle, device linking |
+| Sync Engine | libp2p transport, protocol handlers |
+| Storage Backend | OPFS/IndexedDB/memory abstraction |
+| Eviction Manager | Two-tier eviction with LRU |
+| Query/Index Engine | Orama full-text + graphology graph |
+| Observability | Structured logging (pino), event channels |
+
+| Server Module | Purpose |
+|---|---|
+| Sync Service | Yjs relay with selective replication |
+| ACL Authority | Sign/validate ACL reference nodes |
+| Auth Service | Email-based device linking |
+| Query Bridge | Yjs → PostgreSQL/AGE/pgvector pipeline |
+
+## Project Status
+
+Phase 5 (Implementation) complete. 14 source modules, 276 tests (272 passing + 4 browser-only skipped), 83/83 requirements covered.
+
+## License
+
+[Your license here]

package/dist/acl.d.ts

@@ -0,0 +1,134 @@
+/**
+ * ACL Module — per-subtree access control via server-signed reference nodes.
+ *
+ * Architecture: ADR-007 (Per-subtree ACL via reference nodes)
+ *
+ * Three tiers:
+ * 1. No ACL (open): no reference node → anyone can read/write
+ * 2. ACL unencrypted: reference node with encrypted:false → policy enforcement
+ * 3. ACL encrypted: reference node with encrypted:true → cryptographic enforcement (CEK)
+ */
+import type { AclMap, AclPermissions, CrdtValue, Result } from './types.js';
+import type { ObservabilityContext } from './observability.js';
+import { type HybridPublicKey, type HybridSignature, type HybridKemKeypair } from './crypto.js';
+import { InvalidAclSignatureError, AclError } from './errors.js';
+/** Reference node structure for a subtree ACL. */
+export interface AclReferenceNode {
+    subtreeId: string;
+    owner: string;
+    encrypted: boolean;
+    acl: AclMap;
+    /** Per-user wrapped CEKs (only for encrypted subtrees). */
+    ceks?: Record<string, Uint8Array>;
+    /** Server signature over the ACL data. */
+    signature: HybridSignature;
+}
+/** Serialized form of ACL reference node (for hashing/signing). */
+export interface AclPayload {
+    subtreeId: string;
+    owner: string;
+    encrypted: boolean;
+    acl: AclMap;
+}
+/** Result of an ACL check. */
+export interface AclCheckResult {
+    allowed: boolean;
+    tier: 'open' | 'policy' | 'crypto';
+    /** Decrypted CEK (only for encrypted subtrees, only if user has access). */
+    cek?: Uint8Array;
+}
+export declare class AclManager {
+    private readonly obs;
+    /** In-memory cache of ACL reference nodes. */
+    private readonly refNodes;
+    private serverPublicKey;
+    constructor(obs: ObservabilityContext);
+    /**
+     * Set the trusted server's public key for signature verification.
+     */
+    setServerPublicKey(pk: HybridPublicKey): void;
+    /**
+     * Apply an ACL reference node update (from server or sync).
+     * Verifies server signature before accepting.
+     */
+    applyReferenceNode(node: AclReferenceNode): Result<void, InvalidAclSignatureError>;
+    /**
+     * Check if a user has read permission on a subtree.
+     */
+    checkRead(subtreeId: string, userId: string, ownKem?: HybridKemKeypair): AclCheckResult;
+    /**
+     * Check if a user has write permission on a subtree.
+     */
+    checkWrite(subtreeId: string, userId: string): AclCheckResult;
+    /**
+     * Check if a user has admin permission on a subtree.
+     */
+    checkAdmin(subtreeId: string, userId: string): boolean;
+    /**
+     * Validate a permission grant request.
+     * Only users with a:true can grant permissions.
+     */
+    validateGrant(subtreeId: string, granterId: string, targetPerms: AclPermissions): Result<void, AclError>;
+    /**
+     * Validate a permission revoke request.
+     * Cannot revoke the owner.
+     */
+    validateRevoke(subtreeId: string, revokerId: string, targetId: string): Result<void, AclError>;
+    /**
+     * Create a new ACL reference node for a subtree.
+     * The node must be signed by the server before distribution.
+     */
+    createAclPayload(subtreeId: string, ownerId: string, acl: AclMap, encrypted: boolean): AclPayload;
+    /**
+     * Generate wrapped CEKs for all users in an encrypted subtree.
+     */
+    generateCeks(acl: AclMap, userPublicKeys: Record<string, HybridPublicKey>): {
+        cek: Uint8Array;
+        wrappedCeks: Record<string, Uint8Array>;
+    };
+    /**
+     * Rotate CEK after user revocation.
+     * Generates new CEK and re-wraps for remaining users.
+     */
+    rotateCek(acl: AclMap, userPublicKeys: Record<string, HybridPublicKey>): {
+        cek: Uint8Array;
+        wrappedCeks: Record<string, Uint8Array>;
+    };
+    /**
+     * Get the ACL for a subtree.
+     */
+    getAcl(subtreeId: string): AclMap | undefined;
+    /**
+     * Get reference node for a subtree.
+     */
+    getReferenceNode(subtreeId: string): AclReferenceNode | undefined;
+    /**
+     * Check if a subtree is encrypted.
+     */
+    isEncrypted(subtreeId: string): boolean;
+    /**
+     * Check if a subtree has an ACL.
+     */
+    hasAcl(subtreeId: string): boolean;
+    /**
+     * Get the full reference node for a subtree.
+     */
+    getRefNode(subtreeId: string): AclReferenceNode | undefined;
+}
+/** Serialize ACL payload to bytes for signing/verification. */
+declare function serializeAclPayload(payload: AclPayload): Uint8Array;
+/** Exported for server-side signing. */
+export { serializeAclPayload };
+/**
+ * Serialize an AclReferenceNode to a Yjs-storable flat object.
+ *
+ * Flattens the HybridSignature to top-level `sig_ed25519` / `sig_mlDsa44`
+ * keys so that Yjs Y.Map roundtrip preserves the Uint8Array values.
+ */
+export declare function serializeRefNode(node: AclReferenceNode): Record<string, CrdtValue>;
+/**
+ * Deserialize a Yjs-stored object back into an AclReferenceNode.
+ *
+ * Throws if the data doesn't contain the required fields.
+ */
+export declare function deserializeRefNode(data: Record<string, CrdtValue>): AclReferenceNode;

package/dist/acl.js

@@ -0,0 +1,258 @@
+/**
+ * ACL Module — per-subtree access control via server-signed reference nodes.
+ *
+ * Architecture: ADR-007 (Per-subtree ACL via reference nodes)
+ *
+ * Three tiers:
+ * 1. No ACL (open): no reference node → anyone can read/write
+ * 2. ACL unencrypted: reference node with encrypted:false → policy enforcement
+ * 3. ACL encrypted: reference node with encrypted:true → cryptographic enforcement (CEK)
+ */
+import { verify, wrapCek, unwrapCek, generateCek, } from './crypto.js';
+import { PermissionDeniedError, InvalidAclSignatureError, AclError, } from './errors.js';
+// ── ACL Manager ────────────────────────────────────────────
+// @req FR-28
+export class AclManager {
+    obs;
+    /** In-memory cache of ACL reference nodes. */
+    refNodes = new Map();
+    serverPublicKey = null;
+    constructor(obs) {
+        this.obs = obs;
+    }
+    /**
+     * Set the trusted server's public key for signature verification.
+     */
+    setServerPublicKey(pk) {
+        this.serverPublicKey = pk;
+    }
+    /**
+     * Apply an ACL reference node update (from server or sync).
+     * Verifies server signature before accepting.
+     */
+    // @req FR-28
+    applyReferenceNode(node) {
+        if (!this.serverPublicKey) {
+            // No server key configured — accept in open mode
+            this.refNodes.set(node.subtreeId, node);
+            return { ok: true, value: undefined };
+        }
+        // Verify server signature
+        const payload = serializeAclPayload({
+            subtreeId: node.subtreeId,
+            owner: node.owner,
+            encrypted: node.encrypted,
+            acl: node.acl,
+        });
+        if (!verify(payload, node.signature, this.serverPublicKey)) {
+            this.obs.logger.warn({ subtreeId: node.subtreeId }, 'invalid ACL signature rejected');
+            return { ok: false, error: new InvalidAclSignatureError() };
+        }
+        this.refNodes.set(node.subtreeId, node);
+        this.obs.logger.debug({ subtreeId: node.subtreeId }, 'ACL reference node applied');
+        return { ok: true, value: undefined };
+    }
+    /**
+     * Check if a user has read permission on a subtree.
+     */
+    checkRead(subtreeId, userId, ownKem) {
+        const node = this.refNodes.get(subtreeId);
+        // No ACL → open access
+        if (!node) {
+            return { allowed: true, tier: 'open' };
+        }
+        const perms = node.acl[userId];
+        if (!perms?.r) {
+            return { allowed: false, tier: node.encrypted ? 'crypto' : 'policy' };
+        }
+        // Encrypted subtree → need to decrypt CEK
+        if (node.encrypted && ownKem) {
+            const wrappedCek = node.ceks?.[userId];
+            if (!wrappedCek) {
+                return { allowed: false, tier: 'crypto' };
+            }
+            const result = unwrapCek(wrappedCek, ownKem);
+            if (!result.ok) {
+                return { allowed: false, tier: 'crypto' };
+            }
+            return { allowed: true, tier: 'crypto', cek: result.value };
+        }
+        return { allowed: true, tier: node.encrypted ? 'crypto' : 'policy' };
+    }
+    /**
+     * Check if a user has write permission on a subtree.
+     */
+    checkWrite(subtreeId, userId) {
+        const node = this.refNodes.get(subtreeId);
+        if (!node) {
+            return { allowed: true, tier: 'open' };
+        }
+        const perms = node.acl[userId];
+        if (!perms?.w) {
+            return { allowed: false, tier: node.encrypted ? 'crypto' : 'policy' };
+        }
+        return { allowed: true, tier: node.encrypted ? 'crypto' : 'policy' };
+    }
+    /**
+     * Check if a user has admin permission on a subtree.
+     */
+    checkAdmin(subtreeId, userId) {
+        const node = this.refNodes.get(subtreeId);
+        if (!node)
+            return true; // No ACL = everyone is admin
+        return node.acl[userId]?.a ?? false;
+    }
+    /**
+     * Validate a permission grant request.
+     * Only users with a:true can grant permissions.
+     */
+    validateGrant(subtreeId, granterId, targetPerms) {
+        // Validate permission combinations
+        if (targetPerms.w && !targetPerms.r) {
+            return { ok: false, error: new AclError('Write without read is not allowed', 'INVALID_PERMS') };
+        }
+        if (targetPerms.a && !targetPerms.w) {
+            return { ok: false, error: new AclError('Admin without write is not allowed', 'INVALID_PERMS') };
+        }
+        if (!this.checkAdmin(subtreeId, granterId)) {
+            return { ok: false, error: new PermissionDeniedError('Only admins can grant access') };
+        }
+        return { ok: true, value: undefined };
+    }
+    /**
+     * Validate a permission revoke request.
+     * Cannot revoke the owner.
+     */
+    validateRevoke(subtreeId, revokerId, targetId) {
+        const node = this.refNodes.get(subtreeId);
+        if (!node) {
+            return { ok: false, error: new AclError('No ACL on this subtree', 'NO_ACL') };
+        }
+        if (targetId === node.owner) {
+            return { ok: false, error: new AclError('Cannot revoke owner access', 'OWNER_PROTECTED') };
+        }
+        if (!this.checkAdmin(subtreeId, revokerId)) {
+            return { ok: false, error: new PermissionDeniedError('Only admins can revoke access') };
+        }
+        return { ok: true, value: undefined };
+    }
+    /**
+     * Create a new ACL reference node for a subtree.
+     * The node must be signed by the server before distribution.
+     */
+    createAclPayload(subtreeId, ownerId, acl, encrypted) {
+        return { subtreeId, owner: ownerId, encrypted, acl };
+    }
+    /**
+     * Generate wrapped CEKs for all users in an encrypted subtree.
+     */
+    generateCeks(acl, userPublicKeys) {
+        const cek = generateCek();
+        const wrappedCeks = {};
+        for (const userId of Object.keys(acl)) {
+            const pk = userPublicKeys[userId];
+            if (pk) {
+                wrappedCeks[userId] = wrapCek(cek, pk);
+            }
+        }
+        return { cek, wrappedCeks };
+    }
+    /**
+     * Rotate CEK after user revocation.
+     * Generates new CEK and re-wraps for remaining users.
+     */
+    rotateCek(acl, userPublicKeys) {
+        return this.generateCeks(acl, userPublicKeys);
+    }
+    /**
+     * Get the ACL for a subtree.
+     */
+    getAcl(subtreeId) {
+        return this.refNodes.get(subtreeId)?.acl;
+    }
+    /**
+     * Get reference node for a subtree.
+     */
+    getReferenceNode(subtreeId) {
+        return this.refNodes.get(subtreeId);
+    }
+    /**
+     * Check if a subtree is encrypted.
+     */
+    isEncrypted(subtreeId) {
+        return this.refNodes.get(subtreeId)?.encrypted ?? false;
+    }
+    /**
+     * Check if a subtree has an ACL.
+     */
+    hasAcl(subtreeId) {
+        return this.refNodes.has(subtreeId);
+    }
+    /**
+     * Get the full reference node for a subtree.
+     */
+    getRefNode(subtreeId) {
+        return this.refNodes.get(subtreeId);
+    }
+}
+// ── Helpers ────────────────────────────────────────────────
+/** Serialize ACL payload to bytes for signing/verification. */
+function serializeAclPayload(payload) {
+    const json = JSON.stringify(payload, Object.keys(payload).sort());
+    return new TextEncoder().encode(json);
+}
+/** Exported for server-side signing. */
+export { serializeAclPayload };
+// ── Reference Node Serialization ──────────────────────────
+/**
+ * Serialize an AclReferenceNode to a Yjs-storable flat object.
+ *
+ * Flattens the HybridSignature to top-level `sig_ed25519` / `sig_mlDsa44`
+ * keys so that Yjs Y.Map roundtrip preserves the Uint8Array values.
+ */
+// @req FR-28
+export function serializeRefNode(node) {
+    const result = {
+        subtreeId: node.subtreeId,
+        owner: node.owner,
+        encrypted: node.encrypted,
+        acl: node.acl,
+        sig_ed25519: node.signature.ed25519,
+        sig_mlDsa44: node.signature.mlDsa44,
+    };
+    if (node.ceks) {
+        result.ceks = node.ceks;
+    }
+    return result;
+}
+/**
+ * Deserialize a Yjs-stored object back into an AclReferenceNode.
+ *
+ * Throws if the data doesn't contain the required fields.
+ */
+// @req FR-28
+export function deserializeRefNode(data) {
+    if (typeof data.subtreeId !== 'string' ||
+        typeof data.owner !== 'string' ||
+        typeof data.encrypted !== 'boolean' ||
+        typeof data.acl !== 'object' || data.acl === null ||
+        !(data.sig_ed25519 instanceof Uint8Array) ||
+        !(data.sig_mlDsa44 instanceof Uint8Array)) {
+        throw new AclError('Invalid ACL reference node data', 'ACL_INVALID_DATA');
+    }
+    const node = {
+        subtreeId: data.subtreeId,
+        owner: data.owner,
+        encrypted: data.encrypted,
+        acl: data.acl,
+        signature: {
+            ed25519: data.sig_ed25519,
+            mlDsa44: data.sig_mlDsa44,
+        },
+    };
+    if (data.ceks && typeof data.ceks === 'object' && !ArrayBuffer.isView(data.ceks) && !Array.isArray(data.ceks)) {
+        node.ceks = data.ceks;
+    }
+    return node;
+}
+//# sourceMappingURL=acl.js.map

package/dist/acl.js.map

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

package/dist/crypto.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Crypto Module — PQ hybrid cryptography for Sietch.
+ *
+ * Provides hybrid Ed25519+ML-DSA-44 signing, X25519+ML-KEM-768 key exchange,
+ * AES-256-GCM symmetric encryption, and Merkle-batched signatures.
+ *
+ * Internal module — never exposed directly to the developer API.
+ */
+import type { Result } from './types.js';
+import { CryptoError, KeyExchangeError } from './errors.js';
+/** Classical Ed25519 keypair. */
+export interface Ed25519Keypair {
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}
+/** Post-quantum ML-DSA-44 keypair. */
+export interface MlDsa44Keypair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+/** Classical X25519 keypair. */
+export interface X25519Keypair {
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}
+/** Post-quantum ML-KEM-768 keypair. */
+export interface MlKem768Keypair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+/** Hybrid signing keypair (Ed25519 + ML-DSA-44). */
+export interface HybridSigningKeypair {
+    ed25519: Ed25519Keypair;
+    mlDsa44: MlDsa44Keypair;
+}
+/** Hybrid KEM keypair (X25519 + ML-KEM-768). */
+export interface HybridKemKeypair {
+    x25519: X25519Keypair;
+    mlKem768: MlKem768Keypair;
+}
+/** Complete hybrid keypair (signing + key exchange). */
+export interface HybridKeypair {
+    signing: HybridSigningKeypair;
+    kem: HybridKemKeypair;
+}
+/** Public-only half of a hybrid keypair. */
+export interface HybridPublicKey {
+    signing: {
+        ed25519: Uint8Array;
+        mlDsa44: Uint8Array;
+    };
+    kem: {
+        x25519: Uint8Array;
+        mlKem768: Uint8Array;
+    };
+}
+/** Hybrid signature (Ed25519 + ML-DSA-44 concatenated). */
+export interface HybridSignature {
+    ed25519: Uint8Array;
+    mlDsa44: Uint8Array;
+}
+/** Merkle proof for a single record in a batch. */
+export interface MerkleProof {
+    index: number;
+    siblings: Uint8Array[];
+}
+/** Batch signature with Merkle root signed by hybrid scheme. */
+export interface BatchSignature {
+    root: Uint8Array;
+    signature: HybridSignature;
+    leaves: Uint8Array[];
+}
+/** Shared secret derived from hybrid key exchange. */
+export interface SharedSecret {
+    secret: Uint8Array;
+}
+/**
+ * Generate a complete hybrid keypair for signing and key exchange.
+ *
+ * @returns Hybrid keypair with Ed25519+ML-DSA-44 signing and X25519+ML-KEM-768 KEM
+ */
+export declare function generateKeypair(): HybridKeypair;
+/**
+ * Extract public key portion from a full keypair.
+ */
+export declare function extractPublicKey(keypair: HybridKeypair): HybridPublicKey;
+/**
+ * Sign a message with hybrid Ed25519 + ML-DSA-44 signature.
+ */
+export declare function sign(message: Uint8Array, keypair: HybridSigningKeypair): HybridSignature;
+/**
+ * Verify a hybrid signature against a message and public key.
+ *
+ * Both classical and post-quantum signatures must be valid.
+ */
+export declare function verify(message: Uint8Array, signature: HybridSignature, publicKey: HybridPublicKey): boolean;
+/**
+ * Sign a batch of records using Merkle-batched signatures (ADR-004).
+ *
+ * Up to 64 records share a single hybrid signature via a Merkle tree.
+ * Each record gets a per-record Merkle proof for independent verification.
+ *
+ * @param records - Array of records to sign (max BATCH_SIZE)
+ * @param keypair - Signing keypair
+ * @returns Batch signature with root and per-record leaf hashes
+ */
+export declare function signBatch(records: Uint8Array[], keypair: HybridSigningKeypair): BatchSignature;
+/**
+ * Get a Merkle proof for a specific record in a batch.
+ */
+export declare function getBatchProof(records: Uint8Array[], index: number): MerkleProof;
+/**
+ * Verify a single record against a batch signature using its Merkle proof.
+ */
+export declare function verifyRecord(record: Uint8Array, batchSig: BatchSignature, proof: MerkleProof, publicKey: HybridPublicKey): boolean;
+/**
+ * Perform hybrid key exchange: X25519 + ML-KEM-768.
+ *
+ * Initiator side: encapsulates a shared secret using the responder's public keys.
+ *
+ * @returns Shared secret and encapsulated data to send to responder
+ */
+export declare function keyExchangeInitiate(localKeypair: HybridKemKeypair, remotePublicKey: HybridPublicKey): {
+    shared: SharedSecret;
+    encapsulated: {
+        classical: Uint8Array;
+        pq: Uint8Array;
+    };
+};
+/**
+ * Respond to a hybrid key exchange.
+ *
+ * Responder side: decapsulates the shared secret using own private keys.
+ */
+export declare function keyExchangeRespond(localKeypair: HybridKemKeypair, encapsulated: {
+    classical: Uint8Array;
+    pq: Uint8Array;
+}): Result<SharedSecret, KeyExchangeError>;
+/**
+ * Encrypt plaintext with AES-256-GCM.
+ *
+ * Generates a random 12-byte nonce per invocation (prepended to ciphertext).
+ *
+ * @param plaintext - Data to encrypt
+ * @param key - 32-byte AES key
+ * @returns Nonce (12 bytes) || ciphertext || tag (16 bytes)
+ */
+export declare function encrypt(plaintext: Uint8Array, key: Uint8Array): Uint8Array;
+/**
+ * Decrypt AES-256-GCM ciphertext.
+ *
+ * @param data - Nonce (12 bytes) || ciphertext || tag (16 bytes)
+ * @param key - 32-byte AES key
+ * @returns Decrypted plaintext
+ */
+export declare function decrypt(data: Uint8Array, key: Uint8Array): Result<Uint8Array, CryptoError>;
+/**
+ * Wrap a Content Encryption Key (CEK) for a recipient using hybrid KEM.
+ *
+ * Uses ML-KEM-768 encapsulation to derive a wrapping key, then AES-256-GCM wraps the CEK.
+ *
+ * @returns Wrapped CEK: KEM ciphertext || AES-encrypted CEK
+ */
+export declare function wrapCek(cek: Uint8Array, recipientPk: HybridPublicKey): Uint8Array;
+/**
+ * Unwrap a CEK using own private keys.
+ */
+export declare function unwrapCek(wrapped: Uint8Array, ownKeypair: HybridKemKeypair): Result<Uint8Array, CryptoError>;
+/**
+ * Encrypt private key material for storage using a password-derived key.
+ *
+ * @param keypair - Full hybrid keypair to protect
+ * @param password - User password or browser-derived key
+ * @returns Encrypted keypair bytes
+ */
+export declare function encryptKeypair(keypair: HybridKeypair, password: Uint8Array): Uint8Array;
+/**
+ * Decrypt private key material from storage.
+ */
+export declare function decryptKeypair(encrypted: Uint8Array, password: Uint8Array): Result<HybridKeypair, CryptoError>;
+/**
+ * Generate a random Content Encryption Key (CEK) for subtree encryption.
+ */
+export declare function generateCek(): Uint8Array;