Overview
The FolderService manages folder organization for vault items. Folders provide a way to categorize and organize ciphers within a user’s personal vault.
Source: libs/common/src/vault/services/folder/folder.service.ts
Key Features
- Create, read, update, and delete folders
- Encrypt and decrypt folder data
- Observable-based folder state management
- Automatic “None” folder for unorganized items
- Key rotation support
Observables
folders$
Observable that emits encrypted folders for a user.
folders$(userId: UserId): Observable<Folder[]>
userId: UserId - The user ID to get folders for
Returns: Observable of encrypted folder domain objects
Example:
const folders$ = folderService.folders$(userId);
folders$.subscribe(folders => {
console.log(`User has ${folders.length} folders`);
});
folderViews$
Observable that emits decrypted folder views for a user.
folderViews$(userId: UserId): Observable<FolderView[]>
userId: UserId - The user ID to get folder views for
Returns: Observable of decrypted folder views, includes automatic “None” folder
Example:
const folderViews$ = folderService.folderViews$(userId);
folderViews$.subscribe(folders => {
folders.forEach(folder => {
console.log(`Folder: ${folder.name}`);
});
});
getDecrypted$
Observable for a single decrypted folder by ID.
getDecrypted$(id: string, userId: UserId): Observable<FolderView | undefined>
id: string - The folder IDuserId: UserId - The user ID
Returns: Observable that emits the folder view or undefined if not found
Core Methods
encrypt
Encrypts a folder view for storage.
encrypt(model: FolderView, key: SymmetricCryptoKey): Promise<Folder>
model: FolderView - The folder view to encryptkey: SymmetricCryptoKey - The encryption key (typically user key)
Returns: Promise resolving to encrypted folder
Example:
const folderView = new FolderView();
folderView.name = "Work Accounts";
const userKey = await keyService.getUserKey(userId);
const encrypted = await folderService.encrypt(folderView, userKey);
get
Retrieves a single encrypted folder by ID.
get(id: string, userId: UserId): Promise<Folder>
id: string - The folder IDuserId: UserId - The user ID
Returns: Promise resolving to the folder, or undefined if not found
getAllFromState
Retrieves all folders from state.
getAllFromState(userId: UserId): Promise<Folder[]>
userId: UserId - The user ID
Returns: Promise resolving to array of all folders
getAllDecryptedFromState
Retrieves all decrypted folders from state.
getAllDecryptedFromState(userId: UserId): Promise<FolderView[]>
userId: UserId - The user ID
Returns: Promise resolving to array of decrypted folder views
This method is deprecated and only recommended for CLI usage. Use folderViews$ observable instead for reactive updates.
CRUD Operations
upsert
Inserts or updates folder data in storage.
upsert(folderData: FolderData | FolderData[], userId: UserId): Promise<void>
folderData: FolderData | FolderData[] - Single folder or array of folders to upsertuserId: UserId - The user ID
Example:
const folderData = new FolderData();
folderData.id = "folder-id-123";
folderData.name = encryptedName;
folderData.revisionDate = new Date().toISOString();
await folderService.upsert(folderData, userId);
replace
Replaces all folders for a user.
replace(folders: { [id: string]: FolderData }, userId: UserId): Promise<void>
folders: { [id: string]: FolderData } - Object mapping folder IDs to folder datauserId: UserId - The user ID
Note: This is typically used during sync operations to replace all local folder data.
delete
Deletes one or more folders.
delete(id: string | string[], userId: UserId): Promise<any>
id: string | string[] - Folder ID or array of folder IDs to deleteuserId: UserId - The user ID
Behavior:
- Deletes the folder from storage
- Automatically reassigns ciphers in the deleted folder to “No Folder”
- Updates cipher data to set
folderId to null
Example:
// Delete a single folder
await folderService.delete("folder-id-123", userId);
// Delete multiple folders
await folderService.delete(["folder-1", "folder-2"], userId);
clear
Clears all folder data for a user.
clear(userId: UserId): Promise<void>
userId: UserId - The user ID
Note: This is typically called during logout or account switching.
Key Rotation
getRotatedData
Generates re-encrypted folder data for key rotation.
getRotatedData(
originalUserKey: UserKey,
newUserKey: UserKey,
userId: UserId,
): Promise<FolderWithIdRequest[]>
originalUserKey: UserKey - The original user key (not currently used in implementation)newUserKey: UserKey - The new user key to encrypt withuserId: UserId - The user ID
Returns: Promise resolving to array of re-encrypted folders for server update
Example:
const rotatedFolders = await folderService.getRotatedData(
oldUserKey,
newUserKey,
userId
);
// Send rotated data to server
await apiService.postUserKeyUpdate({
folders: rotatedFolders,
// ... other rotated data
});
Cache Management
clearDecryptedFolderState
Clears the decrypted folder cache.
clearDecryptedFolderState(userId: UserId): Promise<void>
userId: UserId - The user ID
Note: This forces folders to be decrypted again on next access. Called automatically during upsert operations.
Folder Structure
FolderView
Decrypted folder view object.
class FolderView {
id: string;
name: string;
revisionDate: Date;
}
id: string - Unique folder identifiername: string - Decrypted folder namerevisionDate: Date - Last modification date
Folder
Encrypted folder domain object.
class Folder {
id: string;
name: EncString;
revisionDate: Date;
}
id: string - Unique folder identifiername: EncString - Encrypted folder namerevisionDate: Date - Last modification date
FolderData
Raw folder data for storage.
class FolderData {
id: string;
name: string; // Encrypted string representation
revisionDate: string;
}
Special Folders
None Folder
The service automatically adds a “None” folder to the folder list:
const noneFolder = new FolderView();
noneFolder.name = this.i18nService.t("noneFolder");
// Automatically appended to folder list
- No ID (used for ciphers with
folderId === null)
- Localized name from i18n service
- Always appears in folder lists
- Cannot be deleted or modified
- Represents unorganized items
Usage Examples
Creating a New Folder
import { FolderView } from '@bitwarden/common/vault/models/view/folder.view';
import { FolderData } from '@bitwarden/common/vault/models/data/folder.data';
// Create folder view
const folderView = new FolderView();
folderView.name = "Personal Accounts";
// Encrypt the folder
const userKey = await keyService.getUserKey(userId);
const encrypted = await folderService.encrypt(folderView, userKey);
// Save to storage
const folderData = encrypted.toFolderData();
await folderService.upsert(folderData, userId);
Listing All Folders
// Using observable (recommended)
folderService.folderViews$(userId).subscribe(folders => {
folders.forEach(folder => {
console.log(`${folder.id}: ${folder.name}`);
});
});
// Using promise (CLI/scripts)
const folders = await folderService.getAllDecryptedFromState(userId);
folders.forEach(folder => {
console.log(`${folder.id}: ${folder.name}`);
});
Moving Cipher to Folder
// Get the cipher
const cipher = await cipherService.get(cipherId, userId);
// Update folder assignment
cipher.folderId = targetFolderId;
// Save changes
await cipherService.upsert(cipher.toCipherData(), userId);
Deleting a Folder
// Delete folder (ciphers automatically moved to "None")
await folderService.delete(folderId, userId);
// Verify ciphers were reassigned
const ciphers = await cipherService.getAllDecryptedForGrouping(
null, // null = "None" folder
userId,
true // folder = true
);
console.log(`${ciphers.length} items moved to None folder`);
Implementation Notes
Observable Caching
The service maintains a cache of folder view observables to prevent duplicate decryption:
private folderViewCache = new Map<UserId, Observable<FolderView[]>>();
Force Emission
The service uses subjects to force emission of empty arrays during cleanup:
private forceFolderViews: Record<UserId, Subject<FolderView[]>> = {};
- Cipher Service - Manages vault items that can be organized in folders
- Key Service - Provides encryption keys for folder encryption
See Also