@protontech/drive-sdk 0.10.0 → 0.12.0

package/src/internal/photos/photosTransferPayloadBuilder.test.ts

@@ -0,0 +1,380 @@
+import { ValidationError } from '../../errors';
+import { resultOk } from '../../interface';
+import { AlbumsCryptoService } from './albumsCrypto';
+import { DecryptedPhotoNode } from './interface';
+import { PhotoTransferPayloadBuilder } from './photosTransferPayloadBuilder';
+import { PhotosNodesAccess } from './nodes';
+
+/**
+ * Helper to create a mock photo node with minimal required properties.
+ */
+function createMockPhotoNode(
+    uid: string,
+    overrides: Partial<DecryptedPhotoNode> = {},
+): DecryptedPhotoNode {
+    return {
+        uid,
+        parentUid: 'volume1~parent',
+        hash: 'hash',
+        name: resultOk('photo.jpg'),
+        photo: {
+            captureTime: new Date(),
+            mainPhotoNodeUid: undefined,
+            relatedPhotoNodeUids: [],
+            tags: [],
+            albums: [],
+        },
+        activeRevision: {
+            ok: true,
+            value: {
+                uid: 'rev1',
+                state: 'active' as const,
+                creationTime: new Date(),
+                storageSize: 100,
+                signatureEmail: 'test@example.com',
+                claimedModificationTime: new Date(),
+                claimedSize: 100,
+                claimedDigests: { sha1: 'sha1hash' },
+                claimedBlockSizes: [100],
+            },
+        },
+        keyAuthor: { ok: true, value: 'test@example.com' },
+        ...overrides,
+    } as DecryptedPhotoNode;
+}
+
+describe('PhotoTransferPayloadBuilder', () => {
+    let cryptoService: jest.Mocked<AlbumsCryptoService>;
+    let nodesService: jest.Mocked<PhotosNodesAccess>;
+    let targetKeys: { key: unknown; hashKey: Uint8Array };
+    let signingKeys: { type: 'userAddress'; email: string; addressId: string; key: unknown };
+    let builder: PhotoTransferPayloadBuilder;
+
+    beforeEach(() => {
+        targetKeys = {
+            key: 'targetKey' as any,
+            hashKey: new Uint8Array([1, 2, 3]),
+        };
+
+        signingKeys = {
+            type: 'userAddress',
+            email: 'test@example.com',
+            addressId: 'addressId',
+            key: 'signingKey' as any,
+        };
+
+        // @ts-expect-error Mocking for testing purposes
+        cryptoService = {
+            encryptPhotoForAlbum: jest.fn(),
+        };
+
+        // @ts-expect-error Mocking for testing purposes
+        nodesService = {
+            iterateNodes: jest.fn(),
+            getNodePrivateAndSessionKeys: jest.fn(),
+        };
+
+        builder = new PhotoTransferPayloadBuilder(cryptoService, nodesService);
+    });
+
+    describe('preparePhotoPayloads', () => {
+        beforeEach(() => {
+            nodesService.iterateNodes.mockImplementation(async function* (uids: string[]) {
+                for (const uid of uids) {
+                    if (uid === 'volume1~missing') {
+                        yield { missingUid: uid };
+                        continue;
+                    }
+
+                    const photoNode = createMockPhotoNode(uid);
+
+                    // Handle uids in the form 'volumeId~mainPhoto-related:N' where N is the number of related photos
+                    const relatedMatch = /^(.+)~(.+)-related:(\d+)$/.exec(uid);
+                    if (relatedMatch) {
+                        const [, volumeId, , countStr] = relatedMatch;
+                        const count = parseInt(countStr, 10);
+                        photoNode.photo!.relatedPhotoNodeUids = Array.from(
+                            { length: count },
+                            (_, idx) => `${volumeId}~related${idx + 1}`,
+                        );
+                    }
+
+                    yield photoNode;
+                }
+            });
+
+            nodesService.getNodePrivateAndSessionKeys.mockResolvedValue({
+                key: 'nodeKey' as any,
+                nameSessionKey: 'sessionKey' as any,
+                passphrase: 'passphrase',
+                passphraseSessionKey: 'passphraseSessionKey' as any,
+            });
+
+            cryptoService.encryptPhotoForAlbum.mockResolvedValue({
+                contentHash: 'contentHash',
+                hash: 'nameHash',
+                encryptedName: 'encryptedName',
+                nameSignatureEmail: 'test@example.com',
+                armoredNodePassphrase: 'passphrase',
+                armoredNodePassphraseSignature: 'signature',
+                signatureEmail: 'test@example.com',
+            });
+        });
+
+        it('should return payloads and empty errors for a single photo without related photos', async () => {
+            const items = [{ photoNodeUid: 'volume1~photo1' }];
+
+            const result = await builder.preparePhotoPayloads(
+                items,
+                'volume1~root',
+                targetKeys as any,
+                signingKeys as any,
+            );
+
+            expect(result).toMatchObject({
+                payloads: [{
+                    nodeUid: 'volume1~photo1',
+                    contentHash: 'contentHash',
+                    nameHash: 'nameHash',
+                    encryptedName: 'encryptedName',
+                    nameSignatureEmail: 'test@example.com',
+                    nodePassphrase: 'passphrase',
+                    relatedPhotos: [],
+                }],
+                errors: new Map(),
+            });
+            expect(nodesService.iterateNodes).toHaveBeenCalledWith(['volume1~photo1'], undefined);
+            expect(nodesService.getNodePrivateAndSessionKeys).toHaveBeenCalledWith('volume1~photo1');
+            expect(cryptoService.encryptPhotoForAlbum).toHaveBeenCalledTimes(1);
+        });
+
+        it('should include related photos in payload when photo has relatedPhotoNodeUids', async () => {
+            const items = [{ photoNodeUid: 'volume1~mainPhoto-related:3' }];
+
+            const result = await builder.preparePhotoPayloads(
+                items,
+                'volume1~root',
+                targetKeys as any,
+                signingKeys as any,
+            );
+
+            expect(result).toMatchObject({
+                payloads: [{
+                    nodeUid: 'volume1~mainPhoto-related:3',
+                    contentHash: 'contentHash',
+                    nameHash: 'nameHash',
+                    encryptedName: 'encryptedName',
+                    nameSignatureEmail: 'test@example.com',
+                    nodePassphrase: 'passphrase',
+                    relatedPhotos: [{
+                        nodeUid: 'volume1~related1',
+                        contentHash: 'contentHash',
+                        nameHash: 'nameHash',
+                        encryptedName: 'encryptedName',
+                        nameSignatureEmail: 'test@example.com',
+                        nodePassphrase: 'passphrase',
+                    }, {
+                        nodeUid: 'volume1~related2',
+                        contentHash: 'contentHash',
+                        nameHash: 'nameHash',
+                        encryptedName: 'encryptedName',
+                        nameSignatureEmail: 'test@example.com',
+                        nodePassphrase: 'passphrase',
+                    }, {
+                        nodeUid: 'volume1~related3',
+                        contentHash: 'contentHash',
+                        nameHash: 'nameHash',
+                        encryptedName: 'encryptedName',
+                        nameSignatureEmail: 'test@example.com',
+                        nodePassphrase: 'passphrase',
+                    }],
+                }],
+                errors: new Map(),
+            });
+            expect(nodesService.iterateNodes).toHaveBeenCalledTimes(2);
+            expect(nodesService.iterateNodes).toHaveBeenNthCalledWith(1, ['volume1~mainPhoto-related:3'], undefined);
+            expect(nodesService.iterateNodes).toHaveBeenNthCalledWith(
+                2,
+                ['volume1~related1', 'volume1~related2', 'volume1~related3'],
+                undefined,
+            );
+            expect(cryptoService.encryptPhotoForAlbum).toHaveBeenCalledTimes(4);
+        });
+
+        it('should merge additionalRelatedPhotoNodeUids with photo relatedPhotoNodeUids', async () => {
+            const items = [
+                {
+                    photoNodeUid: 'volume1~photo1',
+                    additionalRelatedPhotoNodeUids: ['volume1~extraRelated1'],
+                },
+            ];
+
+            const result = await builder.preparePhotoPayloads(
+                items,
+                'volume1~root',
+                targetKeys as any,
+                signingKeys as any,
+            );
+
+            expect(result).toMatchObject({
+                payloads: [{
+                    nodeUid: 'volume1~photo1',
+                    contentHash: 'contentHash',
+                    nameHash: 'nameHash',
+                    encryptedName: 'encryptedName',
+                    nameSignatureEmail: 'test@example.com',
+                    nodePassphrase: 'passphrase',
+                    relatedPhotos: [{
+                        nodeUid: 'volume1~extraRelated1',
+                        contentHash: 'contentHash',
+                        nameHash: 'nameHash',
+                        encryptedName: 'encryptedName',
+                        nameSignatureEmail: 'test@example.com',
+                        nodePassphrase: 'passphrase',
+                    }],
+                }],
+                errors: new Map(),
+            });
+        });
+
+        it('should put missing node UIDs in errors with ValidationError', async () => {
+            const items = [
+                { photoNodeUid: 'volume1~photo1' },
+                { photoNodeUid: 'volume1~missing' },
+            ];
+
+            const result = await builder.preparePhotoPayloads(
+                items,
+                'volume1~root',
+                targetKeys as any,
+                signingKeys as any,
+            );
+
+            expect(result).toMatchObject({
+                payloads: [{
+                    nodeUid: 'volume1~photo1',
+                    contentHash: 'contentHash',
+                    nameHash: 'nameHash',
+                    encryptedName: 'encryptedName',
+                    nameSignatureEmail: 'test@example.com',
+                    nodePassphrase: 'passphrase',
+                    relatedPhotos: [],
+                }],
+                errors: new Map([['volume1~missing', new ValidationError('Photo not found')]]),
+            });
+        });
+
+        it('should throw when targetKeys.hashKey is missing', async () => {
+            const items = [{ photoNodeUid: 'volume1~photo1' }];
+            const keysWithoutHashKey = { ...targetKeys, hashKey: undefined };
+
+            await expect(
+                builder.preparePhotoPayloads(items, 'volume1~root', keysWithoutHashKey as any, signingKeys as any),
+            ).rejects.toThrow('Target hash key is required to build photo payloads');
+
+            expect(nodesService.iterateNodes).not.toHaveBeenCalled();
+        });
+
+        it('should put error in errors map when encryptPhotoForAlbum fails', async () => {
+            const items = [{ photoNodeUid: 'volume1~photo1' }];
+            const cryptoError = new Error('Crypto operation failed');
+            cryptoService.encryptPhotoForAlbum.mockRejectedValue(cryptoError);
+
+            const result = await builder.preparePhotoPayloads(
+                items,
+                'volume1~root',
+                        targetKeys as any,
+                signingKeys as any,
+            );
+
+            expect(result).toMatchObject({
+                payloads: [],
+                errors: new Map([['volume1~photo1', cryptoError]]),
+            });
+        });
+
+        it('should put error in errors map when getNodePrivateAndSessionKeys fails', async () => {
+            const items = [{ photoNodeUid: 'volume1~photo1' }];
+            const keysError = new Error('Failed to get keys');
+            nodesService.getNodePrivateAndSessionKeys.mockRejectedValue(keysError);
+
+            const result = await builder.preparePhotoPayloads(
+                items,
+                'volume1~root',
+                targetKeys as any,
+                signingKeys as any,
+            );
+
+            expect(result).toMatchObject({
+                payloads: [],
+                errors: new Map([['volume1~photo1', keysError]]),
+            });
+        });
+
+        it('should put error in errors map when photo has no content hash', async () => {
+            const items = [{ photoNodeUid: 'volume1~photo1' }];
+            nodesService.iterateNodes.mockImplementation(async function* (uids: string[]) {
+                const node = createMockPhotoNode(uids[0]);
+                node.activeRevision = { ok: true, value: { ...(node.activeRevision as any).value, claimedDigests: {} } } as any;
+                yield node;
+            });
+
+            const result = await builder.preparePhotoPayloads(
+                items,
+                'volume1~root',
+                targetKeys as any,
+                signingKeys as any,
+            );
+
+            expect(result).toMatchObject({
+                payloads: [],
+                errors: new Map([['volume1~photo1', new Error('Cannot build photo payload without a content hash')]]),
+            });
+        });
+
+        it('should include signatureEmail and nodePassphraseSignature only for anonymous key author', async () => {
+            const items = [{ photoNodeUid: 'volume1~anonymous' }, { photoNodeUid: 'volume1~signed' }];
+            nodesService.iterateNodes.mockImplementation(async function* (uids: string[]) {
+                for (const uid of uids) {
+                    const node = createMockPhotoNode(uid);
+                    if (uid === 'volume1~anonymous') {
+                        node.keyAuthor = { ok: true, value: null };
+                    } else {
+                        node.keyAuthor = { ok: true, value: 'test@example.com' };
+                    }
+                    yield node;
+                }
+            });
+
+            const result = await builder.preparePhotoPayloads(
+                items,
+                'volume1~root',
+                targetKeys as any,
+                signingKeys as any,
+            );
+
+            expect(result).toMatchObject({
+                payloads: [{
+                    nodeUid: 'volume1~anonymous',
+                    contentHash: 'contentHash',
+                    nameHash: 'nameHash',
+                    encryptedName: 'encryptedName',
+                    nameSignatureEmail: 'test@example.com',
+                    nodePassphrase: 'passphrase',
+                    signatureEmail: 'test@example.com',
+                    nodePassphraseSignature: 'signature',
+                    relatedPhotos: [],
+                }, {
+                    nodeUid: 'volume1~signed',
+                    contentHash: 'contentHash',
+                    nameHash: 'nameHash',
+                    encryptedName: 'encryptedName',
+                    nameSignatureEmail: 'test@example.com',
+                    nodePassphrase: 'passphrase',
+                    relatedPhotos: [],
+                }],
+                errors: new Map(),
+            });
+        });
+    });
+});

package/src/internal/photos/photosTransferPayloadBuilder.ts

@@ -0,0 +1,203 @@
+import { c } from 'ttag';
+
+import { ValidationError } from '../../errors';
+import { DecryptedNodeKeys, NodeSigningKeys } from '../nodes/interface';
+import { AlbumsCryptoService } from './albumsCrypto';
+import { DecryptedPhotoNode } from './interface';
+import { PhotosNodesAccess } from './nodes';
+
+export type TransferEncryptedPhotoPayload = TransferEncryptedRelatedPhotoPayload & {
+    relatedPhotos: TransferEncryptedRelatedPhotoPayload[];
+};
+
+type TransferEncryptedRelatedPhotoPayload = {
+    nodeUid: string;
+    contentHash: string;
+    nameHash: string;
+    encryptedName: string;
+    nameSignatureEmail: string;
+    nodePassphrase: string;
+    nodePassphraseSignature?: string;
+    signatureEmail?: string;
+}
+
+/**
+ * Item representing a photo to build a payload for.
+ * Used when preparing payloads for add-to-album (with optional retry related UIDs)
+ * or for favoriting.
+ */
+export type PhotoPayloadItem = {
+    photoNodeUid: string;
+    /**
+     * Additional related photo node UIDs to include (e.g. when retrying after
+     * MissingRelatedPhotosError).
+     */
+    additionalRelatedPhotoNodeUids?: string[];
+};
+
+/**
+ * Builds encrypted photo payloads (TransferEncryptedPhotoPayload) for a set of
+ * photos, including their related photos. Reused by add-to-album and favorite
+ * flows, which only differ by the target keys used for encryption.
+ */
+export class PhotoTransferPayloadBuilder {
+    constructor(
+        private readonly cryptoService: AlbumsCryptoService,
+        private readonly nodesService: PhotosNodesAccess,
+    ) {}
+
+    /**
+     * Prepares encrypted payloads for the given photo items using the provided
+     * target keys and signing keys. Used for add-to-album (album keys) and
+     * favoriting (volume root keys).
+     */
+    async preparePhotoPayloads(
+        items: PhotoPayloadItem[],
+        targetNodeUid: string,
+        targetKeys: DecryptedNodeKeys,
+        signingKeys: NodeSigningKeys,
+        signal?: AbortSignal,
+    ): Promise<{
+        payloads: TransferEncryptedPhotoPayload[];
+        errors: Map<string, Error>;
+    }> {
+        const payloads: TransferEncryptedPhotoPayload[] = [];
+        const errors = new Map<string, Error>();
+
+        if (!targetKeys.hashKey) {
+            throw new Error('Target hash key is required to build photo payloads');
+        }
+
+        const additionalRelatedMap = new Map(
+            items.map((item) => [item.photoNodeUid, item.additionalRelatedPhotoNodeUids || []]),
+        );
+
+        const nodeUids = items.map((item) => item.photoNodeUid);
+        for await (const photoNode of this.nodesService.iterateNodes(nodeUids, signal)) {
+            if ('missingUid' in photoNode) {
+                errors.set(photoNode.missingUid, new ValidationError(c('Error').t`Photo not found`));
+                continue;
+            }
+
+            if (photoNode.parentUid === targetNodeUid) {
+                errors.set(photoNode.uid, new PhotoAlreadyInTargetError());
+                continue;
+            }
+
+            try {
+                const additionalRelated = additionalRelatedMap.get(photoNode.uid) || [];
+                const payload = await this.preparePhotoPayload(
+                    photoNode,
+                    additionalRelated,
+                    targetKeys,
+                    signingKeys,
+                    signal,
+                );
+                payloads.push(payload);
+            } catch (error) {
+                errors.set(
+                    photoNode.uid,
+                    error instanceof Error ? error : new Error(c('Error').t`Unknown error`, { cause: error }),
+                );
+            }
+        }
+
+        return { payloads, errors };
+    }
+
+    private async preparePhotoPayload(
+        photoNode: DecryptedPhotoNode,
+        additionalRelatedPhotoNodeUids: string[],
+        targetKeys: DecryptedNodeKeys,
+        signingKeys: NodeSigningKeys,
+        signal?: AbortSignal,
+    ): Promise<TransferEncryptedPhotoPayload> {
+        const photoData = await this.encryptPhotoForTarget(photoNode, targetKeys, signingKeys);
+
+        const relatedNodeUids = [
+            ...new Set([
+                ...(photoNode.photo?.relatedPhotoNodeUids || []),
+                ...additionalRelatedPhotoNodeUids,
+            ]),
+        ];
+
+        const relatedPhotos =
+            relatedNodeUids.length > 0
+                ? await this.prepareRelatedPhotoPayloads(relatedNodeUids, targetKeys, signingKeys, signal)
+                : [];
+
+        return {
+            ...photoData,
+            relatedPhotos,
+        };
+    }
+
+    private async prepareRelatedPhotoPayloads(
+        nodeUids: string[],
+        targetKeys: DecryptedNodeKeys,
+        signingKeys: NodeSigningKeys,
+        signal?: AbortSignal,
+    ): Promise<Omit<TransferEncryptedPhotoPayload, 'relatedPhotos'>[]> {
+        const payloads: Omit<TransferEncryptedPhotoPayload, 'relatedPhotos'>[] = [];
+
+        for await (const photoNode of this.nodesService.iterateNodes(nodeUids, signal)) {
+            if ('missingUid' in photoNode) {
+                continue;
+            }
+            const payload = await this.encryptPhotoForTarget(photoNode, targetKeys, signingKeys);
+            payloads.push(payload);
+        }
+
+        return payloads;
+    }
+
+    private async encryptPhotoForTarget(
+        photoNode: DecryptedPhotoNode,
+        targetKeys: DecryptedNodeKeys,
+        signingKeys: NodeSigningKeys,
+    ): Promise<Omit<TransferEncryptedPhotoPayload, 'relatedPhotos'>> {
+        const nodeKeys = await this.nodesService.getNodePrivateAndSessionKeys(photoNode.uid);
+
+        const contentSha1 = photoNode.activeRevision?.ok
+            ? photoNode.activeRevision.value.claimedDigests?.sha1
+            : undefined;
+
+        if (!contentSha1) {
+            throw new Error('Cannot build photo payload without a content hash');
+        }
+
+        const encryptedCrypto = await this.cryptoService.encryptPhotoForAlbum(
+            photoNode.name,
+            contentSha1,
+            nodeKeys,
+            { key: targetKeys.key, hashKey: targetKeys.hashKey! },
+            signingKeys,
+        );
+
+        const anonymousKey = photoNode.keyAuthor.ok && photoNode.keyAuthor.value === null;
+        const keySignatureProperties = !anonymousKey
+            ? {}
+            : {
+                  signatureEmail: encryptedCrypto.signatureEmail,
+                  nodePassphraseSignature: encryptedCrypto.armoredNodePassphraseSignature,
+              };
+
+        return {
+            nodeUid: photoNode.uid,
+            contentHash: encryptedCrypto.contentHash,
+            nameHash: encryptedCrypto.hash,
+            encryptedName: encryptedCrypto.encryptedName,
+            nameSignatureEmail: encryptedCrypto.nameSignatureEmail,
+            nodePassphrase: encryptedCrypto.armoredNodePassphrase,
+            ...keySignatureProperties,
+        };
+    }
+}
+
+export class PhotoAlreadyInTargetError extends ValidationError {
+    name = 'PhotoAlreadyInTargetError';
+
+    constructor() {
+        super(c('Error').t`Photo is already in the target album`);
+    }
+}

package/src/internal/photos/upload.ts

@@ -1,5 +1,5 @@
 import { DriveCrypto } from '../../crypto';
-import { ProtonDriveTelemetry, UploadMetadata, Thumbnail, AnonymousUser } from '../../interface';
+import { ProtonDriveTelemetry, UploadMetadata, Thumbnail, AnonymousUser, FeatureFlagProvider } from '../../interface';
 import { DriveAPIService, drivePaths } from '../apiService';
 import { generateFileExtendedAttributes } from '../nodes';
 import { splitNodeRevisionUid } from '../uids';
@@ -119,7 +119,12 @@ export class PhotoStreamUploader extends StreamUploader {
             digests,
         };
 
-        await this.photoUploadManager.commitDraftPhoto(this.revisionDraft, this.manifest, extendedAttributes, this.photoMetadata);
+        await this.photoUploadManager.commitDraftPhoto(
+            this.revisionDraft,
+            await this.getManifest(),
+            extendedAttributes,
+            this.photoMetadata,
+        );
     }
 }
 
@@ -157,7 +162,10 @@ export class PhotoUploadManager extends UploadManager {
         }
 
         // TODO: handle photo extended attributes in the SDK - now it must be passed from the client
-        const generatedExtendedAttributes = generateFileExtendedAttributes(extendedAttributes, uploadMetadata.additionalMetadata);
+        const generatedExtendedAttributes = generateFileExtendedAttributes(
+            extendedAttributes,
+            uploadMetadata.additionalMetadata,
+        );
         const nodeCommitCrypto = await this.cryptoService.commitFile(
             nodeRevisionDraft.nodeKeys,
             manifest,
@@ -165,13 +173,16 @@ export class PhotoUploadManager extends UploadManager {
         );
 
         const sha1 = extendedAttributes.digests.sha1;
-        const contentHash = await this.photoCryptoService.generateContentHash(sha1, nodeRevisionDraft.parentNodeKeys?.hashKey);
+        const contentHash = await this.photoCryptoService.generateContentHash(
+            sha1,
+            nodeRevisionDraft.parentNodeKeys?.hashKey,
+        );
         const photo = {
             contentHash,
-            captureTime: uploadMetadata.captureTime || extendedAttributes.modificationTime,
+            captureTime: uploadMetadata.captureTime || extendedAttributes.modificationTime,
             mainPhotoLinkID: uploadMetadata.mainPhotoLinkID,
             tags: uploadMetadata.tags,
-        }
+        };
         await this.photoApiService.commitDraftPhoto(nodeRevisionDraft.nodeRevisionUid, nodeCommitCrypto, photo);
         await this.notifyNodeUploaded(nodeRevisionDraft);
     }
@@ -179,10 +190,12 @@ export class PhotoUploadManager extends UploadManager {
 
 export class PhotoUploadCryptoService extends UploadCryptoService {
     constructor(
+        telemetry: ProtonDriveTelemetry,
         driveCrypto: DriveCrypto,
         nodesService: NodesService,
+        featureFlagProvider: FeatureFlagProvider,
     ) {
-        super(driveCrypto, nodesService);
+        super(telemetry, driveCrypto, nodesService, featureFlagProvider);
     }
 
     async generateContentHash(sha1: string, parentHashKey: Uint8Array<ArrayBuffer>): Promise<string> {

package/src/internal/sharingPublic/nodes.ts

@@ -86,12 +86,19 @@ export class SharingPublicNodesAPIService extends NodeAPIService {
         const nodeUid = makeNodeUid(volumeId, link.Link.LinkID);
         const encryptedNode = linkToEncryptedNode(this.logger, volumeId, link, isOwnVolumeId);
 
-        // TEMPORARY: Inject public permissions for the root node only.
-        // This ensures the root node has the correct directRole instead of
-        // incorrectly falling back to 'admin' due to null DirectPermissions.
-        // May be fixed by backend later.
+        // TODO: This affects the cache. At this moment, the public link is not cached
+        // anywhere, thus OK. To avoid issues when public links reuses the same cache,
+        // we need to move this either to the interface of given instance, or leave
+        // this as a responsibility to the client.
         if (this.publicRootNodeUid === nodeUid) {
+            // Inject public permissions for the root node only.
+            // This ensures the root node has the correct directRole instead of
+            // incorrectly falling back to 'admin' due to null DirectPermissions.
             encryptedNode.directRole = this.publicRole;
+            // This prevent to have parentUid in case user visited parent folder public link of a public link
+            // Since the session got permissions to get the parentNode,
+            // when visiting children it will return the parentLinkID in links request.
+            encryptedNode.parentUid = undefined;
         }
 
         return encryptedNode;