@protontech/drive-sdk 0.3.0 → 0.3.1

package/src/internal/sharingPublic/cryptoService.ts

@@ -0,0 +1,162 @@
+import { DriveCrypto, PrivateKey } from '../../crypto';
+import { resultOk, resultError, Result } from '../../interface';
+import { getErrorMessage } from '../errors';
+import { EncryptedShareCrypto, EncryptedNode, DecryptedNode, DecryptedNodeKeys } from './interface';
+
+/**
+ * Provides crypto operations for public link data.
+ *
+ * The public link crypto service is responsible for decrypting and encrypting
+ * public link data. It should export high-level actions only, such as "decrypt
+ * share key" instead of low-level operations like "decrypt key". Low-level
+ * operations should be kept private to the module.
+ */
+export class SharingPublicCryptoService {
+    constructor(
+        private driveCrypto: DriveCrypto,
+        private password: string,
+    ) {
+        this.driveCrypto = driveCrypto;
+        this.password = password;
+    }
+
+    async decryptShareKey(encryptedShare: EncryptedShareCrypto): Promise<PrivateKey> {
+        const { key: shareKey } = await this.driveCrypto.decryptKeyWithSrpPassword(
+            this.password,
+            encryptedShare.base64UrlPasswordSalt,
+            encryptedShare.armoredKey,
+            encryptedShare.armoredPassphrase,
+        );
+        return shareKey;
+    }
+
+    // TODO: verfiy it has all needed
+    async decryptNode(
+        node: EncryptedNode,
+        parentKey: PrivateKey,
+    ): Promise<{ node: DecryptedNode; keys?: DecryptedNodeKeys }> {
+        const commonNodeMetadata = {
+            ...node,
+            encryptedCrypto: undefined,
+        };
+
+        const { name } = await this.decryptName(node, parentKey);
+
+        let passphrase, key, passphraseSessionKey;
+        try {
+            const keyResult = await this.decryptKey(node, parentKey);
+            passphrase = keyResult.passphrase;
+            key = keyResult.key;
+            passphraseSessionKey = keyResult.passphraseSessionKey;
+        } catch (error: unknown) {
+            return {
+                node: {
+                    ...commonNodeMetadata,
+                    name,
+                    errors: [error],
+                },
+            };
+        }
+
+        const errors = [];
+
+        let hashKey;
+        if ('folder' in node.encryptedCrypto) {
+            try {
+                const hashKeyResult = await this.decryptHashKey(node, key);
+                hashKey = hashKeyResult.hashKey;
+            } catch (error: unknown) {
+                errors.push(error);
+            }
+        }
+
+        let contentKeyPacketSessionKey;
+        if ('file' in node.encryptedCrypto) {
+            try {
+                const keySessionKeyResult = await this.driveCrypto.decryptAndVerifySessionKey(
+                    node.encryptedCrypto.file.base64ContentKeyPacket,
+                    '',
+                    key,
+                    [],
+                );
+
+                contentKeyPacketSessionKey = keySessionKeyResult.sessionKey;
+            } catch (error: unknown) {
+                errors.push(error);
+            }
+        }
+
+        return {
+            node: {
+                ...commonNodeMetadata,
+                name,
+                errors: errors.length ? errors : undefined,
+            },
+            keys: {
+                passphrase,
+                key,
+                passphraseSessionKey,
+                contentKeyPacketSessionKey,
+                hashKey,
+            },
+        };
+    }
+
+    private async decryptKey(node: EncryptedNode, parentKey: PrivateKey): Promise<DecryptedNodeKeys> {
+        const key = await this.driveCrypto.decryptKey(
+            node.encryptedCrypto.armoredKey,
+            node.encryptedCrypto.armoredNodePassphrase,
+            '',
+            [parentKey],
+            [],
+        );
+
+        return {
+            passphrase: key.passphrase,
+            key: key.key,
+            passphraseSessionKey: key.passphraseSessionKey,
+        };
+    }
+
+    private async decryptName(
+        node: EncryptedNode,
+        parentKey: PrivateKey,
+    ): Promise<{
+        name: Result<string, Error>;
+    }> {
+        try {
+            const { name } = await this.driveCrypto.decryptNodeName(node.encryptedName, parentKey, []);
+
+            return {
+                name: resultOk(name),
+            };
+        } catch (error: unknown) {
+            const errorMessage = getErrorMessage(error);
+            return {
+                name: resultError(new Error(errorMessage)),
+            };
+        }
+    }
+
+    private async decryptHashKey(
+        node: EncryptedNode,
+        nodeKey: PrivateKey,
+    ): Promise<{
+        hashKey: Uint8Array;
+    }> {
+        if (!('folder' in node.encryptedCrypto)) {
+            // This is developer error.
+            throw new Error('Node is not a folder');
+        }
+
+        const { hashKey } = await this.driveCrypto.decryptNodeHashKey(
+            node.encryptedCrypto.folder.armoredHashKey,
+            nodeKey,
+            [],
+        );
+
+        return {
+            hashKey,
+        };
+    }
+}

package/src/internal/sharingPublic/index.ts

@@ -0,0 +1,40 @@
+import { DriveCrypto } from '../../crypto';
+import { ProtonDriveCryptoCache, ProtonDriveTelemetry } from '../../interface';
+import { DriveAPIService } from '../apiService';
+import { SharingPublicAPIService } from './apiService';
+import { SharingPublicCryptoCache } from './cryptoCache';
+import { SharingPublicCryptoService } from './cryptoService';
+import { SharingPublicManager } from './manager';
+
+export { SharingPublicSessionManager } from './session/manager';
+
+/**
+ * Provides facade for the whole sharing public module.
+ *
+ * The sharing public module is responsible for handling public link data, including
+ * API communication, encryption, decryption, and caching.
+ *
+ * This facade provides internal interface that other modules can use to
+ * interact with the public links.
+ */
+export function initSharingPublicModule(
+    telemetry: ProtonDriveTelemetry,
+    apiService: DriveAPIService,
+    driveCryptoCache: ProtonDriveCryptoCache,
+    driveCrypto: DriveCrypto,
+    token: string,
+    password: string,
+) {
+    const api = new SharingPublicAPIService(telemetry.getLogger('sharingPublic-api'), apiService);
+    const cryptoCache = new SharingPublicCryptoCache(telemetry.getLogger('sharingPublic-crypto'), driveCryptoCache);
+    const cryptoService = new SharingPublicCryptoService(driveCrypto, password);
+    const manager = new SharingPublicManager(
+        telemetry.getLogger('sharingPublic-nodes'),
+        api,
+        cryptoCache,
+        cryptoService,
+        token,
+    );
+
+    return manager;
+}

package/src/internal/sharingPublic/interface.ts

@@ -0,0 +1,59 @@
+import { PrivateKey, SessionKey } from "../../crypto";
+import { NodeType, Result, InvalidNameError } from "../../interface";
+
+export interface EncryptedShareCrypto {
+    base64UrlPasswordSalt: string;
+    armoredKey: string;
+    armoredPassphrase: string;
+}
+
+// TODO: reuse node entity, or keep custom?
+interface BaseNode {
+    // Internal metadata
+    hash?: string; // root node doesn't have any hash
+    encryptedName: string;
+
+    // Basic node metadata
+    uid: string;
+    parentUid?: string;
+    type: NodeType;
+    mediaType?: string;
+    totalStorageSize?: number;
+}
+
+export interface EncryptedNode extends BaseNode {
+    encryptedCrypto: EncryptedNodeFolderCrypto | EncryptedNodeFileCrypto;
+}
+
+export interface EncryptedNodeCrypto {
+    signatureEmail?: string;
+    armoredKey: string;
+    armoredNodePassphrase: string;
+    armoredNodePassphraseSignature?: string;
+}
+
+export interface EncryptedNodeFileCrypto extends EncryptedNodeCrypto {
+    file: {
+        base64ContentKeyPacket: string;
+    };
+}
+
+export interface EncryptedNodeFolderCrypto extends EncryptedNodeCrypto {
+    folder: {
+        armoredExtendedAttributes?: string;
+        armoredHashKey: string;
+    };
+}
+
+export interface DecryptedNode extends BaseNode {
+    name: Result<string, Error | InvalidNameError>;
+    errors?: unknown[];
+}
+
+export interface DecryptedNodeKeys {
+    passphrase: string;
+    key: PrivateKey;
+    passphraseSessionKey: SessionKey;
+    contentKeyPacketSessionKey?: SessionKey;
+    hashKey?: Uint8Array;
+}

package/src/internal/sharingPublic/manager.ts

@@ -0,0 +1,85 @@
+import { PrivateKey } from '../../crypto';
+import { Logger } from '../../interface';
+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 *iterateChildren(parentUid: string): AsyncGenerator<DecryptedNode> {
+        // TODO: optimise this - decrypt in parallel
+        for await (const node of this.api.iterateChildren(parentUid)) {
+            const decryptedNode = await this.decryptNode(node);
+            yield decryptedNode;
+        }
+    }
+
+    private async decryptShare(encryptedShare: EncryptedShareCrypto): Promise<void> {
+        const shareKey = await this.cryptoService.decryptShareKey(encryptedShare);
+        await this.cryptoCache.setShareKey(shareKey);
+    }
+
+    private async decryptNode(encryptedNode: EncryptedNode): Promise<DecryptedNode> {
+        const parentKey = await this.getParentKey(encryptedNode);
+
+        const { node: decryptedNode, keys } = await this.cryptoService.decryptNode(encryptedNode, parentKey);
+
+        // TODO: cache of metadata?
+
+        if (keys) {
+            try {
+                await this.cryptoCache.setNodeKeys(decryptedNode.uid, keys);
+            } catch (error: unknown) {
+                this.logger.error(`Failed to cache node keys ${decryptedNode.uid}`, error);
+            }
+        }
+
+        return decryptedNode;
+    }
+
+    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,
+        };
+    }
+}