Bitwarden Seeder Library - Claude Code Configuration

Quick Reference

For detailed pattern descriptions (Factories, Recipes, Models, Scenes, Queries, Data), read README.md.

For detailed usages of the Seeder library, read util/DbSeederUtility/README.md and util/SeederApi/README.md

Commands

# Build
dotnet build util/Seeder/Seeder.csproj

# Run tests
dotnet test test/SeederApi.IntegrationTest/

# Run single test
dotnet test test/SeederApi.IntegrationTest/ --filter "FullyQualifiedName~TestMethodName"

Pattern Decision Tree

Need to create test data?
├─ ONE entity with encryption? → Factory
├─ MANY entities as cohesive operation? → Recipe or Pipeline
├─ Flexible preset-based seeding? → Pipeline (RecipeBuilder + Steps)
├─ Complete test scenario with ID mangling? → Scene
├─ READ existing seeded data? → Query
└─ Data transformation SDK ↔ Server? → Model

Pipeline Architecture

Modern pattern for composable fixture-based and generated seeding.

Flow: Preset JSON → PresetLoader → RecipeBuilder → IStep[] → RecipeExecutor → SeederContext → BulkCommitter

Key actors:

RecipeBuilder: Fluent API with dependency validation
IStep: Isolated units of work (CreateOrganizationStep, CreateUsersStep, etc.)
SeederContext: Shared mutable state bag (NOT thread-safe)
RecipeExecutor: Executes steps sequentially, captures statistics, commits via BulkCommitter
PresetExecutor: Orchestrates preset loading and execution

Phase order: Org → Owner → Generator → Roster → Users → Groups → Collections → Ciphers

See Pipeline/ folder for implementation.

The Recipe Contract

Recipes follow strict rules:

A Recipe SHALL have exactly one public method named Seed()
A Recipe MUST produce one cohesive result
A Recipe MAY have overloaded Seed() methods with different parameters
A Recipe SHALL use private helper methods for internal steps
A Recipe SHALL use BulkCopy for performance when creating multiple entities
A Recipe SHALL compose Factories for individual entity creation
A Recipe SHALL NOT expose implementation details as public methods

Zero-Knowledge Architecture

Critical: Unencrypted vault data never leaves the client. The server never sees plaintext.

The Seeder uses the Rust SDK via FFI because it must behave like a real Bitwarden client:

Generate encryption keys (like client account setup)
Encrypt vault data client-side (same SDK as real clients)
Store only encrypted result

Data Flow

CipherViewDto → Rust SDK encrypt_cipher → EncryptedCipherDto → TransformToServer → Server Cipher Entity

Shared logic: CipherEncryption.cs, EncryptedCipherDtoExtensions.cs

Rust SDK Version Alignment

Component	Version Source
Server Shim	`util/RustSdk/rust/Cargo.toml` git rev
Clients	`@bitwarden/sdk-internal` in clients repo

Before modifying SDK integration, run RustSdkCipherTests to validate roundtrip encryption.

Deterministic Data Generation

Same domain = same seed = reproducible data:

_seed = options.Seed ?? StableHash.ToInt32(options.Domain);

Security Reminders

Test password: asdfasdfasdf
Never commit database dumps with seeded data
Seeded keys are for testing only

3.4 KiB Raw Blame History