Common Library

Platform abstractions, models, and services structure in @bitwarden/common

The @bitwarden/common library is the foundation of the Bitwarden Clients codebase, providing platform-agnostic abstractions, models, and services that are shared across all client applications.

Library Structure

The common library is organized into feature domains and core platform functionality:

libs/common/src/
├── abstractions/          # Core service abstractions
├── admin-console/         # Organization and admin features
├── auth/                  # Authentication and authorization
├── autofill/             # Autofill functionality
├── billing/              # Billing and subscription
├── enums/                # Shared enumerations
├── key-management/       # Cryptographic key management
├── models/               # Domain models
├── platform/             # Platform abstractions and services
├── services/             # Shared service implementations
├── tools/                # Utility tools
├── types/                # TypeScript type definitions
└── vault/                # Vault and cipher management

Core Components

Platform Abstractions

Abstract service interfaces for storage, crypto, logging, and more

Domain Models

Encrypted domain objects and decryptable view models

Service Layer

Business logic implementations and API integrations

Type System

Shared types, enums, and interfaces

Platform Abstractions

The platform layer provides core abstractions that applications must implement for their specific runtime environment.

Key Abstractions

Storage Service

Provides an abstraction for key-value storage:

// libs/common/src/platform/abstractions/storage.service.ts
export abstract class StorageService {
  abstract get<T>(key: string): Promise<T>;
  abstract set<T>(key: string, value: T): Promise<void>;
  abstract remove(key: string): Promise<void>;
  abstract has(key: string): Promise<boolean>;
}

Platform Implementations:

• Browser: Chrome storage API
• Desktop: Electron secure storage
• Web: localStorage/sessionStorage
• CLI: File system JSON storage

Platform Utils Service

Provides platform-specific utilities and device information:

// libs/common/src/platform/abstractions/platform-utils.service.ts
export abstract class PlatformUtilsService {
  abstract getDevice(): DeviceType;
  abstract getDeviceString(): string;
  abstract getClientType(): ClientType;
  abstract isFirefox(): boolean;
  abstract isChrome(): boolean;
  abstract launchUri(uri: string, options?: any): void;
  abstract getApplicationVersion(): Promise<string>;
  abstract supportsWebAuthn(win: Window): boolean;
  abstract supportsAutofill(): boolean;
}

I18n Service

Handles internationalization and localization:

// libs/common/src/platform/abstractions/i18n.service.ts
export abstract class I18nService extends TranslationService {
  abstract userSetLocale$: Observable<string | undefined>;
  abstract locale$: Observable<string>;
  abstract setLocale(locale: string | null): Promise<void>;
  abstract init(): Promise<void>;
}

Messaging Service

Enables cross-component and cross-context communication:

// libs/common/src/platform/abstractions/messaging.service.ts
export abstract class MessagingService {
  abstract send(subscriber: string, arg?: any): void;
}

Other Platform Services

Log Service

Provides logging functionality with different log levels (debug, info, warning, error).

export abstract class LogService {
  abstract debug(message: string): void;
  abstract info(message: string): void;
  abstract warning(message: string): void;
  abstract error(message: string): void;
}

Environment Service

Manages environment-specific URLs and configuration for different deployment environments.

export abstract class EnvironmentService {
  abstract getUrls(): Promise<EnvironmentUrls>;
  abstract setUrls(urls: EnvironmentUrls): Promise<void>;
}

State Service

Provides state management and persistence across the application.

export abstract class StateService {
  abstract getActiveUserId(): Promise<UserId>;
  abstract setActiveUser(userId: UserId): Promise<void>;
}

Models Architecture

The common library uses a three-layer model architecture:

1. Data Models

Represent raw data from API or storage:

// libs/common/src/vault/models/data/cipher.data.ts
export class CipherData {
  id: string;
  organizationId: string;
  folderId: string;
  type: CipherType;
  name: string;  // Encrypted
  notes: string; // Encrypted
  favorite: boolean;
  // ... more fields
}

2. Domain Models

Encapsulate business logic and handle encryption:

// libs/common/src/vault/models/domain/cipher.ts
export class Cipher extends Domain {
  id: string;
  name: EncString;  // Encrypted string
  type: CipherType;
  login?: Login;
  card?: Card;
  identity?: Identity;
  
  constructor(obj?: CipherData) {
    super();
    if (obj) {
      this.id = obj.id;
      this.name = new EncString(obj.name);
      // ...
    }
  }
  
  async decrypt(key: SymmetricCryptoKey): Promise<CipherView> {
    const view = new CipherView(this);
    view.name = await this.decryptString(this.name, key);
    // Decrypt other fields
    return view;
  }
}

3. View Models

Decrypted, user-facing models for UI rendering:

// libs/common/src/vault/models/view/cipher.view.ts
export class CipherView {
  id: string;
  name: string;  // Decrypted
  notes: string; // Decrypted
  type: CipherType;
  favorite: boolean;
  login?: LoginView;
  card?: CardView;
  // ... more fields
}

Domain Base Class

All domain models extend the Domain base class which provides encryption/decryption utilities:

// libs/common/src/platform/models/domain/domain-base.ts
export default class Domain {
  protected async decryptObj<D, V>(
    domain: D,
    viewModel: V,
    props: string[],
    key: SymmetricCryptoKey
  ): Promise<V> {
    // Decrypt specified properties from domain to view model
  }
}

Service Structure

Services in the common library follow a consistent pattern:

Service Organization

libs/common/src/vault/
├── abstractions/
│   ├── cipher.service.ts          # Abstract interface
│   └── folder.service.ts
├── services/
│   ├── cipher.service.ts          # Implementation
│   └── folder.service.ts
└── models/
    ├── domain/                     # Domain models
    ├── data/                       # Data models
    └── view/                       # View models

Example: Cipher Service

Abstraction:

// libs/common/src/vault/abstractions/cipher.service.ts
export abstract class CipherService {
  abstract get(id: string): Promise<Cipher | undefined>;
  abstract getAll(): Promise<Cipher[]>;
  abstract encrypt(cipher: CipherView, key?: SymmetricCryptoKey): Promise<Cipher>;
  abstract decrypt(cipher: Cipher): Promise<CipherView>;
  abstract save(cipher: Cipher): Promise<void>;
  abstract delete(id: string): Promise<void>;
}

Implementation:

// libs/common/src/vault/services/cipher.service.ts
export class DefaultCipherService implements CipherService {
  constructor(
    private cryptoService: CryptoService,
    private stateService: StateService,
    private apiService: ApiService
  ) {}
  
  async get(id: string): Promise<Cipher | undefined> {
    const ciphers = await this.stateService.getCiphers();
    return ciphers[id];
  }
  
  async decrypt(cipher: Cipher): Promise<CipherView> {
    const key = await this.getKeyForCipher(cipher);
    return await cipher.decrypt(key);
  }
  
  // ... other methods
}

Feature Domains

Authentication

Location: libs/common/src/auth/

Abstractions

// Auth service
export abstract class AuthService {
  abstract logIn(credentials: LoginCredentials): Promise<AuthResult>;
  abstract logOut(): Promise<void>;
  abstract getAuthStatus(): Promise<AuthenticationStatus>;
}

Vault Management

Location: libs/common/src/vault/

Key abstractions:

• CipherService - Manage vault items (ciphers)
• FolderService - Organize ciphers into folders
• CollectionService - Organization collections
• SearchService - Search and filter vault items

Key Management

Location: libs/common/src/key-management/

Handles cryptographic operations:

• Key derivation and generation
• Encryption and decryption
• Key rotation and management

Admin Console

Location: libs/common/src/admin-console/

Organization and user management:

• Organization services
• User invitation and management
• Policy enforcement

Enums and Types

Common Enums

// libs/common/src/enums/device-type.enum.ts
export enum DeviceType {
  Android = 0,
  iOS = 1,
  ChromeExtension = 2,
  FirefoxExtension = 3,
  OperaExtension = 4,
  EdgeExtension = 5,
  WindowsDesktop = 6,
  MacOsDesktop = 7,
  LinuxDesktop = 8,
  ChromeBrowser = 9,
  FirefoxBrowser = 10,
  // ...
}

// libs/common/src/vault/enums/cipher-type.ts
export enum CipherType {
  Login = 1,
  SecureNote = 2,
  Card = 3,
  Identity = 4,
  SshKey = 5,
}

Import Examples

// Platform abstractions
import { StorageService } from '@bitwarden/common/platform/abstractions/storage.service';
import { I18nService } from '@bitwarden/common/platform/abstractions/i18n.service';

// Domain models
import { Cipher } from '@bitwarden/common/vault/models/domain/cipher';
import { CipherView } from '@bitwarden/common/vault/models/view/cipher.view';

// Services
import { CipherService } from '@bitwarden/common/vault/abstractions/cipher.service';

// Enums
import { CipherType } from '@bitwarden/common/vault/enums/cipher-type';
import { DeviceType } from '@bitwarden/common/enums/device-type.enum';

// Types
import { UserId } from '@bitwarden/common/types/guid';

Related Libraries

State Library

@bitwarden/state - Advanced state management with RxJS observables

Storage Core

@bitwarden/storage-core - Core storage abstractions and implementations

Key Management

@bitwarden/key-management - Cryptographic key operations

Platform Library

@bitwarden/platform - Platform-specific implementations