@binsky/passman-client-ts 0.1.10 → 0.2.0

package/README.md

@@ -7,3 +7,15 @@ A TypeScript based Passman client library
 
 ---
 
+## Notes about PassmanClient initialization workflow and caching
+
+- Create a PassmanClient instance as data and api (connection) manager to the Passman server part.
+  - providing a PersistenceInterface instance like an overwritten instance of DefaultPersistenceService, allows you to configure PassmanClient internal data reconstruction based on the persistence service (configuration)
+- Preload the available vaults using `passmanClient.preloadVaults()` and use them to create a vault list and to authenticate the users vault password against.
+  - preloaded vaults only contain some metadata without modification options or credentials
+- Call `preloadedVault.testVaultKey('myPassword123')` for one of the preloaded vaults in `passmanClient.preloadedVaults`
+- If the vault key got validated, you can load the full vault including its credentials, calling `Vault.fetchFullVaultFromServer(...)`
+
+Vault cache reconstruction is currently solved by specialized request caching. This also contains the owned, encrypted credential data.
+
+Credential decrypted data will be cached by providing a custom DecryptedDataCachingHandlerInterface implementation.

package/lib/Interfaces/Credential/{CredentialInterface.d.ts → DecryptedCredentialInterface.d.ts}

@@ -3,7 +3,11 @@ import { TagInterface } from "./TagInterface";
 import { IconInterface } from "./IconInterface";
 import { FileInterface } from "../File/FileInterface";
 import { OTPConfigInterface } from "./OTPConfigInterface";
-export interface CredentialInterface {
+/**
+ * Credential interface type of decrypted credential data, as well as more complex field types like files: FileInterface[].
+ * Useful for credential object based in-memory decrypted data cache.
+ */
+export interface DecryptedCredentialInterface {
     credential_id?: number;
     guid?: string;
     user_id: string;

package/lib/Interfaces/Credential/EncryptedCredentialInterface.d.ts

@@ -1,22 +1,23 @@
 import { IconInterface } from "./IconInterface";
 import { ACLInterface } from "../ShareService/ACLInterface";
+import { EncryptedStringType } from "../PassmanCrypto/EncryptedStringType";
 export interface EncryptedCredentialInterface {
     credential_id?: number;
     guid?: string;
     user_id: string;
     vault_id: number;
     label: string;
-    description: string;
-    tags: string;
-    email: string;
-    username: string;
-    password: string;
-    url: string;
-    files: string;
-    custom_fields: string;
-    otp: string;
-    compromised: string;
-    shared_key: string | null;
+    description: EncryptedStringType;
+    tags: EncryptedStringType;
+    email: EncryptedStringType;
+    username: EncryptedStringType;
+    password: EncryptedStringType;
+    url: EncryptedStringType;
+    files: EncryptedStringType;
+    custom_fields: EncryptedStringType;
+    otp: EncryptedStringType;
+    compromised: EncryptedStringType;
+    shared_key: EncryptedStringType | null;
     favicon: string;
     icon: IconInterface | null;
     renew_interval: number | null;

package/lib/Interfaces/Credential/EncryptedOwnedCredentialFromServerInterface.d.ts

@@ -0,0 +1,35 @@
+import { IconInterface } from "./IconInterface";
+import { EncryptedStringType } from "../PassmanCrypto/EncryptedStringType";
+/**
+ * Response type of the PATCH, POST and DELETE /api/v2/credentials/{credentialGuid} api, even for simply owned, owned but shared with others and credentials shared with us.
+ */
+export interface EncryptedOwnedCredentialFromServerInterface {
+    credential_id: number;
+    guid: string;
+    user_id: string;
+    vault_id: number;
+    label: string;
+    description: EncryptedStringType;
+    tags: EncryptedStringType;
+    email: EncryptedStringType;
+    username: EncryptedStringType;
+    password: EncryptedStringType;
+    url: EncryptedStringType;
+    files: EncryptedStringType;
+    custom_fields: EncryptedStringType;
+    otp: EncryptedStringType;
+    compromised: EncryptedStringType;
+    shared_key: EncryptedStringType | null;
+    /**
+     * old, does this field still exist?
+     * @deprecated
+     */
+    favicon: string;
+    icon: IconInterface | null;
+    renew_interval: number | null;
+    expire_time: number;
+    delete_time: number;
+    hidden: boolean;
+    created: number;
+    changed: number;
+}

package/lib/Interfaces/Credential/EncryptedOwnedCredentialFromServerInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/Interfaces/Credential/EncryptedOwnedCredentialToUpdateForServerInterface.d.ts

@@ -0,0 +1,8 @@
+import { ACLInterface } from "../ShareService/ACLInterface";
+import { EncryptedOwnedCredentialFromServerInterface } from "./EncryptedOwnedCredentialFromServerInterface";
+export type SpacialCredentialFieldsToUpdateForServerInterface = {
+    set_share_key: boolean | null;
+    skip_revision: boolean | null;
+    acl?: ACLInterface;
+};
+export type EncryptedOwnedCredentialToUpdateForServerInterface = EncryptedOwnedCredentialFromServerInterface & SpacialCredentialFieldsToUpdateForServerInterface;

package/lib/Interfaces/Credential/EncryptedOwnedCredentialToUpdateForServerInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/Interfaces/Credential/SerializableTransferCredentialInterface.d.ts

@@ -0,0 +1,7 @@
+import { EncryptedOwnedCredentialFromServerInterface } from "./EncryptedOwnedCredentialFromServerInterface";
+import { SerializableACLInterface } from "../ShareService/SerializableACLInterface";
+export interface SerializableTransferCredentialInterface {
+    encryptedData: EncryptedOwnedCredentialFromServerInterface;
+    encryptedSharedCredentialEncryptionKey?: string;
+    acl?: SerializableACLInterface;
+}

package/lib/Interfaces/Credential/SerializableTransferCredentialInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/Interfaces/DecryptedDataCachingHandlerInterface.d.ts

@@ -0,0 +1,20 @@
+export interface DecryptedDataCachingHandlerInterface {
+    /**
+     * Setting value as undefined equals deleting the key-value pair from that cache.
+     * @param cacheName unique cache name (the uniqueness is important to prevent unwanted data exchange between the cache entries)
+     * @param key
+     * @param value
+     */
+    set(cacheName: string, key: string, value: string | number | boolean | null | undefined): Promise<void>;
+    /**
+     * Returns undefined is no value is stored for the given key.
+     * @param cacheName unique cache name (the uniqueness is important to prevent unwanted data exchange between the cache entries)
+     * @param key
+     */
+    get(cacheName: string, key: string): Promise<string | number | boolean | null | undefined>;
+    /**
+     * Clear all data stored in the cache with the given name.
+     * @param cacheName
+     */
+    clearCacheByName(cacheName: string): Promise<void>;
+}

package/lib/Interfaces/DecryptedDataCachingHandlerInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/Interfaces/NextcloudServer/NextcloudServerInterface.d.ts

@@ -1,12 +1,17 @@
 import { LoggingHandlerInterface } from "../LoggingHandlerInterface";
+import { PersistenceInterface } from "../PersistenceInterface";
 export interface NextcloudServerInterface {
     logger: LoggingHandlerInterface;
+    /**
+     * Easy way to pass the available cache handlers into the vaults and credentials-
+     */
+    persistence: PersistenceInterface;
     getBaseUrl(): string;
-    setBaseUrl(value: string): string;
+    setBaseUrl(value: string): void;
     getUser(): string;
-    setUser(value: string): string;
+    setUser(value: string): void;
     getToken(): string;
-    setToken(value: string): string;
+    setToken(value: string): void;
     getApiUrl(): string;
     getJson<T>(endpoint: string, errorCallback: (response: Error) => void, getCachedIfPossible?: boolean): Promise<T | void>;
     deleteJson<T>(endpoint: string, errorCallback: (response: Error) => void): Promise<T | void>;

package/lib/Interfaces/PassmanCrypto/EncryptedStringType.d.ts

@@ -0,0 +1,4 @@
+/**
+ * A base64 encoded string of a Passman SJCL encryption (v1).
+ */
+export type EncryptedStringType = string;

package/lib/Interfaces/PassmanCrypto/EncryptedStringType.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/Interfaces/PersistenceInterface.d.ts

@@ -0,0 +1,10 @@
+import { RequestCachingHandlerInterface } from "./RequestCachingHandlerInterface";
+import { DecryptedDataCachingHandlerInterface } from "./DecryptedDataCachingHandlerInterface";
+export interface PersistenceInterface {
+    /**
+     * Configures whether to auto-restore "all" internal PassmanClient data on constructing PassmanClient.
+     */
+    autoRestoreOnReconstruction(): boolean;
+    getRequestCacheHandler(): RequestCachingHandlerInterface | undefined;
+    getDecryptedDataCacheHandler(): DecryptedDataCachingHandlerInterface | undefined;
+}

package/lib/Interfaces/PersistenceInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/Interfaces/RequestCachingHandlerInterface.d.ts

@@ -1,4 +1,8 @@
 export interface RequestCachingHandlerInterface {
     set(key: string, value: string): Promise<void>;
-    get(key: string): Promise<string>;
+    /**
+     * Returns undefined if this is the value of if no value was defined for the given key.
+     * @param key
+     */
+    get(key: string): Promise<string | undefined>;
 }

package/lib/Interfaces/Revision/RevisionInterface.d.ts

@@ -1,8 +1,8 @@
-import { EncryptedCredentialInterface } from "../Credential/EncryptedCredentialInterface";
+import { EncryptedOwnedCredentialFromServerInterface } from "../Credential/EncryptedOwnedCredentialFromServerInterface";
 export interface RevisionInterface {
     revision_id: number;
     guid: string;
     created: number;
-    credential_data: EncryptedCredentialInterface;
+    credential_data: EncryptedOwnedCredentialFromServerInterface;
     edited_by: string;
 }

package/lib/Interfaces/ShareService/CredentialShareRequestInterface.d.ts

@@ -1,4 +1,4 @@
-import { EncryptedCredentialInterface } from "../Credential/EncryptedCredentialInterface";
+import { EncryptedOwnedCredentialFromServerInterface } from "../Credential/EncryptedOwnedCredentialFromServerInterface";
 export interface CredentialShareRequestInterface {
     acl_id: number;
     item_id: number;
@@ -12,5 +12,5 @@ export interface CredentialShareRequestInterface {
     vault_guid: string;
     shared_key: string;
     pending: boolean;
-    credential_data?: EncryptedCredentialInterface;
+    credential_data?: EncryptedOwnedCredentialFromServerInterface;
 }

package/lib/Interfaces/ShareService/SerializableACLInterface.d.ts

@@ -0,0 +1,14 @@
+export interface SerializableACLInterface {
+    acl_id: number;
+    item_id: number;
+    item_guid: string;
+    user_id: string;
+    created: number;
+    expire: number;
+    expire_views: number;
+    permission: number;
+    vault_id: number;
+    vault_guid: string;
+    shared_key: string;
+    pending: boolean;
+}

package/lib/Interfaces/ShareService/SerializableACLInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/Interfaces/Vault/GenericVaultInformationFromServerInterface.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A single vault response object of api/v2/vaults since it returns an array
+ */
+export interface GenericVaultInformationFromServerInterface {
+    vault_id: number;
+    guid: string;
+    name: string;
+    created: number;
+    public_sharing_key: string | null;
+    last_access: number;
+    challenge_password: string;
+    delete_request_pending: boolean;
+}
+/**
+ * Response of GET api/v2/vaults
+ */
+export type VaultsGetResponseFromServer = GenericVaultInformationFromServerInterface[];

package/lib/Interfaces/Vault/GenericVaultInformationFromServerInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/Interfaces/Vault/SerializableSpecificVaultInformationFromServerInterface.d.ts

@@ -0,0 +1,12 @@
+import { GenericVaultInformationFromServerInterface } from "./GenericVaultInformationFromServerInterface";
+/**
+ * The vault response object of GET api/v2/vaults/{guid}
+ */
+export type SerializableSpecificVaultInformationFromServerInterface = GenericVaultInformationFromServerInterface & {
+    public_sharing_key: string;
+    private_sharing_key: string;
+    sharing_keys_generated: number;
+    last_access: number;
+    delete_request_pending: boolean;
+    vault_settings: null;
+};

package/lib/Interfaces/Vault/SerializableSpecificVaultInformationFromServerInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/Interfaces/Vault/SerializableTransferFullVaultInterface.d.ts

@@ -0,0 +1,6 @@
+import { SerializableTransferCredentialInterface } from "../Credential/SerializableTransferCredentialInterface";
+import { SerializableSpecificVaultInformationFromServerInterface } from "./SerializableSpecificVaultInformationFromServerInterface";
+export interface SerializableTransferFullVaultInterface {
+    serializableSpecificVaultInformation: SerializableSpecificVaultInformationFromServerInterface;
+    encryptedSerializableCredentials: SerializableTransferCredentialInterface[];
+}

package/lib/Interfaces/Vault/SerializableTransferFullVaultInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/Interfaces/Vault/SpecificVaultInformationFromServerInterface.d.ts

@@ -0,0 +1,14 @@
+import { GenericVaultInformationFromServerInterface } from "./GenericVaultInformationFromServerInterface";
+import { EncryptedOwnedCredentialFromServerInterface } from "../Credential/EncryptedOwnedCredentialFromServerInterface";
+/**
+ * The vault response object of GET api/v2/vaults/{guid}
+ */
+export type SpecificVaultInformationFromServerInterface = GenericVaultInformationFromServerInterface & {
+    public_sharing_key: string;
+    private_sharing_key: string;
+    sharing_keys_generated: number;
+    last_access: number;
+    delete_request_pending: boolean;
+    vault_settings: null;
+    credentials: EncryptedOwnedCredentialFromServerInterface[];
+};

package/lib/Interfaces/Vault/SpecificVaultInformationFromServerInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/Interfaces/Vault/VaultCreateServerResponseInterface.d.ts

@@ -0,0 +1,8 @@
+export interface VaultCreateServerResponseInterface {
+    vault_id: number;
+    guid: string;
+    name: string;
+    created: number;
+    public_sharing_key: null;
+    last_access: number;
+}

package/lib/Interfaces/Vault/VaultCreateServerResponseInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/Model/Credential.d.ts

@@ -1,7 +1,6 @@
 import { NextcloudServerInterface } from "../Interfaces/NextcloudServer/NextcloudServerInterface";
 import Vault from "./Vault";
-import { CredentialInterface } from "../Interfaces/Credential/CredentialInterface";
-import { EncryptedCredentialInterface } from "../Interfaces/Credential/EncryptedCredentialInterface";
+import { DecryptedCredentialInterface } from "../Interfaces/Credential/DecryptedCredentialInterface";
 import { CustomFieldInterface } from "../Interfaces/Credential/CustomFieldInterface";
 import { TagInterface } from "../Interfaces/Credential/TagInterface";
 import { IconInterface } from "../Interfaces/Credential/IconInterface";
@@ -10,44 +9,86 @@ import { FileUploadResponseInterface } from "../Interfaces/File/FileUploadRespon
 import { RevisionInterface } from "../Interfaces/Revision/RevisionInterface";
 import { OTPConfigInterface } from "../Interfaces/Credential/OTPConfigInterface";
 import { ACLInterface } from "../Interfaces/ShareService/ACLInterface";
+import { EncryptedOwnedCredentialFromServerInterface } from "../Interfaces/Credential/EncryptedOwnedCredentialFromServerInterface";
+import { SpacialCredentialFieldsToUpdateForServerInterface } from "../Interfaces/Credential/EncryptedOwnedCredentialToUpdateForServerInterface";
+import { SerializableTransferCredentialInterface } from "../Interfaces/Credential/SerializableTransferCredentialInterface";
 export default class Credential {
     protected vault: Vault;
     protected server: NextcloudServerInterface;
     ENCRYPTED_FIELDS: string[];
-    protected encryptedData: EncryptedCredentialInterface;
+    /**
+     * Contains all ENCRYPTED_FIELDS that matches to one of the types: string|number|boolean|null
+     */
+    SERIALIZABLE_ENCRYPTED_FIELDS: string[];
+    /**
+     * encryptedData & spacialServerUpdateFields needs to be merged in order to save to credential to the server (api)
+     * @protected
+     */
+    protected encryptedData: EncryptedOwnedCredentialFromServerInterface;
+    /**
+     * Should not be overwritten/cleared during Credential instance lifetime, since it contains acl data managed by ShareService.
+     * @protected
+     */
+    protected _spacialServerUpdateFields: SpacialCredentialFieldsToUpdateForServerInterface;
+    /**
+     * This is always set if the credential is shared with us.
+     *
+     * The sharedCredentialEncryptionKey is encrypted with the vault key and injected by ShareService.
+     * To be able to hold this credential instance in an (initial, fully) unencrypted state (needed to fetch the full vault without vault key given),
+     * we need to split the encrypted and unencrypted shared credential encryption keys.
+     */
+    encryptedSharedCredentialEncryptionKey?: string;
+    private sharedCredentialEncryptionKey?;
     private decryptedDataCache;
-    sharedCredentialEncryptionKey: string;
     private foundUnspecifiedEncryptionError;
+    private readonly decryptedDataCacheName;
     overwriteVaultKey: string | undefined;
-    constructor(vault: Vault, server: NextcloudServerInterface, encryptedData?: EncryptedCredentialInterface);
+    constructor(vault: Vault, server: NextcloudServerInterface, encryptedData?: EncryptedOwnedCredentialFromServerInterface);
     private initializeAllFields;
     /**
      * Save new credential on the server.
      * The current credential object will be updated with the server response data if possible.
      */
-    save(): Promise<void | EncryptedCredentialInterface>;
+    save(): Promise<void | EncryptedOwnedCredentialFromServerInterface>;
     /**
      * Update / edit an existing credential on the server.
      * The current credential object will be updated with the server response data if possible.
+     * This will not touch the virtual acl field.
      */
-    update(): Promise<void | EncryptedCredentialInterface>;
+    update(): Promise<void | EncryptedOwnedCredentialFromServerInterface>;
     /**
      * Refresh the local credential data based on the server, using the credentials guid.
-     * It is not supported to do that for credentials, shared with us.
+     * It is not supported to do that for credentials, shared with us. (Therefore this will not touch the virtual acl field.)
      */
-    refresh(): Promise<void | EncryptedCredentialInterface>;
+    refresh(): Promise<void | EncryptedOwnedCredentialFromServerInterface>;
     /**
      * Destroys the credential on the server and removes itself from its local vault.
      */
-    destroy(): Promise<void | EncryptedCredentialInterface>;
-    clearDecryptedDataCache(): void;
+    destroy(): Promise<void | EncryptedOwnedCredentialFromServerInterface>;
+    /**
+     * This is the correct function to "lock" the credential (to be called subsequently when the vault got locked).
+     * It clears the decrypted credential data cache as well as a potential sharedCredentialEncryptionKey.
+     * This will not clear the serialized decrypted data cache, managed by the used DecryptedDataCachingHandlerInterface implementation.
+     * Set clearCachingHandlerManagedDecryptedData=true to do so (by calling getDecryptedDataCacheHandler().clearCacheByName('...'))
+     */
+    clearDecryptedDataCache(clearCachingHandlerManagedDecryptedData?: boolean): void;
+    /**
+     * Restore only serializable fields of the CredentialInterface.
+     */
+    restoreSerializedDecryptedDataCache(): Promise<void>;
+    /**
+     * Update or delete an entry in the decrypted data cache.
+     * @param propertyName
+     * @param deleteFromCache
+     */
+    private updateSerializedDecryptedDataCacheEntry;
     /**
      * Create a credential object based on its encrypted data.
      * @param data
      * @param vault
      * @param server
      */
-    static fromData(data: EncryptedCredentialInterface, vault: Vault, server: NextcloudServerInterface): Promise<Credential>;
+    static fromData(data: EncryptedOwnedCredentialFromServerInterface, vault: Vault, server: NextcloudServerInterface): Credential;
     /**
      * Create a credential object based on its guid. This will fetch the current credential data from the server.
      * @param guid
@@ -55,16 +96,17 @@ export default class Credential {
      * @param server
      */
     static fromGuid(guid: string, vault: Vault, server: NextcloudServerInterface): Promise<Credential>;
+    static fromSerializable(serialized: SerializableTransferCredentialInterface, vault: Vault, server: NextcloudServerInterface): Credential;
     getRevisions(): Promise<void | RevisionInterface[]>;
     /**
      * Update credential (encryptedData store) with the new values, if they have changed.
      * This does not update the servers credential instance.
      * @param decryptedCredentialData
      */
-    updateData(decryptedCredentialData: CredentialInterface): void;
-    exportData(): CredentialInterface;
+    updateData(decryptedCredentialData: DecryptedCredentialInterface): void;
+    exportData(): DecryptedCredentialInterface;
     /**
-     * Creates a local 100% clone of the current credential.
+     * Creates a local 100% clone of the current credential. The clone contains only encrypted data.
      */
     clone(): Credential;
     /**
@@ -100,6 +142,10 @@ export default class Credential {
      * @param plainFile
      */
     encryptUploadFile(plainFile: FileInterface): Promise<void | FileUploadResponseInterface>;
+    /**
+     * Serialized, encrypted credential data from non-object (string only) transfer methods (like WebExtension messaging api).
+     */
+    getAsSerializable(): SerializableTransferCredentialInterface;
     /**
      * Deletes the given file from the server.
      * This method does *not* delete the file from the local credential files list!
@@ -107,7 +153,7 @@ export default class Credential {
      */
     deleteFile(file: FileInterface): Promise<void | FileUploadResponseInterface>;
     getVaultGuid(): string;
-    getEncrypted(): EncryptedCredentialInterface;
+    getEncrypted(): EncryptedOwnedCredentialFromServerInterface;
     hasUnspecifiedEncryptionError(): boolean;
     get credential_id(): number;
     set credential_id(value: number);
@@ -164,10 +210,15 @@ export default class Credential {
     set created(value: number);
     get changed(): number;
     set changed(value: number);
-    get set_share_key(): boolean;
+    get set_share_key(): boolean | undefined;
     set set_share_key(value: boolean);
-    get skip_revision(): boolean;
+    get skip_revision(): boolean | undefined;
     set skip_revision(value: boolean);
-    get acl(): ACLInterface;
+    get acl(): ACLInterface | undefined;
+    /**
+     * Will be called short after credential instantiation by the ShareService.
+     * @param value
+     */
     set acl(value: ACLInterface);
+    get spacialServerUpdateFields(): SpacialCredentialFieldsToUpdateForServerInterface;
 }