# Contributing to NodeWarden

Thanks for taking the time to improve NodeWarden.

NodeWarden is a Bitwarden-compatible server with a custom web vault, Cloudflare
Workers/D1 storage, attachment storage, imports/exports, and scheduled backups.
Small changes can affect official clients, backups, migrations, or locale files,
so please keep changes focused and check the related parts of the project.

## Before Opening an Issue

For bug reports, include enough detail for someone else to reproduce the problem:

- The client or browser you used.
- The page, API route, or action that failed.
- Screenshots, logs, or the exact error message.
- Whether the problem happened after sync, import, export, restore, upgrade, or
  a fresh deployment.

Please do not report NodeWarden-specific problems to the official Bitwarden
team. This project is independent from Bitwarden.

## Pull Request Guidelines

Keep pull requests small enough to review. A good PR should explain:

- What changed and why.
- What user-facing behavior changed.
- Which related areas were checked.
- Which commands were run before submitting.

Avoid mixing unrelated refactors with feature or bug-fix work. If a cleanup is
needed before the real fix, mention that clearly in the PR.

## Areas That Need Extra Care

Some parts of the codebase are deliberately connected. When changing one of
these areas, check the related files before calling the work complete.

### Database Changes

Runtime schema lives in `src/services/storage-schema.ts`. The initial D1 schema
lives in `migrations/0001_init.sql`.

If you add or change a table, column, or index:

- Update both schema files.
- Bump `STORAGE_SCHEMA_VERSION` in `src/services/storage.ts`.
- Decide whether the data should be included in instance backup.

### Backup And Restore

Backup export and restore are whitelist-based. This protects old backups from
breaking when fields are removed and prevents transient or secret runtime data
from being exported by accident.

When adding persistent data, check:

- `src/services/backup-archive.ts`
- `src/services/backup-import.ts`
- `webapp/src/lib/api/backup.ts`

Do not export runtime lock rows such as `backup.runner.lock.v1`. Do not import
retired sensitive fields such as `users.api_key`.

### Secrets And Provider Settings

Provider credentials must not be stored or exported as plain config JSON. Follow
the encrypted settings pattern in `src/services/backup-settings-crypto.ts`, or
document a replacement design before changing it.

### Bitwarden Client Compatibility

Official Bitwarden clients may send or expect fields that are not used directly
by the web vault. Cipher and sync changes should preserve unknown client fields
unless they are known-invalid or server-owned.

Check these files when changing vault item shape or sync behavior:

- `src/handlers/ciphers.ts`
- `src/handlers/sync.ts`
- `src/services/storage-cipher-repo.ts`

### Domain Rules

Equivalent-domain settings store both client/UI rule state and derived active
groups. Do not remove `equivalent_domains`, `custom_equivalent_domains`, or
`excluded_global_equivalent_domains` as duplicates without a migration and
compatibility plan.

### Accounts And Passwords

`users.master_password_hash` is for server-side login verification. It is not the
vault decryption key. Password changes, key material, `securityStamp`, and
refresh-token revocation must stay aligned.

Password hints are reminders, not recovery secrets. They must never contain the
master password, recovery codes, API keys, or anything that directly unlocks the
vault.

### Web Vault Styles

The web vault uses Tailwind CSS 4 through `@tailwindcss/vite`. Theme aliases,
dark-mode variants, and source paths are defined in `webapp/src/tailwind.css`,
which also imports `styles.css` so component `@apply` rules share the same theme.
Keep runtime light/dark design tokens in `webapp/src/styles/tokens.css`.
Tailwind 4's browser baseline is Safari 16.4+, Chrome 111+, and Firefox 128+.

### i18n

Locale files are complete standalone bundles. When adding or changing user-facing
text, keep every locale in sync and run the validation script.

For new locales, update:

- `webapp/src/lib/i18n.ts`
- `webapp/src/lib/i18n/locales/*`
- `scripts/i18n-utils.cjs`

## Recommended Checks

Use the Node.js version in `.node-version` for local and Cloudflare builds.
Cloudflare Pages and Workers Builds read this file automatically. If a project
sets `NODE_VERSION` in its dashboard, keep it aligned with this file.

When regenerating the lockfile, use a directory without `node_modules` and
verify `npm ci` with npm 10.9.2, the version used by Cloudflare's build image.
Include optional dependencies so the lockfile also covers native and WASM
dependencies on other platforms.

For most backend or shared changes:

```sh
npx tsc -p tsconfig.json --noEmit
npm run build
```

For webapp text or locale changes:

```sh
npm run i18n:validate
npx tsc -p webapp/tsconfig.json --noEmit
npm run build
```

For documentation-only changes:

```sh
git diff --check
```