Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
150 lines (103 loc) · 4.93 KB

CONTRIBUTING.md

File metadata and controls

150 lines (103 loc) · 4.93 KB
Raw

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:

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

For webapp text or locale changes:

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

For documentation-only changes:

git diff --check