@protontech/drive-sdk 0.0.10

package/src/internal/shares/index.ts

@@ -0,0 +1,35 @@
+import { ProtonDriveEntitiesCache, ProtonDriveCryptoCache, ProtonDriveAccount, ProtonDriveTelemetry } from "../../interface";
+import { DriveCrypto } from '../../crypto';
+import { DriveAPIService } from "../apiService";
+import { SharesAPIService } from "./apiService";
+import { SharesCryptoCache } from "./cryptoCache";
+import { SharesCache } from "./cache";
+import { SharesCryptoService } from "./cryptoService";
+import { SharesManager } from "./manager";
+
+export type { EncryptedShare } from "./interface";
+
+/**
+ * Provides facade for the whole shares module.
+ * 
+ * The shares module is responsible for handling shares metadata, including
+ * API communication, encryption, decryption, caching, and event handling.
+ * 
+ * This facade provides internal interface that other modules can use to
+ * interact with the shares.
+ */
+export function initSharesModule(
+    telemetry: ProtonDriveTelemetry,
+    apiService: DriveAPIService,
+    driveEntitiesCache: ProtonDriveEntitiesCache,
+    driveCryptoCache: ProtonDriveCryptoCache,
+    account: ProtonDriveAccount,
+    crypto: DriveCrypto,
+) {
+    const api = new SharesAPIService(apiService);
+    const cache = new SharesCache(telemetry.getLogger('shares-cache'), driveEntitiesCache);
+    const cryptoCache = new SharesCryptoCache(driveCryptoCache);
+    const cryptoService = new SharesCryptoService(telemetry, crypto, account);
+    const sharesManager = new SharesManager(telemetry.getLogger('shares'), api, cache, cryptoCache, cryptoService, account);
+    return sharesManager;
+}

package/src/internal/shares/interface.ts

@@ -0,0 +1,104 @@
+import { PrivateKey, SessionKey } from "../../crypto";
+import { Result, UnverifiedAuthorError } from "../../interface";
+
+/**
+ * Internal interface providing basic identification of volume and its root
+ * share and node.
+ * 
+ * No interface should inherit from this, this is only for composition to
+ * create basic volume or share interfaces.
+ * 
+ * Volumes do not have necessarily share or node, but we want to always
+ * know what is the root share or node, thus we want to keep this for both
+ * volumes or any type of share.
+ */
+export interface VolumeShareNodeIDs {
+    volumeId: string;
+    shareId: string;
+    rootNodeId: string;
+}
+
+export type Volume = {
+    /**
+     * Creator email and address ID come from the default share.
+     * 
+     * The idea is to keep this information synced, so whenever we check
+     * cached volume information, we have creator details at hand for any
+     * verification checks or creation needs.
+     */
+    creatorEmail: string;
+    addressId: string;
+} & VolumeShareNodeIDs;
+
+/**
+ * Internal share interface.
+ */
+type BaseShare = {
+    /**
+     * Address ID is set only when user is member of the share.
+     * Owner or invitee of share with higher access in the tree
+     * might not have this field set.
+     */
+    addressId?: string;
+    creationTime?: Date;
+    type: ShareType;
+} & VolumeShareNodeIDs;
+
+export enum ShareType {
+    Main = 'main',
+    Standard = 'standard',
+    Device = 'device',
+    Photo = 'photo',
+}
+
+interface BaseRootShare extends BaseShare {
+    /**
+     * Address ID is always available for root shares, in contrast
+     * to other standard shares that might not have it. See the comment
+     * for BaseShare.
+     */
+    addressId: string;
+}
+
+/**
+ * Interface used only internaly in the shares module.
+ * 
+ * Outside of the module, the decrypted share interface should be used.
+ */
+export interface EncryptedShare extends BaseShare {
+    creatorEmail: string;
+    encryptedCrypto: EncryptedShareCrypto;
+    membership?: ShareMembership;
+}
+
+interface ShareMembership {
+    memberUid: string;
+}
+
+/**
+ * Interface used only internaly in the shares module.
+ * 
+ * Outside of the module, the decrypted share interface should be used.
+ */
+export interface EncryptedRootShare extends BaseRootShare {
+    creatorEmail: string;
+    encryptedCrypto: EncryptedShareCrypto;
+}
+
+/**
+ * Interface holding decrypted share metadata.
+ */
+export interface DecryptedRootShare extends BaseRootShare {
+    author: Result<string, UnverifiedAuthorError>,
+}
+
+export interface EncryptedShareCrypto {
+    armoredKey: string;
+    armoredPassphrase: string;
+    armoredPassphraseSignature: string;
+}
+
+export interface DecryptedShareKey {
+    key: PrivateKey;
+    passphraseSessionKey: SessionKey;
+}

package/src/internal/shares/manager.test.ts

@@ -0,0 +1,210 @@
+import { ProtonDriveAccount } from "../../interface";
+import { getMockLogger } from "../../tests/logger";
+import { NotFoundAPIError } from "../apiService";
+import { SharesAPIService } from "./apiService";
+import { SharesCache } from "./cache";
+import { SharesCryptoCache } from "./cryptoCache";
+import { SharesCryptoService } from "./cryptoService";
+import { VolumeShareNodeIDs } from "./interface";
+import { SharesManager } from "./manager";
+
+describe("SharesManager", () => {
+    let apiService: SharesAPIService;
+    let cache: SharesCache;
+    let cryptoCache: SharesCryptoCache;
+    let cryptoService: SharesCryptoService;
+    let account: ProtonDriveAccount;
+
+    let manager: SharesManager;
+
+    beforeEach(() => {
+        // @ts-expect-error No need to implement all methods for mocking
+        apiService = {
+            getMyFiles: jest.fn(),
+            getRootShare: jest.fn(),
+            getShare: jest.fn(),
+            getVolume: jest.fn(),
+            createVolume: jest.fn(),
+        }
+        // @ts-expect-error No need to implement all methods for mocking
+        cache = {
+            setVolume: jest.fn(),
+            getVolume: jest.fn(),
+        }
+        // @ts-expect-error No need to implement all methods for mocking
+        cryptoCache = {
+            setShareKey: jest.fn(),
+            getShareKey: jest.fn(),
+        }
+        // @ts-expect-error No need to implement all methods for mocking
+        cryptoService = {
+            generateVolumeBootstrap: jest.fn(),
+            decryptRootShare: jest.fn(),
+        }
+        // @ts-expect-error No need to implement all methods for mocking
+        account = {
+            getOwnPrimaryAddress: jest.fn(),
+            getOwnAddress: jest.fn(),
+        }
+
+        manager = new SharesManager(getMockLogger(), apiService, cache, cryptoCache, cryptoService, account);
+    });
+
+    describe("getMyFilesIDs", () => {
+        const myFilesShare = {
+            shareId: "myFilesShareId",
+            volumeId: "myFilesVolumeId",
+            rootNodeId: "myFilesRootNodeId",
+        };
+
+        it("should load My files IDs once", async () => {
+            const encryptedShare = {
+                share: myFilesShare,
+                creatorEmail: "email",
+            };
+            const key = {
+                key: "privateKey",
+                sessionKey: "sessionKey",
+            };
+
+            apiService.getMyFiles = jest.fn().mockResolvedValue(encryptedShare);
+            cryptoService.decryptRootShare = jest.fn().mockResolvedValue({ share: myFilesShare, key });
+
+            // Calling twice to check if it loads only once.
+            await manager.getMyFilesIDs();
+            const result = await manager.getMyFilesIDs();
+
+            expect(result).toStrictEqual(myFilesShare);
+            expect(apiService.getMyFiles).toHaveBeenCalledTimes(1);
+            expect(cryptoService.decryptRootShare).toHaveBeenCalledTimes(1);
+            expect(cryptoCache.setShareKey).toHaveBeenCalledWith(myFilesShare.shareId, key);
+            expect(cache.setVolume).toHaveBeenCalledWith({
+                ...myFilesShare,
+                creatorEmail: encryptedShare.creatorEmail,
+            });
+            expect(apiService.createVolume).not.toHaveBeenCalled();
+        });
+
+        it("should create volume when My files section doesn't exist", async () => {
+            apiService.getMyFiles = jest.fn().mockRejectedValue(new NotFoundAPIError("no active volume", 0));
+            account.getOwnPrimaryAddress = jest.fn().mockResolvedValue({ primaryKeyIndex: 0, keys: [{ key: "addressKey" }] });
+            cryptoService.generateVolumeBootstrap = jest.fn().mockResolvedValue({
+                shareKey: {
+                    encrypted: "encrypted share key",
+                    decrypted: "decrypted share key",
+                },
+                rootNode: {
+                    key: {
+                        encrypted: "encrypted root key",
+                    },
+                }
+            });
+            apiService.createVolume = jest.fn().mockResolvedValue(myFilesShare);
+
+            const result = await manager.getMyFilesIDs();
+
+            expect(result).toStrictEqual(myFilesShare);
+            expect(cryptoService.decryptRootShare).not.toHaveBeenCalled();
+            expect(cryptoCache.setShareKey).toHaveBeenCalledWith("myFilesShareId", "decrypted share key");
+        });
+
+        it("should throw on unknown error", async () => {
+            apiService.getMyFiles = jest.fn().mockRejectedValue(new Error("Some error"));
+
+            await expect(manager.getMyFilesIDs()).rejects.toThrow("Some error");
+            expect(cryptoService.decryptRootShare).not.toHaveBeenCalled();
+            expect(apiService.createVolume).not.toHaveBeenCalled();
+        });
+    });
+
+    describe("getSharePrivateKey", () => {
+        it("should return cached private key", async () => {
+            cryptoCache.getShareKey = jest.fn().mockResolvedValue({ key: "cachedPrivateKey" });
+
+            const result = await manager.getSharePrivateKey("shareId");
+
+            expect(result).toBe("cachedPrivateKey");
+        });
+
+        it("should load private key if not in cache", async () => {
+            cryptoCache.getShareKey = jest.fn().mockRejectedValue(new Error('not found'));
+            apiService.getRootShare = jest.fn().mockResolvedValue({ shareId: "shareId" });
+            cryptoService.decryptRootShare = jest.fn().mockResolvedValue({ key: { key: "privateKey" } });
+
+            const result = await manager.getSharePrivateKey("shareId");
+
+            expect(result).toBe("privateKey");
+            expect(cryptoCache.setShareKey).toHaveBeenCalledWith("shareId", { key: "privateKey" });
+        });
+    });
+
+    describe("getMyFilesShareMemberEmailKey", () => {
+        it("should return cached volume email key", async () => {
+            jest.spyOn(manager, 'getMyFilesIDs').mockResolvedValue({ volumeId: "volumeId" } as VolumeShareNodeIDs);
+            cache.getVolume = jest.fn().mockResolvedValue({ addressId: "addressId" });
+            account.getOwnAddress = jest.fn().mockResolvedValue({ email: "email", primaryKeyIndex: 0, keys: [{ key: "addressKey" }] });
+
+            const result = await manager.getMyFilesShareMemberEmailKey();
+
+            expect(result).toEqual({
+                addressId: "addressId",
+                email: "email",
+                addressKey: "addressKey",
+            });
+        });
+
+        it("should load volume email key if not in cache", async () => {
+            jest.spyOn(manager, 'getMyFilesIDs').mockResolvedValue({ volumeId: "volumeId" } as VolumeShareNodeIDs);
+            const share = {
+                volumeId: "volumeId",
+                shareId: "shareId",
+                rootNodeId: "rootNodeId",
+                creatorEmail: "email",
+                addressId: "addressId",
+            }
+            cache.getVolume = jest.fn().mockRejectedValue(new Error('not found'));
+            apiService.getVolume = jest.fn().mockResolvedValue({ shareId: "shareId" });
+            apiService.getRootShare = jest.fn().mockResolvedValue(share);
+            account.getOwnAddress = jest.fn().mockResolvedValue({ email: "email", primaryKeyIndex: 0, keys: [{ key: "addressKey" }] });
+
+            const result = await manager.getMyFilesShareMemberEmailKey();
+
+            expect(result).toEqual({
+                addressId: "addressId",
+                email: "email",
+                addressKey: "addressKey",
+            });
+            expect(cache.setVolume).toHaveBeenCalledWith(share);
+        });
+    });
+
+    describe("getContextShareMemberEmailKey", () => {
+        it("should load share email key only once", async () => {
+            const share = {
+                volumeId: "volumeId",
+                shareId: "shareId",
+                rootNodeId: "rootNodeId",
+                creatorEmail: "creatorEmail",
+                addressId: "addressId",
+            }
+            apiService.getRootShare = jest.fn().mockResolvedValue(share);
+            account.getOwnAddress = jest.fn().mockResolvedValue({ email: "email", primaryKeyIndex: 0, keys: [{ key: "addressKey" }] });
+
+            const result = await manager.getContextShareMemberEmailKey("shareId");
+
+            expect(result).toEqual({
+                addressId: "addressId",
+                email: "email",
+                addressKey: "addressKey",
+            });
+            expect(apiService.getRootShare).toHaveBeenCalledTimes(1);
+            expect(account.getOwnAddress).toHaveBeenCalledTimes(1);
+
+            const result2 = await manager.getContextShareMemberEmailKey("shareId");
+
+            expect(result2).toEqual(result);
+            expect(apiService.getRootShare).toHaveBeenCalledTimes(1);
+            expect(account.getOwnAddress).toHaveBeenCalledTimes(2);
+        });
+    });
+});

package/src/internal/shares/manager.ts

@@ -0,0 +1,213 @@
+import { Logger, MetricContext, ProtonDriveAccount } from "../../interface";
+import { PrivateKey } from "../../crypto";
+import { NotFoundAPIError } from "../apiService";
+import { SharesAPIService } from "./apiService";
+import { SharesCache } from "./cache";
+import { SharesCryptoCache } from "./cryptoCache";
+import { SharesCryptoService } from "./cryptoService";
+import { VolumeShareNodeIDs, EncryptedShare, EncryptedRootShare } from "./interface";
+
+/**
+ * Provides high-level actions for managing shares.
+ *
+ * The manager is responsible for handling shares 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 SharesManager {
+    // Cache for My files IDs.
+    // Those IDs are required very often, so it is better to keep them in memory.
+    // The IDs are not cached in the cache module, as we want to always fetch
+    // them from the API, and not from the this.cache.
+    private myFilesIds?: VolumeShareNodeIDs;
+
+    private rootShares: Map<string, EncryptedRootShare> = new Map();
+
+    constructor(
+        private logger: Logger,
+        private apiService: SharesAPIService,
+        private cache: SharesCache,
+        private cryptoCache: SharesCryptoCache,
+        private cryptoService: SharesCryptoService,
+        private account: ProtonDriveAccount,
+    ) {
+        this.logger = logger;
+        this.apiService = apiService;
+        this.cache = cache;
+        this.cryptoCache = cryptoCache;
+        this.cryptoService = cryptoService;
+        this.account = account;
+    }
+
+    /**
+     * It returns the IDs of the My files section.
+     * 
+     * If the default volume or My files section doesn't exist, it creates it.
+     */
+    async getMyFilesIDs(): Promise<VolumeShareNodeIDs> {
+        if (this.myFilesIds) {
+            return this.myFilesIds;
+        }
+
+        try {
+            const encryptedShare = await this.apiService.getMyFiles();
+
+            // Once any place needs IDs for My files, it will most likely
+            // need also the keys for decrypting the tree. It is better to
+            // decrypt the share here right away.
+            const { share: myFilesShare, key } = await this.cryptoService.decryptRootShare(encryptedShare);
+            await this.cryptoCache.setShareKey(myFilesShare.shareId, key);
+            await this.cache.setVolume({
+                volumeId: myFilesShare.volumeId,
+                shareId: myFilesShare.shareId,
+                rootNodeId: myFilesShare.rootNodeId,
+                creatorEmail: encryptedShare.creatorEmail,
+                addressId: encryptedShare.addressId,
+            });
+
+            this.myFilesIds = {
+                volumeId: myFilesShare.volumeId,
+                shareId: myFilesShare.shareId,
+                rootNodeId: myFilesShare.rootNodeId,
+            };
+            return this.myFilesIds;
+        } catch (error: unknown) {
+            if (error instanceof NotFoundAPIError) {
+                this.logger.warn('Active volume not found, creating a new one');
+                return this.createVolume();
+            }
+            this.logger.error('Failed to get active volume', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Creates new default volume for the user.
+     * 
+     * It generates the volume bootstrap, creates the volume on the server,
+     * and caches the volume metadata.
+     * 
+     * User can have only one default volume.
+     * 
+     * @throws If the volume cannot be created (e.g., one already exists).
+     */
+    private async createVolume(): Promise<VolumeShareNodeIDs> {
+        const address = await this.account.getOwnPrimaryAddress();
+        const primaryKey = address.keys[address.primaryKeyIndex];
+        const bootstrap = await this.cryptoService.generateVolumeBootstrap(primaryKey.key);
+        const myFilesIds = await this.apiService.createVolume(
+            {
+                addressId: address.addressId,
+                addressKeyId: primaryKey.id,
+                ...bootstrap.shareKey.encrypted,
+            },
+            {
+                ...bootstrap.rootNode.key.encrypted,
+                encryptedName: bootstrap.rootNode.encryptedName,
+                armoredHashKey: bootstrap.rootNode.armoredHashKey,
+            },
+        );
+        await this.cryptoCache.setShareKey(myFilesIds.shareId, bootstrap.shareKey.decrypted);
+        return myFilesIds;
+    }
+
+    /**
+     * It is a high-level action that retrieves the private key for a share.
+     * If prefers to use the cache, but if the key is not there, it fetches
+     * the share from the API, decrypts it, and caches it.
+     * 
+     * @param shareId - The ID of the share.
+     * @returns The private key for the share.
+     * @throws If the share is not found or cannot be decrypted, or cached.
+     */
+    async getSharePrivateKey(shareId: string): Promise<PrivateKey> {
+        try {
+            const { key } = await this.cryptoCache.getShareKey(shareId);
+            return key;
+        } catch { }
+
+        const encryptedShare = await this.apiService.getRootShare(shareId);
+        const { key } = await this.cryptoService.decryptRootShare(encryptedShare);
+        await this.cryptoCache.setShareKey(shareId, key);
+        return key.key;
+    }
+
+    async getMyFilesShareMemberEmailKey(): Promise<{
+        email: string,
+        addressId: string,
+        addressKey: PrivateKey,
+        addressKeyId: string,
+    }> {
+        const { volumeId } = await this.getMyFilesIDs();
+
+        try {
+            const { addressId } = await this.cache.getVolume(volumeId);
+            const address = await this.account.getOwnAddress(addressId);
+            return {
+                email: address.email,
+                addressId,
+                addressKey: address.keys[address.primaryKeyIndex].key,
+                addressKeyId: address.keys[address.primaryKeyIndex].id,
+            };
+        } catch { }
+
+        const { shareId } = await this.apiService.getVolume(volumeId);
+        const share = await this.apiService.getRootShare(shareId);
+
+        await this.cache.setVolume({
+            volumeId: share.volumeId,
+            shareId: share.shareId,
+            rootNodeId: share.rootNodeId,
+            creatorEmail: share.creatorEmail,
+            addressId: share.addressId,
+        });
+
+        const address = await this.account.getOwnAddress(share.addressId);
+        return {
+            email: address.email,
+            addressId: share.addressId,
+            addressKey: address.keys[address.primaryKeyIndex].key,
+            addressKeyId: address.keys[address.primaryKeyIndex].id,
+        };
+    }
+
+    async getContextShareMemberEmailKey(shareId: string): Promise<{
+        email: string,
+        addressId: string,
+        addressKey: PrivateKey,
+        addressKeyId: string,
+    }> {
+        let encryptedShare = this.rootShares.get(shareId);
+        if (!encryptedShare) {
+            encryptedShare = await this.apiService.getRootShare(shareId);
+            this.rootShares.set(shareId, encryptedShare);
+        }
+
+        const address = await this.account.getOwnAddress(encryptedShare.addressId);
+
+        return {
+            email: address.email,
+            addressId: encryptedShare.addressId,
+            addressKey: address.keys[address.primaryKeyIndex].key,
+            addressKeyId: address.keys[address.primaryKeyIndex].id,
+        };
+    }
+
+    async getVolumeMetricContext(volumeId: string): Promise<MetricContext> {
+        const { volumeId: myVolumeId } = await this.getMyFilesIDs();
+
+        // SDK doesn't support public sharing yet, also public sharing
+        // doesn't use a volume but shareURL, thus we can simplify and
+        // ignore this case for now.
+        if (volumeId === myVolumeId) {
+            return MetricContext.OwnVolume;
+        }
+        return MetricContext.Shared;
+    }
+
+    async loadEncryptedShare(shareId: string): Promise<EncryptedShare> {
+        return this.apiService.getShare(shareId);
+    }
+}