wip

add docs and tests
[PM-26889] - Typescript 5.9 upgrade with updates (#965 )
2026-01-23 04:43:22 +00:00 · 2026-01-09 17:01:26 -05:00 · 2026-01-09 12:05:14 -05:00 · 2026-01-09 10:07:27 -06:00
20 changed files with 838 additions and 961 deletions
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -1,706 +1,203 @@
-# Bitwarden Directory Connector - Claude Code Configuration
+# Bitwarden Directory Connector

-Sync users and groups from enterprise directory services (LDAP, Entra ID, Google Workspace, Okta, OneLogin) to Bitwarden organizations. Available as both a desktop GUI (Electron + Angular) and a CLI tool (`bwdc`).
+## Project Overview

-## Overview
+Directory Connector is a TypeScript application that synchronizes users and groups from directory services to Bitwarden organizations. It provides both a desktop GUI (built with Angular and Electron) and a CLI tool (bwdc).

-### What This Project Does
+**Supported Directory Services:**

- Connects to enterprise identity providers and retrieves user/group membership data
- Syncs that data to Bitwarden organizations via the Directory Connector API
- Provides both a desktop GUI application (Electron) and a command-line interface (`bwdc`)
+- LDAP (Lightweight Directory Access Protocol) - includes Active Directory and general LDAP servers
+- Microsoft Entra ID (formerly Azure Active Directory)
+- Google Workspace
+- Okta
+- OneLogin

-### Key Concepts
+**Technologies:**

- **Directory Service**: An identity provider (LDAP, Entra ID, GSuite, Okta, OneLogin) that stores users and groups
- **Sync**: The process of fetching entries from a directory and importing them to Bitwarden
- **Delta Sync**: Incremental synchronization that only fetches changes since the last sync
- **Entry**: Base class for `UserEntry` and `GroupEntry` - the core data models
- **Force Sync**: Ignores delta tokens and fetches all entries fresh
- **Test Mode**: Simulates sync without making API calls or updating state
+- TypeScript
+- Angular (GUI)
+- Electron (Desktop wrapper)
+- Node
+- Jest for testing

---
+## Code Architecture & Structure

-## Architecture & Patterns
-
-### System Architecture
+### Directory Organization

 ```
-                    User Request (GUI/CLI)
-                            ↓
-            ┌───────────────────────────────────┐
-            │          Entry Points             │
-            │   main.ts (GUI)  │  bwdc.ts (CLI) │
-            └───────────────────────────────────┘
-                            ↓
-            ┌───────────────────────────────────┐
-            │           SyncService             │
-            │   Orchestrates the sync flow      │
-            └───────────────────────────────────┘
-                            ↓
-            ┌───────────────────────────────────┐
-            │      DirectoryFactoryService      │
-            │   Creates appropriate IDirectory  │
-            └───────────────────────────────────┘
-                            ↓
-    ┌─────────────────────────────────────────────────────┐
-    │              Directory Services                      │
-    │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │
-    │ │  LDAP   │ │ EntraID │ │ GSuite  │ │ Okta/1Login │ │
-    │ └─────────┘ └─────────┘ └─────────┘ └─────────────┘ │
-    └─────────────────────────────────────────────────────┘
-                            ↓
-            ┌───────────────────────────────────┐
-            │        [GroupEntry[], UserEntry[]]│
-            └───────────────────────────────────┘
-                            ↓
-            ┌───────────────────────────────────┐
-            │       RequestBuilder (Batched)    │
-            │   SingleRequestBuilder (<2000)    │
-            │   BatchRequestBuilder  (>2000)    │
-            └───────────────────────────────────┘
-                            ↓
-            ┌───────────────────────────────────┐
-            │         Bitwarden API             │
-            │      POST /import endpoint        │
-            └───────────────────────────────────┘
+src/
+├── abstractions/       # Interface definitions (e.g., IDirectoryService)
+├── services/          # Business logic implementations for directory services, sync, auth
+├── models/            # Data models (UserEntry, GroupEntry, etc.)
+├── commands/          # CLI command implementations
+├── app/               # Angular GUI components
+└── utils/             # Test utilities and fixtures
+
+src-cli/               # CLI-specific code (imports common code from src/)
+
+jslib/                 # Legacy folder structure (mix of deprecated/unused and current code - new code should not be added here)
 ```

+### Key Architectural Patterns
+
+1. **Abstractions = Interfaces**: All interfaces are defined in `/abstractions`
+2. **Services = Business Logic**: Implementations live in `/services`
+3. **Directory Service Pattern**: Each directory provider implements `IDirectoryService` interface
+4. **Separation of Concerns**: GUI (Angular app) and CLI (commands) share the same service layer
+
+## Development Conventions
+
 ### Code Organization

-```
-src/
-├── abstractions/          # Interface definitions (IDirectoryService, etc.)
-├── app/                   # Angular GUI components
-│   ├── tabs/              # Tab-based navigation (Dashboard, Settings, More)
-│   └── services/          # Angular service providers
-├── commands/              # CLI command implementations
-├── enums/                 # TypeScript enums (DirectoryType, etc.)
-├── models/                # Data models (Entry, UserEntry, GroupEntry)
-├── services/              # Business logic implementations
-│   └── directory-services/  # One service per directory provider
-├── bwdc.ts                # CLI entry point
-├── main.ts                # Electron main process entry point
-└── program.ts             # CLI command routing (Commander.js)
+**File Naming:**

-jslib/                     # Legacy shared libraries (do not add new code here)
-utils/                     # Integration test fixtures
-└── openldap/              # Docker configs, test data, certificates
-```
+- kebab-case for files: `ldap-directory.service.ts`
+- Descriptive names that reflect purpose

-### Key Principles
+**Class/Function Naming:**

-1. **Shared Service Layer**: GUI (Angular) and CLI share identical service implementations
-2. **Factory Pattern**: `DirectoryFactoryService` instantiates the correct `IDirectoryService` based on `DirectoryType`
-3. **Secure Storage**: Credentials stored in system keychain via `KeytarSecureStorageService`
-4. **Delta Tracking**: Incremental sync via delta tokens to minimize API calls
+- PascalCase for classes and interfaces
+- camelCase for functions and variables
+- Descriptive names that indicate purpose

-### Core Patterns
+**File Structure:**

-#### Directory Service Pattern
+- Keep files focused on single responsibility
+- Create new service files for distinct directory integrations
+- Separate models into individual files when complex

-**Purpose**: Abstract different identity providers behind a common interface
+### TypeScript Conventions

-**Interface** (`src/abstractions/directory.service.ts`):
+**Import Patterns:**

-```typescript
-export interface IDirectoryService {
-  getEntries(force: boolean, test: boolean): Promise<[GroupEntry[], UserEntry[]]>;
-}
-```
+- Use path aliases (`@/`) for project imports
+  - `@/` - project root
+  - `@/jslib/` - jslib folder
+- ESLint enforces alphabetized import ordering with newlines between groups

-**Implementations** in `src/services/directory-services/`:
+**Type Safety:**

- `ldap-directory.service.ts` - LDAP/Active Directory
- `entra-id-directory.service.ts` - Microsoft Entra ID (Azure AD)
- `gsuite-directory.service.ts` - Google Workspace
- `okta-directory.service.ts` - Okta
- `onelogin-directory.service.ts` - OneLogin
+- Avoid `any` types - use proper typing or `unknown` with type guards
+- Prefer interfaces for contracts, types for unions/intersections
+- Use strict null checks - handle `null` and `undefined` explicitly
+- Leverage TypeScript's type inference where appropriate

-**Factory** (`src/services/directory-factory.service.ts`):
+**Configuration:**

-```typescript
-createService(type: DirectoryType): IDirectoryService
-```
+- Use configuration files or environment variables
+- Never hardcode URLs or configuration values

-#### State Service Pattern
+## Security Best Practices

-**Purpose**: Manage persistent state and credential storage
+**Credential Handling:**

-**Implementation** (`src/services/state.service.ts`):
+- Never log directory service credentials, API keys, or tokens
+- Use secure storage mechanisms for sensitive data
+- Credentials should never be hardcoded
+- Store credentials encrypted, never in plain text

- Configuration and sync settings stored in LowDB (JSON file)
- Sensitive data (passwords, API keys) stored in system keychain
- File locking via `proper-lockfile` to prevent concurrent access corruption
- Platform-specific app data directories:
-  - macOS: `~/Library/Application Support/Bitwarden Directory Connector`
-  - Windows: `%APPDATA%/Bitwarden Directory Connector`
-  - Linux: `~/.config/Bitwarden Directory Connector` or `$XDG_CONFIG_HOME`
+**Sensitive Data:**

---
+- User and group data from directories should be handled securely
+- Avoid exposing sensitive information in error messages
+- Sanitize data before logging
+- Be cautious with data persistence

-## Development Guide
+**Input Validation:**

-### Adding a New Directory Service
+- Validate and sanitize data from external directory services
+- Check for injection vulnerabilities (LDAP injection, etc.)
+- Validate configuration inputs from users

-**1. Create the enum value** (`src/enums/directoryType.ts`)
+**API Security:**

-```typescript
-export enum DirectoryType {
-  Ldap = 0,
-  EntraID = 1,
-  GSuite = 2,
-  Okta = 3,
-  OneLogin = 4,
-  NewProvider = 5, // Add here
-}
-```
+- Ensure authentication flows are implemented correctly
+- Verify SSL/TLS is used for all external connections
+- Check for secure token storage and refresh mechanisms

-**2. Create the configuration model** (`src/models/newProviderConfiguration.ts`)
+## Error Handling

-```typescript
-export class NewProviderConfiguration {
-  apiUrl: string;
-  apiToken: string;
-  // Provider-specific settings
-}
-```
+**Best Practices:**

-**3. Implement the directory service** (`src/services/directory-services/newprovider-directory.service.ts`)
+1. **Try-catch for async operations** - Always wrap external API calls
+2. **Meaningful error messages** - Provide context for debugging
+3. **Error propagation** - Don't swallow errors silently
+4. **User-facing errors** - Separate user messages from developer logs

-```typescript
-import { IDirectoryService } from "@/src/abstractions/directory.service";
-import { GroupEntry } from "@/src/models/groupEntry";
-import { UserEntry } from "@/src/models/userEntry";
-import { BaseDirectoryService } from "./base-directory.service";
+## Performance Best Practices

-export class NewProviderDirectoryService extends BaseDirectoryService implements IDirectoryService {
-  constructor(
-    private logService: LogService,
-    private i18nService: I18nService,
-    private stateService: StateService,
-  ) {
-    super();
-  }
+**Large Dataset Handling:**

-  async getEntries(force: boolean, test: boolean): Promise<[GroupEntry[], UserEntry[]]> {
-    const config = await this.stateService.getDirectory<NewProviderConfiguration>(
-      DirectoryType.NewProvider,
-    );
-    const syncConfig = await this.stateService.getSync();
+- Use pagination for large user/group lists
+- Avoid loading entire datasets into memory at once
+- Consider streaming or batch processing for large operations

-    const groups: GroupEntry[] = [];
-    const users: UserEntry[] = [];
+**API Rate Limiting:**

-    // Fetch from provider API
-    // Apply filters using inherited filter methods
+- Respect rate limits for Microsoft Graph API, Google Admin SDK, etc.
+- Consider batching large API calls where necessary

-    return [groups, users];
-  }
-}
-```
+**Memory Management:**

-**4. Register in the factory** (`src/services/directory-factory.service.ts`)
-
-```typescript
-case DirectoryType.NewProvider:
-  return new NewProviderDirectoryService(
-    this.logService,
-    this.i18nService,
-    this.stateService
-  );
-```
-
-**5. Add state service support** (`src/services/state.service.ts`)
-
-```typescript
-// Add to secure storage keys if credentials involved
-// Add configuration getter/setter methods
-```
-
-**6. Write tests** (`src/services/directory-services/newprovider-directory.service.spec.ts`)
-
-### Common Patterns
-
-#### Error Handling with State Rollback
-
-```typescript
-async sync(force: boolean, test: boolean): Promise<[GroupEntry[], UserEntry[]]> {
-  // Store initial state for rollback
-  const startingUserDelta = await this.stateService.getUserDelta();
-  const startingGroupDelta = await this.stateService.getGroupDelta();
-
-  try {
-    // Perform sync operations
-    const [groups, users] = await this.directoryService.getEntries(force, test);
-    // ... process and submit
-    return [groups, users];
-  } catch (e) {
-    if (!test) {
-      // Rollback deltas on failure
-      await this.stateService.setUserDelta(startingUserDelta);
-      await this.stateService.setGroupDelta(startingGroupDelta);
-    }
-    this.messagingService.send("dirSyncCompleted", { successfully: false });
-    throw e;
-  }
-}
-```
-
-#### Filter Processing
-
-```typescript
-// In BaseDirectoryService
-protected buildIncludeSet(filter: string): Set<string> {
-  // Parse filter like "include:user1@example.com,user2@example.com"
-}
-
-protected buildExcludeSet(filter: string): Set<string> {
-  // Parse filter like "exclude:user1@example.com"
-}
-
-protected shouldIncludeUser(user: UserEntry, include: Set<string>, exclude: Set<string>): boolean {
-  if (exclude.has(user.email)) return false;
-  if (include.size === 0) return true;
-  return include.has(user.email);
-}
-```
-
-### Running the Desktop GUI (Development)
-
-```bash
-npm install
-npm run rebuild          # Rebuild native modules (keytar)
-npm run electron         # Run GUI with hot reload
-```
-
-### Running the CLI (Development)
-
-```bash
-npm install
-npm run build:cli:watch  # Build CLI with watch mode
-node ./build-cli/bwdc.js --help  # Run CLI commands
-```
-
---
-
-## Data Models
-
-### Core Types
-
-```typescript
-// Base entry class (src/models/entry.ts)
-abstract class Entry {
-  referenceId: string; // Unique ID within the directory (e.g., DN for LDAP)
-  externalId: string; // ID used for Bitwarden import
-}
-
-// User entry (src/models/userEntry.ts)
-class UserEntry extends Entry {
-  email: string;
-  disabled: boolean;
-  deleted: boolean;
-}
-
-// Group entry (src/models/groupEntry.ts)
-class GroupEntry extends Entry {
-  name: string;
-  userMemberExternalIds: Set<string>; // External IDs of member users
-  groupMemberReferenceIds: Set<string>; // Reference IDs of nested groups
-  users: UserEntry[]; // Populated for display/simulation
-}
-```
-
-### Directory Type Enum
-
-```typescript
-// src/enums/directoryType.ts
-enum DirectoryType {
-  Ldap = 0,
-  EntraID = 1,
-  GSuite = 2,
-  Okta = 3,
-  OneLogin = 4,
-}
-```
-
-### Configuration Models
-
-Each directory provider has a configuration class in `src/models/`:
-
- `LdapConfiguration` - hostname, port, SSL/TLS, bind credentials, auth mode
- `EntraIdConfiguration` - tenant, client ID, secret key
- `GSuiteConfiguration` - domain, admin user, client email, private key
- `OktaConfiguration` - organization URL, API token
- `OneLoginConfiguration` - client ID, client secret, region
-
-### Sync Configuration
-
-```typescript
-// src/models/syncConfiguration.ts
-interface SyncConfiguration {
-  users: boolean; // Sync users
-  groups: boolean; // Sync groups
-  interval: number; // Minutes between syncs (minimum 5)
-  userFilter: string; // Include/exclude filter
-  groupFilter: string; // Include/exclude filter
-  removeDisabled: boolean; // Remove disabled users from org
-  overwriteExisting: boolean; // Overwrite existing entries
-  largeImport: boolean; // Enable for >2000 entries
-  // LDAP-specific
-  groupObjectClass: string;
-  userObjectClass: string;
-  groupPath: string;
-  userPath: string;
-  // ... additional LDAP attributes
-}
-```
-
---
-
-## Security & Configuration
-
-### Security Rules
-
-**MANDATORY - These rules have no exceptions:**
-
-1. **Never log credentials**: API keys, passwords, tokens, and secrets must never appear in logs
-2. **Never hardcode secrets**: All URLs, credentials, and sensitive data must come from configuration
-3. **Use KeytarSecureStorageService**: All credentials must be stored in the system keychain
-4. **Validate external data**: Sanitize all data received from directory services
-5. **LDAP injection prevention**: Be cautious with user-provided LDAP filters
-
-### Secure Storage Keys
-
-The following are stored in the system keychain (not plain JSON):
-
- `ldapPassword` - LDAP bind password
- `gsuitePrivateKey` - Google Workspace private key
- `entraKey` - Microsoft Entra ID client secret
- `oktaToken` - Okta API token
- `oneLoginClientSecret` - OneLogin client secret
- User/group delta tokens
- Sync hashes
-
-### Environment Variables
-
-| Variable                                   | Required | Description                              | Example              |
-| ------------------------------------------ | -------- | ---------------------------------------- | -------------------- |
-| `BITWARDENCLI_CONNECTOR_APPDATA_DIR`       | No       | CLI app data directory override          | `/custom/path`       |
-| `BITWARDEN_CONNECTOR_APPDATA_DIR`          | No       | GUI app data directory override          | `/custom/path`       |
-| `BITWARDENCLI_CONNECTOR_PLAINTEXT_SECRETS` | No       | Store secrets in plain text (debug only) | `true`               |
-| `BITWARDENCLI_CONNECTOR_DEBUG`             | No       | Enable debug logging                     | `true`               |
-| `BW_CLIENTID`                              | No       | CLI login client ID                      | `organization.xxxxx` |
-| `BW_CLIENTSECRET`                          | No       | CLI login client secret                  | `xxxxx`              |
-| `BW_NOINTERACTION`                         | No       | Disable interactive prompts              | `true`               |
-| `BW_PRETTY`                                | No       | Pretty-print JSON output                 | `true`               |
-| `BW_RAW`                                   | No       | Raw output (no formatting)               | `true`               |
-| `BW_RESPONSE`                              | No       | JSON response format                     | `true`               |
-| `BW_QUIET`                                 | No       | Suppress stdout                          | `true`               |
-
-### Authentication & Authorization
-
- **API Token Authentication**: Uses organization `clientId` + `clientSecret`
- **Token Storage**: Access tokens and refresh tokens stored securely via Keytar
- **Token Refresh**: Automatic refresh when access token expires
- **Auth Service**: `src/services/auth.service.ts` handles the authentication flow
-
---
+- Close connections and clean up resources
+- Remove event listeners when components are destroyed
+- Be cautious with caching large datasets

 ## Testing

-### Test Structure
+**Framework:**

-```
-src/
-├── services/
-│   ├── sync.service.spec.ts              # Unit tests (colocated)
-│   ├── sync.service.integration.spec.ts  # Integration tests
-│   └── directory-services/
-│       ├── ldap-directory.service.spec.ts
-│       └── ldap-directory.service.integration.spec.ts
-utils/
-└── openldap/
-    ├── config-fixtures.ts    # Test configuration helpers
-    ├── user-fixtures.ts      # Expected user data
-    ├── group-fixtures.ts     # Expected group data
-    ├── certs/                # TLS certificates
-    └── docker-compose.yml    # LDAP container config
-```
+- Jest with jest-preset-angular
+- jest-mock-extended for type-safe mocks with `mock<Type>()`

-### Writing Tests
+**Test Organization:**

-**Unit Test Template**:
+- Tests colocated with source files
+- `*.spec.ts` - Unit tests for individual components/services
+- `*.integration.spec.ts` - Integration tests against live directory services
+- Test helpers located in `utils/` directory

-```typescript
-import { mock, MockProxy } from "jest-mock-extended";
+**Test Naming:**

-describe("ServiceName", () => {
-  let logService: MockProxy<LogService>;
-  let stateService: MockProxy<StateService>;
-  let service: ServiceUnderTest;
+- Descriptive, human-readable test names
+- Example: `'should return empty array when no users exist in directory'`

-  beforeEach(() => {
-    logService = mock();
-    stateService = mock();
-    service = new ServiceUnderTest(logService, stateService);
-  });
+**Test Coverage:**

-  it("should do something", async () => {
-    // Arrange
-    stateService.getSomeValue.mockResolvedValue(expectedValue);
+- New features must include tests
+- Bug fixes should include regression tests
+- Changes to core sync logic or directory specific logic require integration tests

-    // Act
-    const result = await service.doSomething();
+**Testing Approach:**

-    // Assert
-    expect(result).toEqual(expectedResult);
-  });
-});
-```
+- **Unit tests**: Mock external API calls using jest-mock-extended
+- **Integration tests**: Use live directory services (Docker containers or configured cloud services)
+- Focus on critical paths (authentication, sync, data transformation)
+- Test error scenarios and edge cases (empty results, malformed data, connection failures), not just happy paths

-**Integration Test Template** (see `ldap-directory.service.integration.spec.ts`):
+## Directory Service Patterns

-```typescript
-// Requires Docker containers running
-// npm run test:integration:setup
+### IDirectoryService Interface

-describe("ldapDirectoryService", () => {
-  let stateService: MockProxy<StateService>;
-  let directoryService: LdapDirectoryService;
+All directory services implement this core interface with methods:

-  beforeEach(() => {
-    stateService = mock();
-    stateService.getDirectoryType.mockResolvedValue(DirectoryType.Ldap);
-    stateService.getDirectory
-      .calledWith(DirectoryType.Ldap)
-      .mockResolvedValue(getLdapConfiguration());
-  });
+- `getUsers()` - Retrieve users from directory and transform them into standard objects
+- `getGroups()` - Retrieve groups from directory and transform them into standard objects
+- Connection and authentication handling

-  it("syncs users and groups", async () => {
-    const result = await directoryService.getEntries(true, true);
-    expect(result).toEqual([groupFixtures, userFixtures]);
-  });
-});
-```
+### Service-Specific Implementations

-### Running Tests
+Each directory service has unique authentication and query patterns:

-```bash
-npm test                           # All unit tests (excludes integration)
-npm test -- path/to/file.spec.ts   # Single test file
-npm run test:watch                 # Watch mode
-
-# Integration tests
-npm run test:integration:setup     # Start Docker containers
-npm run test:integration           # Run integration tests
-npm run test:integration:watch     # Watch mode for integration
-```
-
-### Test Environment
-
- **Mocking**: `jest-mock-extended` with `mock<Type>()` for type-safe mocks
- **Alternative**: `@fluffy-spoon/substitute` available for some tests
- **Integration**: Docker containers for LDAP (OpenLDAP)
- **Fixtures**: Located in `utils/openldap/`
-
---
-
-## Code Style & Standards
-
-### Formatting
-
- **Prettier**: Auto-formatting enforced via pre-commit hooks
- **Config**: `.prettierrc` in project root
-
-### Naming Conventions
-
- `camelCase` for: variables, functions, method names
- `PascalCase` for: classes, interfaces, types, enums
- `SCREAMING_SNAKE_CASE` for: constants (rare in this codebase)
-
-### Imports
-
-**Path Aliases:**
-
- `@/` maps to project root
- Example: `import { SyncService } from "@/src/services/sync.service"`
-
-**Import Order (ESLint enforced):**
-
-1. External packages (node_modules)
-2. jslib imports (`@/jslib/...`)
-3. Project imports (`@/src/...`)
-4. Alphabetized within each group with newlines between groups
-
-```typescript
-// External
-import { mock, MockProxy } from "jest-mock-extended";
-
-// jslib
-import { LogService } from "@/jslib/common/src/abstractions/log.service";
-
-// Project
-import { DirectoryType } from "@/src/enums/directoryType";
-import { SyncService } from "@/src/services/sync.service";
-```
-
-### Comments
-
- Avoid unnecessary comments; code should be self-documenting
- Use JSDoc only for public APIs that need documentation
- Inline comments for complex logic only
-
-### Pre-commit Hooks
-
- **Husky**: Runs `lint-staged` on commit
- **lint-staged**: Runs Prettier on all files, ESLint on TypeScript files
-
-```bash
-npm run lint             # Check ESLint + Prettier
-npm run lint:fix         # Auto-fix ESLint issues
-npm run prettier         # Auto-format with Prettier
-npm run test:types       # TypeScript type checking
-```
-
---
-
-## Anti-Patterns
-
-### DO
-
- ✅ Use `KeytarSecureStorageService` for all credential storage
- ✅ Implement `IDirectoryService` interface for new directory providers
- ✅ Use the factory pattern via `DirectoryFactoryService`
- ✅ Write unit tests with `jest-mock-extended` mocks
- ✅ Handle errors with state rollback (delta tokens)
- ✅ Use path aliases (`@/src/...`) for imports
- ✅ Validate data from external directory services
- ✅ Use `force` and `test` parameters consistently in sync methods
-
-### DON'T
-
- ❌ Log credentials, API keys, or tokens
- ❌ Hardcode URLs, secrets, or configuration values
- ❌ Store sensitive data in LowDB (JSON) - use Keytar
- ❌ Skip input validation for LDAP filters (injection risk)
- ❌ Use `any` types without explicit justification
- ❌ Add new code to `jslib/` (legacy, read-only)
- ❌ Ignore delta token rollback on sync failure
- ❌ Bypass `overwriteExisting` validation for batch imports (>2000 entries)
-
---
-
-## Deployment
-
-### Building
-
-**Desktop GUI (Electron):**
-
-```bash
-npm run build              # Build main + renderer
-npm run build:dist         # Full distribution build
-npm run dist:win           # Windows installer
-npm run dist:mac           # macOS installer
-npm run dist:lin           # Linux packages (AppImage, RPM)
-```
-
-**CLI Tool:**
-
-```bash
-npm run build:cli:prod     # Production build
-npm run dist:cli:win       # Windows executable
-npm run dist:cli:mac       # macOS executable
-npm run dist:cli:lin       # Linux executable
-```
-
-### Versioning
-
-Follow semantic versioning: `MAJOR.MINOR.PATCH`
-
- Version format: `YYYY.MM.PATCH` (e.g., `2025.12.0`)
- Managed in `package.json`
-
-### Publishing
-
- **CI/CD**: GitHub Actions workflows in `.github/workflows/`
- **build.yml**: Multi-platform builds with code signing
- **release.yml**: Version bumping and publishing
- **Code Signing**: Azure Key Vault (Windows), App Store Connect (macOS)
- **Auto-update**: Electron Updater for GUI application
-
---
-
-## Troubleshooting
-
-### Common Issues
-
-#### LDAP Connection Failures
-
-**Problem**: Cannot connect to LDAP server, timeout or connection refused
-
-**Solution**:
-
-1. Verify hostname and port are correct
-2. Check SSL/TLS settings match server configuration
-3. For StartTLS, ensure SSL is enabled and use the non-secure port (389)
-4. For LDAPS, use port 636 and provide CA certificate path
-
-#### Keytar/Native Module Issues
-
-**Problem**: `Error: Module did not self-register` or keytar-related crashes
-
-**Solution**:
-
-```bash
-npm run rebuild    # Rebuild native modules for current Electron version
-npm run reset      # Full reset of keytar module
-```
-
-#### Sync Hash Mismatch
-
-**Problem**: Sync runs but no changes appear in Bitwarden
-
-**Solution**: The sync service skips if the hash matches the previous sync. Use force sync:
-
-```bash
-bwdc sync --force   # CLI
-# Or clear cache
-bwdc clear-cache
-```
-
-#### Large Import Failures
-
-**Problem**: Sync fails for organizations with >2000 users/groups
-
-**Solution**: Enable `largeImport` in sync settings. Note: `overwriteExisting` is incompatible with batch mode.
-
-### Debug Tips
-
- Enable debug logging: `BITWARDENCLI_CONNECTOR_DEBUG=true`
- View data file location: `bwdc data-file`
- Test sync without making changes: `bwdc test`
- Check last sync times: `bwdc last-sync users` / `bwdc last-sync groups`
-
---
+- **LDAP**: Direct LDAP queries, bind authentication
+- **Microsoft Entra ID**: Microsoft Graph API, OAuth tokens
+- **Google Workspace**: Google Admin SDK, service account credentials
+- **Okta/OneLogin**: REST APIs with API tokens

 ## References

-### Official Documentation
-
- [Directory Sync CLI Documentation](https://bitwarden.com/help/directory-sync-cli/)
- [Directory Connector Help](https://bitwarden.com/help/directory-sync/)
-
-### Internal Documentation
-
- [Bitwarden Contributing Guidelines](https://contributing.bitwarden.com/contributing/)
- [Code Style Guide](https://contributing.bitwarden.com/contributing/code-style/)
-
-### Tools & Libraries
-
- [ldapts](https://github.com/ldapts/ldapts) - LDAP client for Node.js
- [Keytar](https://github.com/atom/node-keytar) - Native keychain access
- [Commander.js](https://github.com/tj/commander.js) - CLI framework
- [LowDB](https://github.com/typicode/lowdb) - JSON database
- [Microsoft Graph Client](https://github.com/microsoftgraph/msgraph-sdk-javascript) - Entra ID API
- [Google APIs](https://github.com/googleapis/google-api-nodejs-client) - GSuite API
+- [Architectural Decision Records (ADRs)](https://contributing.bitwarden.com/architecture/adr/)
+- [Contributing Guidelines](https://contributing.bitwarden.com/contributing/)
+- [Code Style](https://contributing.bitwarden.com/contributing/code-style/)
+- [Security Whitepaper](https://bitwarden.com/help/bitwarden-security-white-paper/)
+- [Security Definitions](https://contributing.bitwarden.com/architecture/security/definitions)
--- a/.claude/commands/code-explainer.md
+++ b/.claude/commands/code-explainer.md
@@ -1,30 +0,0 @@
---
-description: "Provides a brief explanation of the code attached, including key components, notable patterns, and a code walkthrough."
---
-
-# Code Explainer
-
-Provide a brief explanation of the code attached. I'm trying to better understand it.
-
-## Key Components
-
- Main classes/functions and their roles
- Important dependencies
- Critical flows
-
-## Notable Patterns
-
- Design patterns used
- Architecture decisions
- Important abstractions
-
-## Code Walkthrough
-
- How it works
- Key decision points
- Important considerations
-
-## Gotchas & Tips
-
- Edge cases to watch for
- Performance considerations
--- a/ESM_MIGRATION_PLAN.md
+++ b/ESM_MIGRATION_PLAN.md
@@ -1,156 +0,0 @@
-# ESM Migration Plan
-
-## Migration Status: Partial Success
-
-The ESM migration has been **partially completed**. The source code is now ESM-compatible with `"type": "module"` in package.json, and webpack outputs CommonJS bundles (`.cjs`) for Node.js compatibility.
-
-### What Works
-
- ✅ CLI build (`bwdc.cjs`) - builds and runs successfully
- ✅ Electron main process (`main.cjs`) - builds successfully
- ✅ All 130 tests pass
- ✅ Source code uses ESM syntax (import/export)
-
-### What Doesn't Work
-
- ❌ Electron renderer build - **pre-existing type errors in jslib** (not caused by this migration)
-
-The renderer build was failing with 37 TypeScript errors in `jslib/` **before** the ESM migration began. These are ArrayBuffer/SharedArrayBuffer type compatibility issues in the jslib submodule that need to be addressed separately.
-
---
-
-## Changes Made
-
-### 1. package.json
-
-```json
-{
-  "type": "module",
-  "main": "main.cjs"
-}
-```
-
-### 2. tsconfig.json
-
-```json
-{
-  "compilerOptions": {
-    "moduleResolution": "node",
-    "module": "ES2020",
-    "skipLibCheck": true,
-    "noEmitOnError": false
-  }
-}
-```
-
-### 3. Webpack Configurations
-
-**CLI (webpack.cli.cjs)**
-
- Output changed to `.cjs` extension
- Added `transpileOnly: true` to ts-loader for faster builds
-
-**Main (webpack.main.cjs)**
-
- Output changed to `.cjs` extension
- Added `transpileOnly: true` to ts-loader
-
-**Renderer (webpack.renderer.cjs)**
-
- Created separate `tsconfig.renderer.json` to isolate Angular compilation
- Removed ESM output experiments (not compatible with Angular's webpack plugin)
-
-### 4. src-cli/package.json
-
-```json
-{
-  "type": "module",
-  "bin": {
-    "bwdc": "../build-cli/bwdc.cjs"
-  }
-}
-```
-
-### 5. New File: tsconfig.renderer.json
-
-Dedicated TypeScript config for Angular renderer to isolate from jslib type issues.
-
---
-
-## Architecture Decision
-
-### Why CJS Output Instead of ESM Output?
-
-The migration uses a **hybrid approach**:
-
- **Source code**: ESM syntax (`import`/`export`)
- **Build output**: CommonJS (`.cjs` files)
-
-This approach was chosen because:
-
-1. **lowdb v1 incompatibility**: The legacy lowdb v1 used in jslib doesn't work properly with ESM output due to lodash interop issues
-
-2. **Native module compatibility**: keytar and other native modules work better with CJS
-
-3. **Electron compatibility**: Electron's main process ESM support is still maturing
-
-4. **jslib constraints**: The jslib submodule is read-only and contains CJS-only patterns
-
-The webpack bundler transpiles ESM source to CJS output, giving us modern syntax in the codebase while maintaining runtime compatibility.
-
---
-
-## Blocking Issues for Full ESM
-
-### 1. jslib Submodule (Read-Only)
-
-The jslib folder contains:
-
- `lowdb` v1.0.0 usage (CJS-only, v7 is ESM but has breaking API changes)
- `node-fetch` v2.7.0 usage (CJS-only, v3 is ESM-only)
- Pre-existing TypeScript errors (ArrayBuffer type mismatches)
-
-### 2. Angular Webpack Plugin
-
-The `@ngtools/webpack` plugin does its own TypeScript compilation and doesn't support `transpileOnly` mode, so it surfaces type errors from jslib.
-
---
-
-## Future Work
-
-To complete full ESM migration:
-
-1. **Update jslib submodule** - Fix type errors, upgrade to ESM-compatible dependencies
-2. **Upgrade lowdb** - From v1 to v7 (requires rewriting storage layer)
-3. **Remove node-fetch** - Use native `fetch` (Node 18+) or upgrade to v3
-4. **Enable ESM output** - Once dependencies are updated, change webpack output to ESM
-
---
-
-## Testing the Migration
-
-```bash
-# Build CLI
-npm run build:cli
-node ./build-cli/bwdc.cjs --help
-
-# Build Electron main
-npm run build:main
-
-# Run tests
-npm test
-```
-
---
-
-## Files Changed
-
-| File                     | Change                                               |
-| ------------------------ | ---------------------------------------------------- |
-| `package.json`           | Added `"type": "module"`, changed main to `main.cjs` |
-| `tsconfig.json`          | Added `skipLibCheck`, `noEmitOnError`                |
-| `tsconfig.renderer.json` | New file for Angular compilation                     |
-| `webpack.cli.cjs`        | Output to `.cjs`, added `transpileOnly`              |
-| `webpack.main.cjs`       | Output to `.cjs`, added `transpileOnly`              |
-| `webpack.renderer.cjs`   | Use separate tsconfig                                |
-| `src-cli/package.json`   | Added `"type": "module"`, updated bin path           |
--- a/docs/google-workspace.md
+++ b/docs/google-workspace.md
@@ -0,0 +1,300 @@
+# Google Workspace Directory Integration
+
+This document provides technical documentation for the Google Workspace (formerly G Suite) directory integration in Bitwarden Directory Connector.
+
+## Overview
+
+The Google Workspace integration synchronizes users and groups from Google Workspace to Bitwarden organizations using the Google Admin SDK Directory API. The service uses a service account with domain-wide delegation to authenticate and access directory data.
+
+## Architecture
+
+### Service Location
+
+- **Implementation**: `src/services/directory-services/gsuite-directory.service.ts`
+- **Configuration Model**: `src/models/gsuiteConfiguration.ts`
+- **Integration Tests**: `src/services/directory-services/gsuite-directory.service.integration.spec.ts`
+
+### Authentication Flow
+
+The Google Workspace integration uses **OAuth 2.0 with Service Accounts** and domain-wide delegation:
+
+1. A service account is created in Google Cloud Console
+2. The service account is granted domain-wide delegation authority
+3. The service account is authorized for specific OAuth scopes in Google Workspace Admin Console
+4. The Directory Connector uses the service account's private key to generate JWT tokens
+5. JWT tokens are exchanged for access tokens to call the Admin SDK APIs
+
+### Required OAuth Scopes
+
+The service account must be granted the following OAuth 2.0 scopes:
+
+```
+https://www.googleapis.com/auth/admin.directory.user.readonly
+https://www.googleapis.com/auth/admin.directory.group.readonly
+https://www.googleapis.com/auth/admin.directory.group.member.readonly
+```
+
+## Configuration
+
+### Required Fields
+
+| Field         | Description                                                                             |
+| ------------- | --------------------------------------------------------------------------------------- |
+| `clientEmail` | Service account email address (e.g., `service-account@project.iam.gserviceaccount.com`) |
+| `privateKey`  | Service account private key in PEM format                                               |
+| `adminUser`   | Admin user email to impersonate for domain-wide delegation                              |
+| `domain`      | Primary domain of the Google Workspace organization                                     |
+
+### Optional Fields
+
+| Field      | Description                                                |
+| ---------- | ---------------------------------------------------------- |
+| `customer` | Customer ID for multi-domain organizations (rarely needed) |
+
+### Example Configuration
+
+```typescript
+{
+  clientEmail: "directory-connector@my-project.iam.gserviceaccount.com",
+  privateKey: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
+  adminUser: "admin@example.com",
+  domain: "example.com",
+  customer: "" // Usually not required
+}
+```
+
+## Setup Instructions
+
+### 1. Create a Service Account
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com)
+2. Create or select a project
+3. Navigate to **IAM & Admin** > **Service Accounts**
+4. Click **Create Service Account**
+5. Enter a name and description
+6. Click **Create and Continue**
+7. Skip granting roles (not needed for this use case)
+8. Click **Done**
+
+### 2. Generate Service Account Key
+
+1. Click on the newly created service account
+2. Navigate to the **Keys** tab
+3. Click **Add Key** > **Create new key**
+4. Select **JSON** format
+5. Click **Create** and download the key file
+6. Extract `client_email` and `private_key` from the JSON file
+
+### 3. Enable Domain-Wide Delegation
+
+1. In the service account details, click **Show Advanced Settings**
+2. Under **Domain-wide delegation**, click **Enable Google Workspace Domain-wide Delegation**
+3. Note the **Client ID** (numeric ID)
+
+### 4. Authorize the Service Account in Google Workspace
+
+1. Go to [Google Workspace Admin Console](https://admin.google.com)
+2. Navigate to **Security** > **API Controls** > **Domain-wide Delegation**
+3. Click **Add new**
+4. Enter the **Client ID** from step 3
+5. Enter the following OAuth scopes (comma-separated):
+   ```
+   https://www.googleapis.com/auth/admin.directory.user.readonly,
+   https://www.googleapis.com/auth/admin.directory.group.readonly,
+   https://www.googleapis.com/auth/admin.directory.group.member.readonly
+   ```
+6. Click **Authorize**
+
+### 5. Configure Directory Connector
+
+Use the extracted values to configure the Directory Connector:
+
+- **Client Email**: From `client_email` in the JSON key file
+- **Private Key**: From `private_key` in the JSON key file (keep the `\n` line breaks)
+- **Admin User**: Email of a super admin user in your Google Workspace domain
+- **Domain**: Your primary Google Workspace domain
+
+## Sync Behavior
+
+### User Synchronization
+
+The service synchronizes the following user attributes:
+
+| Google Workspace Field    | Bitwarden Field             | Notes                                     |
+| ------------------------- | --------------------------- | ----------------------------------------- |
+| `id`                      | `referenceId`, `externalId` | User's unique Google ID                   |
+| `primaryEmail`            | `email`                     | Normalized to lowercase                   |
+| `suspended` OR `archived` | `disabled`                  | User is disabled if suspended or archived |
+| Deleted status            | `deleted`                   | Set to true for deleted users             |
+
+**Special Behavior:**
+
+- The service queries both **active users** and **deleted users** separately
+- Suspended and archived users are included but marked as disabled
+- Deleted users are included with the `deleted` flag set to true
+
+### Group Synchronization
+
+The service synchronizes the following group attributes:
+
+| Google Workspace Field  | Bitwarden Field             | Notes                    |
+| ----------------------- | --------------------------- | ------------------------ |
+| `id`                    | `referenceId`, `externalId` | Group's unique Google ID |
+| `name`                  | `name`                      | Group display name       |
+| Members (type=USER)     | `userMemberExternalIds`     | Individual user members  |
+| Members (type=GROUP)    | `groupMemberReferenceIds`   | Nested group members     |
+| Members (type=CUSTOMER) | `userMemberExternalIds`     | All domain users         |
+
+**Member Types:**
+
+- **USER**: Individual user accounts (only ACTIVE status users are synced)
+- **GROUP**: Nested groups (allows group hierarchy)
+- **CUSTOMER**: Special member type that includes all users in the domain
+
+### Filtering
+
+#### User Filter Examples
+
+```
+exclude:testuser1@bwrox.dev | testuser1@bwrox.dev                   # Exclude multiple users
+|orgUnitPath='/Integration testing'                                 # Users in Integration testing Organizational unit (OU)
+exclude:testuser1@bwrox.dev | orgUnitPath='/Integration testing'    # Combined filter: get users in OU excluding provided user
+|email:testuser*                                                    # Users with email starting with "testuser"
+```
+
+#### Group Filter Examples
+
+An important note for group filters is that it implicitly only syncs users that are in groups. For example, in the case of
+the integration test data, `admin@bwrox.dev` is not a member of any group. Therefore, the first example filter below will
+also implicitly exclude `admin@bwrox.dev`, who is not in any group. This is important because when it is paired with an
+empty user filter, this query may semantically be understood as "sync everyone not in Integration Test Group A," while in
+practice it means "Only sync members of groups not in integration Test Groups A."
+
+```
+exclude:Integration Test Group A                                    # Get all users in groups excluding the provided group.
+```
+
+### User AND Group Filter Examples
+
+```
+
+```
+
+**Filter Syntax:**
+
+- Prefix with `|` for custom filters
+- Use `:` for pattern matching (supports `*` wildcard)
+- Combine multiple conditions with spaces (AND logic)
+
+### Pagination
+
+The service automatically handles pagination for all API calls:
+
+- Users API (active and deleted)
+- Groups API
+- Group Members API
+
+Each API call processes all pages using the `nextPageToken` mechanism until no more results are available.
+
+## Error Handling
+
+### Common Errors
+
+| Error                  | Cause                                 | Resolution                                                 |
+| ---------------------- | ------------------------------------- | ---------------------------------------------------------- |
+| "dirConfigIncomplete"  | Missing required configuration fields | Verify all required fields are provided                    |
+| "authenticationFailed" | Invalid credentials or unauthorized   | Check service account key and domain-wide delegation setup |
+| API returns 401/403    | Missing OAuth scopes                  | Verify scopes are authorized in Admin Console              |
+| API returns 404        | Invalid domain or customer ID         | Check domain configuration                                 |
+
+### Security Considerations
+
+The service implements the following security measures:
+
+1. **Credential sanitization**: Error messages do not expose private keys or sensitive credentials
+2. **Secure authentication**: Uses OAuth 2.0 with JWT tokens, not API keys
+3. **Read-only access**: Only requires read-only scopes for directory data
+4. **No credential logging**: Service account credentials are not logged
+
+## Testing
+
+### Integration Tests
+
+Integration tests are located in `src/services/directory-services/gsuite-directory.service.integration.spec.ts`.
+
+**Test Coverage:**
+
+- Basic sync (users and groups)
+- Sync with filters
+- Users-only sync
+- Groups-only sync
+- User filtering scenarios
+- Group filtering scenarios
+- Disabled users handling
+- Group membership scenarios
+- Error handling
+
+**Running Integration Tests:**
+
+Integration tests require live Google Workspace credentials:
+
+1. Create a `.env` file in the `utils/` folder with:
+   ```
+   GOOGLE_ADMIN_USER=admin@example.com
+   GOOGLE_CLIENT_EMAIL=service-account@project.iam.gserviceaccount.com
+   GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
+   GOOGLE_DOMAIN=example.com
+   ```
+2. Run tests:
+
+   ```bash
+   # Run all integration tests (includes LDAP, Google Workspace, etc.)
+   npm run test:integration
+
+   # Run only Google Workspace integration tests
+   npx jest gsuite-directory.service.integration.spec.ts
+   ```
+
+**Test Data:**
+
+The integration tests expect specific test data in Google Workspace:
+
+- **Users**: 5 test users in organizational unit `/Integration testing`
+  - testuser1@bwrox.dev (in Group A)
+  - testuser2@bwrox.dev (in Groups A & B)
+  - testuser3@bwrox.dev (in Group B)
+  - testuser4@bwrox.dev (no groups)
+  - testuser5@bwrox.dev (disabled)
+
+- **Groups**: 2 test groups with name pattern `Integration*`
+  - Integration Test Group A
+  - Integration Test Group B
+
+## API Reference
+
+### Google Admin SDK APIs Used
+
+- **Users API**: `admin.users.list()`
+  - [Documentation](https://developers.google.com/admin-sdk/directory/reference/rest/v1/users/list)
+
+- **Groups API**: `admin.groups.list()`
+  - [Documentation](https://developers.google.com/admin-sdk/directory/reference/rest/v1/groups/list)
+
+- **Members API**: `admin.members.list()`
+  - [Documentation](https://developers.google.com/admin-sdk/directory/reference/rest/v1/members/list)
+
+### Rate Limits
+
+Google Workspace Directory API rate limits:
+
+- Default: 2,400 queries per minute per user, per Google Cloud Project
+
+The service does not implement rate limiting logic; it relies on API error responses.
+
+## Resources
+
+- [Google Admin SDK Directory API Guide](https://developers.google.com/admin-sdk/directory/v1/guides)
+- [Service Account Authentication](https://developers.google.com/identity/protocols/oauth2/service-account)
+- [Domain-wide Delegation](https://support.google.com/a/answer/162106)
+- [Google Workspace Admin Console](https://admin.google.com)
+- [Bitwarden Directory Connector Documentation](https://bitwarden.com/help/directory-sync/)
--- a/jest.config.cjs
+++ b/jest.config.cjs
@@ -24,20 +24,13 @@ module.exports = {

  roots: ["<rootDir>"],
  modulePaths: [compilerOptions.baseUrl],
-  moduleNameMapper: {
-    ...pathsToModuleNameMapper(compilerOptions.paths, { prefix: "<rootDir>/" }),
-    // ESM compatibility: mock import.meta.url for tests
-    "^(\\.{1,2}/.*)\\.js$": "$1",
-  },
+  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, { prefix: "<rootDir>/" }),
  setupFilesAfterEnv: ["<rootDir>/test.setup.ts"],
  // Workaround for a memory leak that crashes tests in CI:
  // https://github.com/facebook/jest/issues/9430#issuecomment-1149882002
  // Also anecdotally improves performance when run locally
  maxWorkers: 3,

-  // ESM support
-  extensionsToTreatAsEsm: [".ts"],
-
  transform: {
    "^.+\\.tsx?$": [
      "jest-preset-angular",
@@ -50,8 +43,6 @@ module.exports = {
        // Makes tests run faster and reduces size/rate of leak, but loses typechecking on test code
        // See https://bitwarden.atlassian.net/browse/EC-497 for more info
        isolatedModules: true,
-        // ESM support
-        useESM: true,
      },
    ],
  },
--- a/jslib/common/spec/utils.ts
+++ b/jslib/common/spec/utils.ts
@@ -33,5 +33,5 @@ export function makeStaticByteArray(length: number, start = 0) {
  for (let i = 0; i < length; i++) {
    arr[i] = start + i;
  }
-  return arr;
+  return arr.buffer;
 }
--- a/jslib/common/src/misc/nodeUtils.ts
+++ b/jslib/common/src/misc/nodeUtils.ts
@@ -26,9 +26,4 @@ export class NodeUtils {
        .on("error", (err) => reject(err));
    });
  }
-
-  // https://stackoverflow.com/a/31394257
-  static bufferToArrayBuffer(buf: Buffer): ArrayBuffer {
-    return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
-  }
 }
--- a/jslib/common/src/misc/utils.ts
+++ b/jslib/common/src/misc/utils.ts
@@ -36,7 +36,7 @@ export class Utils {
    Utils.global = Utils.isNode && !Utils.isBrowser ? global : window;
  }

-  static fromB64ToArray(str: string): Uint8Array {
+  static fromB64ToArray(str: string): Uint8Array<ArrayBuffer> {
    if (Utils.isNode) {
      return new Uint8Array(Buffer.from(str, "base64"));
    } else {
@@ -49,11 +49,11 @@ export class Utils {
    }
  }

-  static fromUrlB64ToArray(str: string): Uint8Array {
+  static fromUrlB64ToArray(str: string): Uint8Array<ArrayBuffer> {
    return Utils.fromB64ToArray(Utils.fromUrlB64ToB64(str));
  }

-  static fromHexToArray(str: string): Uint8Array {
+  static fromHexToArray(str: string): Uint8Array<ArrayBuffer> {
    if (Utils.isNode) {
      return new Uint8Array(Buffer.from(str, "hex"));
    } else {
@@ -65,7 +65,7 @@ export class Utils {
    }
  }

-  static fromUtf8ToArray(str: string): Uint8Array {
+  static fromUtf8ToArray(str: string): Uint8Array<ArrayBuffer> {
    if (Utils.isNode) {
      return new Uint8Array(Buffer.from(str, "utf8"));
    } else {
@@ -78,7 +78,7 @@ export class Utils {
    }
  }

-  static fromByteStringToArray(str: string): Uint8Array {
+  static fromByteStringToArray(str: string): Uint8Array<ArrayBuffer> {
    const arr = new Uint8Array(str.length);
    for (let i = 0; i < str.length; i++) {
      arr[i] = str.charCodeAt(i);
@@ -99,8 +99,8 @@ export class Utils {
    }
  }

-  static fromBufferToUrlB64(buffer: ArrayBuffer): string {
-    return Utils.fromB64toUrlB64(Utils.fromBufferToB64(buffer));
+  static fromBufferToUrlB64(buffer: Uint8Array<ArrayBuffer>): string {
+    return Utils.fromB64toUrlB64(Utils.fromBufferToB64(buffer.buffer));
  }

  static fromB64toUrlB64(b64Str: string) {
--- a/jslib/common/src/services/crypto.service.ts
+++ b/jslib/common/src/services/crypto.service.ts
@@ -636,9 +636,9 @@ export class CryptoService implements CryptoServiceAbstraction {

    const encBytes = new Uint8Array(encBuf);
    const encType = encBytes[0];
-    let ctBytes: Uint8Array = null;
-    let ivBytes: Uint8Array = null;
-    let macBytes: Uint8Array = null;
+    let ctBytes: Uint8Array<ArrayBuffer> = null;
+    let ivBytes: Uint8Array<ArrayBuffer> = null;
+    let macBytes: Uint8Array<ArrayBuffer> = null;

    switch (encType) {
      case EncryptionType.AesCbc128_HmacSha256_B64:
--- a/jslib/node/spec/services/nodeCryptoFunction.service.spec.ts
+++ b/jslib/node/spec/services/nodeCryptoFunction.service.spec.ts
@@ -94,7 +94,7 @@ describe("NodeCrypto Function Service", () => {
    it("should fail with prk too small", async () => {
      const cryptoFunctionService = new NodeCryptoFunctionService();
      const f = cryptoFunctionService.hkdfExpand(
-        Utils.fromB64ToArray(prk16Byte),
+        Utils.fromB64ToArray(prk16Byte).buffer,
        "info",
        32,
        "sha256",
@@ -105,7 +105,7 @@ describe("NodeCrypto Function Service", () => {
    it("should fail with outputByteSize is too large", async () => {
      const cryptoFunctionService = new NodeCryptoFunctionService();
      const f = cryptoFunctionService.hkdfExpand(
-        Utils.fromB64ToArray(prk32Byte),
+        Utils.fromB64ToArray(prk32Byte).buffer,
        "info",
        8161,
        "sha256",
@@ -341,7 +341,7 @@ function testHkdf(
  utf8Key: string,
  unicodeKey: string,
 ) {
-  const ikm = Utils.fromB64ToArray("criAmKtfzxanbgea5/kelQ==");
+  const ikm = Utils.fromB64ToArray("criAmKtfzxanbgea5/kelQ==").buffer;

  const regularSalt = "salt";
  const utf8Salt = "üser_salt";
@@ -393,7 +393,7 @@ function testHkdfExpand(
  it("should create valid " + algorithm + " " + outputByteSize + " byte okm", async () => {
    const cryptoFunctionService = new NodeCryptoFunctionService();
    const okm = await cryptoFunctionService.hkdfExpand(
-      Utils.fromB64ToArray(b64prk),
+      Utils.fromB64ToArray(b64prk).buffer,
      info,
      outputByteSize,
      algorithm,
--- a/package-lock.json
+++ b/package-lock.json
@@ -105,7 +105,7 @@
        "ts-loader": "9.5.2",
        "tsconfig-paths-webpack-plugin": "4.2.0",
        "type-fest": "5.3.0",
-        "typescript": "5.8.3",
+        "typescript": "5.9.3",
        "webpack": "5.104.1",
        "webpack-cli": "6.0.1",
        "webpack-merge": "6.0.1",
@@ -600,6 +600,7 @@
      "integrity": "sha512-4JLXU0tD6OZNVqlwzm3HGEhAHufSiyv+skb7q0d2367VDMzrU1Q/ZeepvkcHH0rZie6uqEtTQQe0OEOOluH3Mg==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@types/eslint-scope": "^3.7.7",
        "@types/estree": "^1.0.8",
@@ -741,6 +742,7 @@
      "integrity": "sha512-CVskZnF38IIxVVlKWi1VCz7YH/gHMJu2IY9bD1AVoBBGIe0xA4FRXJkW2Y+EDs9vQqZTkZZljhK5gL65Ro1PeQ==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@angular-eslint/bundled-angular-compiler": "20.7.0",
        "eslint-scope": "^9.0.0"
@@ -770,6 +772,7 @@
      "resolved": "https://registry.npmjs.org/@angular/animations/-/animations-20.3.15.tgz",
      "integrity": "sha512-ikyKfhkxoqQA6JcBN0B9RaN6369sM1XYX81Id0lI58dmWCe7gYfrTp8ejqxxKftl514psQO3pkW8Gn1nJ131Gw==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "tslib": "^2.3.0"
      },
@@ -954,6 +957,7 @@
      "resolved": "https://registry.npmjs.org/@angular/common/-/common-20.3.15.tgz",
      "integrity": "sha512-k4mCXWRFiOHK3bUKfWkRQQ8KBPxW8TAJuKLYCsSHPCpMz6u0eA1F0VlrnOkZVKWPI792fOaEAWH2Y4PTaXlUHw==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "tslib": "^2.3.0"
      },
@@ -970,6 +974,7 @@
      "resolved": "https://registry.npmjs.org/@angular/compiler/-/compiler-20.3.15.tgz",
      "integrity": "sha512-lMicIAFAKZXa+BCZWs3soTjNQPZZXrF/WMVDinm8dQcggNarnDj4UmXgKSyXkkyqK5SLfnLsXVzrX6ndVT6z7A==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "tslib": "^2.3.0"
      },
@@ -983,6 +988,7 @@
      "integrity": "sha512-8sJoxodxsfyZ8eJ5r6Bx7BCbazXYgsZ1+dE8t5u5rTQ6jNggwNtYEzkyReoD5xvP+MMtRkos3xpwq4rtFnpI6A==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@babel/core": "7.28.3",
        "@jridgewell/sourcemap-codec": "^1.4.14",
@@ -1015,6 +1021,7 @@
      "resolved": "https://registry.npmjs.org/@angular/core/-/core-20.3.15.tgz",
      "integrity": "sha512-NMbX71SlTZIY9+rh/SPhRYFJU0pMJYW7z/TBD4lqiO+b0DTOIg1k7Pg9ydJGqSjFO1Z4dQaA6TteNuF99TJCNw==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "tslib": "^2.3.0"
      },
@@ -1058,6 +1065,7 @@
      "resolved": "https://registry.npmjs.org/@angular/platform-browser/-/platform-browser-20.3.15.tgz",
      "integrity": "sha512-TxRM/wTW/oGXv/3/Iohn58yWoiYXOaeEnxSasiGNS1qhbkcKtR70xzxW6NjChBUYAixz2ERkLURkpx3pI8Q6Dw==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "tslib": "^2.3.0"
      },
@@ -1080,6 +1088,7 @@
      "resolved": "https://registry.npmjs.org/@angular/platform-browser-dynamic/-/platform-browser-dynamic-20.3.15.tgz",
      "integrity": "sha512-RizuRdBt0d6ongQ2y8cr8YsXFyjF8f91vFfpSNw+cFj+oiEmRC1txcWUlH5bPLD9qSDied8qazUi0Tb8VPQDGw==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "tslib": "^2.3.0"
      },
@@ -1142,6 +1151,7 @@
      "integrity": "sha512-yDBHV9kQNcr2/sUr9jghVyz9C3Y5G2zUM2H2lo+9mKv4sFgbA8s8Z9t8D1jiTkGoO/NoIfKMyKWr4s6CN23ZwQ==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@ampproject/remapping": "^2.2.0",
        "@babel/code-frame": "^7.27.1",
@@ -3006,6 +3016,7 @@
      "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "fast-deep-equal": "^3.1.1",
        "fast-json-stable-stringify": "^2.0.0",
@@ -4440,6 +4451,7 @@
      "resolved": "https://registry.npmjs.org/@inquirer/prompts/-/prompts-7.8.2.tgz",
      "integrity": "sha512-nqhDw2ZcAUrKNPwhjinJny903bRhI0rQhiDz1LksjeRxqa36i3l75+4iXbOy0rlDpLJGxqtgoPavQjmmyS5UJw==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@inquirer/checkbox": "^4.2.1",
        "@inquirer/confirm": "^5.1.14",
@@ -4936,6 +4948,7 @@
      "integrity": "sha512-mpiz3dutLbkW2MNFubUGUEVLkTGiqW6yLVTA+JbP6fI6J5iL9Y0Nlg8k95pcF8ctKwCS7WVxteBs29hhfAotzQ==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@jest/environment": "^29.7.0",
        "@jest/expect": "^29.7.0",
@@ -7863,6 +7876,7 @@
      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.2.tgz",
      "integrity": "sha512-LPM2G3Syo1GLzXLGJAKdqoU35XvrWzGJ21/7sgZTUpbkBaOasTj8tjwn6w+hCkqaa1TfJ/w67rJSwYItlJ2mYw==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "undici-types": "~6.21.0"
      }
@@ -8113,6 +8127,7 @@
      "integrity": "sha512-6/cmF2piao+f6wSxUsJLZjck7OQsYyRtcOZS02k7XINSNlz93v6emM8WutDQSXnroG2xwYlEVHJI+cPA7CPM3Q==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@typescript-eslint/scope-manager": "8.50.0",
        "@typescript-eslint/types": "8.50.0",
@@ -8220,6 +8235,7 @@
      "integrity": "sha512-iX1mgmGrXdANhhITbpp2QQM2fGehBse9LbTf0sidWK6yg/NE+uhV5dfU1g6EYPlcReYmkE9QLPq/2irKAmtS9w==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
      },
@@ -8295,6 +8311,7 @@
      "integrity": "sha512-87KgUXET09CRjGCi2Ejxy3PULXna63/bMYv72tCAlDJC3Yqwln0HiFJ3VJMst2+mEtNtZu5oFvX4qJGjKsnAgg==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@eslint-community/eslint-utils": "^4.7.0",
        "@typescript-eslint/scope-manager": "8.50.0",
@@ -9037,6 +9054,7 @@
      "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "bin": {
        "acorn": "bin/acorn"
      },
@@ -9138,6 +9156,7 @@
      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz",
      "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "fast-deep-equal": "^3.1.3",
        "fast-uri": "^3.0.1",
@@ -9417,7 +9436,6 @@
      "integrity": "sha512-+25nxyyznAXF7Nef3y0EbBeqmGZgeN/BxHX29Rs39djAfaFalmQ89SE6CWyDCHzGL0yt/ycBtNOmGTW0FyGWNw==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "archiver-utils": "^2.1.0",
        "async": "^3.2.4",
@@ -9437,7 +9455,6 @@
      "integrity": "sha512-bEL/yUb/fNNiNTuUz979Z0Yg5L+LzLxGJz8x79lYmR54fmTIb6ob/hNQgkQnIUDWIFjZVQwl9Xs356I6BAMHfw==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "glob": "^7.1.4",
        "graceful-fs": "^4.2.0",
@@ -9460,7 +9477,6 @@
      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "balanced-match": "^1.0.0",
        "concat-map": "0.0.1"
@@ -9473,7 +9489,6 @@
      "deprecated": "Glob versions prior to v9 are no longer supported",
      "dev": true,
      "license": "ISC",
-      "peer": true,
      "dependencies": {
        "fs.realpath": "^1.0.0",
        "inflight": "^1.0.4",
@@ -9494,8 +9509,7 @@
      "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
      "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==",
      "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
    },
    "node_modules/archiver-utils/node_modules/minimatch": {
      "version": "3.1.2",
@@ -9503,7 +9517,6 @@
      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
      "dev": true,
      "license": "ISC",
-      "peer": true,
      "dependencies": {
        "brace-expansion": "^1.1.7"
      },
@@ -9517,7 +9530,6 @@
      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "core-util-is": "~1.0.0",
        "inherits": "~2.0.3",
@@ -9533,8 +9545,7 @@
      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
      "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
    },
    "node_modules/archiver-utils/node_modules/string_decoder": {
      "version": "1.1.1",
@@ -9542,7 +9553,6 @@
      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "safe-buffer": "~5.1.0"
      }
@@ -10310,6 +10320,7 @@
        }
      ],
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "baseline-browser-mapping": "^2.9.0",
        "caniuse-lite": "^1.0.30001759",
@@ -10808,6 +10819,7 @@
      "integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
      "devOptional": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "readdirp": "^4.0.1"
      },
@@ -11190,7 +11202,6 @@
      "integrity": "sha512-D3uMHtGc/fcO1Gt1/L7i1e33VOvD4A9hfQLP+6ewd+BvG/gQ84Yh4oftEhAdjSMgBgwGL+jsppT7JYNpo6MHHg==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "buffer-crc32": "^0.2.13",
        "crc32-stream": "^4.0.2",
@@ -11664,7 +11675,6 @@
      "integrity": "sha512-ROmzCKrTnOwybPcJApAA6WBWij23HVfGVNKqqrZpuyZOHqK2CwHSvpGuyt/UNNvaIjEd8X5IFGp4Mh+Ie1IHJQ==",
      "dev": true,
      "license": "Apache-2.0",
-      "peer": true,
      "bin": {
        "crc32": "bin/crc32.njs"
      },
@@ -11678,7 +11688,6 @@
      "integrity": "sha512-NT7w2JVU7DFroFdYkeq8cywxrgjPHWkdX1wjpRQXPX5Asews3tA+Ght6lddQO5Mkumffp3X7GEqku3epj2toIw==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "crc-32": "^1.2.0",
        "readable-stream": "^3.4.0"
@@ -12325,6 +12334,7 @@
      "integrity": "sha512-rcJUkMfnJpfCboZoOOPf4L29TRtEieHNOeAbYPWPxlaBw/Z1RKrRA86dOI9rwaI4tQSc/RD82zTNHprfUHXsoQ==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "app-builder-lib": "24.13.3",
        "builder-util": "24.13.1",
@@ -12664,7 +12674,6 @@
      "integrity": "sha512-oHkV0iogWfyK+ah9ZIvMDpei1m9ZRpdXcvde1wTpra2U8AFDNNpqJdnin5z+PM1GbQ5BoaKCWas2HSjtR0HwMg==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "app-builder-lib": "24.13.3",
        "archiver": "^5.3.1",
@@ -12678,7 +12687,6 @@
      "integrity": "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "graceful-fs": "^4.2.0",
        "jsonfile": "^6.0.1",
@@ -13394,6 +13402,7 @@
      "integrity": "sha512-BhHmn2yNOFA9H9JmmIVKJmd288g9hrVRDkdoIgRCRuSySRUHH7r/DI6aAXW9T1WwUuY3DFgrcaqB+deURBLR5g==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@eslint-community/eslint-utils": "^4.8.0",
        "@eslint-community/regexpp": "^4.12.1",
@@ -13580,6 +13589,7 @@
      "integrity": "sha512-whOE1HFo/qJDyX4SnXzP4N6zOWn79WhnCUY/iDR0mPfQZO8wcYE4JClzI2oZrhBnnMUCBCHZhO6VQyoBU95mZA==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@rtsao/scc": "^1.1.0",
        "array-includes": "^3.1.9",
@@ -14065,6 +14075,7 @@
      "resolved": "https://registry.npmjs.org/express/-/express-5.1.0.tgz",
      "integrity": "sha512-DT9ck5YIRU+8GYzzU5kT3eHGA5iL+1Zd0EutOmTE9Dtk+Tvuzd23VBU+ec7HPNSTxXYO55gPV/hq4pSBJDjFpA==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "accepts": "^2.0.0",
        "body-parser": "^2.2.0",
@@ -15553,6 +15564,7 @@
      "integrity": "sha512-QSf1yjtSAsmf7rYBV7XX86uua4W/vkhIt0xNXKbsi2foEeW7vjJQz4bhnpL3xH+l1ryl1680uNv968Z+X6jSYg==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@types/html-minifier-terser": "^6.0.0",
        "html-minifier-terser": "^6.0.2",
@@ -16963,6 +16975,7 @@
      "integrity": "sha512-NIy3oAFp9shda19hy4HK0HRTWKtPJmGdnvywu01nOqNC2vZg+Z+fvJDxpMQA88eb2I9EcafcdjYgsDthnYTvGw==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@jest/core": "^29.7.0",
        "@jest/types": "^29.6.3",
@@ -17261,6 +17274,7 @@
      "integrity": "sha512-k9iQbsf9OyOfdzWH8HDmrRT0gSIcX+FLNW7IQq94tFX0gynPwqDTW0Ho6iMVNjGz/nb+l/vW3dWM2bbLLpkbXA==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@jest/environment": "^29.7.0",
        "@jest/fake-timers": "^29.7.0",
@@ -17827,6 +17841,7 @@
      "integrity": "sha512-/imKNG4EbWNrVjoNC/1H5/9GFy+tqjGBHCaSsN+P2RnPqjsLmv6UD3Ej+Kj8nBWaRAwyk7kK5ZUc+OEatnTR3A==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "bin": {
        "jiti": "bin/jiti.js"
      }
@@ -18146,7 +18161,6 @@
      "integrity": "sha512-b94GiNHQNy6JNTrt5w6zNyffMrNkXZb3KTkCZJb2V1xaEGCk093vkZ2jk3tpaeP33/OiXC+WvK9AxUebnf5nbw==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "readable-stream": "^2.0.5"
      },
@@ -18159,8 +18173,7 @@
      "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
      "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==",
      "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
    },
    "node_modules/lazystream/node_modules/readable-stream": {
      "version": "2.3.8",
@@ -18168,7 +18181,6 @@
      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "core-util-is": "~1.0.0",
        "inherits": "~2.0.3",
@@ -18184,8 +18196,7 @@
      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
      "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
    },
    "node_modules/lazystream/node_modules/string_decoder": {
      "version": "1.1.1",
@@ -18193,7 +18204,6 @@
      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "safe-buffer": "~5.1.0"
      }
@@ -18272,6 +18282,7 @@
      "integrity": "sha512-kdTwsyRuncDfjEs0DlRILWNvxhDG/Zij4YLO4TMJgDLW+8OzpfkdPnRgrsRuY1o+oaxJGWsps5f/RVBgGmmN0w==",
      "dev": true,
      "license": "Apache-2.0",
+      "peer": true,
      "dependencies": {
        "copy-anything": "^2.0.1",
        "parse-node-version": "^1.0.1",
@@ -18637,6 +18648,7 @@
      "resolved": "https://registry.npmjs.org/listr2/-/listr2-9.0.1.tgz",
      "integrity": "sha512-SL0JY3DaxylDuo/MecFeiC+7pedM0zia33zl0vcjgwcq1q1FWWF1To9EIauPbl8GbMCU0R2e0uJ8bZunhYKD2g==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "cli-truncate": "^4.0.0",
        "colorette": "^2.0.20",
@@ -18872,16 +18884,14 @@
      "resolved": "https://registry.npmjs.org/lodash.defaults/-/lodash.defaults-4.2.0.tgz",
      "integrity": "sha512-qjxPLHd3r5DnsdGacqOMU6pb/avJzdh9tFX2ymgoZE27BmjXrNy/y4LoaiTeAb+O3gL8AfpJGtqfX/ae2leYYQ==",
      "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
    },
    "node_modules/lodash.difference": {
      "version": "4.5.0",
      "resolved": "https://registry.npmjs.org/lodash.difference/-/lodash.difference-4.5.0.tgz",
      "integrity": "sha512-dS2j+W26TQ7taQBGN8Lbbq04ssV3emRw4NY58WErlTO29pIqS0HmoT5aJ9+TUQ1N3G+JOZSji4eugsWwGp9yPA==",
      "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
    },
    "node_modules/lodash.escaperegexp": {
      "version": "4.1.2",
@@ -18895,8 +18905,7 @@
      "resolved": "https://registry.npmjs.org/lodash.flatten/-/lodash.flatten-4.4.0.tgz",
      "integrity": "sha512-C5N2Z3DgnnKr0LOpv/hKCgKdb7ZZwafIrsesve6lmzvZIRZRGaZ/l6Q8+2W7NaT+ZwO3fFlSCzCzrDCFdJfZ4g==",
      "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
    },
    "node_modules/lodash.isequal": {
      "version": "4.5.0",
@@ -18911,8 +18920,7 @@
      "resolved": "https://registry.npmjs.org/lodash.isplainobject/-/lodash.isplainobject-4.0.6.tgz",
      "integrity": "sha512-oSXzaWypCMHkPC3NvBEaPHf0KsA5mvPrOPgQWDsbg8n7orZ290M0BmC/jgRZ4vcJ6DTAhjrsSYgdsW/F+MFOBA==",
      "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
    },
    "node_modules/lodash.memoize": {
      "version": "4.1.2",
@@ -18933,8 +18941,7 @@
      "resolved": "https://registry.npmjs.org/lodash.union/-/lodash.union-4.6.0.tgz",
      "integrity": "sha512-c4pB2CdGrGdjMKYLA+XiRDO7Y0PRQbm/Gzg8qMj+QH+pFVAoTp5sBpO0odL3FjoPCGjK96p6qsP+yQoiLoOBcw==",
      "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
    },
    "node_modules/log-symbols": {
      "version": "6.0.0",
@@ -21482,6 +21489,7 @@
        }
      ],
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "nanoid": "^3.3.11",
        "picocolors": "^1.1.1",
@@ -22052,7 +22060,6 @@
      "integrity": "sha512-v05I2k7xN8zXvPD9N+z/uhXPaj0sUFCe2rcWZIpBsqxfP7xXFQ0tipAd/wjj1YxWyWtUS5IDJpOG82JKt2EAVA==",
      "dev": true,
      "license": "Apache-2.0",
-      "peer": true,
      "dependencies": {
        "minimatch": "^5.1.0"
      }
@@ -22764,6 +22771,7 @@
      "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.2.tgz",
      "integrity": "sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA==",
      "license": "Apache-2.0",
+      "peer": true,
      "dependencies": {
        "tslib": "^2.1.0"
      }
@@ -22865,6 +22873,7 @@
      "integrity": "sha512-uf6HoO8fy6ClsrShvMgaKUn14f2EHQLQRtpsZZLeU/Mv0Q1K5P0+x2uvH6Cub39TVVbWNSrraUhDAoFph6vh0A==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "chokidar": "^4.0.0",
        "immutable": "^5.0.2",
@@ -24292,6 +24301,7 @@
      "integrity": "sha512-+6erLbBm0+LROX2sPXlUYx/ux5PyE9K/a92Wrt6oA+WDAoFTdpHE5tCYCI5PNzq2y8df4rA+QgHLJuR4jNymsg==",
      "dev": true,
      "license": "BSD-2-Clause",
+      "peer": true,
      "dependencies": {
        "@jridgewell/source-map": "^0.3.3",
        "acorn": "^8.14.0",
@@ -24858,7 +24868,8 @@
      "version": "2.8.1",
      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
-      "license": "0BSD"
+      "license": "0BSD",
+      "peer": true
    },
    "node_modules/tuf-js": {
      "version": "3.1.0",
@@ -25025,11 +25036,12 @@
      "license": "MIT"
    },
    "node_modules/typescript": {
-      "version": "5.8.3",
-      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.8.3.tgz",
-      "integrity": "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ==",
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
      "dev": true,
      "license": "Apache-2.0",
+      "peer": true,
      "bin": {
        "tsc": "bin/tsc",
        "tsserver": "bin/tsserver"
@@ -25171,6 +25183,7 @@
      "dev": true,
      "hasInstallScript": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "napi-postinstall": "^0.3.0"
      },
@@ -25380,6 +25393,7 @@
      "integrity": "sha512-4cKBO9wR75r0BeIWWWId9XK9Lj6La5X846Zw9dFfzMRw38IlTk2iCcUt6hsyiDRcPidc55ZParFYDXi0nXOeLQ==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "esbuild": "^0.25.0",
        "fdir": "^6.5.0",
@@ -25545,6 +25559,7 @@
      "integrity": "sha512-Qphch25abbMNtekmEGJmeRUhLDbe+QfiWTiqpKYkpCOWY64v9eyl+KRRLmqOFA2AvKPpc9DC6+u2n76tQLBoaA==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@types/eslint-scope": "^3.7.7",
        "@types/estree": "^1.0.8",
@@ -25594,6 +25609,7 @@
      "integrity": "sha512-MfwFQ6SfwinsUVi0rNJm7rHZ31GyTcpVE5pgVA3hwFRb7COD4TzjUUwhGWKfO50+xdc2MQPuEBBJoqIMGt3JDw==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@discoveryjs/json-ext": "^0.6.1",
        "@webpack-cli/configtest": "^3.0.1",
@@ -25700,6 +25716,7 @@
      "integrity": "sha512-QcQ72gh8a+7JO63TAx/6XZf/CWhgMzu5m0QirvPfGvptOusAxG12w2+aua1Jkjr7hzaWDnJ2n6JFeexMHI+Zjg==",
      "dev": true,
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@types/bonjour": "^3.5.13",
        "@types/connect-history-api-fallback": "^1.5.4",
@@ -26697,6 +26714,7 @@
      "integrity": "sha512-lcYcMxX2PO9XMGvAJkJ3OsNMw+/7FKes7/hgerGUYWIoWu5j/+YQqcZr5JnPZWzOsEBgMbSbiSTn/dv/69Mkpw==",
      "dev": true,
      "license": "ISC",
+      "peer": true,
      "bin": {
        "yaml": "bin.mjs"
      },
@@ -26832,7 +26850,6 @@
      "integrity": "sha512-9qv4rlDiopXg4E69k+vMHjNN63YFMe9sZMrdlvKnCjlCRWeCBswPPMPUfx+ipsAWq1LXHe70RcbaHdJJpS6hyQ==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "archiver-utils": "^3.0.4",
        "compress-commons": "^4.1.2",
@@ -26848,7 +26865,6 @@
      "integrity": "sha512-KVgf4XQVrTjhyWmx6cte4RxonPLR9onExufI1jhvw/MQ4BB6IsZD5gT8Lq+u/+pRkWna/6JoHpiQioaqFP5Rzw==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "glob": "^7.2.3",
        "graceful-fs": "^4.2.0",
@@ -26871,7 +26887,6 @@
      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "balanced-match": "^1.0.0",
        "concat-map": "0.0.1"
@@ -26884,7 +26899,6 @@
      "deprecated": "Glob versions prior to v9 are no longer supported",
      "dev": true,
      "license": "ISC",
-      "peer": true,
      "dependencies": {
        "fs.realpath": "^1.0.0",
        "inflight": "^1.0.4",
@@ -26906,7 +26920,6 @@
      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
      "dev": true,
      "license": "ISC",
-      "peer": true,
      "dependencies": {
        "brace-expansion": "^1.1.7"
      },
@@ -26919,6 +26932,7 @@
      "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
      "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
      "license": "MIT",
+      "peer": true,
      "funding": {
        "url": "https://github.com/sponsors/colinhacks"
      }
@@ -26937,7 +26951,8 @@
      "resolved": "https://registry.npmjs.org/zone.js/-/zone.js-0.15.1.tgz",
      "integrity": "sha512-XE96n56IQpJM7NAoXswY3XRLcWFW83xe0BiAOeMD7K5k5xecOeul3Qcpx6GqEeeHNkW5DWL5zOyTbEfB4eti8w==",
      "devOptional": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
    }
  }
 }
--- a/package.json
+++ b/package.json
@@ -3,7 +3,6 @@
  "productName": "Bitwarden Directory Connector",
  "description": "Sync your user directory to your Bitwarden organization.",
  "version": "2025.12.0",
-  "type": "module",
  "keywords": [
    "bitwarden",
    "password",
@@ -17,7 +16,7 @@
    "url": "https://github.com/bitwarden/directory-connector"
  },
  "license": "GPL-3.0",
-  "main": "main.cjs",
+  "main": "main.js",
  "scripts": {
    "sub:init": "git submodule update --init --recursive",
    "sub:update": "git submodule update --remote",
@@ -136,7 +135,7 @@
    "ts-loader": "9.5.2",
    "tsconfig-paths-webpack-plugin": "4.2.0",
    "type-fest": "5.3.0",
-    "typescript": "5.8.3",
+    "typescript": "5.9.3",
    "webpack": "5.104.1",
    "webpack-cli": "6.0.1",
    "webpack-merge": "6.0.1",
--- a/src-cli/package.json
+++ b/src-cli/package.json
@@ -3,17 +3,16 @@
  "productName": "Bitwarden Directory Connector",
  "description": "Sync your user directory to your Bitwarden organization.",
  "version": "2.9.5",
-  "type": "module",
  "author": "Bitwarden Inc. <hello@bitwarden.com> (https://bitwarden.com)",
  "homepage": "https://bitwarden.com",
  "license": "GPL-3.0",
-  "main": "main.mjs",
+  "main": "main.js",
  "repository": {
    "type": "git",
    "url": "https://github.com/bitwarden/directory-connector"
  },
  "bin": {
-    "bwdc": "../build-cli/bwdc.cjs"
+    "bwdc": "../build-cli/bwdc.js"
  },
  "pkg": {
    "assets": "../build-cli/**/*"
--- a/src/services/directory-services/gsuite-directory.service.integration.spec.ts
+++ b/src/services/directory-services/gsuite-directory.service.integration.spec.ts
@@ -50,36 +50,221 @@ describe("gsuiteDirectoryService", () => {
    directoryService = new GSuiteDirectoryService(logService, i18nService, stateService);
  });

-  it("syncs without using filters (includes test data)", async () => {
-    const directoryConfig = getGSuiteConfiguration();
-    stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(directoryConfig);
+  describe("basic sync fetching users and groups", () => {
+    it("syncs without using filters (includes test data)", async () => {
+      const directoryConfig = getGSuiteConfiguration();
+      stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(directoryConfig);

-    const syncConfig = getSyncConfiguration({
-      groups: true,
-      users: true,
+      const syncConfig = getSyncConfiguration({
+        groups: true,
+        users: true,
+      });
+      stateService.getSync.mockResolvedValue(syncConfig);
+
+      const result = await directoryService.getEntries(true, true);
+
+      expect(result[0]).toEqual(expect.arrayContaining(groupFixtures));
+      expect(result[1]).toEqual(expect.arrayContaining(userFixtures));
    });
-    stateService.getSync.mockResolvedValue(syncConfig);

-    const result = await directoryService.getEntries(true, true);
+    it("syncs using user and group filters (exact match for test data)", async () => {
+      const directoryConfig = getGSuiteConfiguration();
+      stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(directoryConfig);

-    expect(result[0]).toEqual(expect.arrayContaining(groupFixtures));
-    expect(result[1]).toEqual(expect.arrayContaining(userFixtures));
+      const syncConfig = getSyncConfiguration({
+        groups: true,
+        users: true,
+        userFilter: INTEGRATION_USER_FILTER,
+        groupFilter: INTEGRATION_GROUP_FILTER,
+      });
+      stateService.getSync.mockResolvedValue(syncConfig);
+
+      const result = await directoryService.getEntries(true, true);
+
+      expect(result).toEqual([groupFixtures, userFixtures]);
+    });
+
+    it("syncs only users when groups sync is disabled", async () => {
+      const directoryConfig = getGSuiteConfiguration();
+      stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(directoryConfig);
+
+      const syncConfig = getSyncConfiguration({
+        groups: false,
+        users: true,
+        userFilter: INTEGRATION_USER_FILTER,
+      });
+      stateService.getSync.mockResolvedValue(syncConfig);
+
+      const result = await directoryService.getEntries(true, true);
+
+      expect(result[0]).toBeUndefined();
+      expect(result[1]).toEqual(expect.arrayContaining(userFixtures));
+    });
+
+    it("syncs only groups when users sync is disabled", async () => {
+      const directoryConfig = getGSuiteConfiguration();
+      stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(directoryConfig);
+
+      const syncConfig = getSyncConfiguration({
+        groups: true,
+        users: false,
+        groupFilter: INTEGRATION_GROUP_FILTER,
+      });
+      stateService.getSync.mockResolvedValue(syncConfig);
+
+      const result = await directoryService.getEntries(true, true);
+
+      expect(result[0]).toEqual(expect.arrayContaining(groupFixtures));
+      expect(result[1]).toEqual([]);
+    });
  });

-  it("syncs using user and group filters (exact match for test data)", async () => {
-    const directoryConfig = getGSuiteConfiguration();
-    stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(directoryConfig);
+  describe("users", () => {
+    it("includes disabled users in sync results", async () => {
+      const directoryConfig = getGSuiteConfiguration();
+      stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(directoryConfig);

-    const syncConfig = getSyncConfiguration({
-      groups: true,
-      users: true,
-      userFilter: INTEGRATION_USER_FILTER,
-      groupFilter: INTEGRATION_GROUP_FILTER,
+      const syncConfig = getSyncConfiguration({
+        users: true,
+        userFilter: INTEGRATION_USER_FILTER,
+      });
+      stateService.getSync.mockResolvedValue(syncConfig);
+
+      const result = await directoryService.getEntries(true, true);
+
+      const disabledUser = userFixtures.find((u) => u.email === "testuser5@bwrox.dev");
+      expect(result[1]).toContainEqual(disabledUser);
+      expect(disabledUser.disabled).toBe(true);
    });
-    stateService.getSync.mockResolvedValue(syncConfig);

-    const result = await directoryService.getEntries(true, true);
+    it("filters users by org unit path", async () => {
+      const directoryConfig = getGSuiteConfiguration();
+      stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(directoryConfig);

-    expect(result).toEqual([groupFixtures, userFixtures]);
+      const syncConfig = getSyncConfiguration({
+        users: true,
+        userFilter: INTEGRATION_USER_FILTER,
+      });
+      stateService.getSync.mockResolvedValue(syncConfig);
+
+      const result = await directoryService.getEntries(true, true);
+
+      expect(result[1]).toEqual(userFixtures);
+      expect(result[1].length).toBe(5);
+    });
+
+    it("filters users by email pattern", async () => {
+      const directoryConfig = getGSuiteConfiguration();
+      stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(directoryConfig);
+
+      const syncConfig = getSyncConfiguration({
+        users: true,
+        userFilter: "|email:testuser1*",
+      });
+      stateService.getSync.mockResolvedValue(syncConfig);
+
+      const result = await directoryService.getEntries(true, true);
+
+      const testuser1 = userFixtures.find((u) => u.email === "testuser1@bwrox.dev");
+      expect(result[1]).toContainEqual(testuser1);
+      expect(result[1].length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe("groups", () => {
+    it("filters groups by name pattern", async () => {
+      const directoryConfig = getGSuiteConfiguration();
+      stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(directoryConfig);
+
+      const syncConfig = getSyncConfiguration({
+        groups: true,
+        users: true,
+        userFilter: INTEGRATION_USER_FILTER,
+        groupFilter: INTEGRATION_GROUP_FILTER,
+      });
+      stateService.getSync.mockResolvedValue(syncConfig);
+
+      const result = await directoryService.getEntries(true, true);
+
+      expect(result[0]).toEqual(groupFixtures);
+      expect(result[0].length).toBe(2);
+    });
+
+    it("includes group members correctly", async () => {
+      const directoryConfig = getGSuiteConfiguration();
+      stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(directoryConfig);
+
+      const syncConfig = getSyncConfiguration({
+        groups: true,
+        users: true,
+        userFilter: INTEGRATION_USER_FILTER,
+        groupFilter: INTEGRATION_GROUP_FILTER,
+      });
+      stateService.getSync.mockResolvedValue(syncConfig);
+
+      const result = await directoryService.getEntries(true, true);
+
+      const groupA = result[0].find((g) => g.name === "Integration Test Group A");
+      expect(groupA).toBeDefined();
+      expect(groupA.userMemberExternalIds.size).toBe(2);
+      expect(groupA.userMemberExternalIds.has("111605910541641314041")).toBe(true);
+      expect(groupA.userMemberExternalIds.has("111147009830456099026")).toBe(true);
+
+      const groupB = result[0].find((g) => g.name === "Integration Test Group B");
+      expect(groupB).toBeDefined();
+      expect(groupB.userMemberExternalIds.size).toBe(2);
+      expect(groupB.userMemberExternalIds.has("111147009830456099026")).toBe(true);
+      expect(groupB.userMemberExternalIds.has("100150970267699397306")).toBe(true);
+    });
+
+    it("handles groups with no members", async () => {
+      const directoryConfig = getGSuiteConfiguration();
+      stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(directoryConfig);
+
+      const syncConfig = getSyncConfiguration({
+        groups: true,
+        users: true,
+        userFilter: INTEGRATION_USER_FILTER,
+        groupFilter: "|name:Integration*",
+      });
+      stateService.getSync.mockResolvedValue(syncConfig);
+
+      const result = await directoryService.getEntries(true, true);
+
+      // All test groups should have members, but ensure the code handles empty groups
+      expect(result[0]).toBeDefined();
+      expect(Array.isArray(result[0])).toBe(true);
+    });
+  });
+
+  describe("error handling", () => {
+    it("throws error when directory configuration is incomplete", async () => {
+      stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(
+        getGSuiteConfiguration({
+          clientEmail: "",
+        }),
+      );
+
+      const syncConfig = getSyncConfiguration({
+        users: true,
+      });
+      stateService.getSync.mockResolvedValue(syncConfig);
+
+      await expect(directoryService.getEntries(true, true)).rejects.toThrow();
+    });
+
+    it("throws error when authentication fails with invalid credentials", async () => {
+      const directoryConfig = getGSuiteConfiguration({
+        privateKey: "-----BEGIN PRIVATE KEY-----\nINVALID_KEY\n-----END PRIVATE KEY-----\n",
+      });
+      stateService.getDirectory.calledWith(DirectoryType.GSuite).mockResolvedValue(directoryConfig);
+
+      const syncConfig = getSyncConfiguration({
+        users: true,
+      });
+      stateService.getSync.mockResolvedValue(syncConfig);
+
+      await expect(directoryService.getEntries(true, true)).rejects.toThrow();
+    });
  });
 });
--- a/src/services/directory-services/gsuite-directory.service.ts
+++ b/src/services/directory-services/gsuite-directory.service.ts
@@ -14,6 +14,22 @@ import { BaseDirectoryService } from "../baseDirectory.service";

 import { IDirectoryService } from "./directory.service";

+/**
+ * Google Workspace (formerly G Suite) Directory Service
+ *
+ * This service integrates with Google Workspace to synchronize users and groups
+ * to Bitwarden organizations using the Google Admin SDK Directory API.
+ *
+ * @remarks
+ * Authentication is performed using a service account with domain-wide delegation.
+ * The service account must be granted the following OAuth 2.0 scopes:
+ * - https://www.googleapis.com/auth/admin.directory.user.readonly
+ * - https://www.googleapis.com/auth/admin.directory.group.readonly
+ * - https://www.googleapis.com/auth/admin.directory.group.member.readonly
+ *
+ * @see {@link https://developers.google.com/admin-sdk/directory/v1/guides | Google Admin SDK Directory API}
+ * @see {@link https://support.google.com/a/answer/162106 | Domain-wide delegation of authority}
+ */
 export class GSuiteDirectoryService extends BaseDirectoryService implements IDirectoryService {
  private client: JWT;
  private service: admin_directory_v1.Admin;
@@ -30,6 +46,29 @@ export class GSuiteDirectoryService extends BaseDirectoryService implements IDir
    this.service = google.admin("directory_v1");
  }

+  /**
+   * Retrieves users and groups from Google Workspace directory
+   * @returns A tuple containing [groups, users] arrays
+   *
+   * @remarks
+   * This function:
+   * 1. Validates the directory type matches GSuite
+   * 2. Loads directory and sync configuration
+   * 3. Authenticates with Google Workspace using service account credentials
+   * 4. Retrieves users (if enabled in sync config)
+   * 5. Retrieves groups and their members (if enabled in sync config)
+   * 6. Applies any user/group filters specified in sync configuration
+   *
+   * User and group filters follow Google Workspace Directory API query syntax:
+   * - Use `|` prefix for custom filters (e.g., "|orgUnitPath='/Engineering'")
+   * - Multiple conditions can be combined with AND/OR operators
+   *
+   * @example
+   * ```typescript
+   * const [groups, users] = await service.getEntries(true, false);
+   * console.log(`Synced ${users.length} users and ${groups.length} groups`);
+   * ```
+   */
  async getEntries(force: boolean, test: boolean): Promise<[GroupEntry[], UserEntry[]]> {
    const type = await this.stateService.getDirectoryType();
    if (type !== DirectoryType.GSuite) {
@@ -65,6 +104,26 @@ export class GSuiteDirectoryService extends BaseDirectoryService implements IDir
    return [groups, users];
  }

+  /**
+   * Retrieves all users from Google Workspace directory
+   *
+   * @returns Array of UserEntry objects representing users in the directory
+   *
+   * @remarks
+   * This method performs two separate queries:
+   * 1. Active users (including suspended and archived)
+   * 2. Deleted users (marked with deleted flag)
+   *
+   * The method handles pagination automatically, fetching all pages of results.
+   * Users are filtered based on the userFilter specified in sync configuration.
+   *
+   * User properties mapped:
+   * - referenceId: User's unique Google ID
+   * - externalId: User's unique Google ID (same as referenceId)
+   * - email: User's primary email address (lowercase)
+   * - disabled: True if user is suspended or archived
+   * - deleted: True if user is deleted from the directory
+   */
  private async getUsers(): Promise<UserEntry[]> {
    const entries: UserEntry[] = [];
    const query = this.createDirectoryQuery(this.syncConfig.userFilter);
@@ -132,6 +191,13 @@ export class GSuiteDirectoryService extends BaseDirectoryService implements IDir
    return entries;
  }

+  /**
+   * Transforms a Google Workspace user object into a UserEntry
+   *
+   * @param user - Google Workspace user object from the API
+   * @param deleted - Whether this user is from the deleted users list
+   * @returns UserEntry object or null if user data is invalid
+   */
  private buildUser(user: admin_directory_v1.Schema$User, deleted: boolean) {
    if ((user.emails == null || user.emails === "") && !deleted) {
      return null;
@@ -146,6 +212,17 @@ export class GSuiteDirectoryService extends BaseDirectoryService implements IDir
    return entry;
  }

+  /**
+   * Retrieves all groups from Google Workspace directory
+   *
+   * @param setFilter - Tuple of [isWhitelist, Set<string>] for filtering groups
+   * @param users - Array of UserEntry objects to reference when processing members
+   * @returns Array of GroupEntry objects representing groups in the directory
+   *
+   * @remarks
+   * For each group, the method also retrieves all group members by calling the
+   * members API. Groups are filtered based on the groupFilter in sync configuration.
+   */
  private async getGroups(
    setFilter: [boolean, Set<string>],
    users: UserEntry[],
@@ -185,6 +262,19 @@ export class GSuiteDirectoryService extends BaseDirectoryService implements IDir
    return entries;
  }

+  /**
+   * Transforms a Google Workspace group object into a GroupEntry with members
+   *
+   * @param group - Google Workspace group object from the API
+   * @param users - Array of UserEntry objects for reference
+   * @returns GroupEntry object with all members populated
+   *
+   * @remarks
+   * This method retrieves all members of the group, handling three member types:
+   * - USER: Individual user members (only active status users are included)
+   * - GROUP: Nested group members
+   * - CUSTOMER: Special type that includes all users in the domain
+   */
  private async buildGroup(group: admin_directory_v1.Schema$Group, users: UserEntry[]) {
    let nextPageToken: string = null;

@@ -230,6 +320,26 @@ export class GSuiteDirectoryService extends BaseDirectoryService implements IDir
    return entry;
  }

+  /**
+   * Authenticates with Google Workspace using service account credentials
+   *
+   * @throws Error if required configuration fields are missing or authentication fails
+   *
+   * @remarks
+   * Authentication uses a JWT with the following required fields:
+   * - clientEmail: Service account email address
+   * - privateKey: Service account private key (PEM format)
+   * - subject: Admin user email to impersonate (for domain-wide delegation)
+   *
+   * The service account must be configured with domain-wide delegation and granted
+   * the required OAuth scopes in the Google Workspace Admin Console.
+   *
+   * Optional configuration:
+   * - domain: Filters results to a specific domain
+   * - customer: Customer ID for multi-domain organizations
+   *
+   * @see {@link https://developers.google.com/identity/protocols/oauth2/service-account | Service account authentication}
+   */
  private async auth() {
    if (
      this.dirConfig.clientEmail == null ||
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -7,7 +7,7 @@
    "pretty": true,
    "moduleResolution": "node",
    "noImplicitAny": true,
-    "target": "ES2020",
+    "target": "ES2016",
    "module": "ES2020",
    "lib": ["es5", "es6", "es7", "dom"],
    "sourceMap": true,
@@ -18,8 +18,6 @@
    "outDir": "dist",
    "baseUrl": ".",
    "resolveJsonModule": true,
-    "skipLibCheck": true,
-    "noEmitOnError": false,
    "paths": {
      "tldjs": ["./jslib/common/src/misc/tldjs.noop"],
      "@/*": ["./*"]
--- a/tsconfig.renderer.json
+++ b/tsconfig.renderer.json
@@ -1,13 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "angularCompilerOptions": {
-    "strictTemplates": true,
-    "preserveWhitespaces": true
-  },
-  "compilerOptions": {
-    "skipLibCheck": true,
-    "noEmitOnError": false
-  },
-  "include": ["src/app"],
-  "exclude": ["jslib", "**/*.spec.ts"]
-}
--- a/webpack.cli.cjs
+++ b/webpack.cli.cjs
@@ -14,12 +14,7 @@ const ENV = (process.env.ENV = process.env.NODE_ENV);
 const moduleRules = [
  {
    test: /\.ts$/,
-    use: {
-      loader: "ts-loader",
-      options: {
-        transpileOnly: true,
-      },
-    },
+    use: "ts-loader",
    exclude: path.resolve(__dirname, "node_modules"),
  },
  {
@@ -67,7 +62,7 @@ const config = {
    modules: [path.resolve("node_modules")],
  },
  output: {
-    filename: "[name].cjs",
+    filename: "[name].js",
    path: path.resolve(__dirname, "build-cli"),
  },
  module: { rules: moduleRules },
--- a/webpack.main.cjs
+++ b/webpack.main.cjs
@@ -10,12 +10,7 @@ const common = {
    rules: [
      {
        test: /\.tsx?$/,
-        use: {
-          loader: "ts-loader",
-          options: {
-            transpileOnly: true,
-          },
-        },
+        use: "ts-loader",
        exclude: /node_modules\/(?!(@bitwarden)\/).*/,
      },
    ],
@@ -62,9 +57,6 @@ const main = {
      ],
    }),
  ],
-  output: {
-    filename: "[name].cjs",
-  },
  externals: {
    "electron-reload": "commonjs2 electron-reload",
    keytar: "commonjs2 keytar",
--- a/webpack.renderer.cjs
+++ b/webpack.renderer.cjs
@@ -38,7 +38,7 @@ const common = {
  plugins: [],
  resolve: {
    extensions: [".tsx", ".ts", ".js", ".json"],
-    plugins: [new TsconfigPathsPlugin({ configFile: "./tsconfig.renderer.json" })],
+    plugins: [new TsconfigPathsPlugin({ configFile: "./tsconfig.json" })],
    symlinks: false,
    modules: [path.resolve("node_modules")],
  },
@@ -113,7 +113,7 @@ const renderer = {
  },
  plugins: [
    new AngularWebpackPlugin({
-      tsConfigPath: "tsconfig.renderer.json",
+      tsConfigPath: "tsconfig.json",
      entryModule: "src/app/app.module#AppModule",
      sourceMap: true,
    }),
Author	SHA1	Message	Date
Brandon	5761a391f7	wip	2026-01-09 17:01:26 -05:00
Brandon	8cd2850e8d	add docs and tests	2026-01-09 12:05:14 -05:00
Jared McCannon	21ce02f431	[PM-26889] - Typescript 5.9 upgrade with updates (#965 ) * [deps]: Update typescript to v5.9.3 * Updated return types. --------- Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>	2026-01-09 10:07:27 -06:00