@protontech/drive-sdk 0.0.10

package/src/crypto/utils.ts

@@ -0,0 +1,40 @@
+// This file has copy-pasted utilities from CryptoProxy located in Proton web clients monorepo.
+
+export function uint8ArrayToBase64String(array: Uint8Array) {
+    return encodeBase64(arrayToBinaryString(array));
+}
+
+export function base64StringToUint8Array(string: string){
+    return binaryStringToArray(decodeBase64(string) || '');
+}
+
+const ifDefined =
+    <T, R>(cb: (input: T) => R) =>
+    <U extends T | undefined>(input: U) => {
+        return (input !== undefined ? cb(input as T) : undefined) as U extends T ? R : undefined;
+    };
+
+const encodeBase64 = ifDefined((input: string) => btoa(input).trim());
+
+const decodeBase64 = ifDefined((input: string) => atob(input.trim()));
+
+const arrayToBinaryString = (bytes: Uint8Array) => {
+    const result = [];
+    const bs = 1 << 14;
+    const j = bytes.length;
+
+    for (let i = 0; i < j; i += bs) {
+        // @ts-expect-error Uint8Array treated as number[]
+        // eslint-disable-next-line prefer-spread
+        result.push(String.fromCharCode.apply(String, bytes.subarray(i, i + bs < j ? i + bs : j)));
+    }
+    return result.join('');
+};
+
+const binaryStringToArray = (str: string) => {
+    const result = new Uint8Array(str.length);
+    for (let i = 0; i < str.length; i++) {
+        result[i] = str.charCodeAt(i);
+    }
+    return result;
+};

package/src/errors.ts

@@ -0,0 +1,168 @@
+import { c } from 'ttag';
+
+/**
+ * Base class for all SDK errors.
+ * 
+ * This class can be used for catching all SDK errors. The error should have
+ * translated message in the `message` property that should be shown to the
+ * user without any modification.
+ * 
+ * No retries should be done as that is already handled by the SDK.
+ * 
+ * When SDK throws an error and it is not `ProtonDriveError`, it is unhandled error
+ * by the SDK and usually indicates bug in the SDK. Please, report it.
+ */
+export class ProtonDriveError extends Error {
+    name = 'ProtonDriveError';
+}
+
+/**
+ * Error thrown when the operation is aborted.
+ * 
+ * This error is thrown when the operation is aborted by the user.
+ * For example, by calling `abort()` on the `AbortSignal`.
+ */
+export class AbortError extends ProtonDriveError {
+    name = 'AbortError';
+
+    constructor(message?: string) {
+        super(message || c('Error').t`Operation aborted`);
+    }
+}
+
+/**
+ * Error thrown when the validation fails.
+ * 
+ * This error is thrown when the validation of the input fails.
+ * Validation can be done on the client side or on the server side.
+ *
+ * For example, on the client, it can be thrown when the node name doesn't
+ * follow the required format, etc., while on the server side, it can be thrown
+ * when there is not enough permissions, etc.
+ */
+export class ValidationError extends ProtonDriveError {
+    name = 'ValidationError';
+
+    /**
+     * Internal API code.
+     * 
+     * Use only for debugging purposes.
+     */
+    public readonly code?: number;
+
+    constructor(message: string, code?: number) {
+        super(message);
+        this.code = code;
+    }
+}
+
+/**
+ * Error thrown when the node already exists.
+ * 
+ * This error is thrown when the node with the same name already exists in the
+ * parent folder. The client should ask the user to replace the existing node
+ * or choose another name. The available name is provided in the `availableName`
+ * property (that will contain original name with the index that can be used).
+ */
+export class NodeAlreadyExistsValidationError extends ValidationError {
+    name = 'NodeAlreadyExistsValidationError';
+
+    public readonly availableName: string;
+
+    constructor(message: string, code: number, availableName: string) {
+        super(message, code);
+        this.availableName = availableName;
+    }
+}
+
+/**
+ * Error thrown when the API call fails.
+ * 
+ * This error covers both HTTP errors and API errors. SDK automatically
+ * retries the request before the error is thrown. The sepcific algorithm
+ * used for retries depends on the type of the error.
+ * 
+ * Client should not retry the request when this error is thrown.
+ */
+export class ServerError extends ProtonDriveError {
+    name = 'ServerError';
+
+    /**
+     * HTTP status code of the response.
+     * 
+     * Use only for debugging purposes.
+     */
+    public readonly statusCode?: number;
+    /**
+     * Internal API code.
+     * 
+     * Use only for debugging purposes.
+     */
+    public readonly code?: number;
+}
+
+/**
+ * Error thrown when the client makes too many requests to the API.
+ * 
+ * SDK is configured to stay below the rate limits, but it can still happen if
+ * client is running multiple SDKs in parallel, or if the rate limits are
+ * changed on the server side.
+ * 
+ * SDK automatically retries the request before the error is thrown after
+ * waiting for the required time specified by the server.
+ * 
+ * Client should slow down calling SDK when this error is thrown.
+ * 
+ * You can be also notified about the rate limits by the `requestsThrottled`
+ * event. See `onMessage` method on the SDK class for more details.
+ */
+export class RateLimitedError extends ServerError {
+    name = 'RateLimitedError';
+
+    code = 429;
+}
+
+/**
+ * Error thrown when the client is not connected to the internet.
+ * 
+ * Client should check the internet connection when this error is thrown.
+ * 
+ * You can also be notified about the connection status by the `offline` event
+ * See `onMessage` method on the SDK class for more details.
+ */
+export class ConnectionError extends ProtonDriveError {
+    name = 'ConnectionError';
+}
+
+/**
+ * Error thrown when the decryption fails.
+ * 
+ * Client should report this error to the user and report bug report.
+ * 
+ * In most cases, there is no decryption error. Every decryption error should
+ * be not exposed but set as empty value on the node, for example. But in the
+ * case of the file content, if block cannot be decrypted, decryption error
+ * is thrown.
+ */
+export class DecryptionError extends ProtonDriveError {
+    name = 'DecryptionError';
+}
+
+/**
+ * Error thrown when the data integrity check fails.
+ * 
+ * Client should report this error to the user and report bug report.
+ * 
+ * For example, it can happen when hashes don't match, etc. In some cases,
+ * SDK allows to run command without verification checks for debug purposes.
+ */
+export class IntegrityError extends ProtonDriveError {
+    name = 'IntegrityError';
+
+    public readonly debug?: object;
+
+    constructor(message: string, debug?: object) {
+        super(message);
+        this.debug = debug;
+    }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Use only what is exported here. This is the public supported API of the SDK.
+ */
+
+import { makeNodeUid } from './internal/uids';
+
+export * from './interface';
+export * from './cache';
+export * from './errors';
+export type { OpenPGPCrypto, OpenPGPCryptoProxy } from './crypto';
+export { OpenPGPCryptoWithCryptoProxy } from './crypto';
+export { ProtonDriveClient } from './protonDriveClient';
+export { VERSION } from './version';
+
+/**
+ * Provides the node UID for the given raw volume and node IDs.
+ * 
+ * This is required only for the internal implementation to provide
+ * backward compatibility with the old Drive web setup.
+ * 
+ * If you are having share ID, use `ProtonDriveClient::getNodeUid` instead.
+ * 
+ * @deprecated This method is not part of the public API.
+ * @param volumeId - Volume of the node.
+ * @param nodeId - Node/link ID (not UID).
+ * @returns The node UID.
+ */
+export function generateNodeUid(volumeId: string, nodeId: string) {
+    return makeNodeUid(volumeId, nodeId);
+}

package/src/interface/account.ts

@@ -0,0 +1,38 @@
+import { PrivateKey, PublicKey } from '../crypto';
+
+export interface ProtonDriveAccount {
+    /**
+     * Get own primary address.
+     *
+     * @throws Error If there is no primary address.
+     */
+    getOwnPrimaryAddress(): Promise<ProtonDriveAccountAddress>,
+    /**
+     * Get own address by email or addressId.
+     *
+     * @throws Error If there is no address with given email or addressId.
+     */
+    getOwnAddress(emailOrAddressId: string): Promise<ProtonDriveAccountAddress>,
+    /**
+     * Returns whether given email can be used to share files with Proton Drive.
+     */
+    hasProtonAccount(email: string): Promise<boolean>,
+    /**
+     * Get public keys for given email.
+     *
+     * Does not throw if there is no public key for given email, but returns empty array.
+     *
+     * @throws Error Only if there is an error while fetching keys.
+     */
+    getPublicKeys(email: string): Promise<PublicKey[]>,
+}
+
+export interface ProtonDriveAccountAddress {
+    email: string,
+    addressId: string,
+    primaryKeyIndex: number,
+    keys: {
+        id: string,
+        key: PrivateKey,
+    }[],
+}

package/src/interface/author.ts

@@ -0,0 +1,29 @@
+import { Result } from './result';
+
+/**
+ * Author with verification status.
+ * 
+ * It can be either a string (email) or an anonymous user.
+ * 
+ * If author cannot be verified, the result is failure with an error.
+ * The client can still get claimed author from the error object, but
+ * it must be used with caution.
+ */
+export type Author = Result<string | AnonymousUser, UnverifiedAuthorError>;
+
+/**
+ * Anonymous user. Used when user shares folder publicly and anonymous
+ * users can access the folder and upload new files without being logged in.
+ */
+export type AnonymousUser = null;
+
+/**
+ * Unverified author.
+ * 
+ * If author cannot be verified, the result is this object containing
+ * the claimed author and the verification error.
+ */
+export type UnverifiedAuthorError = {
+    claimedAuthor?: string,
+    error: string,
+}

package/src/interface/devices.ts

@@ -0,0 +1,21 @@
+import { Result } from './result';
+import { InvalidNameError } from './nodes';
+
+export type Device = {
+    uid: string,
+    type: DeviceType,
+    name: Result<string, Error | InvalidNameError>,
+    rootFolderUid: string,
+    creationTime: Date,
+    lastSyncDate?: Date;
+    /** @deprecated to be removed once Volume-based navigation is implemented in web */
+    shareId: string;
+}
+
+export enum DeviceType {
+    Windows = 'Windows',
+    MacOS = 'MacOS',
+    Linux = 'Linux',
+}
+
+export type DeviceOrUid = Device | string;

package/src/interface/download.ts

@@ -0,0 +1,32 @@
+export interface FileDownloader {
+    /**
+     * Get the claimed size of the file in bytes.
+     * 
+     * This provides total clear-text size of the file. This is encrypted
+     * information that is not known to the Proton Drive and thus it is
+     * explicitely stated as claimed only and must be treated that way.
+     * It can be wrong or missing completely.
+     */
+    getClaimedSizeInBytes(): number | undefined,
+
+    /**
+     * Download, decrypt and verify the content from the server and write
+     * to the provided stream.
+     * 
+     * @param onProgress - Callback that is called with the number of downloaded bytes
+     */
+    writeToStream(streamFactory: WritableStream, onProgress: (downloadedBytes: number) => void): DownloadController,
+
+    /**
+     * Same as `writeToStream` but without verification checks.
+     * 
+     * Use this only for debugging purposes.
+     */
+    unsafeWriteToStream(streamFactory: WritableStream, onProgress: (downloadedBytes: number) => void): DownloadController,
+}
+
+export interface DownloadController {
+    pause(): void,
+    resume(): void,
+    completion(): Promise<void>,
+}

package/src/interface/events.ts

@@ -0,0 +1,30 @@
+import { Device } from './devices';
+import { MaybeNode } from './nodes';
+
+export type DeviceEventCallback = (deviceEvent: DeviceEvent) => void;
+export type NodeEventCallback = (nodeEvent: NodeEvent) => void;
+
+export type NodeEvent = {
+    type: 'update',
+    uid: string,
+    node: MaybeNode,
+} | {
+    type: 'remove',
+    uid: string,
+}
+
+export type DeviceEvent = {
+    type: 'update',
+    uid: string,
+    device: Device,
+} | {
+    type: 'remove',
+    uid: string,
+}
+
+export enum SDKEvent {
+    TransfersPaused = "transfersPaused",
+    TransfersResumed = "transfersResumed",
+    RequestsThrottled = "requestsThrottled",
+    RequestsUnthrottled = "requestsUnthrottled",
+}

package/src/interface/httpClient.ts

@@ -0,0 +1,42 @@
+export interface ProtonDriveHTTPClient {
+    fetchJson(options: ProtonDriveHTTPClientJsonOptions): Promise<Response>;
+    fetchBlob(options: ProtonDriveHTTPClientBlobOptions): Promise<Response>;
+}
+
+export type ProtonDriveHTTPClientJsonOptions = ProtonDriveHTTPClientBaseOptions & {
+    json?: object,
+}
+
+export type ProtonDriveHTTPClientBlobOptions = ProtonDriveHTTPClientBaseOptions & {
+    body?: XMLHttpRequestBodyInit,
+    onProgress?: (progress: number) => void,
+}
+
+type ProtonDriveHTTPClientBaseOptions = {
+    url: string,
+    method: string,
+    headers: Headers,
+    /**
+     * The timeout in milliseconds.
+     *
+     * When timeout is reached, the request will be aborted with TimeoutError.
+     */
+    timeoutMs: number,
+    signal?: AbortSignal,
+}
+
+export type ProtonDriveConfig = {
+    /**
+     * The base URL for the Proton Drive (without schema).
+     *
+     * If not provided, defaults to 'drive-api.proton.me'.
+     */
+    baseUrl?: string,
+
+    /**
+     * The language to use for error messages.
+     *
+     * If not provided, defaults to 'en'.
+     */
+    language?: string,
+}

package/src/interface/index.ts

@@ -0,0 +1,46 @@
+import { ProtonDriveCache } from '../cache';
+import { OpenPGPCrypto, PrivateKey, SessionKey, SRPModule } from '../crypto';
+import { ProtonDriveAccount } from './account';
+import { ProtonDriveHTTPClient, ProtonDriveConfig } from './httpClient';
+import { Telemetry, MetricEvent } from './telemetry';
+
+export type { Result } from './result';
+export { resultOk, resultError } from './result';
+export type { ProtonDriveAccount, ProtonDriveAccountAddress } from './account';
+export type { Author, UnverifiedAuthorError, AnonymousUser } from './author';
+export type { Device, DeviceOrUid } from './devices';
+export { DeviceType } from './devices';
+export type { FileDownloader, DownloadController } from './download';
+export type { NodeEvent, DeviceEvent, DeviceEventCallback, NodeEventCallback } from './events';
+export { SDKEvent } from './events';
+export type { ProtonDriveHTTPClient, ProtonDriveHTTPClientJsonOptions, ProtonDriveHTTPClientBlobOptions, ProtonDriveConfig } from './httpClient';
+export type { MaybeNode, NodeEntity, DegradedNode, MaybeMissingNode, MissingNode, InvalidNameError, Revision, NodeOrUid, RevisionOrUid, NodeResult } from './nodes';
+export { NodeType, MemberRole, RevisionState } from './nodes';
+export type { ProtonInvitation, ProtonInvitationWithNode, NonProtonInvitation, Member, PublicLink, Bookmark, ProtonInvitationOrUid, NonProtonInvitationOrUid, BookmarkOrUid, ShareNodeSettings, UnshareNodeSettings, ShareMembersSettings, SharePublicLinkSettings, SharePublicLinkSettingsObject, ShareResult } from './sharing';
+export { NonProtonInvitationState } from './sharing';
+export type { Telemetry, Logger, MetricAPIRetrySucceededEvent, MetricUploadEvent, MetricsUploadErrorType, MetricDownloadEvent, MetricsDownloadErrorType, MetricDecryptionErrorEvent, MetricsDecryptionErrorField, MetricVerificationErrorEvent, MetricVerificationErrorField, MetricVolumeEventsSubscriptionsChangedEvent, MetricEvent } from './telemetry';
+export { MetricContext } from './telemetry';
+export type { Fileuploader, UploadController, UploadMetadata } from './upload';
+export type { Thumbnail, ThumbnailResult } from './thumbnail';
+export { ThumbnailType } from './thumbnail';
+
+export type ProtonDriveTelemetry = Telemetry<MetricEvent>;
+export type ProtonDriveEntitiesCache = ProtonDriveCache<string>;
+export type ProtonDriveCryptoCache = ProtonDriveCache<CachedCryptoMaterial>;
+export type CachedCryptoMaterial = {
+    passphrase?: string,
+    key: PrivateKey,
+    passphraseSessionKey: SessionKey,
+    hashKey?: Uint8Array,
+};
+
+export interface ProtonDriveClientContructorParameters {
+    httpClient: ProtonDriveHTTPClient,
+    entitiesCache: ProtonDriveEntitiesCache,
+    cryptoCache: ProtonDriveCryptoCache,
+    account: ProtonDriveAccount,
+    openPGPCryptoModule: OpenPGPCrypto,
+    srpModule: SRPModule,
+    config?: ProtonDriveConfig,
+    telemetry?: ProtonDriveTelemetry,
+};

package/src/interface/nodes.ts

@@ -0,0 +1,168 @@
+import { Result } from './result';
+import { Author } from './author';
+
+/**
+ * Node representing a file or folder in the system.
+ * 
+ * This covers both happy path and degraded path. It is used in the SDK to
+ * represent the node in a way that is easy to work with. Whenever any field
+ * cannot be decrypted, it is returned as `DegradedNode` type.
+ */
+export type MaybeNode = Result<NodeEntity, DegradedNode>;
+
+/**
+ * Node representing a file or folder in the system, or missing node.
+ * 
+ * In most cases, SDK returns `MaybeNode`, but in some specific cases, when
+ * client is requesting specific nodes, SDK must return `MissingNode` type
+ * to indicate the case when the node is not available. That can be when
+ * the node does not exist, or when the node is not available for the user
+ * (e.g. unshared with the user).
+ */
+export type MaybeMissingNode = Result<NodeEntity, DegradedNode | MissingNode>;
+
+export type MissingNode = {
+    missingUid: string,
+};
+
+/**
+ * Node representing a file or folder in the system.
+ * 
+ * This is a happy path representation of the node. It is used in the SDK to
+ * represent the node in a way that is easy to work with. Whenever any field
+ * cannot be decrypted, it is returned as `DegradedNode` type.
+ * 
+ * SDK never returns this entity directly but wrapped in `MaybeNode`.
+ *
+ * Note on naming: Node is reserved by JS/DOM, thus we need exception how the
+ * entity is called.
+ */
+export type NodeEntity = {
+    uid: string,
+    parentUid?: string,
+    name: string,
+    /**
+     * Author of the node key.
+     * 
+     * Person who created the node and keys for it. If user A uploads the file
+     * and user B renames the file and uploads new revision, name and content
+     * author is user B, while key author stays to user A who has forever
+     * option to decrypt latest versions.
+     */
+    keyAuthor: Author,
+    /**
+     * Author of the name.
+     * 
+     * Person who named the file. If user A uploads the file and user B renames
+     * the file, key and content author is user A, while name author is user B.
+     */
+    nameAuthor: Author,
+    directMemberRole: MemberRole,
+    type: NodeType,
+    mediaType?: string,
+    /**
+     * Whether the node is shared. If true, the node is shared with at least
+     * one user, or via public link.
+     */
+    isShared: boolean,
+    /**
+     * Created on server date.
+     */
+    creationTime: Date,
+    trashTime?: Date,
+    /**
+     * Total size of all revisions, encrypted size on the server.
+     */
+    totalStorageSize?: number,
+    activeRevision?: Revision,
+    folder?: {
+        claimedModificationTime?: Date,
+    },
+}
+
+/**
+ * Degraded node representing a file or folder in the system.
+ * 
+ * This is a degraded path representation of the node. It is used in the SDK to
+ * represent the node in a way that is easy to work with. Whenever any field
+ * cannot be decrypted, it is returned as `DegradedNode` type.
+ * 
+ * SDK never returns this entity directly but wrapped in `MaybeNode`.
+ * 
+ * The node can be still used around, but it is not guaranteed that all
+ * properties are decrypted, or that all actions can be performed on it.
+ * 
+ * For example, if the node has issue decrypting the name, the name will be
+ * set as `Error` and potentially rename or move actions will not be
+ * possible, but download and upload new revision will still work.
+ */
+export type DegradedNode = Omit<NodeEntity, 'name' | 'activeRevision'> & {
+    name: Result<string, Error | InvalidNameError>,
+    activeRevision?: Result<Revision, Error>,
+    /**
+     * If the error is not related to any specific field, it is set here.
+     * 
+     * For example, if the node has issue decrypting the name, the name will be
+     * set as `Error` while this will be empty.
+     * 
+     * On the other hand, if the node has issue decrypting the node key, but
+     * the name is still working, this will include the node key error, while
+     * the name will be set to the decrypted value.
+     */
+    errors?: unknown[],
+}
+
+/**
+ * Invalid name error represents node name that includes invalid characters.
+ */
+export type InvalidNameError = {
+    /**
+     * Placeholder instead of node name that client can use to display.
+     */
+    name: string,
+    error: string,
+}
+
+export enum NodeType {
+    File = "file",
+    Folder = "folder",
+}
+
+export enum MemberRole {
+    Viewer = "viewer",
+    Editor = "editor",
+    Admin = "admin",
+    Inherited = "inherited",
+}
+
+export type Revision = {
+    uid: string,
+    state: RevisionState,
+    creationTime: Date, // created on server date
+    contentAuthor: Author,
+    /**
+     * Encrypted size of the revision, as stored on the server.
+     */
+    storageSize: number,
+    /**
+     * Raw size of the revision, as stored in extended attributes.
+     */
+    claimedSize?: number,
+    claimedModificationTime?: Date,
+    claimedDigests?: {
+        sha1?: string,
+    },
+    claimedAdditionalMetadata?: object,
+}
+
+export enum RevisionState {
+    Active = "active",
+    Superseded = "superseded",
+}
+
+export type NodeOrUid = MaybeNode | NodeEntity | DegradedNode | string;
+export type RevisionOrUid = Revision | string;
+
+export type NodeResult =
+    {uid: string, ok: true} |
+    {uid: string, ok: false, error: string};

package/src/interface/result.ts

@@ -0,0 +1,11 @@
+export type Result<T, E> =
+| { ok: true; value: T }
+| { ok: false; error: E };
+
+export function resultOk<T, E>(value: T): Result<T, E> {
+    return { ok: true, value };
+}
+
+export function resultError<T, E>(error: E): Result<T, E> {
+    return { ok: false, error };
+}