@protontech/drive-sdk 0.0.10

package/src/internal/nodes/cache.ts

@@ -0,0 +1,240 @@
+import { EntityResult } from "../../cache";
+import { ProtonDriveEntitiesCache, Logger } from "../../interface";
+import { splitNodeUid } from "../uids";
+import { DecryptedNode } from "./interface";
+
+export enum CACHE_TAG_KEYS {
+    ParentUid = 'nodeParentUid',
+    Trashed = 'nodeTrashed',
+}
+
+type DecryptedNodeResult = (
+    {uid: string, ok: true, node: DecryptedNode} |
+    {uid: string, ok: false, error: string}
+);
+
+/**
+ * Provides caching for nodes metadata.
+ * 
+ * The cache is responsible for serialising and deserialising node metadata,
+ * recording parent-child relationships, and recursively removing nodes.
+ * 
+ * The cache of node metadata should not contain any crypto material.
+ */
+export class NodesCache {
+    constructor(private logger: Logger, private driveCache: ProtonDriveEntitiesCache) {
+        this.logger = logger;
+        this.driveCache = driveCache;
+    }
+
+    async setNode(node: DecryptedNode): Promise<void> {
+        const key = getCacheUid(node.uid);
+        const nodeData = serialiseNode(node);
+        const { volumeId } = splitNodeUid(node.uid);
+
+        const tags = [`volume:${volumeId}`];
+        if (node.parentUid) {
+            tags.push(`${CACHE_TAG_KEYS.ParentUid}:${node.parentUid}`)
+        }
+        if (node.trashTime) {
+            tags.push(`${CACHE_TAG_KEYS.Trashed}`)
+        }
+
+        await this.driveCache.setEntity(key, nodeData, tags);
+    }
+
+    async getNode(nodeUid: string): Promise<DecryptedNode> {
+        const key = getCacheUid(nodeUid);
+        const nodeData = await this.driveCache.getEntity(key);
+        try {
+            return deserialiseNode(nodeData);
+        } catch (error: unknown) {
+            await this.removeCorruptedNode({ nodeUid }, error);
+            throw new Error(`Failed to deserialise node: ${error instanceof Error ? error.message : error}`)
+        }
+    }
+
+    /**
+     * Set all nodes on given node as stale. This is useful when we
+     * get refresh event from the server and we thus don't know
+     * which nodes were up-to-date anymore.
+     */
+    async setNodesStaleFromVolume(volumeId: string): Promise<void> {
+        for await (const result of this.driveCache.iterateEntitiesByTag(`volume:${volumeId}`)) {
+            const node = await this.convertCacheResult(result);
+            if (node && node.ok) {
+                node.node.isStale = true;
+                await this.setNode(node.node);
+            }
+        }
+
+        // Force all calls to children UIDs to be re-fetched.
+        for await (const result of this.driveCache.iterateEntitiesByTag(`children-volume:${volumeId}`)) {
+            await this.driveCache.removeEntities([result.key]);
+        }
+    }
+
+    /**
+     * Remove corrupted node never throws, but it logs so we can know
+     * about issues and fix them. It is crucial to remove corrupted
+     * nodes and rather let SDK re-fetch them than to auotmatically
+     * fix issues and do not bother user with it.
+     */
+    private async removeCorruptedNode({ nodeUid, cacheUid }: { nodeUid?: string, cacheUid?: string }, corruptionError: unknown): Promise<void> {
+        this.logger.error(`Removing corrupted nodes from the cache`, corruptionError);
+        try {
+            if (nodeUid) {
+                await this.removeNodes([nodeUid]);
+            } else if (cacheUid) {
+                await this.driveCache.removeEntities([cacheUid]);
+            }
+        } catch (removingError: unknown) {
+            // The node will not be returned, thus SDK will re-fetch
+            // and re-cache it. Setting it again should then fix the
+            // problem.
+            this.logger.warn(`Failed to remove corrupted node from the cache: ${removingError instanceof Error ? removingError.message : removingError}`);
+        }
+    }
+
+    async removeNodes(nodeUids: string[]): Promise<void> {
+        const cacheUids = nodeUids.map(getCacheUid);
+        await this.driveCache.removeEntities(cacheUids);
+        for (const nodeUid of nodeUids) {
+            try {
+                const childrenCacheUids = await this.getRecursiveChildrenCacheUids(nodeUid);
+                // Reverse the order to remove children first.
+                // Crucial to not leave any children without parent
+                // if removing nodes fails.
+                childrenCacheUids.reverse();
+                await this.driveCache.removeEntities(childrenCacheUids);
+            } catch (error: unknown) {
+                this.logger.error(`Failed to remove children from the cache`, error);
+            }
+        }
+    }
+
+    private async getRecursiveChildrenCacheUids(parentNodeUid: string): Promise<string[]> {
+        const cacheUids = [];
+        for await (const result of this.driveCache.iterateEntitiesByTag(`${CACHE_TAG_KEYS.ParentUid}:${parentNodeUid}`)) {
+            cacheUids.push(result.key);
+            const childrenCacheUids = await this.getRecursiveChildrenCacheUids(getNodeUid(result.key));
+            cacheUids.push(...childrenCacheUids);
+        }
+        return cacheUids;
+    }
+
+    async *iterateNodes(nodeUids: string[]): AsyncGenerator<DecryptedNodeResult> {
+        const cacheUids = nodeUids.map(getCacheUid);
+        for await (const result of this.driveCache.iterateEntities(cacheUids)) {
+            const node = await this.convertCacheResult(result);
+            if (node) {
+                yield node;
+            }
+        }
+    }
+
+    async *iterateChildren(parentNodeUid: string): AsyncGenerator<DecryptedNodeResult> {
+        for await (const result of this.driveCache.iterateEntitiesByTag(`${CACHE_TAG_KEYS.ParentUid}:${parentNodeUid}`)) {
+            const node = await this.convertCacheResult(result);
+            if (node && (!node.ok || !node.node.trashTime)) {
+                yield node;
+            }
+        }
+    }
+
+    async *iterateTrashedNodes(): AsyncGenerator<DecryptedNodeResult> {
+        for await (const result of this.driveCache.iterateEntitiesByTag(CACHE_TAG_KEYS.Trashed)) {
+            const node = await this.convertCacheResult(result);
+            if (node) {
+                yield node;
+            }
+        }
+    }
+
+    /**
+     * Converts result from the cache with cache UID and data to result of node
+     * with node UID and DecryptedNode.
+     */
+    private async convertCacheResult(result: EntityResult<string>): Promise<DecryptedNodeResult | null> {
+        let nodeUid;
+        try {
+            nodeUid = getNodeUid(result.key);
+        } catch (error: unknown) {
+            await this.removeCorruptedNode({ cacheUid: result.key }, error)
+            return null;
+        }
+        if (result.ok) {
+            let node;
+            try {
+                node = deserialiseNode(result.value)
+            } catch (error: unknown) {
+                await this.removeCorruptedNode({ nodeUid }, error);
+                return null;
+            }
+            return {
+                uid: nodeUid,
+                ok: true,
+                node,
+            }
+        } else {
+            return {
+                ...result,
+                uid: nodeUid,
+            };
+        }
+    }
+
+    async setFolderChildrenLoaded(nodeUid: string): Promise<void> {
+        const { volumeId } = splitNodeUid(nodeUid);
+        await this.driveCache.setEntity(`node-children-${nodeUid}`, 'loaded', [`children-volume:${volumeId}`]);
+    }
+
+    async resetFolderChildrenLoaded(nodeUid: string): Promise<void> {
+        await this.driveCache.removeEntities([`node-children-${nodeUid}`]);
+    }
+
+    async isFolderChildrenLoaded(nodeUid: string): Promise<boolean> {
+        try {
+            await this.driveCache.getEntity(`node-children-${nodeUid}`);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+}
+
+function getCacheUid(nodeUid: string) {
+    return `node-${nodeUid}`;
+}
+
+function getNodeUid(cacheUid: string) {
+    if (!cacheUid.startsWith('node-')) {
+        throw new Error(`Unexpected cached node uid "${cacheUid}"`);
+    }
+    return cacheUid.substring(5);
+}
+
+function serialiseNode(node: DecryptedNode) {
+    return JSON.stringify(node);
+}
+
+function deserialiseNode(nodeData: string): DecryptedNode {
+    const node = JSON.parse(nodeData);
+    if (
+       !node || typeof node !== 'object' ||
+       !node.uid || typeof node.uid !== 'string' ||
+       !node.directMemberRole || typeof node.directMemberRole !== 'string' ||
+       !node.type || typeof node.type !== 'string' ||
+       (typeof node.mediaType !== 'string' && node.mediaType !== undefined) ||
+       typeof node.isShared !== 'boolean' ||
+       !node.creationTime || typeof node.creationTime !== 'string' ||
+       (typeof node.trashTime !== 'string' && node.trashTime !== undefined)
+   ) {
+       throw new Error(`Invalid node data: ${nodeData}`);
+   }
+   return {
+       ...node,
+       creationTime: new Date(node.creationTime),
+       trashTime: node.trashTime ? new Date(node.trashTime) : undefined,
+   };
+}

package/src/internal/nodes/cryptoCache.test.ts

@@ -0,0 +1,92 @@
+import { PrivateKey, SessionKey } from "../../crypto";
+import { MemoryCache } from "../../cache";
+import { CachedCryptoMaterial } from "../../interface";
+import { getMockLogger } from "../../tests/logger";
+import { NodesCryptoCache } from "./cryptoCache";
+
+describe('nodesCryptoCache', () => {
+    let memoryCache: MemoryCache<CachedCryptoMaterial>;
+    let cache: NodesCryptoCache;
+
+    const generatePrivateKey = (name: string) => {
+        return name as unknown as PrivateKey
+    }
+
+    const generateSessionKey = (name: string) => {
+        return name as unknown as SessionKey
+    }
+
+    beforeEach(async () => {
+        memoryCache = new MemoryCache();
+        await memoryCache.setEntity('nodeKeys-missingPassphrase', {
+            key: 'privateKey',
+            sessionKey: 'sessionKey',
+        } as any);
+
+        cache = new NodesCryptoCache(getMockLogger(), memoryCache);
+    });
+
+    it('should store and retrieve keys', async () => {
+        const nodeId = 'newNodeId';
+        const keys = { passphrase: 'pass', key: generatePrivateKey('privateKey'), passphraseSessionKey: generateSessionKey('sessionKey'), hashKey: undefined };
+
+        await cache.setNodeKeys(nodeId, keys);
+        const result = await cache.getNodeKeys(nodeId);
+
+        expect(result).toStrictEqual(keys);
+    });
+
+    it('should replace and retrieve new keys', async () => {
+        const nodeId = 'newNodeId';
+        const keys1 = { passphrase: 'pass', key: generatePrivateKey('privateKey1'), passphraseSessionKey: generateSessionKey('sessionKey1'), hashKey: undefined };
+        const keys2 = { passphrase: 'pass', key: generatePrivateKey('privateKey2'), passphraseSessionKey: generateSessionKey('sessionKey2'), hashKey: undefined };
+
+        await cache.setNodeKeys(nodeId, keys1);
+        await cache.setNodeKeys(nodeId, keys2);
+        const result = await cache.getNodeKeys(nodeId);
+
+        expect(result).toStrictEqual(keys2);
+    });
+
+    it('should remove keys', async () => {
+        const nodeId = 'newNodeId';
+        const keys = { passphrase: 'pass', key: generatePrivateKey('privateKey'), passphraseSessionKey: generateSessionKey('sessionKey'), hashKey: undefined };
+
+        await cache.setNodeKeys(nodeId, keys);
+        await cache.removeNodeKeys([nodeId]);
+
+        try {
+            await cache.getNodeKeys(nodeId);
+            throw new Error('Should have thrown an error');
+        } catch (error) {
+            expect(`${error}`).toBe('Error: Entity not found');
+        }
+    });
+
+    it('should throw an error when retrieving a non-existing entity', async () => {
+        const nodeId = 'newNodeId';
+
+        try {
+            await cache.getNodeKeys(nodeId);
+            throw new Error('Should have thrown an error');
+        } catch (error) {
+            expect(`${error}`).toBe('Error: Entity not found');
+        }
+    });
+
+    it('should throw an error when retrieving a bad keys and remove the key', async () => {
+        try {
+            await cache.getNodeKeys('missingPassphrase');
+            throw new Error('Should have thrown an error');
+        } catch (error) {
+            expect(`${error}`).toBe('Error: Failed to deserialize node keys: missing passphrase');
+        }
+
+        try {
+            await memoryCache.getEntity('nodeKeys-missingPassphrase');
+            throw new Error('Should have thrown an error');
+        } catch (error) {
+            expect(`${error}`).toBe('Error: Entity not found');
+        }
+    });
+});

package/src/internal/nodes/cryptoCache.ts

@@ -0,0 +1,47 @@
+import { ProtonDriveCryptoCache, Logger } from "../../interface";
+import { DecryptedNodeKeys } from "./interface";
+
+/**
+ * Provides caching for node crypto material.
+ * 
+ * The cache is responsible for serialising and deserialising node
+ * crypto material.
+ */
+export class NodesCryptoCache {
+    constructor(private logger: Logger, private driveCache: ProtonDriveCryptoCache) {
+        this.logger = logger;
+        this.driveCache = driveCache;
+    }
+
+    async setNodeKeys(nodeUid: string, keys: DecryptedNodeKeys): Promise<void> {
+        const cacheUid = getCacheKey(nodeUid);
+        await this.driveCache.setEntity(cacheUid, keys);
+    }
+
+    async getNodeKeys(nodeUid: string): Promise<DecryptedNodeKeys> {
+        const nodeKeysData = await this.driveCache.getEntity(getCacheKey(nodeUid));
+        if (!nodeKeysData.passphrase) {
+            try {
+                await this.removeNodeKeys([nodeUid]);
+            } catch (removingError: unknown) {
+                // The node keys will not be returned, thus SDK will re-fetch
+                // and re-cache it. Setting it again should then fix the problem.
+                this.logger.warn(`Failed to remove corrupted node keys from the cache: ${removingError instanceof Error ? removingError.message : removingError}`);
+            }
+            throw new Error(`Failed to deserialize node keys: missing passphrase`);
+        }
+        return {
+            ...nodeKeysData,
+            passphrase: nodeKeysData.passphrase,
+        };
+    }
+
+    async removeNodeKeys(nodeUids: string[]): Promise<void> {
+        const cacheUids = nodeUids.map(getCacheKey);
+        await this.driveCache.removeEntities(cacheUids);
+    }
+}
+
+function getCacheKey(nodeUid: string) {
+    return `nodeKeys-${nodeUid}`;
+}