Adds flightcheck status command; xtend crypto with reset option (#466)

Co-authored-by: Jonathan Prusik <jprusik@users.noreply.github.com>

Author: blackwood

.claude/CLAUDE.md

@@ -59,18 +59,23 @@ npm run test:static:notification
 # Single spec file
 npm run pretest && NODE_EXTRA_CA_CERTS=ssl.crt npx playwright test tests/static/autofill-forms.spec.ts
 
-# Public (live site) tests
+# Public (live site) tests — NEVER run these; they hit real external sites
 npm run test:public:debug
 
 # Accessibility tests
 npm run test:a11y:browser
 npm run test:a11y:web
 
 # Utilities
+npm run flightcheck           # check environment prerequisites
 npm run prettier:fix          # format all files
 npm run typecheck             # typecheck scripts/ and tests/
+npm run setup:install         # generate and write BW_INSTALLATION_ID / BW_INSTALLATION_KEY
+npm run setup:crypto          # generate and write crypto values to .env
+npm run setup:flags           # sync feature flags from REMOTE_VAULT_CONFIG_MATCH into flags.json
 npm run setup:vault           # create account + seed vault
 npm run seed:vault:ciphers    # seed vault only (account must exist)
+npm run seed:vault:import     # import a vault JSON file (requires VAULT_IMPORT_FILE)
 ```
 
 ## Debug Helpers
@@ -82,6 +87,7 @@ npm run seed:vault:ciphers    # seed vault only (account must exist)
 
 1. **No real credentials in test data**: All vault passwords are fake (e.g., `"fakeBasicFormPassword"`). Prefix test credential values with `fake`.
 2. **No secrets in source**: Crypto material, master password hashes, and API keys live only in `.env` (gitignored). Generated by `npm run setup:crypto` — never set manually.
+    - `VAULT_EMAIL` is used as a PBKDF2 salt and as a seeding value for generating the install keys — changing it invalidates `MASTER_PASSWORD_HASH` and requires manually removing the generated crypto vars from `.env`, running `npm run setup:crypto`, and starting fresh with a new DB.
 3. **Zero-knowledge invariant**: Account creation in `create-account.ts` sends a pre-hashed master password and encrypted key material — never the plaintext password — to the server API.
 4. **Downloads disabled**: The browser fixture sets `acceptDownloads: false`.
 

README.md

@@ -73,12 +73,23 @@ As a secondary concern, BIT aspires to track and anticipate feature compatibilit
 - Next run `npm run setup:all`, entering your system password when prompted.
 - Run static tests with `npm run test:static`.
 
+## Returning Workflow
+
+Run `npm run flightcheck` to check which prerequisites are satisfied and get specific commands for anything that needs attention. Typically you only need to do the initial set up once; after that all that's needed is:
+
+```bash
+docker compose up -d --wait   # start the vault server
+npm run test:static:debug
+```
+
 ## Setup
 
 - Create an `.env` file in the root directory with values pointing to the vault you want to test against (use `.env.example` as guidance) and populate it with your desired values
 
 > Important! Once you've generated installation and crypto values for your `.env` file, DO NOT CHANGE the seeding values (`VAULT_EMAIL`, `VAULT_PASSWORD`, `KDF_ITERATIONS`). Doing so requires regenerating your installation and crypto secret values and rebuilding/updating server.
 
+> If you do need to change `VAULT_EMAIL` or `VAULT_PASSWORD`, manually remove the generated crypto vars (`KDF_ITERATIONS`, `MASTER_PASSWORD_HASH`, `PROTECTED_SYMMETRIC_KEY`, `GENERATED_RSA_KEY_PAIR_PUBLIC_KEY`, `GENERATED_RSA_KEY_PAIR_PROTECTED_PRIVATE_KEY`) from your `.env`, run `npm run setup:crypto`, then `npm run setup:vault`. Note that changing `VAULT_EMAIL` may also require regenerating install keys (`npm run setup:install`) and rebuilding the vault, depending on what you're trying to do.
+
 - Run `npm run setup:install` to generate and add installation values to your dotfile
   - Alternatively, you can generate them at `https://bitwarden.com/host` and add them to your dotfile manually as `BW_INSTALLATION_ID` and `BW_INSTALLATION_KEY`
 - Run `npm run setup:crypto` to generate and add crypto values to your dotfile
@@ -113,6 +124,14 @@ Using Docker Compose will set up all the services required by the extension for
 
 Create and start the containers and volumes with `docker compose up -d --build --remove-orphans`, and teardown with `docker compose down -v`
 
+> If the image pull fails with a network error (e.g. `unexpected EOF`), re-run `docker compose pull` and then retry. If it continues to fail, try increasing the timeout: `COMPOSE_HTTP_TIMEOUT=120 docker compose pull`. A common underlying cause is endpoint protection or firewall rules blocking the pull.
+
+> If startup fails with `port is already allocated`, a previous container session is holding the port — often a prior BIT stack (e.g. after updating the image version). Run `npm run flightcheck` to identify which project owns the port and get the exact teardown command.
+
+> Each compose project uses its own database volume. Switching to a different vault image version means a fresh database — re-run `npm run setup:vault` after bringing the new stack up. Old project volumes are not removed automatically. If `npm run flightcheck` detects a wrong-version or missing stack, it will list any BIT volumes from other projects and show the `docker volume rm` commands to clean them up.
+
+> If you have previously seeded a vault, you don't need to run setup again — just start it. This is especially relevant when switching between several environments (for example, different server images or feature flag configurations): each has its own volume, so bringing one back up restores its prior state as-is.
+
 ### Seeding Your Vault
 
 > If using Docker Compose to host the server environment (as described in the previous section), you may need to wait for the services within the `bitwarden` container to enter a running state before running any seeding scripts.

package.json

@@ -43,6 +43,7 @@
     "seed:vault:ciphers": "./scripts/seeder.sh",
     "seed:vault:ciphers:refresh": "REFRESH=true ./scripts/seeder.sh",
     "seed:vault:import": "./scripts/vault-import.sh",
+    "flightcheck": "./scripts/flightcheck.sh",
     "setup:all": "./scripts/first-time-setup.sh",
     "setup:extension": "rimraf clients && git clone https://github.com/bitwarden/clients.git clients && cd clients && npm ci",
     "setup:install": "ts-node ./scripts/generate-installation.ts",

scripts/create-account.ts

@@ -22,7 +22,7 @@ type AccountCreationResponseData = ResponseData;
 let failedAttemptsCount = 0;
 
 async function createAccount() {
-  if (failedAttemptsCount > 60) {
+  if (failedAttemptsCount > 25) {
     throw new Error("The account was unable to be created.");
   }
 
@@ -72,6 +72,16 @@ async function createAccount() {
       }
 
       console.log(`Retrying account creation at ${vaultHost}...`);
+      if (preCreationResponseData.validationErrors) {
+        // Validation errors indicate a real misconfiguration — always surface them
+        if (preCreationResponseData.message) {
+          console.log(`\x1b[2m  ${preCreationResponseData.message}\x1b[0m`);
+        }
+        Object.entries(preCreationResponseData.validationErrors).forEach(
+          ([field, msgs]) =>
+            console.log(`\x1b[2m    ${field}: ${msgs.join(", ")}\x1b[0m`),
+        );
+      }
       failedAttemptsCount++;
       setTimeout(createAccount, 3000);
       return;