@protontech/drive-sdk 0.0.10

package/src/internal/sharing/events.test.ts

@@ -0,0 +1,268 @@
+import { getMockLogger } from "../../tests/logger";
+import { DriveEvent, DriveEventType } from "../events";
+import { NodesService, SharingType } from "./interface";
+import { SharingCache } from "./cache";
+import { handleSharedByMeNodes, handleSharedWithMeNodes } from "./events";
+import { SharingAccess } from "./sharingAccess";
+
+describe("handleSharedByMeNodes", () => {
+    let cache: SharingCache;
+    let nodesService: NodesService;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+
+        // @ts-expect-error No need to implement all methods for mocking
+        cache = {
+            addSharedByMeNodeUid: jest.fn(),
+            removeSharedByMeNodeUid: jest.fn(),
+            setSharedWithMeNodeUids: jest.fn(),
+        };
+        // @ts-expect-error No need to implement all methods for mocking
+        nodesService = {
+            getNode: jest.fn().mockResolvedValue({ uid: 'nodeUid', name: { ok: true, value: 'name' } }),
+        };
+    });
+
+    const testCases: { 
+        title: string,
+        existingNodeUids: string[],
+        event: DriveEvent,
+        added: boolean,
+        removed: boolean,
+    }[] = [
+        {
+            title: "should add if new own shared node is created",
+            existingNodeUids: [],
+            event: {
+                type: DriveEventType.NodeCreated,
+                nodeUid: "nodeUid",
+                parentNodeUid: "parentUid",
+                isTrashed: false,
+                isShared: true,
+                isOwnVolume: true,
+            },
+            added: true,
+            removed: false,
+        },
+        {
+            title: "should not add if new shared node is not own",
+            existingNodeUids: [],
+            event: {
+                type: DriveEventType.NodeCreated,
+                nodeUid: "nodeUid",
+                parentNodeUid: "parentUid",
+                isTrashed: false,
+                isShared: true,
+                isOwnVolume: false,
+            },
+            added: false,
+            removed: false,
+        },
+        {
+            title: "should not add if new own node is not shared",
+            existingNodeUids: [],
+            event: {
+                type: DriveEventType.NodeCreated,
+                nodeUid: "nodeUid",
+                parentNodeUid: "parentUid",
+                isTrashed: false,
+                isShared: false,
+                isOwnVolume: true,
+            },
+            added: false,
+            removed: false,
+        },
+        {
+            title: "should add if own node is updated and shared",
+            existingNodeUids: [],
+            event: {
+                type: DriveEventType.NodeUpdated,
+                nodeUid: "nodeUid",
+                parentNodeUid: "parentUid",
+                isTrashed: false,
+                isShared: true,
+                isOwnVolume: true,
+            },
+            added: true,
+            removed: false,
+        },
+        {
+            title: "should add/update if shared node is updated",
+            existingNodeUids: ["nodeUid"],
+            event: {
+                type: DriveEventType.NodeUpdated,
+                nodeUid: "nodeUid",
+                parentNodeUid: "parentUid",
+                isTrashed: false,
+                isShared: true,
+                isOwnVolume: true,
+            },
+            added: true,
+            removed: false,
+        },
+        {
+            title: "should remove if shared node is un-shared",
+            existingNodeUids: ["nodeUid"],
+            event: {
+                type: DriveEventType.NodeUpdated,
+                nodeUid: "nodeUid",
+                parentNodeUid: "parentUid",
+                isTrashed: false,
+                isShared: false,
+                isOwnVolume: true,
+            },
+            added: false,
+            removed: true,
+        },
+        {
+            title: "should not remove if non-shared node is updated",
+            existingNodeUids: [],
+            event: {
+                type: DriveEventType.NodeUpdated,
+                nodeUid: "nodeUid",
+                parentNodeUid: "parentUid",
+                isTrashed: false,
+                isShared: false,
+                isOwnVolume: true,
+            },
+            added: false,
+            removed: false,
+        },
+        {
+            title: "should remove if shared node is deleted",
+            existingNodeUids: ["nodeUid"],
+            event: {
+                type: DriveEventType.NodeDeleted,
+                nodeUid: "nodeUid",
+                parentNodeUid: "parentUid",
+                isOwnVolume: true,
+            },
+            added: false,
+            removed: true,
+        },
+        {
+            title: "should not remove if non-shared node is deleted",
+            existingNodeUids: [],
+            event: {
+                type: DriveEventType.NodeDeleted,
+                nodeUid: "nodeUid",
+                parentNodeUid: "parentUid",
+                isOwnVolume: true,
+            },
+            added: false,
+            removed: false,
+        },
+    ];
+
+    describe("with listeners", () => {
+        testCases.map(({ title, existingNodeUids, event, added, removed }) => {
+            it(title, async () => {
+                cache.getSharedByMeNodeUids = jest.fn().mockResolvedValue(existingNodeUids);
+                const listener = jest.fn();
+                const listeners = [{ type: SharingType.SharedByMe, callback: listener }];
+
+                await handleSharedByMeNodes(getMockLogger(), event, cache, listeners, nodesService);
+    
+                if (added) {
+                    expect(cache.addSharedByMeNodeUid).toHaveBeenCalledWith("nodeUid");
+                    expect(listener).toHaveBeenCalledWith(expect.objectContaining({ type: 'update', uid: 'nodeUid' }));
+                } else {
+                    expect(cache.addSharedByMeNodeUid).not.toHaveBeenCalled();
+                }
+                if (removed) {
+                    expect(cache.removeSharedByMeNodeUid).toHaveBeenCalledWith("nodeUid");
+                    expect(listener).toHaveBeenCalledWith({ type: 'remove', uid: 'nodeUid' });
+                } else {
+                    expect(cache.removeSharedByMeNodeUid).not.toHaveBeenCalled();
+                }
+                if (!added && !removed) {
+                    expect(listener).not.toHaveBeenCalled();
+                }
+ 
+                expect(cache.setSharedWithMeNodeUids).not.toHaveBeenCalled();
+            });
+        });
+    });
+
+    describe("without listeners", () => {
+        testCases.map(({ title, existingNodeUids, event, added, removed }) => {
+            it(title, async () => {
+                cache.getSharedByMeNodeUids = jest.fn().mockResolvedValue(existingNodeUids);
+                const listener = jest.fn();
+                const listeners = [{ type: SharingType.sharedWithMe, callback: listener }];
+
+                await handleSharedByMeNodes(getMockLogger(), event, cache, listeners, nodesService);
+    
+                if (added) {
+                    expect(cache.addSharedByMeNodeUid).toHaveBeenCalledWith("nodeUid");
+                } else {
+                    expect(cache.addSharedByMeNodeUid).not.toHaveBeenCalled();
+                }
+                if (removed) {
+                    expect(cache.removeSharedByMeNodeUid).toHaveBeenCalledWith("nodeUid");
+                } else {
+                    expect(cache.removeSharedByMeNodeUid).not.toHaveBeenCalled();
+                }
+
+                expect(listener).not.toHaveBeenCalled();
+                expect(cache.setSharedWithMeNodeUids).not.toHaveBeenCalled();
+            });
+        });
+    });
+});
+
+describe("handleSharedWithMeNodes", () => {
+    let cache: SharingCache;
+    let sharingAccess: SharingAccess;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+
+        // @ts-expect-error No need to implement all methods for mocking
+        cache = {
+            getSharedWithMeNodeUids: jest.fn(),
+            setSharedWithMeNodeUids: jest.fn(),
+        };
+        // @ts-expect-error No need to implement all methods for mocking
+        sharingAccess = {
+            iterateSharedNodesWithMe: jest.fn(),
+        };
+    });
+
+    it("should only update cache", async () => {
+        const event: DriveEvent = {
+            type: DriveEventType.ShareWithMeUpdated,
+        };
+
+        await handleSharedWithMeNodes(event, cache, [], sharingAccess);
+
+        expect(cache.setSharedWithMeNodeUids).toHaveBeenCalledWith(undefined);
+        expect(cache.getSharedWithMeNodeUids).not.toHaveBeenCalled();
+        expect(sharingAccess.iterateSharedNodesWithMe).not.toHaveBeenCalled();
+    });
+
+    it("should update cache and notify listener", async () => {
+        cache.getSharedWithMeNodeUids = jest.fn().mockResolvedValue(["nodeUid1", "nodeUid4"]);
+        sharingAccess.iterateSharedNodesWithMe = jest.fn().mockImplementation(async function* () {
+            yield { uid: "nodeUid1", name: { ok: true, value: "name1" } };
+            yield { uid: "nodeUid2", name: { ok: true, value: "name2" } };
+            yield { uid: "nodeUid3", name: { ok: true, value: "name3" } };
+        });
+        const listener = jest.fn();
+        const event: DriveEvent = {
+            type: DriveEventType.ShareWithMeUpdated,
+        };
+
+        await handleSharedWithMeNodes(event, cache, [{ type: SharingType.sharedWithMe, callback: listener }], sharingAccess);
+
+        expect(cache.setSharedWithMeNodeUids).toHaveBeenCalledWith(undefined);
+        expect(cache.getSharedWithMeNodeUids).toHaveBeenCalled();
+        expect(sharingAccess.iterateSharedNodesWithMe).toHaveBeenCalled();
+        expect(listener).toHaveBeenCalledTimes(4);
+        expect(listener).toHaveBeenCalledWith(expect.objectContaining({ type: 'update', uid: 'nodeUid1' }));
+        expect(listener).toHaveBeenCalledWith(expect.objectContaining({ type: 'update', uid: 'nodeUid2' }));
+        expect(listener).toHaveBeenCalledWith(expect.objectContaining({ type: 'update', uid: 'nodeUid3' }));
+        expect(listener).toHaveBeenCalledWith({ type: 'remove', uid: 'nodeUid4' });
+    });
+});

package/src/internal/sharing/events.ts

@@ -0,0 +1,166 @@
+import { NodeEventCallback, Logger } from "../../interface";
+import { convertInternalNode } from "../../transformers";
+import { DriveEventsService, DriveEvent, DriveEventType } from "../events";
+import { SharingCache } from "./cache";
+import { SharingType, NodesService } from "./interface";
+import { SharingAccess } from "./sharingAccess";
+
+type Listeners = {
+    type: SharingType,
+    callback: NodeEventCallback,
+}[];
+
+/**
+ * Provides both event handling and subscription mechanism for user.
+ * 
+ * The service is responsible for handling events regarding sharing listing
+ * from the DriveEventsService, and for providing a subscription mechanism
+ * for the user to listen to updates of specific group of nodes, such as
+ * any update to list of shared with me nodes.
+ */
+export class SharingEvents {
+    private listeners: Listeners = [];
+
+    constructor(logger: Logger, events: DriveEventsService, cache: SharingCache, nodesService: NodesService, sharingAccess: SharingAccess) {
+        events.addListener(async (events, fullRefreshVolumeId) => {
+            // Technically we need to refresh only the shared by me nodes for
+            // own volume, and shared with me nodes only when the event comes
+            // as core refresh event is converted to it.
+            // We can optimise later, for now we refresh everything to make
+            // it simpler. The cache is smart enough to not do unnecessary
+            // requests to the API and refresh on web is rare without
+            // persistant cache for now.
+            if (fullRefreshVolumeId) {
+                await cache.setSharedByMeNodeUids(undefined);
+                await cache.setSharedWithMeNodeUids(undefined);
+                return
+            }
+
+            for (const event of events) {
+                await handleSharedByMeNodes(logger, event, cache, this.listeners, nodesService);
+                await handleSharedWithMeNodes(event, cache, this.listeners, sharingAccess);
+            }
+        });
+    }
+
+    subscribeToSharedNodesByMe(callback: NodeEventCallback) {
+        this.listeners.push({ type: SharingType.SharedByMe, callback });
+        return () => {
+            this.listeners = this.listeners.filter(listener => listener.callback !== callback);
+        }
+    }
+
+    subscribeToSharedNodesWithMe(callback: NodeEventCallback) {
+        this.listeners.push({ type: SharingType.sharedWithMe, callback });
+        return () => {
+            this.listeners = this.listeners.filter(listener => listener.callback !== callback);
+        }
+    }
+}
+
+/**
+ * Update cache and notify listeners accordingly for any updates
+ * to nodes that are shared by me.
+ *
+ * Any node create or update that is being shared, is automatically
+ * added to the cache and the listeners are notified about the
+ * update of the node.
+ *
+ * Any node delete or update that is not being shared, and the cache
+ * includes the node, is removed from the cache and the listeners are
+ * notified about the removal of the node.
+ *
+ * @throws Only if the client's callback throws.
+ */
+export async function handleSharedByMeNodes(logger: Logger, event: DriveEvent, cache: SharingCache, listeners: Listeners, nodesService: NodesService) {
+    if (event.type === DriveEventType.ShareWithMeUpdated || !event.isOwnVolume) {
+        return;
+    }
+
+    const subscribedListeners = listeners.filter(({ type }) => type === SharingType.SharedByMe);
+
+    if ([DriveEventType.NodeCreated, DriveEventType.NodeUpdated, DriveEventType.NodeUpdatedMetadata].includes(event.type) && event.isShared) {
+        try {
+            await cache.addSharedByMeNodeUid(event.nodeUid);
+        } catch (error: unknown) {
+            logger.error(`Skipping shared by me node cache update`, error);
+        }
+        if (subscribedListeners.length) {
+            let node;
+            try {
+                node = await nodesService.getNode(event.nodeUid);
+            } catch (error: unknown) {
+                logger.error(`Skipping shared by me node update event to listener`, error);
+                return;
+            }
+            subscribedListeners.forEach(({ callback }) => callback({ type: 'update', uid: node.uid, node: convertInternalNode(node) }));
+        }
+    }
+
+    if (
+        ((event.type === DriveEventType.NodeUpdated || event.type === DriveEventType.NodeUpdatedMetadata) && !event.isShared)
+        || event.type === DriveEventType.NodeDeleted
+    ) {
+        let nodeWasShared = false;
+        try {
+            const cachedNodeUids = await cache.getSharedByMeNodeUids();
+            nodeWasShared = cachedNodeUids.includes(event.nodeUid);
+        } catch {
+            // Cache can be empty.
+        }
+
+        if (nodeWasShared) {
+            try {
+                await cache.removeSharedByMeNodeUid(event.nodeUid);
+            } catch (error: unknown) {
+                logger.error(`Skipping shared by me node cache remove`, error);
+            }
+            subscribedListeners.forEach(({ callback }) => callback({ type: 'remove', uid: event.nodeUid }));
+        }
+    }
+}
+
+/**
+ * Update cache and notify listeners accordingly for any updates
+ * to nodes that are shared with me.
+ *
+ * There is only one event type that is relevant for shared with me
+ * nodes, which is the ShareWithMeUpdated event. The event is triggered
+ * when the list of shared with me nodes is updated.
+ * 
+ * The cache is cleared and re-populated fully when the client
+ * requests the list of shared with me, or is actively listening.
+ * 
+ * If the client listenes to shared with me updates, the client receives
+ * update to the full list of shared with me nodes, including remove
+ * updates for nodes that are no longer shared with me, but was before.
+ *
+ * @throws Only if the client's callback throws.
+ */
+export async function handleSharedWithMeNodes(event: DriveEvent, cache: SharingCache, listeners: Listeners, sharingAccess: SharingAccess) {
+    if (event.type !== DriveEventType.ShareWithMeUpdated) {
+        return;
+    }
+
+    let cachedNodeUids: string[] = [];
+    const subscribedListeners = listeners.filter(({ type }) => type === SharingType.sharedWithMe);
+    if (subscribedListeners.length) {
+        cachedNodeUids = await cache.getSharedWithMeNodeUids();
+    }
+
+    // Clearing the cache must be first, sharingAccess is no-op if cache is set.
+    await cache.setSharedWithMeNodeUids(undefined);
+
+    if (subscribedListeners.length) {
+        const nodeUids = [];
+        for await (const node of sharingAccess.iterateSharedNodesWithMe()) {
+            nodeUids.push(node.uid);
+            subscribedListeners.forEach(({ callback }) => callback({ type: 'update', uid: node.uid, node: convertInternalNode(node) }));
+        }
+        for (const nodeUid of cachedNodeUids) {
+            if (!nodeUids.includes(nodeUid)) {
+                subscribedListeners.forEach(({ callback }) => callback({ type: 'remove', uid: nodeUid }));
+            }
+        }
+    }
+}

package/src/internal/sharing/index.ts

@@ -0,0 +1,43 @@
+import { ProtonDriveAccount, ProtonDriveEntitiesCache, ProtonDriveTelemetry } from "../../interface";
+import { DriveCrypto } from '../../crypto';
+import { DriveAPIService } from "../apiService";
+import { DriveEventsService } from "../events";
+import { SharingAPIService } from "./apiService";
+import { SharingCache } from "./cache";
+import { SharingCryptoService } from "./cryptoService";
+import { SharingEvents } from "./events";
+import { SharingAccess } from "./sharingAccess";
+import { SharingManagement } from "./sharingManagement";
+import { SharesService, NodesService, NodesEvents } from "./interface";
+
+/**
+ * Provides facade for the whole sharing module.
+ * 
+ * The sharing module is responsible for handling invitations, bookmarks,
+ * standard shares, listing shared nodes, etc. It includes API communication,
+ * encryption, decryption, caching, and event handling.
+ */
+export function initSharingModule(
+    telemetry: ProtonDriveTelemetry,
+    apiService: DriveAPIService,
+    driveEntitiesCache: ProtonDriveEntitiesCache,
+    account: ProtonDriveAccount,
+    crypto: DriveCrypto,
+    driveEvents: DriveEventsService,
+    sharesService: SharesService,
+    nodesService: NodesService,
+    nodesEvents: NodesEvents,
+) {
+    const api = new SharingAPIService(telemetry.getLogger('sharing-api'), apiService);
+    const cache = new SharingCache(driveEntitiesCache);
+    const cryptoService = new SharingCryptoService(crypto, account);
+    const sharingAccess = new SharingAccess(api, cache, cryptoService, sharesService, nodesService);
+    const sharingEvents = new SharingEvents(telemetry.getLogger('sharing-events'), driveEvents, cache, nodesService, sharingAccess);
+    const sharingManagement = new SharingManagement(telemetry.getLogger('sharing'), api, cryptoService, account, sharesService, nodesService, nodesEvents);
+
+    return {
+        access: sharingAccess,
+        events: sharingEvents,
+        management: sharingManagement,
+    };
+}

package/src/internal/sharing/interface.ts

@@ -0,0 +1,177 @@
+import { NodeType, MemberRole, NonProtonInvitationState, MissingNode, ShareResult, PublicLink } from "../../interface";
+import { PrivateKey, SessionKey } from "../../crypto";
+import { EncryptedShare } from "../shares";
+import { DecryptedNode } from "../nodes";
+
+export enum SharingType {
+    SharedByMe = 'sharedByMe',
+    sharedWithMe = 'sharedWithMe',
+}
+
+/**
+ * Internal interface for creating new invitation.
+ */
+export interface EncryptedInvitationRequest {
+    addedByEmail: string;
+    inviteeEmail: string;
+    base64KeyPacket: string;
+    base64KeyPacketSignature: string;
+    role: MemberRole;
+}
+
+/**
+ * Internal interface of existing invitation on the API.
+ * 
+ * This interface is used only for managing the invitations. For listing
+ * invitations with node metadata, see `EncryptedInvitationWithNode`.
+ */
+export interface EncryptedInvitation extends EncryptedInvitationRequest {
+    uid: string;
+    invitationTime: Date;
+}
+
+/**
+ * Internal interface of existing invitation with the share and node metadata.
+ * 
+ * Invitation with node is used for listing shared nodes with me, so it includes
+ * what is being shared as well.
+ */
+export interface EncryptedInvitationWithNode extends EncryptedInvitation {
+    share: {
+        armoredKey: string;
+        armoredPassphrase: string;
+        creatorEmail: string;
+    };
+    node: {
+        type: NodeType;
+        mediaType?: string;
+        encryptedName: string;
+    }
+}
+
+/**
+ * Internal interface for creating new external invitation.
+ */
+export interface EncryptedExternalInvitationRequest {
+    inviterAddressId: string;
+    inviteeEmail: string;
+    role: MemberRole;
+    base64Signature: string;
+}
+
+/**
+ * Internal interface of existing external invitation on the API.
+ */
+export interface EncryptedExternalInvitation extends Omit<EncryptedExternalInvitationRequest, 'inviterAddressId'> {
+    uid: string;
+    invitationTime: Date;
+    addedByEmail: string;
+    state: NonProtonInvitationState;
+}
+
+/**
+ * Internal interface of existing member on the API.
+ */
+export interface EncryptedMember {
+    uid: string;
+    invitationTime: Date;
+    addedByEmail: string;
+    inviteeEmail: string;
+    role: MemberRole;
+    base64KeyPacket: string;
+    base64KeyPacketSignature: string;
+}
+
+/**
+ * Internal interface of existing member with the share and node metadata.
+ */
+export interface EncryptedBookmark {
+    tokenId: string;
+    creationTime: Date;
+    share: {
+        armoredKey: string;
+        armoredPassphrase: string;
+    };
+    url: {
+        encryptedUrlPassword?: string;
+        base64SharePasswordSalt: string;
+    };
+    node: {
+        type: NodeType;
+        mediaType?: string;
+        encryptedName: string;
+        armoredKey: string;
+        armoredNodePassphrase: string;
+        file: {
+            base64ContentKeyPacket?: string;
+        };
+    };
+}
+
+export interface EncryptedPublicLink {
+    uid: string,
+    creationTime: Date,
+    expirationTime?: Date,
+    role: MemberRole,
+    flags: number,
+    creatorEmail: string,
+    publicUrl: string,
+    armoredUrlPassword: string,
+    urlPasswordSalt: string,
+    base64SharePassphraseKeyPacket: string,
+    sharePassphraseSalt: string,
+}
+
+export interface EncryptedPublicLinkCrypto {
+    base64SharePasswordSalt: string,
+    base64SharePassphraseKeyPacket: string,
+    armoredPassword: string,
+}
+
+export interface ShareResultWithCreatorEmail extends ShareResult {
+    publicLink?: PublicLinkWithCreatorEmail;
+}
+
+export interface PublicLinkWithCreatorEmail extends PublicLink {
+    creatorEmail: string;
+}
+
+
+/**
+ * Interface describing the dependencies to the shares module.
+ */
+export interface SharesService {
+    getMyFilesIDs(): Promise<{ volumeId: string }>,
+    loadEncryptedShare(shareId: string): Promise<EncryptedShare>,
+    getContextShareMemberEmailKey(shareId: string): Promise<{
+        email: string,
+        addressId: string,
+        addressKey: PrivateKey,
+    }>,
+}
+
+/**
+ * Interface describing the dependencies to the nodes module.
+ */
+export interface NodesService {
+    getNode(nodeUid: string): Promise<DecryptedNode>,
+    getNodeKeys(nodeUid: string): Promise<{ key: PrivateKey }>,
+    getNodePrivateAndSessionKeys(nodeUid: string): Promise<{
+        key: PrivateKey,
+        passphraseSessionKey: SessionKey,
+        nameSessionKey: SessionKey,
+    }>,
+    getRootNodeEmailKey(nodeUid: string): Promise<{
+        email: string,
+        addressId: string,
+        addressKey: PrivateKey,
+    }>,
+    iterateNodes(nodeUids: string[], signal?: AbortSignal): AsyncGenerator<DecryptedNode | MissingNode>;
+}
+
+/**
+ * Interface describing the dependencies to the nodes module.
+ */
+export interface NodesEvents {
+    nodeUpdated(partialNode: { uid: string, shareId: string | undefined, isShared: boolean }): Promise<void>,
+}