CLAUDE.md

1# Bitwarden Seeder Library - Claude Code Configuration
2 
3## Quick Reference
4 
5**For detailed pattern descriptions (Factories, Recipes, Models, Scenes, Queries, Data), read `README.md`.**
6 
7**For detailed usages of the Seeder library, read `util/SeederUtility/README.md` and `util/SeederApi/README.md`**
8 
9## Commands
10 
11```bash
12# Build
13dotnet build util/Seeder/Seeder.csproj
14 
15# Run tests
16dotnet test test/SeederApi.IntegrationTest/
17 
18# Run single test
19dotnet test test/SeederApi.IntegrationTest/ --filter "FullyQualifiedName~TestMethodName"
20```
21 
22## Pattern Decision Tree
23 
24```
25Need to create test data?
26├─ ONE entity with encryption? → Factory
27├─ ONE cipher from a SeedVaultItem? → CipherSeed.FromSeedItem() + {Type}CipherSeeder.Create()
28├─ MANY entities as cohesive operation? → Recipe or Pipeline
29├─ Flexible preset-based seeding? → Pipeline (RecipeBuilder + Steps)
30├─ Complete test scenario with ID mangling? → Scene
31├─ READ existing seeded data? → Query
32└─ Data transformation plaintext ↔ encrypted? → Model
33```
34 
35## Pipeline Architecture
36 
37**Modern pattern for composable fixture-based and generated seeding.**
38 
39**Flow**: Preset JSON or Options → RecipeOrchestrator → RecipeBuilder → IStep/IAsyncStep[] → RecipeExecutor → SeederContext → BulkCommitter → IPostCommitStep[]
40 
41**Key actors**:
42 
43- **RecipeBuilder**: Fluent API with dependency validation
44- **IStep / IAsyncStep**: Isolated units of work (CreateOrganizationStep, CreateUsersStep, etc.). Use `IAsyncStep` for steps that do real I/O. A step additionally marked `IPostCommitStep` is deferred until after the bulk commit, so it observes committed rows — but sees cleared entity lists, since only the `EntityRegistry` and the context's scalar properties survive the commit.
45- **SeederContext**: Shared mutable state bag (NOT thread-safe)
46- **RecipeExecutor**: Awaits steps sequentially, captures statistics, commits via BulkCommitter, then runs any post-commit steps
47- **RecipeOrchestrator**: Orchestrates recipe building and execution (from presets or options)
48- **SeederDependencies** (`Options/`): Bundles infrastructure services (`DatabaseContext`, `IMapper`, `IPasswordHasher<User>`, `IManglerService`, `ILicensingService`, `IAttachmentStorageService`) into a single record. Recipes and the Orchestrator accept this instead of loose parameters. The CLI utility builds it via `SeederServiceFactory.Create().ToDependencies()`.
49 
50**Why two step interfaces, not one async contract?** Deliberate — don't unify. Collapsing to one `Task ExecuteAsync(SeederContext)` costs: rewrite 22 step classes (18 in `Steps/`, 4 test doubles); force 20 `.Execute(context)` sites in `test/SeederApi.IntegrationTest/Steps/` to `await`, their test methods to `async`; and `TreatWarningsAsErrors` is on repo-wide (`Directory.Build.props`), so CS1998 makes `async` without `await` a build error — every sync step needs `return Task.CompletedTask`. Permanent trap. The split costs less: two-arm union in `OrderedStep`, `object`-typed `Inner`, one duplicated `RecipeBuilder` registration. Diverges from `IScene`/`IQuery` — single `Task`-returning, no sync twin.
51 
52**Fixture/preset separation**: Fixtures (organizations, rosters, ciphers) are independent and never reference each other. The preset is the only layer that composes fixtures and defines cross-cutting relationships (folder assignments, favorites). See `Seeds/docs/architecture.md`.
53 
54**Phase order (org presets)**: Org → OrgApiKey → Roster → Owner (conditional) → Generator (conditional) → Users → Groups → Collections → Folders → Ciphers → CipherAttachments → CipherCollections → CipherFolders → CipherFavorites → PersonalCiphers
55**Phase order (individual presets)**: IndividualUser → NamedFolders → Generator → Folders → Ciphers → CipherAttachments → FolderAssignments → FavoriteAssignments
56 
57**Individual user presets** use the Pipeline with `CreateIndividualUserStep` (no org, no groups, no collections). These presets live in `Seeds/fixtures/presets/individual/` and are identified by having a `"user"` key instead of `"organization"`. They support `folderNames`, `folderAssignments`, and `favoriteAssignments` for fixture-driven personal vault organization. See `Seeds/docs/presets.md` for the catalog.
58 
59See `Pipeline/` folder for implementation.
60 
61## Parallelism
62 
63Steps execute sequentially (phase order preserved by RecipeExecutor). Async steps are awaited one at a time and MUST NOT be batched with `Task.WhenAll` — `SeederContext` is not thread-safe and each step reads state written by the ones before it. Within a step, `CreateUsersStep` and `GeneratePersonalCiphersStep` use `Parallel.For` internally for CPU-bound Rust FFI work (key generation, encryption).
64 
65**Thread-safety requirements:**
66 
67- `GeneratorContext` lazy properties (`??=`) must be force-initialized before any `Parallel.For` loop to prevent a data race
68- Generators use `ThreadLocal<Faker>` for thread-safe deterministic data generation
69- `ManglerService` and `SeederContext` are NOT thread-safe -- pre-compute their outputs before entering parallel loops
70 
71## Performance A/B Testing
72 
73When measuring step-level performance changes, use paired worktrees:
74 
75- Create `server-PM-XXXXX/perf-baseline` and `server-PM-XXXXX/perf-optimized` worktrees
76- Both worktrees get `Stopwatch` timing in `RecipeExecutor.ExecuteAsync()` (the baseline measurement)
77- Only the optimized worktree gets actual code changes
78- Run presets with `--mangle` flag to avoid DB collisions between runs
79- Compare per-step timings across 3+ runs each, discard the first run (JIT warmup)
80- `.worktrees/` is already in `.gitignore`
81 
82## Density Profiles
83 
84Steps accept an optional `DensityProfile` that controls relationship patterns between users, groups, collections, and ciphers. When null, steps use the original round-robin behavior. When present, steps branch into density-aware algorithms.
85 
86**Key files**:
87 
88- `Options/DensityProfile.cs` — strongly-typed options (public class)
89- `Models/SeedPresetDensity.cs` — JSON preset deserialization targets (internal records)
90- `Data/Enums/MembershipDistributionShape.cs` — Uniform, PowerLaw, MegaGroup
91- `Data/Enums/CollectionFanOutShape.cs` — Uniform, PowerLaw, FrontLoaded
92- `Data/Enums/CipherCollectionSkew.cs` — Uniform, HeavyRight
93- `Data/Distributions/PermissionDistributions.cs` — 11 named distributions by org tier
94 
95**Backward compatibility contract**: `DensityProfile? == null` MUST produce identical output to the original code. Every step guards this with `if (_density == null) { /* original path */ }`.
96 
97**Preset JSON**: Add an optional `"density": { ... }` block. See `Seeds/schemas/preset.schema.json` for the full schema.
98 
99**Presets**: Organized into `features/`, `qa/`, `scale/`, `validation/` folders under `Seeds/fixtures/presets/`. See `Seeds/docs/presets.md` for the full catalog.
100 
101**Verification**: SQL queries for validating density algorithms are in `Seeds/docs/verification.md`.
102 
103## Regression Testing
104 
105Changes to `Factories/`, `Steps/`, `Scenes/`, or `Recipes/` need more than the unit suite — it covers none of the CLI, the SeederApi, or a real database. `Seeds/docs/regression.md` maps each changed path to the preset that reaches it and the assertion that proves it, and records the known non-regressions worth not chasing. Claude drives the CLI, API, and SQL; the developer smoke-tests the web vault.
106 
107## Data/ File Organization
108 
109New files under `Data/` belong in the matching subfolder (`Distributions/`, `Enums/`, `Generators/`, `Static/`) — never loose at the top level. See `Data/README.md` for what each subfolder holds. If a new file's concern doesn't fit an existing subfolder, that's a signal to create one, not to drop it loose.
110 
111**Two Enums homes, by concern:** `Data/Enums/` (namespace `Bit.Seeder.Data.Enums`) holds the generation-config surface (`CompanyType`, `PasswordStrength`, distribution shapes, etc. — "Enums are the API"). Crypto-taxonomy enums that describe how seeded vault data is encrypted (`CipherEncryptionType`, `AttachmentSchemeType`) live in the top-level `Enums/` folder (namespace `Bit.Seeder.Enums`), one enum per file.
112 
113## The Recipe Contract
114 
115Recipes follow strict rules:
116 
1171. A Recipe SHALL accept `SeederDependencies` as its single constructor parameter
1182. A Recipe SHALL have exactly one public entry point — `Seed()` when synchronous, `SeedAsync()` when it returns `Task`/`Task<T>`. Pipeline-backed Recipes (`OrganizationRecipe`, `IndividualUserRecipe`) are async; the direct-to-database Recipes (`CollectionsRecipe`, `GroupsRecipe`, `OrganizationDomainRecipe`, `OrganizationWithUsersRecipe`) remain synchronous.
1193. A Recipe MUST produce one cohesive result
1204. A Recipe MAY overload that entry point with different parameters
1215. A Recipe SHALL use private helper methods for internal steps
1226. A Recipe SHALL use BulkCopy for performance when creating multiple entities
1237. A Recipe SHALL compose Factories for individual entity creation
1248. A Recipe SHALL NOT expose implementation details as public methods
125 
126## Zero-Knowledge Architecture
127 
128**Critical:** Unencrypted vault data never leaves the client. The server never sees plaintext.
129 
130The Seeder uses the Rust SDK via FFI because it must behave like a real Bitwarden client:
131 
1321. Generate encryption keys (like client account setup)
1332. Encrypt vault data client-side (same SDK as real clients)
1343. Store only encrypted result
135 
136## Data Flow
137 
138### Pipeline path (fixture → entity)
139 
140```
141SeedVaultItem → CipherSeed.FromSeedItem() → CipherSeed → {Type}CipherSeeder.Create(options) → CipherViewDto → encrypt_fields (Rust FFI) → EncryptedCipherDto → EncryptedCipherDtoExtensions → Server Cipher Entity
142```
143 
144### Core encryption (shared by all paths)
145 
146```
147CipherViewDto → JSON + [EncryptProperty] field paths → encrypt_fields (Rust FFI, bitwarden_crypto) → EncryptedCipherDto → EncryptedCipherDtoExtensions → Server Cipher Entity
148```
149 
150Shared logic: `Factories/CipherEncryption.cs`, `Models/EncryptedCipherDtoExtensions.cs`
151 
152## Rust Crypto Dependency
153 
154The Rust shim (`util/RustSdk/rust/`) depends only on `bitwarden_crypto`. It does **not** depend on `bitwarden_vault` — the seeder drives field selection via `[EncryptProperty]` attributes, not SDK cipher types.
155 
156Before modifying encryption integration, run `RustSdkCipherTests` to validate roundtrip encryption.
157 
158## Encryption Schemes (crypto taxonomy)
159 
160Seeded data spans two orthogonal encryption axes, named with Bitwarden's canonical vocabulary (defined in `Enums/CipherEncryptionType.cs` and `Enums/AttachmentSchemeType.cs`):
161 
162- **Cipher encryption** (`cipherEncryption`): `userKey` (no cipher key; `Cipher.Key` null) or `cipherKey` (per-cipher key wrapped by the vault key).
163- **Attachment scheme version** (`attachmentVersion`): `v0` (no attachment key), `v1` (attachment key wrapped by the vault key), `v2` (attachment key wrapped by the cipher key).
164 
165**Invariant:** a cipher and its attachments use the same strategy — `v2` requires a `cipherKey` host. `Steps/CreateCipherAttachmentsStep.cs` and `Seeds/schemas/cipher.schema.json` both enforce this; keep them in sync.
166 
167**Wire mapping:** `AttachmentSchemeType.{V0,V1,V2}` casts to `u32 {0,1,2}` and is matched verbatim in `util/RustSdk/rust/src/attachment.rs`. The value *is* the version number — do not reintroduce an offset.
168 
169**Do not conflate with account Encryption V1/V2.** Attachment `v0/v1/v2` is key-wrapping only. Everything the seeder emits is Encryption-V1 type-2 `EncString` (AES-256-CBC-HMAC); no COSE/type-7 path exists. A future V2/COSE capability is a **separate** axis (a new enum), never a new attachment version.
170 
171## Deterministic Data Generation
172 
173Same domain = same seed = reproducible data:
174 
175```csharp
176var seed = options.Seed ?? DeriveStableSeed(options.Domain);
177```
178 
179## Scenarios
180 
181Developer-facing documentation in `Seeds/docs/scenarios/`. Each file maps an engineering problem to a Seeder command.
182 
183**Maintenance rules:**
184 
185- When adding a new preset, check if an existing scenario should reference it as a variation
186- When adding a new command or flag, check if it enables a new scenario or changes an existing one
187- When CLI flags, commands, or preset names change, scan all `*.md` files under `Seeds/` and `SeederUtility/` for stale references
188- Scenario files follow the template in `Seeds/docs/scenarios/README.md`
189- Never duplicate CLI flag documentation — link to `SeederUtility/README.md`
190- Never duplicate preset catalog details — link to `Seeds/docs/presets.md`
191- Scenarios describe _why_ (the problem). READMEs describe _how_ (the tool). Keep the split clean.
192 
193**File relationships:**
194 
195- `SeederUtility/README.md` → CLI reference (commands, flags, examples) → links to scenarios
196- `Seeds/docs/presets.md` → what exists (the catalog) → scenarios link back to it
197- `Seeds/docs/scenarios/` → why you'd use it (problem → command)
198 
199## Collection Management Settings
200 
201**Collection management settings are not plan-gated.** `AllowAdminAccessToAllCollectionItems`, `LimitCollectionCreation`, `LimitCollectionDeletion`, and `LimitItemDeletion` apply identically across all plan types. They are org-level admin settings, not billing-plan features.
202 
203**These settings alter access control behavior.** When seeding scenarios that test member vs. admin permissions, collection creation/deletion policies, or item-level access, set them explicitly in the preset rather than relying on defaults.
204 
205**Configurable in presets and CLI.** Use the JSON preset `organization` block (e.g. `"limitCollectionCreation": true`) or the CLI flags: `--limit-collection-creation`, `--limit-collection-deletion`, `--limit-item-deletion`, `--allow-admin-collection-access`.
206 
207## Security Reminders
208 
209- Default test password: `asdfasdfasdf` (overridable via `--password` CLI flag or `SeederSettings`)
210- Never commit database dumps with seeded data
211- Seeded keys are for testing only
212