@protontech/drive-sdk 0.12.1 → 0.13.1

package/src/internal/upload/smallFileUploader.ts

@@ -0,0 +1,353 @@
+import { PrivateKey, SessionKey } from '../../crypto';
+import { AbortError, IntegrityError } from '../../errors';
+import { Logger, Thumbnail, ThumbnailType, UploadMetadata } from '../../interface';
+import { getErrorMessage } from '../errors';
+import { generateFileExtendedAttributes } from '../nodes';
+import { UploadAPIService } from './apiService';
+import { BlockVerifier, verifyBlockWithContentKey } from './blockVerifier';
+import { UploadCryptoService } from './cryptoService';
+import { UploadDigests } from './digests';
+import { Uploader } from './fileUploader';
+import { NodeRevisionDraft, NodeCrypto } from './interface';
+import { UploadManager } from './manager';
+import { readStreamToUint8Array } from './streamReader';
+import { MAX_BLOCK_ENCRYPTION_RETRIES } from './streamUploader';
+import { UploadTelemetry } from './telemetry';
+
+export type NodeKeys = {
+    key: PrivateKey;
+    contentKeyPacket: Uint8Array<ArrayBuffer>;
+    contentKeyPacketSessionKey: SessionKey;
+    signingKeys: NodeCrypto['signingKeys'];
+};
+
+/**
+ * Base uploader for small file and small revision uploads.
+ * Shares the single-request flow: read content, get node crypto, encrypt, then call API.
+ */
+abstract class SmallUploader extends Uploader {
+    protected logger: Logger;
+
+    constructor(
+        telemetry: UploadTelemetry,
+        apiService: UploadAPIService,
+        cryptoService: UploadCryptoService,
+        manager: UploadManager,
+        metadata: UploadMetadata,
+        onFinish: () => void,
+        signal: AbortSignal | undefined,
+    ) {
+        super(telemetry, apiService, cryptoService, manager, metadata, onFinish, signal);
+        this.logger = telemetry.getLoggerForSmallUpload();
+    }
+    protected async createRevisionDraft(): Promise<{
+        revisionDraft: NodeRevisionDraft;
+        blockVerifier: BlockVerifier;
+    }> {
+        throw new Error('Small upload does not use revision draft');
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    protected async deleteRevisionDraft(revisionDraft: NodeRevisionDraft): Promise<void> {
+        throw new Error('Small upload does not use revision draft');
+    }
+
+    protected async startUpload(
+        stream: ReadableStream,
+        thumbnails: Thumbnail[],
+        onProgress?: (uploadedBytes: number) => void,
+    ): Promise<{ nodeRevisionUid: string; nodeUid: string }> {
+        try {
+            const result = await this.handleUpload(stream, thumbnails);
+
+            onProgress?.(this.metadata.expectedSize);
+            void this.telemetry.uploadFinished(result.nodeRevisionUid, this.metadata.expectedSize);
+            return result;
+        } catch (error) {
+            void this.telemetry.uploadInitFailed(this.getTelemetryContextUid(), error, this.metadata.expectedSize);
+            throw error;
+        } finally {
+            this.onFinish();
+        }
+    }
+
+    protected abstract getTelemetryContextUid(): string;
+
+    protected abstract handleUpload(
+        stream: ReadableStream,
+        thumbnails: Thumbnail[],
+    ): Promise<{
+        nodeUid: string;
+        nodeRevisionUid: string;
+    }>;
+
+    protected async buildPayloads(
+        nodeKeys: NodeKeys,
+        stream: ReadableStream,
+        thumbnails: Thumbnail[],
+    ): Promise<{
+        commitPayload: {
+            armoredManifestSignature: string;
+            armoredExtendedAttributes: string;
+        };
+        encryptedBlock:
+            | {
+                  encryptedData: Uint8Array<ArrayBuffer>;
+                  armoredSignature: string;
+                  verificationToken: Uint8Array<ArrayBuffer>;
+              }
+            | undefined;
+        encryptedThumbnails: { type: ThumbnailType; encryptedData: Uint8Array<ArrayBuffer> }[];
+    }> {
+        const content = await this.readStreamContent(stream);
+
+        const [encryptedThumbnails, encryptedBlock] = await Promise.all([
+            this.encryptThumbnails(nodeKeys, thumbnails),
+            this.encryptContentBlock(nodeKeys, content.data),
+        ]);
+        const commitPayload = await this.encryptCommitPayload(nodeKeys, content.sha1, encryptedBlock);
+
+        return {
+            commitPayload,
+            encryptedBlock,
+            encryptedThumbnails,
+        };
+    }
+
+    private async readStreamContent(stream: ReadableStream): Promise<{
+        data: Uint8Array<ArrayBuffer>;
+        sha1: string;
+    }> {
+        const content = await readStreamToUint8Array(stream, this.abortController.signal);
+
+        if (content.length !== this.metadata.expectedSize) {
+            throw new IntegrityError(new Error('Stream size does not match expected size').message, {
+                actual: content.length,
+                expected: this.metadata.expectedSize,
+            });
+        }
+
+        const digests = new UploadDigests();
+        digests.update(content);
+        const contentSha1 = digests.digests().sha1;
+
+        if (this.metadata.expectedSha1 && contentSha1 !== this.metadata.expectedSha1) {
+            throw new IntegrityError(new Error('File hash does not match expected hash').message, {
+                uploadedSha1: contentSha1,
+                expectedSha1: this.metadata.expectedSha1,
+            });
+        }
+
+        return {
+            data: content,
+            sha1: contentSha1,
+        };
+    }
+
+    private async encryptThumbnails(
+        nodeKeys: NodeKeys,
+        thumbnails: Thumbnail[],
+    ): Promise<{ type: ThumbnailType; encryptedData: Uint8Array<ArrayBuffer> }[]> {
+        const result = [];
+        for (const thumbnail of thumbnails) {
+            this.logger.debug(`Encrypting thumbnail ${thumbnail.type}`);
+            const enc = await this.cryptoService.encryptThumbnail(nodeKeys, thumbnail);
+            result.push({ type: thumbnail.type, encryptedData: enc.encryptedData });
+        }
+        return result;
+    }
+
+    private async encryptContentBlock(
+        nodeKeys: NodeKeys,
+        content: Uint8Array<ArrayBuffer>,
+    ): Promise<
+        | {
+              encryptedData: Uint8Array<ArrayBuffer>;
+              armoredSignature: string;
+              verificationToken: Uint8Array<ArrayBuffer>;
+              blockHash: Uint8Array<ArrayBuffer>;
+          }
+        | undefined
+    > {
+        this.logger.debug(`Encrypting block`);
+
+        if (content.length === 0) {
+            return;
+        }
+
+        let attempt = 0;
+        let integrityError = false;
+        let encrypted;
+        while (!encrypted) {
+            attempt++;
+            try {
+                encrypted = await this.cryptoService.encryptBlock(
+                    (encryptedBlock) =>
+                        verifyBlockWithContentKey(
+                            this.cryptoService,
+                            nodeKeys.contentKeyPacket,
+                            nodeKeys.contentKeyPacketSessionKey,
+                            encryptedBlock,
+                        ),
+                    nodeKeys,
+                    content,
+                    0,
+                );
+                if (integrityError) {
+                    void this.telemetry.logBlockVerificationError(true);
+                }
+            } catch (error: unknown) {
+                // Do not retry or report anything if the upload was aborted.
+                if (error instanceof AbortError) {
+                    throw error;
+                }
+
+                if (error instanceof IntegrityError) {
+                    integrityError = true;
+                }
+
+                if (attempt <= MAX_BLOCK_ENCRYPTION_RETRIES) {
+                    this.logger.warn(`Block encryption failed #${attempt}, retrying: ${getErrorMessage(error)}`);
+                    continue;
+                }
+
+                this.logger.error(`Failed to encrypt block`, error);
+                if (integrityError) {
+                    void this.telemetry.logBlockVerificationError(false);
+                }
+                throw error;
+            }
+        }
+
+        const blockHash = await encrypted.hashPromise;
+        return {
+            encryptedData: encrypted.encryptedData,
+            armoredSignature: encrypted.armoredSignature,
+            verificationToken: encrypted.verificationToken,
+            blockHash,
+        };
+    }
+
+    private async encryptCommitPayload(
+        nodeKeys: NodeKeys,
+        contentSha1: string,
+        encryptedBlock:
+            | {
+                  blockHash: Uint8Array<ArrayBuffer>;
+              }
+            | undefined,
+    ): Promise<{
+        armoredManifestSignature: string;
+        armoredExtendedAttributes: string;
+    }> {
+        this.logger.debug(`Preparing commit payload`);
+
+        const manifest = encryptedBlock ? encryptedBlock.blockHash : new Uint8Array(0);
+        const extendedAttributes = generateFileExtendedAttributes(
+            {
+                modificationTime: this.metadata.modificationTime,
+                size: this.metadata.expectedSize,
+                blockSizes: this.metadata.expectedSize > 0 ? [this.metadata.expectedSize] : [],
+                digests: { sha1: contentSha1 },
+            },
+            this.metadata.additionalMetadata,
+        );
+        const commitCrypto = await this.cryptoService.commitFile(nodeKeys, manifest, extendedAttributes);
+        return {
+            armoredManifestSignature: commitCrypto.armoredManifestSignature,
+            armoredExtendedAttributes: commitCrypto.armoredExtendedAttributes,
+        };
+    }
+}
+
+/**
+ * Uploader for small new files using the single-request small file endpoint.
+ */
+export class SmallFileUploader extends SmallUploader {
+    constructor(
+        telemetry: UploadTelemetry,
+        apiService: UploadAPIService,
+        cryptoService: UploadCryptoService,
+        manager: UploadManager,
+        metadata: UploadMetadata,
+        onFinish: () => void,
+        signal: AbortSignal | undefined,
+        private parentFolderUid: string,
+        private name: string,
+    ) {
+        super(telemetry, apiService, cryptoService, manager, metadata, onFinish, signal);
+        this.parentFolderUid = parentFolderUid;
+        this.name = name;
+    }
+
+    protected getTelemetryContextUid(): string {
+        return this.parentFolderUid;
+    }
+
+    protected async handleUpload(
+        stream: ReadableStream,
+        thumbnails: Thumbnail[],
+    ): Promise<{
+        nodeUid: string;
+        nodeRevisionUid: string;
+    }> {
+        const nodeCrypto = await this.manager.generateNewFileCrypto(this.parentFolderUid, this.name);
+        const nodeKeys = {
+            key: nodeCrypto.nodeKeys.decrypted.key,
+            contentKeyPacket: nodeCrypto.contentKey.encrypted.contentKeyPacket,
+            contentKeyPacketSessionKey: nodeCrypto.contentKey.decrypted.contentKeyPacketSessionKey,
+            signingKeys: nodeCrypto.signingKeys,
+        };
+        const payloads = await this.buildPayloads(nodeKeys, stream, thumbnails);
+        return this.manager.uploadFile(
+            this.parentFolderUid,
+            nodeCrypto,
+            this.metadata,
+            payloads.commitPayload,
+            payloads.encryptedBlock,
+            payloads.encryptedThumbnails,
+        );
+    }
+}
+
+/**
+ * Uploader for small new revisions using the single-request small revision endpoint.
+ * Reuses the existing file's keys.
+ */
+export class SmallFileRevisionUploader extends SmallUploader {
+    constructor(
+        telemetry: UploadTelemetry,
+        apiService: UploadAPIService,
+        cryptoService: UploadCryptoService,
+        manager: UploadManager,
+        metadata: UploadMetadata,
+        onFinish: () => void,
+        signal: AbortSignal | undefined,
+        private nodeUid: string,
+    ) {
+        super(telemetry, apiService, cryptoService, manager, metadata, onFinish, signal);
+        this.nodeUid = nodeUid;
+    }
+
+    protected getTelemetryContextUid(): string {
+        return this.nodeUid;
+    }
+
+    protected async handleUpload(
+        stream: ReadableStream,
+        thumbnails: Thumbnail[],
+    ): Promise<{
+        nodeUid: string;
+        nodeRevisionUid: string;
+    }> {
+        const nodeKeys = await this.manager.getExistingFileNodeCrypto(this.nodeUid);
+        const payloads = await this.buildPayloads(nodeKeys, stream, thumbnails);
+        return this.manager.uploadSmallRevision(
+            this.nodeUid,
+            nodeKeys,
+            payloads.commitPayload,
+            payloads.encryptedBlock,
+            payloads.encryptedThumbnails,
+        );
+    }
+}

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

@@ -0,0 +1,109 @@
+import { AbortError } from '../../errors';
+import { readStreamToUint8Array } from './streamReader';
+
+describe('readStreamToUint8Array', () => {
+    it('should return empty Uint8Array for empty stream', async () => {
+        const stream = new ReadableStream<Uint8Array<ArrayBuffer>>({
+            start(controller) {
+                controller.close();
+            },
+        });
+
+        const result = await readStreamToUint8Array(stream);
+
+        expect(result).toEqual(new Uint8Array([]));
+        expect(result.length).toBe(0);
+    });
+
+    it('should read single chunk into Uint8Array', async () => {
+        const stream = new ReadableStream<Uint8Array<ArrayBuffer>>({
+            start(controller) {
+                controller.enqueue(new Uint8Array([1, 2, 3]));
+                controller.close();
+            },
+        });
+
+        const result = await readStreamToUint8Array(stream);
+
+        expect(result).toEqual(new Uint8Array([1, 2, 3]));
+        expect(result.length).toBe(3);
+    });
+
+    it('should concatenate multiple chunks into single Uint8Array', async () => {
+        const stream = new ReadableStream<Uint8Array<ArrayBuffer>>({
+            start(controller) {
+                controller.enqueue(new Uint8Array([1, 2, 3]));
+                controller.enqueue(new Uint8Array([4, 5, 6]));
+                controller.enqueue(new Uint8Array([7, 8, 9]));
+                controller.close();
+            },
+        });
+
+        const result = await readStreamToUint8Array(stream);
+
+        expect(result).toEqual(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9]));
+        expect(result.length).toBe(9);
+    });
+
+    it('should work without abort signal', async () => {
+        const stream = new ReadableStream<Uint8Array<ArrayBuffer>>({
+            start(controller) {
+                controller.enqueue(new Uint8Array([42]));
+                controller.close();
+            },
+        });
+
+        const result = await readStreamToUint8Array(stream);
+
+        expect(result).toEqual(new Uint8Array([42]));
+    });
+
+    it('should throw AbortError when signal is aborted during read', async () => {
+        const controller = new AbortController();
+        const stream = new ReadableStream<Uint8Array<ArrayBuffer>>({
+            start(streamController) {
+                streamController.enqueue(new Uint8Array([1, 2, 3]));
+                setTimeout(() => {
+                    streamController.enqueue(new Uint8Array([4, 5, 6]));
+                    streamController.close();
+                }, 50);
+            },
+        });
+
+        setTimeout(() => controller.abort(), 10);
+
+        await expect(readStreamToUint8Array(stream, controller.signal)).rejects.toThrow(AbortError);
+    });
+
+    it('should throw AbortError when signal is already aborted before read', async () => {
+        const controller = new AbortController();
+        controller.abort();
+
+        const stream = new ReadableStream<Uint8Array<ArrayBuffer>>({
+            start(streamController) {
+                streamController.enqueue(new Uint8Array([1, 2, 3]));
+                streamController.close();
+            },
+        });
+
+        await expect(readStreamToUint8Array(stream, controller.signal)).rejects.toThrow(AbortError);
+    });
+
+    it('should release reader lock so stream can be consumed once', async () => {
+        const stream = new ReadableStream<Uint8Array<ArrayBuffer>>({
+            start(controller) {
+                controller.enqueue(new Uint8Array([1]));
+                controller.close();
+            },
+        });
+
+        const result = await readStreamToUint8Array(stream);
+
+        expect(result).toEqual(new Uint8Array([1]));
+
+        const reader = stream.getReader();
+        const { done } = await reader.read();
+        expect(done).toBe(true);
+        reader.releaseLock();
+    });
+});

package/src/internal/upload/streamReader.ts

@@ -0,0 +1,38 @@
+import { AbortError } from "../../errors";
+
+/**
+ * Reads a ReadableStream into a Uint8Array.
+ */
+export async function readStreamToUint8Array(
+    stream: ReadableStream<Uint8Array<ArrayBuffer>>,
+    signal?: AbortSignal,
+): Promise<Uint8Array<ArrayBuffer>> {
+    const reader = stream.getReader();
+    const chunks: Uint8Array[] = [];
+    let totalLength = 0;
+
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            if (signal?.aborted) {
+                throw new AbortError();
+            }
+            const chunk = value;
+            totalLength += chunk.length;
+            chunks.push(chunk);
+        }
+
+        const result = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return result;
+    } finally {
+        reader.releaseLock();
+    }
+}

package/src/internal/upload/streamUploader.ts

@@ -39,7 +39,7 @@ const MAX_UPLOADING_BLOCKS = 5;
  * This is to automatically retry random errors that can happen
  * during encryption, for example bitflips.
  */
-const MAX_BLOCK_ENCRYPTION_RETRIES = 1;
+export const MAX_BLOCK_ENCRYPTION_RETRIES = 1;
 
 /**
  * Maximum number of retries for block upload.

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

@@ -38,7 +38,9 @@ describe('UploadTelemetry', () => {
             eventName: 'upload',
             volumeType: 'own_volume',
             uploadedSize: 0,
+            approximateUploadedSize: 0,
             expectedSize: 1000,
+            approximateExpectedSize: 4095,
             error: 'unknown',
             originalError: error,
         });
@@ -52,7 +54,9 @@ describe('UploadTelemetry', () => {
             eventName: 'upload',
             volumeType: 'own_volume',
             uploadedSize: 500,
+            approximateUploadedSize: 4095,
             expectedSize: 1000,
+            approximateExpectedSize: 4095,
             error: 'unknown',
             originalError: error,
         });
@@ -65,7 +69,9 @@ describe('UploadTelemetry', () => {
             eventName: 'upload',
             volumeType: 'own_volume',
             uploadedSize: 1000,
+            approximateUploadedSize: 4095,
             expectedSize: 1000,
+            approximateExpectedSize: 4095,
         });
     });
 

package/src/internal/upload/telemetry.ts

@@ -1,12 +1,12 @@
 import { RateLimitedError, ValidationError, IntegrityError } from '../../errors';
 import { ProtonDriveTelemetry, MetricsUploadErrorType, Logger } from '../../interface';
-import { LoggerWithPrefix } from '../../telemetry';
+import { LoggerWithPrefix, reduceSizePrecision } from '../../telemetry';
 import { APIHTTPError } from '../apiService';
 import { splitNodeUid, splitNodeRevisionUid } from '../uids';
 import { SharesService } from './interface';
 
 export class UploadTelemetry {
-    private logger: Logger;
+    readonly logger: Logger;
 
     constructor(
         private telemetry: ProtonDriveTelemetry,
@@ -17,6 +17,10 @@ export class UploadTelemetry {
         this.sharesService = sharesService;
     }
 
+    getLoggerForSmallUpload() {
+        return new LoggerWithPrefix(this.logger, `small upload`);
+    }
+
     getLoggerForRevision(revisionUid: string) {
         return new LoggerWithPrefix(this.logger, `revision ${revisionUid}`);
     }
@@ -91,6 +95,8 @@ export class UploadTelemetry {
         this.telemetry.recordMetric({
             eventName: 'upload',
             volumeType,
+            approximateUploadedSize: reduceSizePrecision(options.uploadedSize),
+            approximateExpectedSize: reduceSizePrecision(options.expectedSize),
             ...options,
         });
     }

package/src/protonDrivePhotosClient.ts

@@ -454,7 +454,7 @@ export class ProtonDrivePhotosClient {
         name: string,
         metadata: UploadMetadata & {
             captureTime?: Date;
-            mainPhotoLinkID?: string;
+            mainPhotoNodeUid?: string;
             tags?: PhotoTag[];
         },
         signal?: AbortSignal,

package/src/protonDrivePublicLinkClient.ts

@@ -174,6 +174,8 @@ export class ProtonDrivePublicLinkClient {
             this.sharingPublic.nodes.access,
             featureFlagProvider,
             fullConfig.clientUid,
+            // Public links do not support small file upload.
+            false,
         );
 
         this.experimental = {

package/src/telemetry.test.ts

@@ -0,0 +1,40 @@
+import { reduceSizePrecision } from './telemetry';
+
+describe('reduceSizePrecision', () => {
+    it('returns 0 for size 0', () => {
+        expect(reduceSizePrecision(0)).toBe(0);
+    });
+
+    it('returns 4095 for very small files (size < 4096)', () => {
+        expect(reduceSizePrecision(1)).toBe(4095);
+        expect(reduceSizePrecision(100)).toBe(4095);
+        expect(reduceSizePrecision(4095)).toBe(4095);
+    });
+
+    it('returns precision (100_000) for sizes from 4096 to below precision', () => {
+        expect(reduceSizePrecision(4096)).toBe(100_000);
+        expect(reduceSizePrecision(50_000)).toBe(100_000);
+        expect(reduceSizePrecision(99_999)).toBe(100_000);
+    });
+
+    it('returns size unchanged when size equals precision', () => {
+        expect(reduceSizePrecision(100_000)).toBe(100_000);
+    });
+
+    it('rounds down to nearest 100_000 for sizes above precision', () => {
+        expect(reduceSizePrecision(100_001)).toBe(100_000);
+        expect(reduceSizePrecision(150_000)).toBe(100_000);
+        expect(reduceSizePrecision(199_999)).toBe(100_000);
+        expect(reduceSizePrecision(200_000)).toBe(200_000);
+        expect(reduceSizePrecision(250_000)).toBe(200_000);
+        expect(reduceSizePrecision(299_999)).toBe(200_000);
+        expect(reduceSizePrecision(300_000)).toBe(300_000);
+    });
+
+    it('handles large sizes', () => {
+        expect(reduceSizePrecision(1_000_000)).toBe(1_000_000);
+        expect(reduceSizePrecision(1_500_000)).toBe(1_500_000);
+        expect(reduceSizePrecision(1_999_999)).toBe(1_900_000);
+        expect(reduceSizePrecision(10_000_000)).toBe(10_000_000);
+    });
+});

package/src/telemetry.ts

@@ -352,3 +352,25 @@ class ConsoleMetricHandler<T extends MetricEvent> implements MetricHandler<T> {
         );
     }
 }
+
+export function reduceSizePrecision(size: number): number {
+    // The client shouldn't send the clear text size of the file.
+    // The intented upload size is needed only for early validation that
+    // the file can fit in the remaining quota to avoid data transfer when
+    // the upload would be rejected. The backend will still validate
+    // the quota during block upload and revision commit.
+    const precision = 100_000; // bytes
+
+    if (size === 0) {
+        return 0;
+    }
+    // We care about very small files in metrics, thus we handle explicitely
+    // the very small files so they appear correctly in metrics.
+    if (size < 4096) {
+        return 4095;
+    }
+    if (size < precision) {
+        return precision;
+    }
+    return Math.floor(size / precision) * precision;
+}

package/src/transformers.ts

@@ -24,6 +24,7 @@ type InternalPartialNode = Pick<
     | 'nameAuthor'
     | 'directRole'
     | 'membership'
+    | 'ownedBy'
     | 'type'
     | 'mediaType'
     | 'isShared'
@@ -93,6 +94,7 @@ export function convertInternalNode(node: InternalPartialNode): PublicMaybeNode
         nameAuthor: node.nameAuthor,
         directRole: node.directRole,
         membership: node.membership,
+        ownedBy: node.ownedBy,
         type: node.type,
         mediaType: node.mediaType,
         isShared: node.isShared,