Merge branch 'main' into ai/create-querying-bitwarden-database-skill

Author: theMickster

.claude/commands/bump-rust-sdk.md

@@ -37,6 +37,6 @@ if echo "$ALL_CHANGED" | grep -q '^\.claude/skills/bump-rust-sdk/references/api-
   exit 0
 fi
 
-REASON="util/RustSdk/rust/Cargo.toml was modified but the API surface reference was not updated. Read all .rs files in util/RustSdk/rust/src/ and regenerate .claude/skills/bump-rust-sdk/references/api-surface.md to reflect the current imports, types, and traits used from bitwarden-core, bitwarden-crypto, and bitwarden-vault."
+REASON="util/RustSdk/rust/Cargo.toml was modified but the API surface reference was not updated. Read all .rs files in util/RustSdk/rust/src/ and regenerate .claude/skills/bump-rust-sdk/references/api-surface.md to reflect the current imports, types, and traits used from bitwarden-crypto."
 
 jq -n --arg reason "$REASON" '{ "decision": "block", "reason": $reason }'

.claude/hooks/rust-sdk-surface-check.sh

@@ -1,143 +1,111 @@
 ---
 name: bump-rust-sdk
-description: This skill should be used when the user asks to "bump the Rust SDK", "update sdk-internal", "bump bitwarden-crypto", "update RustSdk dependencies", "align server SDK with clients", or needs to update the bitwarden/sdk-internal git rev pins in util/RustSdk/rust/Cargo.toml. Provides the methodology for mapping client NPM versions to git commit SHAs, analyzing breaking changes, auditing the API surface, and verifying the bump end-to-end.
+description: Bump the server's util/RustSdk `bitwarden-crypto` git-rev pin to a bitwarden/clients release — map the client's sdk-internal version to a commit, fix breaking changes, then verify.
+when_to_use: When asked to bump the Rust SDK, sdk-internal, or bitwarden-crypto, update RustSdk dependencies, or align the server SDK with clients. Not client-side @bitwarden/sdk-internal npm/package.json bumps.
 ---
 
-# Bump sdk-internal Rust Crate Dependencies
+# Bump sdk-internal Rust crate dependencies
 
 ## Overview
 
-The server's `util/RustSdk/rust/Cargo.toml` pins `bitwarden-crypto` from the
-`bitwarden/sdk-internal` repository by git rev. This must be periodically bumped to stay
-aligned with the Bitwarden client applications.
+`util/RustSdk/rust/Cargo.toml` pins `bitwarden-crypto` from `bitwarden/sdk-internal` by git rev; bump
+it periodically to track a `bitwarden/clients` release. RustSdk is Seeder **test** infrastructure
+(`util/`, not `src/` production): it gives the C# Seeder field-level encryption
+(`encrypt_string`/`decrypt_string`/`encrypt_fields`) to produce cryptographically correct Protected
+Data for integration tests. `EncryptPropertyAttribute` drives which fields get encrypted.
 
-The RustSdk is used by the Seeder to produce cryptographically correct Protected Data for
-integration testing. It is NOT part of the production server runtime. The Rust layer provides
-generic field-level encryption (`encrypt_string`, `decrypt_string`, `encrypt_fields`) and
-key generation — the C# Seeder drives which fields to encrypt via `EncryptPropertyAttribute`.
+## NPM → git-rev mapping
 
-## Key Challenge: NPM-to-Git-Rev Mapping
-
-The clients consume sdk-internal via **NPM packages** (`@bitwarden/sdk-internal`), while the
-server consumes it via **Rust git rev pins**. The NPM version (e.g., `0.2.0-main.522`) does not
-directly correspond to a git tag — it encodes a GitHub Actions **workflow run number**.
-
-### Version Format
-
-```
-0.2.0-main.522
-│     │     │
-│     │     └── GitHub Actions run number for publish-wasm-internal workflow
-│     └── Branch name (/ replaced with -)
-└── Base version from sdk-internal
-```
-
-### How to Find the Git Rev
-
-1. Determine the target NPM version from the clients repo (see Step 1 below)
-2. Find the `Publish @bitwarden/sdk-internal` workflow ID in the sdk-internal repo
-3. Query the GitHub Actions API for the specific run number
-4. Extract the `head_sha` — that is the git rev to pin in Cargo.toml
-
-The specific API queries are documented in `references/methodology.md`.
-
-## Process Overview
-
-### Step 1: Identify Target Version
-
-Determine which sdk-internal version to target. Check the latest production release tag from
-`bitwarden/clients` (e.g., `web-v2026.2.0`):
+Clients consume sdk-internal as npm (`@bitwarden/sdk-internal`, e.g. `0.2.0-main.841`); the server
+pins a git rev. The `.NNN` suffix is an opaque counter from a private Azure publish task — **not** a
+GitHub Actions `run_number`, and it does not track `main` commits 1:1. Do not infer the SHA from a run
+number or timestamp; both pick the wrong commit (verified: `841→c5d5bba`, `842→c9f9dba`, `840→1e45444`
+— no time correlation). Read the commit the build bakes into the published WASM instead:
 
 ```bash
-cd /path/to/clients
-git show web-v2026.2.0:package.json | grep sdk-internal
+# <VERSION> is the npm version from the clients release tag (Step 1), e.g. 0.2.0-main.841
+cd "$(mktemp -d)"
+curl -sSL "https://registry.npmjs.org/@bitwarden/sdk-internal/-/sdk-internal-<VERSION>.tgz" -o pkg.tgz
+tar xzf pkg.tgz
+grep -ao "main ([0-9a-f]\{7\})" package/bitwarden_wasm_internal_bg.wasm | sort -u   # -> main (c5d5bba)
+cd /path/to/sdk-internal && git rev-parse c5d5bba   # -> full rev to pin in Cargo.toml
 ```
 
-This gives the NPM version (e.g., `0.2.0-main.522`). Extract the run number (522).
-
-### Step 2: Map NPM Version to Git SHA
-
-Query the GitHub Actions API to find the commit that produced that NPM build. See
-`references/methodology.md` for the exact commands.
-
-### Step 3: Analyze Breaking Changes
-
-Compare the current pinned rev against the target rev, focusing on `bitwarden-crypto`:
-
-```bash
-cd /path/to/sdk-internal
-git log --oneline <old-rev>..<new-rev> -- crates/bitwarden-crypto
-```
-
-Cross-reference each commit against the API surface documented in `references/api-surface.md`.
-
-### Step 4: Apply Changes
-
-1. Update `Cargo.toml` — bump the `bitwarden-crypto` rev pin to the new SHA
-2. Fix any compilation errors from breaking changes (type renames, new parameters, etc.)
-3. Add `#[allow(deprecated)]` for any newly-deprecated APIs (with a comment explaining why)
-
-### Step 5: Build and Verify (Claude)
-
-```bash
-cd util/RustSdk/rust
-cargo build                # Must compile cleanly
-cargo test                 # All tests must pass (roundtrip test is critical)
-cargo fmt --check          # Formatting must be clean
-git diff ../NativeMethods.g.cs  # FFI signatures should be unchanged
-```
-
-Also run the C# integration tests:
-
-```bash
-dotnet test test/SeederApi.IntegrationTest/
-```
-
-### Step 6: Human Verification (HUMAN ONLY)
-
-**Claude does NOT perform this step.** Present these commands to the human engineer and wait
-for confirmation before proceeding.
-
-The human runs SeederUtility and SeederApi to verify Protected Data is correctly produced and
-decryptable by the web client. See `references/methodology.md` for the specific test commands
-and validation criteria.
-
-## Security Notes
-
-- The RustSdk lives in `util/` (test infrastructure), not `src/` (production)
-- The server never decrypts Vault Data — zero-knowledge invariant is unaffected
-- Aligning with the production client release ensures the Seeder produces Protected Data
-  using the same cryptographic primitives as real clients
-- Review `Cargo.lock` diff for unexpected transitive crypto crate changes (rsa, aes, sha2, etc.)
-
-## Keeping References Current
-
-The API surface reference (`references/api-surface.md`) must always reflect the actual code.
-Two mechanisms enforce this:
-
-1. **Post-bump step** — The `/bump-rust-sdk` command includes a mandatory final step to
-   regenerate `api-surface.md` by reading the actual `*.rs` source files.
-2. **Stop hook** — `.claude/hooks/rust-sdk-surface-check.sh` blocks if `Cargo.toml` was
-   modified but `api-surface.md` was not updated in the same session.
-
-To regenerate: read all `.rs` files in `util/RustSdk/rust/src/`, extract every `use` statement
-from `bitwarden_crypto`, and rewrite `references/api-surface.md` to match.
-
-## Additional Resources
-
-### Reference Files
-
-- **`references/methodology.md`** — Detailed step-by-step commands including GitHub Actions API
-  queries, breaking change analysis checklist, human verification commands, and a worked example
-  from the Feb 2026 bump
-- **`references/api-surface.md`** — Complete inventory of types, traits, and functions the RustSdk
-  imports from `bitwarden-crypto`, used to assess breaking change impact
-
-## Files Modified in a Typical Bump
-
-| File                              | Change                                          |
-| --------------------------------- | ----------------------------------------------- |
-| `util/RustSdk/rust/Cargo.toml`    | `bitwarden-crypto` rev pin update               |
-| `util/RustSdk/rust/src/*.rs`      | Type renames, new parameters, deprecation fixes |
-| `util/RustSdk/rust/Cargo.lock`    | Auto-regenerated (commit alongside)             |
-| `util/RustSdk/NativeMethods.g.cs` | Should NOT change (verify)                      |
+That full SHA is the exact source the production client runs. `@bitwarden/commercial-sdk-internal`
+ships the same commit, so the open-source tarball's embedded SHA is authoritative for both.
+
+## Process
+
+1. **Identify target** — latest `web-v*` release tag from clients, then its npm version:
+   ```bash
+   gh release list --repo bitwarden/clients --limit 5 | grep web-v
+   git -C /path/to/clients show <tag>:package.json | grep sdk-internal   # -> 0.2.0-main.841
+   ```
+2. **Map npm → git SHA** — the mapping section above.
+3. **Analyze breaking changes** — cross-ref each commit against `references/api-surface.md`; watch for
+   type renames, removed/deprecated functions, changed signatures, and trait changes:
+   ```bash
+   cd /path/to/sdk-internal
+   git log --oneline <old-rev>..<new-rev> -- crates/bitwarden-crypto
+   git diff <old-rev>..<new-rev> -- crates/bitwarden-crypto/src/keys/mod.rs crates/bitwarden-crypto/src/lib.rs
+   ```
+4. **Apply** —
+   - Update the `bitwarden-crypto` `rev` in `Cargo.toml`.
+   - **MSRV check:** compare the target's workspace `rust-version` against `util/RustSdk/rust-toolchain.toml`;
+     if the MSRV rose above our channel, bump the channel to the **MSRV** (not sdk-internal's dev
+     toolchain), else the build fails "requires rustc X or newer".
+   - `cargo update -p bitwarden-crypto` (targeted — re-resolves only what the new rev needs; a bare
+     `cargo update` churns the lockfile).
+   - Fix compile errors; add `#[allow(deprecated)]` + a why-comment for newly-deprecated APIs.
+5. **Build & verify (Claude)** —
+   ```bash
+   cd util/RustSdk/rust
+   cargo build && cargo test        # roundtrip test is the gate: encrypt_string_decrypt_string_roundtrip
+   cargo fmt --check
+   git diff ../NativeMethods.g.cs   # must be unchanged
+   dotnet test test/SeederApi.IntegrationTest/
+   ```
+   Review the `Cargo.lock` diff for unexpected transitive crypto crates (`rsa`, `aes`, `sha2`).
+6. **Human verification (human only — present these, do not run them)** — the human seeds and confirms
+   Protected Data is decryptable in the web client:
+   ```bash
+   cd util/SeederUtility
+   dotnet run -- organization -n SdkBumpTest -d sdk-bump-test.example -u 3 -c 10 -g 5 -o Traditional -m
+   # or a preset:  dotnet run -- seed --preset dunder-mifflin-enterprise-full --mangle
+
+   # SeederApi HTTP alternative — start `dotnet run` in util/SeederApi, then:
+   curl -X POST localhost:5000/seed -H 'X-Play-Id: sdk-bump-test' -H 'Content-Type: application/json' \
+     -d '{"template":"SingleUserScene","arguments":{"email":"test@example.com","password":"<8+ char pwd>"}}'
+   curl -X DELETE localhost:5000/seed/sdk-bump-test   # cleanup
+   ```
+   Pass = seeded users log in with the fake master password (see `util/SeederUtility/README.md`),
+   ciphers are decryptable in the web vault, no Seeder errors, and cleanup deletes all tracked entities.
+
+## Security notes
+
+- RustSdk is `util/` test infrastructure, not `src/` production; the server never decrypts Vault Data,
+  so the zero-knowledge invariant is unaffected.
+- Matching the production client release makes the Seeder produce Protected Data with the same
+  cryptographic primitives real clients use.
+
+## Keeping api-surface.md current
+
+`references/api-surface.md` must mirror the actual code. After a bump, regenerate it: read every `.rs`
+in `util/RustSdk/rust/src/`, extract the `bitwarden_crypto` `use` statements, and rewrite the file.
+A Stop hook (`.claude/hooks/rust-sdk-surface-check.sh`) blocks if `Cargo.toml` changed but
+`api-surface.md` did not.
+
+## Files typically modified
+
+| File | Change |
+| --- | --- |
+| `util/RustSdk/rust/Cargo.toml` | `bitwarden-crypto` rev pin |
+| `util/RustSdk/rust-toolchain.toml` | bump `channel` only if the MSRV rose |
+| `util/RustSdk/rust/src/*.rs` | breaking-change fixes |
+| `util/RustSdk/rust/Cargo.lock` | re-resolved (`cargo update -p bitwarden-crypto`) |
+| `util/RustSdk/NativeMethods.g.cs` | should NOT change — verify |
+
+## References
+
+- `references/api-surface.md` — types, traits, and functions imported from `bitwarden-crypto`.
+- `references/examples/2026-06-bump.md` — the June 2026 bump, worked end-to-end.

.claude/skills/bump-rust-sdk/SKILL.md

@@ -0,0 +1,7 @@
+# bump-rust-sdk evals
+
+Behavior test cases for the `bump-rust-sdk` skill, in the `skill-creator` schema.
+
+`evals.json` holds five cases covering the skill's substantive decisions: the NPM→git-SHA mapping, resisting the deprecated run-number method, the MSRV/toolchain bump, targeted `cargo update -p`, and a breaking-change fix. Each case's `expectations` are the pass criteria; cases 4 and 5 carry `notes` recording their ablation outcomes (earned vs. borderline).
+
+Run with `/skill-creator:skill-creator` in Benchmark mode (with-skill vs. without-skill).