@protontech/drive-sdk 0.3.0 → 0.3.2

package/src/internal/sharingPublic/manager.ts

@@ -0,0 +1,86 @@
+import { PrivateKey } from '../../crypto';
+import { Logger } from '../../interface';
+import { parseNode } from '../nodes/nodesAccess';
+import { SharingPublicAPIService } from './apiService';
+import { SharingPublicCryptoCache } from './cryptoCache';
+import { SharingPublicCryptoService } from './cryptoService';
+import { EncryptedShareCrypto, EncryptedNode, DecryptedNode, DecryptedNodeKeys } from './interface';
+
+// TODO: comment
+export class SharingPublicManager {
+    constructor(
+        private logger: Logger,
+        private api: SharingPublicAPIService,
+        private cryptoCache: SharingPublicCryptoCache,
+        private cryptoService: SharingPublicCryptoService,
+        private token: string,
+    ) {
+        this.logger = logger;
+        this.api = api;
+        this.cryptoCache = cryptoCache;
+        this.cryptoService = cryptoService;
+        this.token = token;
+    }
+
+    async getRootNode(): Promise<DecryptedNode> {
+        const { encryptedNode, encryptedShare } = await this.api.getPublicLinkRoot(this.token);
+        await this.decryptShare(encryptedShare);
+        return this.decryptNode(encryptedNode);
+    }
+
+    async *iterateFolderChildren(parentUid: string, signal?: AbortSignal): AsyncGenerator<DecryptedNode> {
+        // TODO: optimise this - decrypt in parallel
+        for await (const node of this.api.iterateFolderChildren(parentUid, signal)) {
+            const decryptedNode = await this.decryptNode(node);
+            yield decryptedNode;
+        }
+    }
+
+    private async decryptShare(encryptedShare: EncryptedShareCrypto): Promise<void> {
+        const shareKey = await this.cryptoService.decryptPublicLinkShareKey(encryptedShare);
+        await this.cryptoCache.setShareKey(shareKey);
+    }
+
+    private async decryptNode(encryptedNode: EncryptedNode): Promise<DecryptedNode> {
+        const parentKey = await this.getParentKey(encryptedNode);
+
+        const { node: unparsedNode, keys } = await this.cryptoService.decryptNode(encryptedNode, parentKey);
+        const node = await parseNode(this.logger, unparsedNode);
+
+        // TODO: cache of metadata?
+        if (keys) {
+            try {
+                await this.cryptoCache.setNodeKeys(node.uid, keys);
+            } catch (error: unknown) {
+                this.logger.error(`Failed to cache node keys ${node.uid}`, error);
+            }
+        }
+
+        return node;
+    }
+
+    private async getParentKey(node: Pick<DecryptedNode, 'parentUid'>): Promise<PrivateKey> {
+        if (node.parentUid) {
+            // TODO: try-catch
+            const keys = await this.getNodeKeys(node.parentUid);
+            return keys.key;
+        }
+
+        try {
+            return await this.cryptoCache.getShareKey();
+        } catch {
+            await this.getRootNode();
+            return this.cryptoCache.getShareKey();
+        }
+    }
+
+    async getNodeKeys(nodeUid: string): Promise<DecryptedNodeKeys> {
+        try {
+            const keys = await this.cryptoCache.getNodeKeys(nodeUid);
+            return keys;
+        } catch {
+            // TODO: handle this
+            throw new Error('Node key not found in cache');
+        }
+    }
+}

package/src/internal/sharingPublic/session/apiService.ts

@@ -0,0 +1,74 @@
+import { DriveAPIService, drivePaths } from '../../apiService';
+import { PublicLinkInfo, PublicLinkSrpAuth } from './interface';
+
+type GetPublicLinkInfoResponse =
+    drivePaths['/drive/urls/{token}/info']['get']['responses']['200']['content']['application/json'];
+
+type PostPublicLinkAuthRequest = Extract<
+    drivePaths['/drive/urls/{token}/auth']['post']['requestBody'],
+    { content: object }
+>['content']['application/json'];
+type PostPublicLinkAuthResponse =
+        drivePaths['/drive/urls/{token}/auth']['post']['responses']['200']['content']['application/json'];
+
+/**
+ * Provides API communication for managing public link session (not data).
+ *
+ * The service is responsible for transforming local objects to API payloads
+ * and vice versa. It should not contain any business logic.
+ */
+export class SharingPublicSessionAPIService {
+    constructor(private apiService: DriveAPIService) {
+        this.apiService = apiService;
+    }
+
+    /**
+     * Start a SRP handshake for public link session.
+     */
+    async initPublicLinkSession(token: string): Promise<PublicLinkInfo> {
+        const response = await this.apiService.get<GetPublicLinkInfoResponse>(`drive/urls/${token}/info`);
+        return {
+            srp: {
+                version: response.Version,
+                modulus: response.Modulus,
+                serverEphemeral: response.ServerEphemeral,
+                salt: response.UrlPasswordSalt,
+                srpSession: response.SRPSession,
+            },
+            isCustomPasswordProtected: (response.Flags & 1) === 1,
+            isLegacy: response.Flags === 0 || response.Flags === 1,
+            vendorType: response.VendorType,
+        };
+    }
+
+    /**
+     * Authenticate a public link session.
+     *
+     * It returns the server proof that must be validated, and the session uid
+     * with an optional access token. The access token is only returned if
+     * the session is newly created.
+     */
+    async authPublicLinkSession(
+        token: string,
+        srp: PublicLinkSrpAuth,
+    ): Promise<{
+        serverProof: string;
+        sessionUid: string;
+        sessionAccessToken?: string;
+    }> {
+        const response = await this.apiService.post<PostPublicLinkAuthRequest, PostPublicLinkAuthResponse>(
+            `drive/urls/${token}/auth`,
+            {
+                ClientProof: srp.clientProof,
+                ClientEphemeral: srp.clientEphemeral,
+                SRPSession: srp.srpSession,
+            },
+        );
+
+        return {
+            serverProof: response.ServerProof,
+            sessionUid: response.UID,
+            sessionAccessToken: response.AccessToken,
+        };
+    }
+}

package/src/internal/sharingPublic/session/httpClient.ts

@@ -0,0 +1,48 @@
+import {
+    ProtonDriveHTTPClient,
+    ProtonDriveHTTPClientBlobRequest,
+    ProtonDriveHTTPClientJsonRequest,
+} from '../../../interface';
+import { HTTPErrorCode } from '../../apiService';
+import { SharingPublicLinkSession } from './session';
+
+/**
+ * HTTP client to get access to public link of given session.
+ *
+ * It is responsible for adding the session headers to the request if the session
+ * is authenticated, and re-authenticating the session if the session is expired.
+ */
+export class SharingPublicSessionHttpClient implements ProtonDriveHTTPClient {
+    constructor(
+        private httpClient: ProtonDriveHTTPClient,
+        private session: SharingPublicLinkSession,
+    ) {
+        this.httpClient = httpClient;
+        this.session = session;
+    }
+
+    async fetchJson(options: ProtonDriveHTTPClientJsonRequest) {
+        const response = await this.httpClient.fetchJson(this.getOptionsWithSessionHeaders(options));
+
+        if (response.status === HTTPErrorCode.UNAUTHORIZED) {
+            await this.session.reauth();
+            return this.httpClient.fetchJson(this.getOptionsWithSessionHeaders(options));
+        }
+
+        return response;
+    }
+
+    async fetchBlob(options: ProtonDriveHTTPClientBlobRequest) {
+        return this.httpClient.fetchBlob(this.getOptionsWithSessionHeaders(options));
+    }
+
+    private getOptionsWithSessionHeaders(options: ProtonDriveHTTPClientJsonRequest) {
+        // Set headers if the session is newly created.
+        // This is needed only if the user is not logged in.
+        if (this.session.session.accessToken) {
+            options.headers.set('x-pm-uid', this.session.session.uid);
+            options.headers.set('Authorization', `Bearer ${this.session.session.accessToken}`);
+        }
+        return options;
+    }
+}

package/src/internal/sharingPublic/session/index.ts

@@ -0,0 +1 @@
+export { SharingPublicSessionManager } from './manager';

package/src/internal/sharingPublic/session/interface.ts

@@ -0,0 +1,20 @@
+export type PublicLinkInfo = {
+    srp: PublicLinkSrpInfo;
+    isCustomPasswordProtected: boolean;
+    isLegacy: boolean;
+    vendorType: number;
+};
+
+export type PublicLinkSrpInfo = {
+    version: number;
+    modulus: string;
+    serverEphemeral: string;
+    salt: string;
+    srpSession: string;
+};
+
+export type PublicLinkSrpAuth = {
+    clientProof: string;
+    clientEphemeral: string;
+    srpSession: string;
+};

package/src/internal/sharingPublic/session/manager.ts

@@ -0,0 +1,97 @@
+import { ProtonDriveHTTPClient } from '../../../interface';
+import { SRPModule } from '../../../crypto';
+import { DriveAPIService } from '../../apiService';
+import { SharingPublicSessionAPIService } from './apiService';
+import { SharingPublicSessionHttpClient } from './httpClient';
+import { PublicLinkInfo } from './interface';
+import { SharingPublicLinkSession } from './session';
+import { getTokenAndPasswordFromUrl } from './url';
+
+/**
+ * Manages sessions for public links.
+ *
+ * It can be used to get access to multiple public links.
+ */
+export class SharingPublicSessionManager {
+    private api: SharingPublicSessionAPIService;
+
+    private infosPerToken: Map<string, PublicLinkInfo> = new Map();
+
+    constructor(
+        private httpClient: ProtonDriveHTTPClient,
+        apiService: DriveAPIService,
+        private srpModule: SRPModule,
+    ) {
+        this.httpClient = httpClient;
+        this.srpModule = srpModule;
+
+        this.api = new SharingPublicSessionAPIService(apiService);
+    }
+
+    /**
+     * Get the info for a public link.
+     *
+     * It returns the info for the public link, including if it is custom
+     * password protected, if it is legacy (not supported anymore), and
+     * the vendor type (whether it is Proton Docs, for example, and should
+     * be redirected to the public Docs app).
+     *
+     * @param url - The URL of the public link.
+     */
+    async getInfo(url: string): Promise<{
+        isCustomPasswordProtected: boolean;
+        isLegacy: boolean;
+        vendorType: number;
+    }> {
+        const { token } = getTokenAndPasswordFromUrl(url);
+
+        const info = await this.api.initPublicLinkSession(token);
+        this.infosPerToken.set(token, info);
+
+        return {
+            isCustomPasswordProtected: info.isCustomPasswordProtected,
+            isLegacy: info.isLegacy,
+            vendorType: info.vendorType,
+        };
+    }
+
+    /**
+     * Authenticate a public link session.
+     *
+     * It returns HTTP client that must be used for the endpoints to access the
+     * public link data.
+     *
+     * It returnes parsed token and full password (password from the URL +
+     * custom password) that can be used for decrypting the share key.
+     *
+     * @param url - The URL of the public link.
+     * @param customPassword - The custom password for the public link, if it is
+     * custom password protected.
+     */
+    async auth(
+        url: string,
+        customPassword?: string,
+    ): Promise<{
+        token: string;
+        password: string;
+        httpClient: SharingPublicSessionHttpClient;
+    }> {
+        const { token, password: urlPassword } = getTokenAndPasswordFromUrl(url);
+
+        let info = this.infosPerToken.get(token);
+        if (!info) {
+            info = await this.api.initPublicLinkSession(token);
+        }
+
+        const password = `${urlPassword}${customPassword || ''}`;
+
+        const session = new SharingPublicLinkSession(this.api, this.srpModule, token, password);
+        await session.auth(info.srp);
+
+        return {
+            token,
+            password,
+            httpClient: new SharingPublicSessionHttpClient(this.httpClient, session),
+        };
+    }
+}

package/src/internal/sharingPublic/session/session.ts

@@ -0,0 +1,78 @@
+import { SRPModule } from "../../../crypto";
+import { SharingPublicSessionAPIService } from "./apiService";
+import { PublicLinkInfo, PublicLinkSrpInfo } from "./interface";
+
+/**
+ * Session for a public link.
+ *
+ * It is responsible for initializing and authenticating the public link session
+ * with the SRP handshake. It also can re-authenticate the session if it is expired.
+ */
+export class SharingPublicLinkSession {
+    private sessionUid?: string;
+    private sessionAccessToken?: string;
+
+    constructor(
+        private apiService: SharingPublicSessionAPIService,
+        private srpModule: SRPModule,
+        private token: string,
+        private password: string,
+    ) {
+        this.apiService = apiService;
+        this.srpModule = srpModule;
+        this.token = token;
+        this.password = password;
+    }
+
+    async reauth(): Promise<void> {
+        const info = await this.init();
+        await this.auth(info.srp);
+    }
+
+    async init(): Promise<PublicLinkInfo> {
+        return this.apiService.initPublicLinkSession(this.token);
+    }
+
+    async auth(srp: PublicLinkSrpInfo): Promise<void> {
+        const { expectedServerProof, clientProof, clientEphemeral } = await this.srpModule.getSrp(
+            srp.version,
+            srp.modulus,
+            srp.serverEphemeral,
+            srp.salt,
+            this.password,
+        );
+
+        const auth = await this.apiService.authPublicLinkSession(this.token, {
+            clientProof,
+            clientEphemeral,
+            srpSession: srp.srpSession,
+        });
+
+        if (auth.serverProof !== expectedServerProof) {
+            throw new Error('Invalid server proof');
+        }
+
+        this.sessionUid = auth.sessionUid;
+        this.sessionAccessToken = auth.sessionAccessToken;
+    }
+
+    /**
+     * Get the session uid and access token.
+     *
+     * The access token is only returned if the session is newly created.
+     * If the access token is not available, it means the existing session
+     * can be used to access the public link.
+     *
+     * @throws If the session is not initialized.
+     */
+    get session() {
+        if (!this.sessionUid) {
+            throw new Error('Session not initialized');
+        }
+
+        return {
+            uid: this.sessionUid,
+            accessToken: this.sessionAccessToken,
+        };
+    }
+}

package/src/internal/sharingPublic/session/url.test.ts

@@ -0,0 +1,72 @@
+import { ValidationError } from '../../../errors';
+import { getTokenAndPasswordFromUrl } from './url';
+
+describe('getTokenAndPasswordFromUrl', () => {
+    describe('valid URLs', () => {
+        it('should extract token and password from a valid URL', () => {
+            const url = 'https://drive.proton.me/urls/abc123#def456';
+            const result = getTokenAndPasswordFromUrl(url);
+
+            expect(result).toEqual({
+                token: 'abc123',
+                password: 'def456'
+            });
+        });
+
+        it('should handle URLs with different domains', () => {
+            const url = 'https://example.com/urls/mytoken#mypassword';
+            const result = getTokenAndPasswordFromUrl(url);
+
+            expect(result).toEqual({
+                token: 'mytoken',
+                password: 'mypassword'
+            });
+        });
+
+        it('should handle URLs with query parameters', () => {
+            const url = 'https://drive.proton.me/urls/token123?param=value#password456';
+            const result = getTokenAndPasswordFromUrl(url);
+
+            expect(result).toEqual({
+                token: 'token123',
+                password: 'password456'
+            });
+        });
+    });
+
+    describe('should throw ValidationError', () => {
+        it('when token is missing (no path)', () => {
+            const url = 'https://drive.proton.me/#password123';
+
+            expect(() => getTokenAndPasswordFromUrl(url)).toThrow(ValidationError);
+        });
+
+        it('when token is missing (empty path segment)', () => {
+            const url = 'https://drive.proton.me/urls/#password123';
+
+            expect(() => getTokenAndPasswordFromUrl(url)).toThrow(ValidationError);
+        });
+
+        it('when password is missing (no hash)', () => {
+            const url = 'https://drive.proton.me/urls/token123';
+
+            expect(() => getTokenAndPasswordFromUrl(url)).toThrow(ValidationError);
+            expect(() => getTokenAndPasswordFromUrl(url)).toThrow('Invalid URL');
+        });
+
+        it('when password is empty (empty hash)', () => {
+            const url = 'https://drive.proton.me/urls/token123#';
+
+            expect(() => getTokenAndPasswordFromUrl(url)).toThrow(ValidationError);
+            expect(() => getTokenAndPasswordFromUrl(url)).toThrow('Invalid URL');
+        });
+
+        it('for empty string', () => {
+            expect(() => getTokenAndPasswordFromUrl('')).toThrow();
+        });
+
+        it('for invalid URL format', () => {
+            expect(() => getTokenAndPasswordFromUrl('not-a-url')).toThrow();
+        });
+    });
+});

package/src/internal/sharingPublic/session/url.ts

@@ -0,0 +1,23 @@
+import { c } from 'ttag';
+
+import { ValidationError } from '../../../errors';
+
+/**
+ * Parse the token and password from the URL.
+ *
+ * The URL format is: https://drive.proton.me/urls/token#password
+ *
+ * @param url - The URL of the public link.
+ * @returns The token and password.
+ */
+export function getTokenAndPasswordFromUrl(url: string): { token: string; password: string } {
+    const urlObj = new URL(url);
+    const token = urlObj.pathname.split('/').pop();
+    const password = urlObj.hash.slice(1);
+
+    if (!token || !password) {
+        throw new ValidationError(c('Error').t`Invalid URL`);
+    }
+
+    return { token, password };
+}

package/src/internal/upload/streamUploader.test.ts

@@ -189,8 +189,10 @@ describe('StreamUploader', () => {
 
         const verifyOnProgress = async (uploadedBytes: number[]) => {
             expect(onProgress).toHaveBeenCalledTimes(uploadedBytes.length);
+            let fileProgress = 0;
             for (let i = 0; i < uploadedBytes.length; i++) {
-                expect(onProgress).toHaveBeenNthCalledWith(i + 1, uploadedBytes[i]);
+                fileProgress += uploadedBytes[i];
+                expect(onProgress).toHaveBeenNthCalledWith(i + 1, fileProgress);
             }
         };
 

package/src/internal/upload/streamUploader.ts

@@ -122,7 +122,7 @@ export class StreamUploader {
             this.logger.info(`Starting upload`);
             await this.encryptAndUploadBlocks(stream, thumbnails, (uploadedBytes) => {
                 fileProgress += uploadedBytes;
-                onProgress?.(uploadedBytes);
+                onProgress?.(fileProgress);
             });
 
             this.logger.debug(`All blocks uploaded, committing`);

package/src/protonDriveClient.ts

@@ -1,3 +1,5 @@
+import { getConfig } from './config';
+import { DriveCrypto, SessionKey } from './crypto';
 import {
     Logger,
     ProtonDriveClientContructorParameters,
@@ -26,16 +28,6 @@ import {
     ThumbnailResult,
     SDKEvent,
 } from './interface';
-import { DriveCrypto, SessionKey } from './crypto';
-import { DriveAPIService } from './internal/apiService';
-import { initSharesModule } from './internal/shares';
-import { initNodesModule } from './internal/nodes';
-import { initSharingModule } from './internal/sharing';
-import { initDownloadModule } from './internal/download';
-import { initUploadModule } from './internal/upload';
-import { DriveEventsService, DriveListener } from './internal/events';
-import { SDKEvents } from './internal/sdkEvents';
-import { getConfig } from './config';
 import {
     getUid,
     getUids,
@@ -45,9 +37,18 @@ import {
     convertInternalNode,
 } from './transformers';
 import { Telemetry } from './telemetry';
+import { DriveAPIService } from './internal/apiService';
 import { initDevicesModule } from './internal/devices';
+import { initDownloadModule } from './internal/download';
+import { DriveEventsService, DriveListener, EventSubscription } from './internal/events';
+import { initNodesModule } from './internal/nodes';
+import { SDKEvents } from './internal/sdkEvents';
+import { initSharesModule } from './internal/shares';
+import { initSharingModule } from './internal/sharing';
+import { SharingPublicSessionManager } from './internal/sharingPublic';
+import { initUploadModule } from './internal/upload';
 import { makeNodeUid } from './internal/uids';
-import { EventSubscription } from './internal/events/interface';
+import { ProtonDrivePublicLinkClient } from './protonDrivePublicLinkClient';
 
 /**
  * ProtonDriveClient is the main interface for the ProtonDrive SDK.
@@ -66,6 +67,7 @@ export class ProtonDriveClient {
     private download: ReturnType<typeof initDownloadModule>;
     private upload: ReturnType<typeof initUploadModule>;
     private devices: ReturnType<typeof initDevicesModule>;
+    private sessionManager: SharingPublicSessionManager;
 
     public experimental: {
         /**
@@ -82,6 +84,20 @@ export class ProtonDriveClient {
          * This is used by Docs app to encrypt and decrypt document updates.
          */
         getDocsKey: (nodeUid: NodeOrUid) => Promise<SessionKey>;
+        /**
+         * Experimental feature to get the info for a public link
+         * required to authenticate the public link.
+         */
+        getPublicLinkInfo: (url: string) => Promise<{
+            isCustomPasswordProtected: boolean;
+            isLegacy: boolean;
+            vendorType: number;
+        }>;
+        /**
+         * Experimental feature to authenticate a public link and
+         * return the client for the public link to access it.
+         */
+        authPublicLink: (url: string, customPassword?: string) => Promise<ProtonDrivePublicLinkClient>;
     };
 
     constructor({
@@ -167,6 +183,8 @@ export class ProtonDriveClient {
             latestEventIdProvider,
         );
 
+        this.sessionManager = new SharingPublicSessionManager(httpClient, apiService, srpModule);
+
         this.experimental = {
             getNodeUrl: async (nodeUid: NodeOrUid) => {
                 this.logger.debug(`Getting node URL for ${getUid(nodeUid)}`);
@@ -180,6 +198,25 @@ export class ProtonDriveClient {
                 }
                 return keys.contentKeyPacketSessionKey;
             },
+            getPublicLinkInfo: async (url: string) => {
+                this.logger.info(`Getting info for public link ${url}`);
+                return this.sessionManager.getInfo(url);
+            },
+            authPublicLink: async (url: string, customPassword?: string) => {
+                this.logger.info(`Authenticating public link ${url}`);
+                const { httpClient, token, password } = await this.sessionManager.auth(url, customPassword);
+                return new ProtonDrivePublicLinkClient({
+                    httpClient,
+                    cryptoCache,
+                    account,
+                    openPGPCryptoModule,
+                    srpModule,
+                    config,
+                    telemetry,
+                    token,
+                    password,
+                });
+            },
         };
     }