@protontech/drive-sdk 0.0.10

package/src/internal/nodes/nodesManagement.ts

@@ -0,0 +1,272 @@
+import { c } from 'ttag';
+
+import { MemberRole, NodeType, NodeResult, resultOk } from "../../interface";
+import { AbortError, ValidationError } from "../../errors";
+import { getErrorMessage } from '../errors';
+import { NodeAPIService } from "./apiService";
+import { NodesCryptoCache } from "./cryptoCache";
+import { NodesCryptoService } from "./cryptoService";
+import { NodesEvents } from './events';
+import { DecryptedNode } from "./interface";
+import { NodesAccess } from "./nodesAccess";
+import { validateNodeName } from "./validations";
+import { generateFolderExtendedAttributes } from "./extendedAttributes";
+
+/**
+ * Provides high-level actions for managing nodes.
+ *
+ * The manager is responsible for handling nodes metadata, including
+ * API communication, encryption, decryption, and caching.
+ *
+ * This module uses other modules providing low-level operations, such
+ * as API service, cache, crypto service, etc.
+ */
+export class NodesManagement {
+    constructor(
+        private apiService: NodeAPIService,
+        private cryptoCache: NodesCryptoCache,
+        private cryptoService: NodesCryptoService,
+        private nodesAccess: NodesAccess,
+        private nodesEvents: NodesEvents,
+    ) {
+        this.apiService = apiService;
+        this.cryptoCache = cryptoCache;
+        this.cryptoService = cryptoService;
+        this.nodesAccess = nodesAccess;
+        this.nodesEvents = nodesEvents;
+    }
+
+    async renameNode(nodeUid: string, newName: string, options = { allowRenameRootNode: false }): Promise<DecryptedNode> {
+        validateNodeName(newName);
+
+        const node = await this.nodesAccess.getNode(nodeUid);
+        const { nameSessionKey: nodeNameSessionKey } = await this.nodesAccess.getNodePrivateAndSessionKeys(nodeUid);
+        const parentKeys = await this.nodesAccess.getParentKeys(node);
+        const address = await this.nodesAccess.getRootNodeEmailKey(nodeUid);
+
+        if (!options.allowRenameRootNode && (!node.hash || !parentKeys.hashKey)) {
+            throw new ValidationError(c('Error').t`Renaming root item is not allowed`)
+        }
+
+        const {
+            signatureEmail,
+            armoredNodeName,
+            hash,
+        } = await this.cryptoService.encryptNewName(nodeNameSessionKey, address, parentKeys.hashKey, newName);
+
+        // Because hash is optional, lets ensure we have it unless explicitely
+        // allowed to rename root node.
+        if (!options.allowRenameRootNode && !hash) {
+            throw new Error("Node hash not generated");
+        }
+
+        await this.apiService.renameNode(
+            nodeUid,
+            {
+                hash: node.hash,
+            },
+            {
+                encryptedName: armoredNodeName,
+                nameSignatureEmail: signatureEmail,
+                hash: hash,
+            }
+        );
+        const newNode: DecryptedNode = {
+            ...node,
+            name: resultOk(newName),
+            nameAuthor: resultOk(signatureEmail),
+            hash,
+        }
+        await this.nodesEvents.nodeUpdated(newNode);
+        return newNode;
+    }
+
+    // Improvement requested: move nodes in parallel
+    async* moveNodes(nodeUids: string[], newParentNodeUid: string, signal?: AbortSignal): AsyncGenerator<NodeResult> {
+        for (const nodeUid of nodeUids) {
+            if (signal?.aborted) {
+                throw new AbortError(c('Error').t`Move operation aborted`);
+            }
+            try {
+                await this.moveNode(nodeUid, newParentNodeUid);
+                yield {
+                    uid: nodeUid,
+                    ok: true,
+                }
+            } catch (error: unknown) {
+                yield {
+                    uid: nodeUid,
+                    ok: false,
+                    error: getErrorMessage(error),
+                }
+            }
+        }
+    }
+
+    async moveNode(nodeUid: string, newParentUid: string): Promise<DecryptedNode> {
+        const [node, address] = await Promise.all([
+            this.nodesAccess.getNode(nodeUid),
+            this.nodesAccess.getRootNodeEmailKey(newParentUid),
+        ]);
+
+        const [keys, newParentKeys] = await Promise.all([
+            this.nodesAccess.getNodePrivateAndSessionKeys(nodeUid),
+            this.nodesAccess.getNodeKeys(newParentUid),
+        ]);
+
+        if (!node.hash) {
+            throw new ValidationError(c('Error').t`Moving root item is not allowed`);
+        }
+        if (!newParentKeys.hashKey) {
+            throw new ValidationError(c('Error').t`Moving item to a non-folder is not allowed`);
+        }
+
+        const encryptedCrypto = await this.cryptoService.moveNode(
+            node,
+            keys,
+            { key: newParentKeys.key, hashKey: newParentKeys.hashKey },
+            address,
+        );
+
+        // Node could be uploaded or renamed by anonymous user and thus have
+        // missing signatures that must be added to the move request.
+        // Node passphrase and signature email must be passed if and only if
+        // the the signatures are missing (key author is null).
+        const anonymousKey = node.keyAuthor.ok && node.keyAuthor.value === null;
+        const keySignatureProperties = !anonymousKey ? {} : {
+            signatureEmail: encryptedCrypto.signatureEmail,
+            armoredNodePassphraseSignature: encryptedCrypto.armoredNodePassphraseSignature,
+        }
+        await this.apiService.moveNode(
+            nodeUid,
+            {
+                hash: node.hash,
+            }, 
+            {
+                ...keySignatureProperties,
+                parentUid: newParentUid,
+                armoredNodePassphrase: encryptedCrypto.armoredNodePassphrase,
+                encryptedName: encryptedCrypto.encryptedName,
+                nameSignatureEmail: encryptedCrypto.nameSignatureEmail,
+                hash: encryptedCrypto.hash,
+                // TODO: When moving photos, we need to pass content hash.
+            }
+        );
+        const newNode: DecryptedNode = {
+            ...node,
+            parentUid: newParentUid,
+            hash: encryptedCrypto.hash,
+            keyAuthor: resultOk(encryptedCrypto.signatureEmail),
+            nameAuthor: resultOk(encryptedCrypto.nameSignatureEmail),
+        };
+        await this.nodesEvents.nodeUpdated(newNode);
+        return newNode;
+    }
+
+    async* trashNodes(nodeUids: string[], signal?: AbortSignal): AsyncGenerator<NodeResult> {
+        const nodesOrMissing = await Array.fromAsync(this.nodesAccess.iterateNodes(nodeUids, signal));
+        const nodes = nodesOrMissing.filter(node => !('missingUid' in node)) as DecryptedNode[];
+
+        for await (const result of this.apiService.trashNodes(nodeUids, signal)) {
+            if (result.ok) {
+                const node = nodes.find(node => node.uid === result.uid);
+                if (node) {
+                    await this.nodesEvents.nodeUpdated({
+                        ...node,
+                        trashTime: new Date(),
+                    });
+                }
+            }
+
+            yield result;
+        }
+    }
+
+    async* restoreNodes(nodeUids: string[], signal?: AbortSignal): AsyncGenerator<NodeResult> {
+        const nodesOrMissing = await Array.fromAsync(this.nodesAccess.iterateNodes(nodeUids, signal));
+        const nodes = nodesOrMissing.filter(node => !('missingUid' in node)) as DecryptedNode[];
+
+        for await (const result of this.apiService.restoreNodes(nodeUids, signal)) {
+            if (result.ok) {
+                const node = nodes.find(node => node.uid === result.uid);
+                if (node) {
+                    await this.nodesEvents.nodeUpdated({
+                        ...node,
+                        trashTime: undefined,
+                    });
+                }
+            }
+
+            yield result;
+        }
+    }
+
+    async* deleteNodes(nodeUids: string[], signal?: AbortSignal): AsyncGenerator<NodeResult> {
+        const deletedNodeUids = [];
+
+        for await (const result of this.apiService.deleteNodes(nodeUids, signal)) {
+            if (result.ok) {
+                deletedNodeUids.push(result.uid);
+            }
+            yield result;
+        }
+
+        await this.nodesEvents.nodesDeleted(deletedNodeUids);
+    }
+
+    async createFolder(parentNodeUid: string, folderName: string, modificationTime?: Date): Promise<DecryptedNode> {
+        validateNodeName(folderName);
+
+        const parentKeys = await this.nodesAccess.getNodeKeys(parentNodeUid);
+        if (!parentKeys.hashKey) {
+            throw new ValidationError(c('Error').t`Creating folders in non-folders is not allowed`);
+        }
+
+        const address = await this.nodesAccess.getRootNodeEmailKey(parentNodeUid);
+        const extendedAttributes = generateFolderExtendedAttributes(modificationTime);
+
+        const { encryptedCrypto, keys } = await this.cryptoService.createFolder(
+            { key: parentKeys.key, hashKey: parentKeys.hashKey },
+            address,
+            folderName,
+            extendedAttributes,
+        );
+        const nodeUid = await this.apiService.createFolder(parentNodeUid, {
+            armoredKey: encryptedCrypto.armoredKey,
+            armoredHashKey: encryptedCrypto.folder.armoredHashKey,
+            armoredNodePassphrase: encryptedCrypto.armoredNodePassphrase,
+            armoredNodePassphraseSignature: encryptedCrypto.armoredNodePassphraseSignature,
+            signatureEmail: encryptedCrypto.signatureEmail,
+            encryptedName: encryptedCrypto.encryptedName,
+            hash: encryptedCrypto.hash,
+            armoredExtendedAttributes: encryptedCrypto.folder.armoredExtendedAttributes,
+        });
+
+        const node: DecryptedNode = {
+            // Internal metadata
+            hash: encryptedCrypto.hash,
+            encryptedName: encryptedCrypto.encryptedName,
+
+            // Basic node metadata
+            uid: nodeUid,
+            parentUid: parentNodeUid,
+            type: NodeType.Folder,
+            mediaType: "Folder",
+            creationTime: new Date(),
+
+            // Share node metadata
+            isShared: false,
+            directMemberRole: MemberRole.Inherited,
+
+            // Decrypted metadata
+            isStale: false,
+            keyAuthor: resultOk(encryptedCrypto.signatureEmail),
+            nameAuthor: resultOk(encryptedCrypto.signatureEmail),
+            name: resultOk(folderName),
+        }
+
+        await this.nodesEvents.nodeCreated(node);
+        await this.cryptoCache.setNodeKeys(nodeUid, keys);
+        return node;
+    }
+}

package/src/internal/nodes/nodesRevisions.ts

@@ -0,0 +1,58 @@
+import { Logger, Revision } from "../../interface";
+import { makeNodeUidFromRevisionUid } from "../uids";
+import { NodeAPIService } from "./apiService";
+import { NodesCryptoService } from "./cryptoService";
+import { NodesAccess } from "./nodesAccess";
+import { parseFileExtendedAttributes } from "./extendedAttributes";
+
+/**
+ * Provides access to revisions metadata.
+ */
+export class NodesRevisons {
+    constructor(
+        private logger: Logger,
+        private apiService: NodeAPIService,
+        private cryptoService: NodesCryptoService,
+        private nodesAccess: NodesAccess,
+    ) {
+        this.logger = logger;
+        this.apiService = apiService;
+        this.cryptoService = cryptoService;
+        this.nodesAccess = nodesAccess;
+    }
+
+    async getRevision(nodeRevisionUid: string): Promise<Revision> {
+        const nodeUid = makeNodeUidFromRevisionUid(nodeRevisionUid);
+        const { key } = await this.nodesAccess.getNodeKeys(nodeUid);
+
+        const encryptedRevision = await this.apiService.getRevision(nodeRevisionUid);
+        const revision = await this.cryptoService.decryptRevision(nodeUid, encryptedRevision, key);
+        const extendedAttributes = parseFileExtendedAttributes(this.logger, revision.extendedAttributes);
+        return {
+            ...revision,
+            ...extendedAttributes,
+        };
+    }
+
+    async* iterateRevisions(nodeUid: string, signal?: AbortSignal): AsyncGenerator<Revision> {
+        const { key } = await this.nodesAccess.getNodeKeys(nodeUid);
+
+        const encryptedRevisions = await this.apiService.getRevisions(nodeUid, signal);
+        for (const encryptedRevision of encryptedRevisions) {
+            const revision = await this.cryptoService.decryptRevision(nodeUid, encryptedRevision, key);
+            const extendedAttributes = parseFileExtendedAttributes(this.logger, revision.extendedAttributes);
+            yield {
+                ...revision,
+                ...extendedAttributes,
+            };
+        }
+    }
+
+    async restoreRevision(nodeRevisionUid: string): Promise<void> {
+        await this.apiService.restoreRevision(nodeRevisionUid);
+    }
+
+    async deleteRevision(nodeRevisionUid: string): Promise<void> {
+        await this.apiService.deleteRevision(nodeRevisionUid);
+    }
+}

package/src/internal/nodes/validations.ts

@@ -0,0 +1,26 @@
+import { c, msgid } from 'ttag';
+
+import { ValidationError } from '../../errors';
+
+const MAX_NODE_NAME_LENGTH = 255;
+
+/**
+ * @throws Error if the name is empty, long, or includes slash in the name.
+ */
+export function validateNodeName(name: string): void {
+    if (!name) {
+        throw new ValidationError(c('Error').t`Name must not be empty`);
+    }
+    if (name.length > MAX_NODE_NAME_LENGTH) {
+        throw new ValidationError(
+            c('Error').ngettext(
+                msgid`Name must be ${MAX_NODE_NAME_LENGTH} character long at most`,
+                `Name must be ${MAX_NODE_NAME_LENGTH} characters long at most`,
+                MAX_NODE_NAME_LENGTH
+            )
+        );
+    }
+    if (name.includes('/')) {
+        throw new ValidationError(c('Error').t`Name must not contain the character '/'`);
+    }
+}

package/src/internal/photos/albums.ts

@@ -0,0 +1,29 @@
+import { PhotosAPIService } from "./apiService";
+import { PhotosCache } from "./cache";
+import { NodesService } from "./interface";
+
+export class Albums {
+    constructor(
+        private apiService: PhotosAPIService,
+        private cache: PhotosCache,
+        private nodesService: NodesService,
+    ) {
+        this.apiService = apiService;
+        this.cache = cache;
+        this.nodesService = nodesService;
+    }
+
+    async* iterateAlbums() {
+        for await (const album of this.apiService.iterateAlbums()) {
+            const node = await this.nodesService.getNode(album.uid);
+            yield {
+                node,
+            }
+        }
+    }
+
+    async createAlbum(albumName: string) {
+        const albumdUid = this.apiService.createAlbum(albumName);
+        await this.cache.setAlbum(albumdUid);
+    }
+}

package/src/internal/photos/apiService.ts

@@ -0,0 +1,16 @@
+import { DriveAPIService } from "../apiService";
+
+export class PhotosAPIService {
+    constructor(private apiService: DriveAPIService) {
+        this.apiService = apiService;
+    }
+
+    async* iterateTimeline(): AsyncGenerator<any> {
+    }
+
+    async* iterateAlbums(): AsyncGenerator<any> {
+    }
+
+    async createAlbum(object: any): Promise<any> {
+    }
+}

package/src/internal/photos/cache.ts

@@ -0,0 +1,11 @@
+import { ProtonDriveEntitiesCache } from "../../interface";
+
+export class PhotosCache {
+    constructor(private driveCache: ProtonDriveEntitiesCache) {
+        this.driveCache = driveCache;
+    }
+
+    async setAlbum(album: any) {
+        await this.driveCache.setEntity(album.uid, album);
+    }
+}

package/src/internal/photos/index.ts

@@ -0,0 +1,23 @@
+import { DriveAPIService } from "../apiService";
+import { ProtonDriveEntitiesCache } from "../../interface";
+import { PhotosAPIService } from "./apiService";
+import { PhotosCache } from "./cache";
+import { PhotosTimeline } from "./photosTimeline";
+import { Albums } from "./albums";
+import { NodesService } from "./interface";
+
+export function initPhotosModule(
+    apiService: DriveAPIService,
+    driveEntitiesCache: ProtonDriveEntitiesCache,
+    nodesService: NodesService,
+) {
+    const api = new PhotosAPIService(apiService);
+    const cache = new PhotosCache(driveEntitiesCache);
+    const timeline = new PhotosTimeline(api, cache, nodesService);
+    const albums = new Albums(api, cache, nodesService);
+
+    return {
+        timeline,
+        albums,
+    }
+}

package/src/internal/photos/interface.ts

@@ -0,0 +1,7 @@
+import { MissingNode } from "../../interface";
+import { DecryptedNode } from "../nodes";
+
+export interface NodesService {
+    getNode(nodeUid: string): Promise<DecryptedNode>;
+    iterateNodes(nodeUids: string[], signal?: AbortSignal): AsyncGenerator<DecryptedNode | MissingNode>;
+}

package/src/internal/photos/photosTimeline.ts

@@ -0,0 +1,18 @@
+import { PhotosAPIService } from "./apiService";
+import { PhotosCache } from "./cache";
+import { NodesService } from "./interface";
+
+export class PhotosTimeline {
+    constructor(
+        private apiService: PhotosAPIService,
+        private cache: PhotosCache,
+        private nodesService: NodesService,
+    ) {
+        this.apiService = apiService;
+        this.cache = cache;
+        this.nodesService = nodesService;
+    }
+
+    async getTimelineStructure() {
+    }
+}

package/src/internal/sdkEvents.test.ts

@@ -0,0 +1,55 @@
+import { SDKEvent } from "../interface";
+import { SDKEvents } from "./sdkEvents";
+
+describe("SDKEvents", () => {
+    let sdkEvents: SDKEvents;
+    let logger: { debug: jest.Mock };
+
+    beforeEach(() => {
+        logger = { debug: jest.fn() };
+        sdkEvents = new SDKEvents({ getLogger: () => logger } as any);
+    });
+
+    it("should log when no listeners are present for an event", () => {
+        sdkEvents.requestsThrottled();
+
+        expect(logger.debug).toHaveBeenCalledWith("No listeners for event: requestsThrottled");
+    });
+
+    it("should emit an event to its listeners", () => {
+        const requestsThrottledListener = jest.fn();
+        sdkEvents.addListener(SDKEvent.RequestsThrottled, requestsThrottledListener);
+        const requestsUnthrottledListener = jest.fn();
+        sdkEvents.addListener(SDKEvent.RequestsUnthrottled, requestsUnthrottledListener);
+
+        sdkEvents.requestsThrottled();
+
+        expect(requestsThrottledListener).toHaveBeenCalled();
+        expect(requestsUnthrottledListener).not.toHaveBeenCalled();
+        expect(logger.debug).toHaveBeenCalledWith("Emitting event: requestsThrottled");
+    });
+
+    it("should emit an event to multiple listeners", () => {
+        const requestsThrottledListener1 = jest.fn();
+        const requestsThrottledListener2 = jest.fn();
+        sdkEvents.addListener(SDKEvent.RequestsThrottled, requestsThrottledListener1);
+        sdkEvents.addListener(SDKEvent.RequestsThrottled, requestsThrottledListener2);
+
+        sdkEvents.requestsThrottled();
+
+        expect(requestsThrottledListener1).toHaveBeenCalled();
+        expect(requestsThrottledListener2).toHaveBeenCalled();
+        expect(logger.debug).toHaveBeenCalledWith("Emitting event: requestsThrottled");
+    });
+
+    it("should not emit after unsubsribe", () => {
+        const callback = jest.fn();
+        const unsubscribe = sdkEvents.addListener(SDKEvent.RequestsThrottled, callback);
+
+        sdkEvents.requestsThrottled();
+        unsubscribe();
+        sdkEvents.requestsThrottled();
+
+        expect(callback).toHaveBeenCalledTimes(1);
+    });
+});

package/src/internal/sdkEvents.ts

@@ -0,0 +1,52 @@
+import { ProtonDriveTelemetry, Logger, SDKEvent } from "../interface";
+
+export class SDKEvents {
+    private logger: Logger;
+    private listeners: Map<SDKEvent, (() => void)[]> = new Map();
+
+    constructor(telemetry: ProtonDriveTelemetry) {
+        this.logger = telemetry.getLogger('sdk-events');
+    }
+
+    addListener(eventName: SDKEvent, callback: () => void): () => void {
+        this.listeners.set(eventName, [
+            ...(this.listeners.get(eventName) || []),
+            callback,
+        ]);
+
+        return () => {
+            this.listeners.set(
+                eventName,
+                this.listeners.get(eventName)?.filter((cb) => cb !== callback) || []
+            );
+        }
+    }
+
+    transfersPaused(): void {
+        this.emit(SDKEvent.TransfersPaused);
+    }
+
+    transfersResumed(): void {
+        this.emit(SDKEvent.TransfersResumed);
+    }
+
+    requestsThrottled(): void {
+        this.emit(SDKEvent.RequestsThrottled);
+    }
+
+    requestsUnthrottled(): void {
+        this.emit(SDKEvent.RequestsUnthrottled);
+    }
+
+    private emit(eventName: SDKEvent): void {
+        if (!this.listeners.get(eventName)?.length) {
+            this.logger.debug(`No listeners for event: ${eventName}`);
+            return;
+        }
+
+        this.logger.debug(`Emitting event: ${eventName}`);
+        this.listeners
+            .get(eventName)
+            ?.forEach((callback) => callback());
+    }
+}