41 | );
42 | }
43 |
--------------------------------------------------------------------------------
/docs/architecture/sdk/versioning.md:
--------------------------------------------------------------------------------
1 | # Versioning and breaking changes
2 |
3 | The SDK strives towards maintaining backward compatibility for a reasonable time. This ensures that
4 | client applications can safely upgrade to newer versions of the SDK without resolving a large number
5 | of breaking changes. For a more in-depth explanation of what constitutes a breaking change in rust,
6 | see the [SemVer Compatibility section](https://doc.rust-lang.org/cargo/reference/semver.html) in
7 | [the Cargo book](https://doc.rust-lang.org/cargo/index.html).
8 |
9 | There may be certain functionality that is actively being developed and is not yet stable. In these
10 | cases, they should be marked as such and gated behind a `unstable` feature flag. Consuming client
11 | applications should avoid merging changes that depend on these features into `main`.
12 |
13 | ## Public APIs
14 |
15 | To track breaking changes to the public APIs for Secrets Manager, we use a [changelog file in the
16 | `bitwarden` crate][changelog]. This file should be updated with noteworthy changes.
17 |
18 | [changelog]: https://github.com/bitwarden/sdk-sm/blob/main/crates/bitwarden/CHANGELOG.md
19 |
--------------------------------------------------------------------------------
/docs/architecture/deep-dives/push-notifications/index.md:
--------------------------------------------------------------------------------
1 | # Push Notifications
2 |
3 | Bitwarden uses push notifications to communicate in real-time from the Bitwarden server to its
4 | clients.
5 |
6 | ## Uses at Bitwarden
7 |
8 | Currently, this functionality is used for:
9 |
10 | - Syncing the vault between clients
11 | - Passwordless login requests
12 |
13 | ## Technology in Use
14 |
15 | The Bitwarden server initiates push notifications when relevant actions are performed, typically
16 | either when a user's data has changed and it needs to be synced, or an action requiring user input
17 | is performed.
18 |
19 | There are currently two different methods being used for push notifications:
20 |
21 | - The mobile applications use Azure Notification Hub, which is an abstraction of the Push
22 | Notification Services (PNSs) for the Apple and Android ecosystems. Self-hosted instances relay
23 | their mobile messages through the Bitwarden cloud-hosted service.
24 | - The other clients use SignalR, which is a two-way RPC usually over WebSockets (but has fallbacks
25 | to other protocols) to establish real-time client communications with our non-mobile clients.
26 |
--------------------------------------------------------------------------------
/docs/architecture/clients/presentation/cli.md:
--------------------------------------------------------------------------------
1 | # CLI
2 |
3 | The CLI has a slightly different architecture than the other clients, which matches it's nature. CLI
4 | sessions are short lived and only execute a single task and then exit. This means that the CLI
5 | doesn't need to keep track of the memory state in the same way as the other clients.
6 |
7 | ## Commands
8 |
9 | Since the CLI is a command line interface, everything is structured around commands. Each command
10 | execute a specific task. Similar to _Angular Components_, _Commands_ aims to be as lightweight as
11 | possible with most business logic being handled by services. This allows for code sharing between
12 | different commands, but also with the Angular presentation layer.
13 |
14 | A basic command essentially only implements a single method, `run`. The Command classes are
15 | instantiated by the `Program` class.
16 |
17 | ```ts
18 | export class ConfigCommand {
19 | // Dependencies are manually wired up in the Program class.
20 | constructor(private environmentService: EnvironmentService) {}
21 |
22 | async run(setting: string, value: string, options: program.OptionValues): Promise {
23 | // Set configuration
24 | }
25 | }
26 | ```
27 |
--------------------------------------------------------------------------------
/cspell.yaml:
--------------------------------------------------------------------------------
1 | ---
2 | dictionaries:
3 | - custom-words
4 | dictionaryDefinitions:
5 | - name: custom-words
6 | path: ./custom-words.txt
7 | addWords: true
8 | patterns:
9 | # Ignore multi-line code blocks
10 | # Ref: https://cspell.org/configuration/patterns/
11 | # Modified to avoid matching line breaks before/after which had unexpected results
12 | - name: markdown_code_block
13 | pattern: |
14 | /
15 | ^[ \t]* # match optional whitespace before the ```
16 | (`{3}).* # match the ``` and any optional language specification afterwards
17 | [\s\S]*? # the block of code
18 | ^[ \t]* # match optional whitespace before the ```
19 | \1 # end of the block
20 | /gmx
21 |
22 | # Ignore inline code blocks
23 | - name: markdown_code_inline
24 | pattern: |
25 | /
26 | ` # match the opening `
27 | .*? # match any characters, lazily (so that we stop at the next tilde)
28 | ` # match the closing `
29 | /gx
30 | languageSettings:
31 | - languageId:
32 | - markdown
33 | - mdx
34 | ignoreRegExpList:
35 | - markdown_code_block
36 | - markdown_code_inline
37 |
--------------------------------------------------------------------------------
/docs/contributing/database-migrations/ef.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar_position: 2
3 | ---
4 |
5 | # Entity Framework
6 |
7 | :::info
8 |
9 | For instructions on how to apply database migrations, please refer to the
10 | [Getting Started](../../getting-started/server/database/ef/index.mdx#updating-the-database)
11 | documentation.
12 |
13 | :::
14 |
15 | If you alter the database schema, you must create an EF migration script to ensure that EF databases
16 | keep pace with these changes. Developers must do this and include the migrations with their PR.
17 |
18 | To create these scripts, you must first update your data model in `Core/Entities` as desired. This
19 | will be used to generate the migrations for each of our EF targets. Additionally, for table changes
20 | it is strongly recommended to define or update an `IEntityTypeConfiguration` to accurately
21 | represent any constraints needed on the data model.
22 |
23 | Once the model is updated, navigate to the `dev` directory in the `server` repo and execute the
24 | `ef_migrate.ps1` PowerShell command. You should provide a name for the migration as the only
25 | parameter:
26 |
27 | ```bash
28 | pwsh ef_migrate.ps1 [NAME_OF_MIGRATION]
29 | ```
30 |
31 | This will generate the migrations, which should then be included in your PR.
32 |
--------------------------------------------------------------------------------
/docs/getting-started/clients/desktop/microsoft-store.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar_custom_props:
3 | access: bitwarden
4 | ---
5 |
6 | # Microsoft Store
7 |
8 | To debug the Microsoft Store application you need to generate a Code Signing certificate which can
9 | be done using the following powershell command:
10 |
11 | ```powershell
12 | New-SelfSignedCertificate -Type Custom `
13 | -Subject "CN=ElectronSign, 0=Your Corporation, C=US" `
14 | -TextExtension @("2.5.29.19={text}false") `
15 | -KeyUsage DigitalSignature `
16 | -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.3", "2.5.29.19={text}") `
17 | -FriendlyName ElectronSign `
18 | -CertStoreLocation "Cert:\CurrentUser\My"
19 | ```
20 |
21 | The generated certificate needs to be copied into to `Cert:\CurrentUser\Trusted People`, which tells
22 | the OS to trust the certificate. This is easiest done using the `certmgr` tool.
23 |
24 | The [Windows SDK][sdk] is required in order to access the signtool.
25 |
26 | ```powershell
27 | npm run dist:win
28 |
29 | cd dist
30 | "C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\x64\signtool.exe" sign /v /fd sha256 /n "14D52771-DE3C-4886-B8BF-825BA7690418" .\Bitwarden-2022..appx
31 | ```
32 |
33 | [sdk]: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/
34 |
--------------------------------------------------------------------------------
/docs/getting-started/clients/browser/ff-private.md:
--------------------------------------------------------------------------------
1 | # Firefox Private Mode
2 |
3 | You cannot run add-ons in Firefox Private Mode using the normal side-loading technique. This is
4 | because only they appear in the `about:debugging` page, which doesn’t give you the option to enable
5 | the extension in Private Mode.
6 |
7 | As an alternative, you can install the development build as an unsigned add-on using the steps
8 | below.
9 |
10 | ## Prerequisites
11 |
12 | 1. Install Firefox Developer Edition
13 | 2. Configure Firefox Developer Edition:
14 | 1. Open Firefox Developer Edition
15 | 2. Navigate to `about:config`
16 | 3. Set the `xpinstall.signatures.required` setting to `false` (add the setting if it’s not in
17 | the list already)
18 |
19 | ## Steps
20 |
21 | 1. Open your local browser repository on the command line
22 | 2. Build and package the browser extension with `npm run dist:firefox`
23 | 3. Open Firefox Developer Edition and navigate to `about:addons`
24 | 4. Click the cog in the top-right next to “Manage Your Extensions”
25 | 5. Click “Install Add-on From File”
26 | 6. Open `dist/dist-firefox.zip` in your local repository
27 | 7. The extension will now be the `about:addons` page. Click on the name of the extension to expand
28 | it, and then toggle “Run in Private Windows”.
29 |
--------------------------------------------------------------------------------
/docs/architecture/adr/0009-angular-composition-over-inheritance.md:
--------------------------------------------------------------------------------
1 | ---
2 | adr: "0009"
3 | status: Accepted
4 | date: 2022-07-25
5 | tags: [clients, angular]
6 | ---
7 |
8 | # 0009 - Composition over inheritance
9 |
10 |
11 |
12 | ## Context and problem statement
13 |
14 | We currently rely heavily on inheritance for our Angular applications. While this seemed like a
15 | natural decision at the time since it allowed us to quickly share code between different areas. It
16 | has also lead to tight coupling and therefore difficulty in understanding the impact a change will
17 | have. It also encourages large page-level components.
18 |
19 | ## Considered options
20 |
21 | - **Do nothing** - Maintain the status quo, not really an option.
22 | - **Prefer composition over inheritance** - Split up components into small components that do one
23 | thing and one thing only. Keep components thin, and share functionality primarily using
24 | _Services_.
25 |
26 | ## Decision outcome
27 |
28 | Chosen option: **Prefer composition over inheritance**
29 |
30 | ### Positive consequences
31 |
32 | - Thinner components
33 | - Better understanding of the impact a change has since it will now be isolated to a single
34 | component only.
35 |
36 | ### Negative consequences
37 |
38 | - Inheritance tends to be well understood.
39 |
--------------------------------------------------------------------------------
/docs/contributing/code-style/web/html.md:
--------------------------------------------------------------------------------
1 | # HTML
2 |
3 | Please ensure each input field and button has a descriptive ID. This will allow QA to more
4 | efficiently write test automation.
5 |
6 | The IDs should have the three following _components_:
7 |
8 | - **Component Name**: To ensure IDs stay unique we prefix them with the component name. While this
9 | may change it rarely does and since we avoid re-using the same component name multiple times this
10 | should be unique.
11 | - **HTML Element**: This allows you at a quick glance understand what we're accessing.
12 | - **Readable name**: Descriptive name of what we're accessing.
13 |
14 | Please use dashes within components, and separate the _components_ using underscore.
15 |
16 | ```
17 | __
18 |
19 | register_button_submit
20 | register-form_input_email
21 | ```
22 |
23 | When writing components for the component library it's sometimes necessary to ensure an ID exists in
24 | order to properly handle accessibility with references to other elements. Consider using an auto
25 | generated ID but ensure it can be overridden. Use the following naming convention for automatic IDs:
26 |
27 | ```
28 | -
29 |
30 | bit-input-0
31 | ```
32 |
33 | Please ensure words in the selector are separated using dash and not camelCase.
34 |
--------------------------------------------------------------------------------
/.github/workflows/scan.yml:
--------------------------------------------------------------------------------
1 | name: Scan
2 |
3 | on:
4 | workflow_dispatch:
5 | push:
6 | branches:
7 | - "main"
8 | pull_request:
9 | types: [opened, synchronize, reopened]
10 | branches-ignore:
11 | - "main"
12 | pull_request_target:
13 | types: [opened, synchronize, reopened]
14 | branches:
15 | - "main"
16 |
17 | permissions: {}
18 |
19 | jobs:
20 | check-run:
21 | name: Check PR run
22 | uses: bitwarden/gh-actions/.github/workflows/check-run.yml@main
23 | permissions:
24 | contents: read
25 |
26 | sast:
27 | name: Checkmarx
28 | uses: bitwarden/gh-actions/.github/workflows/_checkmarx.yml@main
29 | needs: check-run
30 | secrets:
31 | AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
32 | AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
33 | AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
34 | permissions:
35 | contents: read
36 | pull-requests: write
37 | security-events: write
38 | id-token: write
39 |
40 | quality:
41 | name: Sonar
42 | uses: bitwarden/gh-actions/.github/workflows/_sonar.yml@main
43 | needs: check-run
44 | secrets:
45 | AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
46 | AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
47 | AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
48 | permissions:
49 | contents: read
50 | pull-requests: write
51 | id-token: write
52 |
--------------------------------------------------------------------------------
/.github/CODEOWNERS:
--------------------------------------------------------------------------------
1 | # Please sort into logical groups with comment headers. Sort groups in order of specificity.
2 | # For example, default owners should always be the first group.
3 | # Sort lines alphabetically within these groups to avoid accidentally adding duplicates.
4 | #
5 | # https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
6 |
7 | # Leads for all reviews of documentation
8 | * @bitwarden/tech-leads
9 |
10 | # Unowned files
11 | package.json
12 | package-lock.json
13 |
14 | # Architecture department for architecture content
15 | docs/architecture @bitwarden/dept-architecture
16 |
17 | # Key management and Architecture for crypto concepts
18 | docs/architecture/cryptography @bitwarden/team-key-management-dev @bitwarden/dept-architecture
19 |
20 | # Architecture and AppSec for security concepts
21 | docs/architecture/security @bitwarden/team-appsec @bitwarden/dept-architecture
22 |
23 | # Shared workflows ownership
24 | .github/workflows/build.yml @bitwarden/dept-bre @bitwarden/tech-leads
25 |
26 | # Docker-related files
27 | **/Dockerfile @bitwarden/team-appsec @bitwarden/dept-bre
28 | **/*.dockerignore @bitwarden/team-appsec @bitwarden/dept-bre
29 | **/entrypoint.sh @bitwarden/team-appsec @bitwarden/dept-bre
30 | **/docker-compose.yml @bitwarden/team-appsec @bitwarden/dept-bre
31 |
32 | # Claude related files
33 | .claude/ @bitwarden/team-ai-sme
34 | .github/workflows/respond.yml @bitwarden/team-ai-sme
35 | .github/workflows/review-code.yml @bitwarden/team-ai-sme
36 |
--------------------------------------------------------------------------------
/.github/PULL_REQUEST_TEMPLATE.md:
--------------------------------------------------------------------------------
1 | ## 🎟️ Tracking
2 |
3 |
4 |
5 | ## 📔 Objective
6 |
7 |
8 |
9 | ## ⏰ Reminders before review
10 |
11 | - Contributor guidelines followed
12 | - All formatters and local linters executed and passed
13 | - Written new unit and / or integration tests where applicable
14 | - Protected functional changes with optionality (feature flags)
15 | - Used internationalization (i18n) for all UI strings
16 | - CI builds passed
17 | - Communicated to DevOps any deployment requirements
18 | - Updated any necessary documentation (Confluence, contributing docs) or informed the documentation
19 | team
20 |
21 | ## 🦮 Reviewer guidelines
22 |
23 |
24 |
25 | - 👍 (`:+1:`) or similar for great changes
26 | - 📝 (`:memo:`) or ℹ️ (`:information_source:`) for notes or general info
27 | - ❓ (`:question:`) for questions
28 | - 🤔 (`:thinking:`) or 💭 (`:thought_balloon:`) for more open inquiry that's not quite a confirmed
29 | issue and could potentially benefit from discussion
30 | - 🎨 (`:art:`) for suggestions / improvements
31 | - ❌ (`:x:`) or ⚠️ (`:warning:`) for more significant problems or concerns needing attention
32 | - 🌱 (`:seedling:`) or ♻️ (`:recycle:`) for future improvements or indications of technical debt
33 | - ⛏ (`:pick:`) for minor or nitpick changes
34 |
--------------------------------------------------------------------------------
/docs/architecture/adr/0002-public-module-npm-packages.md:
--------------------------------------------------------------------------------
1 | ---
2 | adr: "0002"
3 | status: Accepted
4 | date: 2022-06-02
5 | tags: [clients]
6 | ---
7 |
8 | # 0002 - Public API for modules
9 |
10 |
11 |
12 | ## Context and problem statement
13 |
14 | We currently use direct file reference across different packages. This had led to everything in the
15 | packages being available to any other package across our projects. Which makes it difficult to
16 | identity what potential side effects a change might have as they are not isolated to the individual
17 | package. Traditionally only a specific subset of a package is exposed as a public module, which
18 | provides safety that changes will be internal to the package and ideally covered by it's unit tests.
19 |
20 | ## Considered options
21 |
22 | - **Direct references** - We can decide to continue as is. Without a public API.
23 | - **Define public modules using index.ts** - We add `index.ts` to each folder that defines the
24 | "public" interfaces. The other packages then imports the root index file and are forbidden from
25 | direct references to internal files.
26 |
27 | ## Decision outcome
28 |
29 | Chosen option: **Define a public module using index.ts**.
30 |
31 | ### Positive consequences
32 |
33 | - The public module is defined.
34 | - Imports can be kept cleaner since not every file needs to be manually imported.
35 | - Safety in knowing that a change is isolated to the package.
36 |
37 | ### Negative consequences
38 |
39 | - We will have to update `index.ts` files whenever we add a new exported API.
40 |
--------------------------------------------------------------------------------
/src/css/custom.css:
--------------------------------------------------------------------------------
1 | /**
2 | * Any CSS included here will be global. The classic template
3 | * bundles Infima by default. Infima is a CSS framework designed to
4 | * work well for content-centric websites.
5 | */
6 |
7 | /* You can override the default Infima variables here. */
8 | :root {
9 | --ifm-color-primary: #175ddc;
10 | --ifm-color-primary-dark: #1554c6;
11 | --ifm-color-primary-darker: #144fbb;
12 | --ifm-color-primary-darkest: #10419a;
13 | --ifm-color-primary-light: #2369e8;
14 | --ifm-color-primary-lighter: #2e71e9;
15 | --ifm-color-primary-lightest: #4f87ed;
16 | --ifm-code-font-size: 95%;
17 | --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
18 | }
19 |
20 | /* For readability concerns, you should choose a lighter palette in dark mode. */
21 | [data-theme="dark"] {
22 | --ifm-color-primary: #6a99f0;
23 | --ifm-color-primary-dark: #4b83ed;
24 | --ifm-color-primary-darker: #3b79eb;
25 | --ifm-color-primary-darkest: #165cdc;
26 | --ifm-color-primary-light: #89aff3;
27 | --ifm-color-primary-lighter: #99b9f5;
28 | --ifm-color-primary-lightest: #c8daf9;
29 | --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
30 | }
31 |
32 | .navbar__brand b {
33 | margin-left: 5px;
34 | }
35 |
36 | .navbar--fixed-top {
37 | height: 4rem;
38 | }
39 |
40 | .navbar__logo {
41 | height: 2.8rem;
42 | }
43 |
44 | .navbar__link--active,
45 | .menu__link--active {
46 | font-weight: bold;
47 | }
48 |
49 | figcaption {
50 | text-align: center;
51 | font-style: italic;
52 | }
53 |
54 | .theme-doc-markdown dt {
55 | font-weight: bold;
56 | }
57 |
58 | .theme-doc-markdown dd {
59 | margin-bottom: 1rem;
60 | }
61 |
--------------------------------------------------------------------------------
/docs/architecture/deep-dives/ssh/index.md:
--------------------------------------------------------------------------------
1 | # SSH Keys and Agent
2 |
3 | :::info
4 |
5 | For more information on how Bitwarden implements its SSH agent, see [SSH Agent](./agent).
6 |
7 | :::
8 |
9 | ## What are SSH Keys?
10 |
11 | SSH keys are asymmetric key pairs that can be used for signing. Historically they were intended for
12 | logging into servers, but recently they can also be used for signing arbitrary data such as Git
13 | commits or even regular files. These key pairs consist of a private key, an associated public key,
14 | and fingerprint; the latter two can be used to verify a signature created using the private key.
15 |
16 | When stored on disk private keys can be stored in different formats. The modern, widely supported
17 | format is `OPENSSH` encoding, which supports all of `RSA`, `ECDSA`, and `Ed25519` keys. Some
18 | applications use the older `PKCS#8` format which is more complex. Further, `PKCS#8` encoded
19 | `Ed25519` keys are not supported by OpenSSH and need to be converted to `OPENSSH` format before they
20 | can be used.
21 |
22 | Private keys may be encrypted with a passphrase when stored on disk or left unprotected. When using
23 | a passphrase, the encryption key is derived from the passphrase using a
24 | [KDF](https://en.wikipedia.org/wiki/Key_derivation_function) such as `bcrypt`. SSH private keys can
25 | be encrypted using different ciphers -- `AES-128`, `AES-192`, `AES-256`, or `3DES`. Keys can be used
26 | directly by applications but more commonly they are loaded and held in an SSH agent. An agent can,
27 | after decrypting, hold the keys in memory and provide signing capabilities. Keys can also be stored
28 | on hardware tokens like YubiKeys (`ed25519-sk`).
29 |
--------------------------------------------------------------------------------
/custom-words.txt:
--------------------------------------------------------------------------------
1 | # Custom dictionary for spellchecking. Before adding a word here, consider whether you can put
2 | # it in a single (`) or multiline (```) code snippet instead, as they are automatically ignored
3 | # by the spellchecker. Please keep the list sorted alphabetically.
4 | AndroidX
5 | AOSP
6 | backplane
7 | Bitwarden
8 | bitwardensecret
9 | bytemark
10 | Casbin
11 | clickjacking
12 | codebases
13 | CODEOWNERS
14 | COSE
15 | CQRS
16 | CQS
17 | CTAP2
18 | deinitializer
19 | deinitializers
20 | dockerized
21 | dotfile
22 | F-Droid
23 | frontmatter
24 | Gitter
25 | HKDF
26 | HMAC
27 | hotfix
28 | hotfixed
29 | hotfixes
30 | Hyperscale
31 | iframes
32 | inet
33 | initialisms
34 | IntelliJ
35 | Iterm
36 | Jetpack
37 | jslib
38 | jumpcloud
39 | keychain
40 | keypair
41 | keyserver
42 | Kubebuilder
43 | LDIF
44 | libmagic
45 | LLDB
46 | Mailcatcher
47 | minio
48 | MVVM
49 | NGRX
50 | OIDCS
51 | Omnisharp
52 | onboarded
53 | opid
54 | OTLP
55 | owasp
56 | passcode
57 | passwordless
58 | pinentry
59 | PNSs
60 | POSIX
61 | precompiler
62 | proxied
63 | recompositions
64 | Redis
65 | refactorings
66 | roadmap
67 | roadmaps
68 | rollout
69 | rollouts
70 | rustup
71 | sandboxed
72 | SARIF
73 | SAST
74 | SCIM
75 | SDET
76 | SDLC
77 | Serilog
78 | signtool
79 | signup
80 | sqlcmd
81 | struct
82 | structs
83 | subfolders
84 | subprocessor
85 | toolset
86 | TOTP
87 | typealias
88 | typecheck
89 | typechecks
90 | typesafe
91 | unsynchronized
92 | WCAG
93 | Xcodes.app
94 | xcworkspace
95 | xmldoc
96 | Yellowpages
97 | Yubico
98 | YubiKey
99 | YubiKeys
100 |
101 | # Forbidden words
102 | !auto-fill
103 | !auto-filled
104 |
--------------------------------------------------------------------------------
/docs/contributing/user-secrets.md:
--------------------------------------------------------------------------------
1 | # Modifying User Secrets
2 |
3 | ## Manually editing user secrets
4 |
5 | We recommend using the automated helper script described in the
6 | [Server Setup Guide](../getting-started/server/guide.md). However, you can manually edit or
7 | troubleshoot your user secrets using the instructions below. If you are manually editing using
8 | secrets, make sure to remember to copy your changes across to all projects if required.
9 |
10 | ### Editing user secrets - Visual Studio on Windows
11 |
12 | Right-click on the project in the Solution Explorer and click **Manage User Secrets**.
13 |
14 | ### Editing user secrets - Visual Studio on macOS
15 |
16 | Open a terminal and navigate to the project directory.
17 |
18 | Add a user secret by running:
19 |
20 | ```bash
21 | dotnet user-secrets set "" ""
22 | ```
23 |
24 | View currently set secrets by running:
25 |
26 | ```bash
27 | dotnet user-secrets list
28 | ```
29 |
30 | By default, user secret files are located in:
31 |
32 | ```bash
33 | ~/.microsoft/usersecrets//secrets.json
34 | ```
35 |
36 | You can edit this file directly, which is much easier than using the command line tool.
37 |
38 | ### Editing user secrets - Visual Studio Code
39 |
40 | - Install the
41 | [.NET Core User Secrets](https://marketplace.visualstudio.com/items?itemName=adrianwilczynski.user-secrets)
42 | extension
43 | - Right-click on your project's **.csproj** file and select **Manage User Secrets**
44 |
45 | ### Editing user secrets - Rider
46 |
47 | - Navigate to **Preferences -> Plugins** and Install .NET Core User Secrets
48 | - Right click on the a project and click **Tools** > **Open project user secrets**
49 |
--------------------------------------------------------------------------------
/docs/getting-started/sdk/secrets-manager/index.mdx:
--------------------------------------------------------------------------------
1 | # Secrets Manager
2 |
3 | This section contains development information for the Bitwarden Secrets Manager CLI, language
4 | wrappers, and integrations based on the SDK.
5 |
6 | For more in-depth documentation please review the [SDK Architecture](../../../architecture/sdk),
7 | Secrets Manager SDK project's [`README`](https://github.com/bitwarden/sdk-sm).
8 |
9 | ## Requirements
10 |
11 | - [Rust](https://www.rust-lang.org/tools/install) latest stable version - (preferably installed via
12 | [rustup](https://rustup.rs/))
13 | - NodeJS and NPM.
14 |
15 | See the [Tools and Libraries](../../tools/index.md) page for more information.
16 |
17 | ## Setup instructions
18 |
19 | 1. Clone the repository:
20 |
21 | ```bash
22 | git clone https://github.com/bitwarden/sdk-sm.git
23 | cd sdk
24 | ```
25 |
26 | 2. Install the dependencies:
27 |
28 | ```bash
29 | npm ci
30 | ```
31 |
32 | ## Building the SDK
33 |
34 | To build the SDK, run the following command:
35 |
36 | ```bash
37 | cargo build
38 | ```
39 |
40 | ## Web client
41 |
42 | To start the web client, follow the
43 | [Web Vault setup instructions](../../clients/web-vault/index.mdx) and create an organization with
44 | Secrets Manager enabled. Then use the organization switcher to go to Secrets Manager.
45 |
46 | 
47 |
48 | :::info
49 |
50 | If you have enabled Secrets Manager for your org and do not see Secrets Manager in the product
51 | switcher, you may need to manually enable it for your user by going to **Admin Console** ->
52 | **Members** -> check _"This user can access Secrets Manager"_ for your user.
53 |
54 | 
55 |
56 | :::
57 |
--------------------------------------------------------------------------------
/scripts/generate-certs.sh:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env bash
2 |
3 | ROOT_DIR=$(git rev-parse --show-toplevel)
4 |
5 | # Load .env values into the environment
6 | set -o allexport
7 | . "$ROOT_DIR/.env"
8 | set +o allexport
9 |
10 | openssl req -x509 -newkey rsa:4096 -keyout $SSL_KEY_FILE -out $SSL_CRT_FILE -sha256 -days 1826 -nodes \
11 | -subj "/CN=localhost/O=Bitwarden Contributing Docs Local Development" \
12 | -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
13 |
14 | chmod +rw $SSL_CRT_FILE
15 | chmod +rw $SSL_KEY_FILE
16 |
17 | printf "Certificate generated! When prompted, enter your password to update your system's secure store with the Certificate Authority.\n\n"
18 | printf "Alternatively, you can manually add it with:\n"
19 |
20 | # Mac OSX
21 | if [[ "$OSTYPE" == "darwin"* ]]; then
22 | printf "\e[30m\e[44m sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain $SSL_CRT_FILE \e[0m\n"
23 |
24 | sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ssl.crt
25 | # If not Mac OS, assume *nix
26 | else
27 | printf "\e[30m\e[44m sudo cp $SSL_CRT_FILE /usr/local/share/ca-certificates/ && sudo update-ca-certificates \e[0m\n\n"
28 | printf "Important Note! Chromium doesn't use 'ca-certificates' on *nix. Instead it uses nssdb for cert storage, and depending on your configuration, may be in the shared system store at '\$HOME/.pki/nssdb', in Chromium's local snap store (e.g. '\$HOME/snap/chromium/current/.pki/nssdb'), or elsewhere. You will need to install the appropriate binary for your distro to run 'certutil -d sql:\$CHROMIUM_SECURE_STORE -A -t "CP,CP," -n DocsLocalDevelopmentSSL -i ./$SSL_CRT_FILE' from the project root."
29 |
30 | sudo cp $SSL_CRT_FILE /usr/local/share/ca-certificates/
31 | sudo update-ca-certificates
32 | fi
33 |
--------------------------------------------------------------------------------
/docs/getting-started/server/secrets/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar_custom_props:
3 | access: bitwarden
4 | ---
5 |
6 | # User Secrets
7 |
8 | The server repository comes with it’s own `dev/secrets.json` file for community contributors.
9 | Internal Bitwarden developers will need a different user secrets file in order to properly emulate
10 | the cloud environment.
11 |
12 | The user secrets file that we use for development can be found in the Development collection in the
13 | Bitwarden app. If you don’t have access to this collection, please contact your manager.
14 |
15 | 
16 |
17 | This secure note has 2 attachments:
18 |
19 | 1. `secrets.json` - the default recommended user secrets for development. This will use the local
20 | Docker services as outlined in the [Server Setup Guide](../guide.md) (e.g. MailCatcher and
21 | Azurite).
22 | 2. `additional-keys-for-cloud-services.json` - these are optional keys you can add to your
23 | `secrets.json` if you want to enable test cloud services instead of the local Docker services.
24 | It is not a complete secrets file and cannot be used on its own.
25 |
26 | ## Updating the shared user secrets
27 |
28 | If you need to update the shared user secrets, please follow these rules:
29 |
30 | - new user secrets should go in one `.json` file only. We want to avoid duplicate keys across both
31 | files.
32 | - avoid creating new `.json` files as a means of version control. Often the information (such as
33 | auth keys) can be retrieved from the original source if we need to roll back. If you feel that you
34 | must create a backup, mark it as "DEPRECATED" with the date. `secrets.json` and
35 | `additional-keys-for-cloud-services.json` should always contain the most up-to-date secrets.
36 | - announce any updates in the `#team-eng` Slack channel so that everyone knows to update their local
37 | instance.
38 |
--------------------------------------------------------------------------------
/docs/getting-started/clients/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar_position: 3
3 | ---
4 |
5 | # Web clients
6 |
7 | This section contains development information for each of the Bitwarden Typescript client
8 | applications:
9 |
10 | - [Web Vault](./web-vault)
11 | - [Browser](./browser)
12 | - [Desktop](./desktop)
13 | - [CLI](./cli)
14 |
15 | In this context, "clients" generally refers to the Typescript clients, which are located in the
16 | `clients` mono-repository.
17 |
18 | ## Requirements
19 |
20 | Before you start, you should have Node and npm installed. See the [Tools and Libraries](../tools)
21 | page for more information.
22 |
23 | ## Setup instructions
24 |
25 | Before doing work on any of the clients, you need to clone and setup the `clients` mono-repository.
26 |
27 | 1. Clone the repository:
28 |
29 | ```bash
30 | git clone https://github.com/bitwarden/clients.git
31 | ```
32 |
33 | 2. Install the dependencies:
34 |
35 | ```bash
36 | cd clients
37 | npm ci
38 | ```
39 |
40 | :::info
41 |
42 | You should only ever install dependencies from the root of the repository. Don't try to install
43 | dependencies for individual client applications.
44 |
45 | :::
46 |
47 | 3. Configure git blame to ignore certain commits (generally administrative changes, such as
48 | formatting):
49 |
50 | ```bash
51 | git config blame.ignoreRevsFile .git-blame-ignore-revs
52 | ```
53 |
54 | 4. Open the `clients.code-workspace` file in Visual Studio Code. This has been configured to use
55 | [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) to
56 | improve your development experience. Each client will appear as its own workspace in the
57 | Explorer panel on the left-hand side.
58 |
59 | You're now ready to continue with any additional instructions for the particular client you want to
60 | work on.
61 |
--------------------------------------------------------------------------------
/docs/architecture/sdk/data-models.md:
--------------------------------------------------------------------------------
1 | # Data models
2 |
3 | The SDK is expected to be used in a variety of projects, and to that end it defines a stable public
4 | interface. Care must be taken to avoid exposing the inner workings on the SDK including its data
5 | model.
6 |
7 | ## Public interface
8 |
9 | The public interface of the SDK is anything that is exposed externally, be it function names, types,
10 | or exposed models. The SDK generally exposes request and response models that contains the expected
11 | data for each API call.
12 |
13 | We can generally group the public models into the following categories:
14 |
15 | - **View models**: Models that generally represents a decrypted state, examples are `CipherView`,
16 | `CipherListView`, `FolderView`, etc.
17 | - **Request models**: Models that are used to send data into the SDK. Some examples are
18 | `ProjectGetRequest`, `ProjectCreateRequest`, etc.
19 | - **Response models**: Returns data from the SDK e.g. `ProjectResponse`.
20 |
21 | ## Internal models
22 |
23 | The SDK also maintains internal models:
24 |
25 | - **API models**: [Auto-generated models](./server-bindings.md) that are used to interact with the
26 | server.
27 | - **Domain models**: General data models used to represent a specific concern in the SDK. For
28 | example, `Cipher`, `Folder`, etc.
29 | - **DTO**: Data Transfer Objects are used to transfer data between layers of the SDK. They are
30 | generally used to decouple the domain models from the API models.
31 |
32 | ```kroki type=plantuml
33 | @startuml
34 | skinparam componentStyle rectangle
35 | component [""""] as Domain
36 | component [""""Requests] As Requests
37 | component [""""Response] as Response
38 | component [""""Views] as Views
39 | component [""""DTOs] as DTOs
40 |
41 | [Response] -r-> [Domain]
42 | [Domain] -r-> [Requests]
43 | [Domain] <--> [Views]
44 | [Domain] <--> [DTOs]
45 | @enduml
46 | ```
47 |
--------------------------------------------------------------------------------
/docs/architecture/security/principles/02-locked-vault-is-secure.mdx:
--------------------------------------------------------------------------------
1 | # P02 - A locked vault is secure
2 |
3 | Clients must ensure that highly sensitive vault data cannot be accessed in plain text once the vault
4 | has been locked, even if the device becomes compromised after the lock occurs. Protections are not
5 | guaranteed if the device is compromised before the vault is locked.
6 |
7 | ## Threat model
8 |
9 | A device has been compromised while the Bitwarden vault is locked (protections are not guaranteed if
10 | device is compromised before the vault is locked). Attacker has full access to userspace, but not
11 | kernel space.
12 |
13 | ## Security goals
14 |
15 | - Attackers cannot retrieve decrypted vault data
16 | - Attackers cannot retrieve user encryption keys
17 | - Attackers cannot inject arbitrary items as vault data
18 | - Attackers cannot edit encrypted vault data without alerting user or breaking items.
19 |
20 | ## Technical considerations
21 |
22 | Achieving this principle depends on the limitations of the platform and environment. For instance,
23 | in environments like JavaScript, where memory management is not fully under the control of the
24 | client, there may be residual plaintext in memory after the vault is locked. While ideal protection
25 | cannot be guaranteed in such cases, efforts must be made to minimize these risks through techniques
26 | such as clearing memory buffers and leveraging platform security features when available.
27 |
28 | ## Key storage mechanisms must provide adequate protection
29 |
30 | Mechanisms used for storing encryption keys when the vault is locked, such as PINs or auto-login,
31 | must provide an appropriate level of security. If encryption keys are stored in less secure
32 | environments (e.g. in the OS's keyring), the associated risks must be carefully considered and
33 | mitigated to ensure that unauthorized access to the vault remains limited, even when convenience
34 | features are used.
35 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/issue.yml:
--------------------------------------------------------------------------------
1 | name: Bug Report
2 | description: File a bug report
3 | labels: [bug]
4 | body:
5 | - type: markdown
6 | attributes:
7 | value: |
8 | Thanks for taking the time to fill out this bug report!
9 |
10 | Please do not submit feature requests. The [Community Forums](https://community.bitwarden.com) has a section for submitting, voting for, and discussing product feature requests.
11 | - type: input
12 | id: page
13 | attributes:
14 | label: Page
15 | description: Full url of the page where the issue was found.
16 | validations:
17 | required: true
18 | - type: textarea
19 | id: expected
20 | attributes:
21 | label: Expected Result
22 | description: A clear and concise description of what you expected to happen.
23 | validations:
24 | required: true
25 | - type: textarea
26 | id: actual
27 | attributes:
28 | label: Actual Result
29 | description: A clear and concise description of what is happening.
30 | validations:
31 | required: true
32 | - type: textarea
33 | id: screenshots
34 | attributes:
35 | label: Screenshots or Videos
36 | description: If applicable, add screenshots and/or a short video to help explain your problem.
37 | - type: textarea
38 | id: additional-context
39 | attributes:
40 | label: Additional Context
41 | description: Add any other context about the problem here.
42 | - type: checkboxes
43 | id: issue-tracking-info
44 | attributes:
45 | label: Issue Tracking Info
46 | description: |
47 | Issue tracking information
48 | options:
49 | - label:
50 | I understand that work is tracked outside of Github. A PR will be linked to this issue
51 | should one be opened to address it, but Bitwarden doesn't use fields like "assigned",
52 | "milestone", or "project" to track progress.
53 |
--------------------------------------------------------------------------------
/docs/architecture/adr/0001-reactive-forms.md:
--------------------------------------------------------------------------------
1 | ---
2 | adr: "0001"
3 | status: Accepted
4 | date: 2022-05-28
5 | tags: [clients, angular, forms]
6 | ---
7 |
8 | # 0001 - Angular Reactive Forms
9 |
10 |
11 |
12 | ## Context and problem statement
13 |
14 | Most of the forms in our Angular applications use the template driven forms. Lately we have been
15 | noticing issues scaling and maintaining these forms. And have begun mixing the use of
16 | template-driven with reactive forms.
17 |
18 | Maintaining two ways of handling forms are complex and moving full into a single approach will
19 | ensure a more consistent experience for developers and users.
20 |
21 | ## Considered options
22 |
23 | - **Reactive forms** - Provide direct, explicit access to the underlying forms object model.
24 | Compared to template-driven forms, they are more robust: they're more scalable, reusable, and
25 | testable. If forms are a key part of your application, or you're already using reactive patterns
26 | for building your application, use reactive forms.
27 | - **Template-driven forms** - Rely on directives in the template to create and manipulate the
28 | underlying object model. They are useful for adding a simple form to an app, such as an email list
29 | signup form. They're straightforward to add to an app, but they don't scale as well as reactive
30 | forms. If you have very basic form requirements and logic that can be managed solely in the
31 | template, template-driven forms could be a good fit.
32 |
33 | Source: https://angular.io/guide/forms-overview#choosing-an-approach
34 |
35 | ## Decision outcome
36 |
37 | Chosen option: **Reactive forms**, because our needs exceed what template-driven forms are
38 | recommended for.
39 |
40 | ### Positive consequences
41 |
42 | - You never need to think which form method to use.
43 |
44 | ### Negative consequences
45 |
46 | - Using only reactive form means we might have some additional boilerplate.
47 |
--------------------------------------------------------------------------------
/docs/architecture/adr/0013-deprecate-global-request-response-models.md:
--------------------------------------------------------------------------------
1 | ---
2 | adr: "0013"
3 | status: Accepted
4 | date: 2022-09-16
5 | tags: [clients, angular]
6 | ---
7 |
8 | # 0013 - Deprecate global request/response models
9 |
10 |
11 |
12 | ## Context and problem statement
13 |
14 | Our Angular application currently partially uses a layered folder structure. This results in a
15 | domain context being split between multiple folders several levels deep. This causes friction since
16 | modifying services often requires modifying the models belonging to that service.
17 |
18 | Understandably our application uses a lot of models, however the biggest and most isolated part of
19 | the models are the request and responses. Which makes them a good starting point.
20 |
21 | ## Considered options
22 |
23 | - **Continue as is** - We can continue as we are, and continue to put models in
24 | `libs/common/models`.
25 | - **Place models next to their owner** - Request and responses are owned by a single API service.
26 | They can therefore be placed close to their service which keeps connected changes close to each
27 | other.
28 |
29 | ### Decision Outcome
30 |
31 | Use the **Place models next to their owner** for request and response models.
32 |
33 | A rule of thumb is to put any model that is used in the abstraction in the abstraction directory.
34 | And any model used in the service in the service directory. Abstractions are part of the service
35 | public interface, while services are part of the internal interface.
36 |
37 | ### Example
38 |
39 | ```text
40 | libs/common/
41 | abstractions/folder/
42 | folder.service.abstraction.ts
43 | folder-api.service.abstraction.ts
44 | responses/
45 | folder.response.ts (Exposed as public API)
46 | services/folder/
47 | folder.service.ts
48 | folder-api.service.ts
49 | requests/
50 | folder.request.ts (Internal, only used within the implementation)
51 | ```
52 |
--------------------------------------------------------------------------------
/docs/architecture/adr/0005-refactor-api-service.md:
--------------------------------------------------------------------------------
1 | ---
2 | adr: "0005"
3 | status: Accepted
4 | date: 2022-07-08
5 | tags: [clients, angular]
6 | ---
7 |
8 | # 0005 - Refactor Api Service
9 |
10 |
11 |
12 | ## Context and problem statement
13 |
14 | The `ApiService` currently handles _all_ API requests. This has resulted in the class evolving into
15 | a Bloater, and as of right now consists of **2021** lines of code, and has **268** methods.
16 | Additionally, since it knows everything related to the servers it also needs to import every request
17 | and response which necessitates that the `ApiService` and request/responses are put in the same npm
18 | package.
19 |
20 | ## Considered options
21 |
22 | - **Extract Class** - We should break up the class using the _Extract Class_ refactor, where each
23 | domain context should have its own _API_ service. The `ApiService` should be converted into a
24 | generic service that doesn't care what the request or response is and should only be used within
25 | other API services.
26 | - **Do nothing** - Leave it as is.
27 |
28 | ## Decision outcome
29 |
30 | Chosen option: **Extract Class**
31 |
32 | The naming of these new classes should be `{Domain}ApiService`, the folder domain for example should
33 | be called `FolderApiService`.
34 |
35 | Example of the refactor:
36 |
37 | - [`folder-api.service.ts`][folder-api]: Create a new service, move the methods from `ApiService` to
38 | the new service. During this refactor we also moved the server knowledge from the `FolderService`,
39 | as it should only be responsible for maintaining it's state.
40 | - [`api.service.ts`][api]: Remove the old methods from the `ApiService`.
41 |
42 | [folder-api]:
43 | https://github.com/bitwarden/clients/pull/3011/files#diff-11b3488b9977f06625349680f81554505613715cfcc9890ebb356a74579c236a
44 | [api]:
45 | https://github.com/bitwarden/clients/pull/3011/files#diff-6c8f3163b688c01f589d1e9ee5b7998aea4a0aedde8333c3939fb6181c301bed
46 |
--------------------------------------------------------------------------------
/docs/architecture/deep-dives/passkeys/implementations/relying-party/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Relying Party
3 | sidebar_position: 1
4 | ---
5 |
6 | # Overview
7 |
8 | Bitwarden can act as a Relying Party (RP) for passkeys. This means that you can log in to Bitwarden
9 | using a passkey. Bitwarden supports passkeys as a second factor of authentication (2FA) and as a
10 | primary factor of authentication. When used as a primary factor of authentication, Bitwarden will
11 | not require you to enter a username or password when logging in. In cases where your passkey
12 | [supports encryption](prf.md), your passkey will be able to decrypt your data as well. If your
13 | passkey does not support encryption, Bitwarden will prompt you to enter a password to unlock your
14 | vault.
15 |
16 | ## Implementations
17 |
18 | Bitwarden currently has two implementations for authenticating users using passkeys:
19 |
20 | - Older 2FA "WebAuthn" implementation
21 | - Newer "Log in with Passkeys" implementation
22 |
23 | Both implementations use the same FIDO2 technologies, but are completely separate and share almost
24 | no code. From a user perspective "Log in with Passkeys" is a first-factor authentication method,
25 | while the older "WebAuthn" implementation is a second-factor. "Log in with Passkeys" takes advantage
26 | of FIDO2 User Verification and therefore completely replaces the other existing 2FA methods.
27 |
28 | The 2FA implementation will eventually be consolidated with the newer "Log in with Passkey"
29 | implementation.
30 |
31 | ## Storage modality
32 |
33 | - The 2FA "WebAuthn" implementation supports both client-side and server-side storage mode.
34 | - The "Log in with Passkeys" implementation only supports the client-side storage mode.
35 |
36 | ## Discoverability
37 |
38 | - The 2FA "WebAuthn" implementation does not support discoverability, as it is a second-factor
39 | authentication method and supports the server-side storage mode.
40 | - The "Log in with Passkeys" implementation requires discoverable credentials.
41 |
--------------------------------------------------------------------------------
/docs/architecture/clients/data-model.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar_position: 2
3 | ---
4 |
5 | # Data Model
6 |
7 | This document describes the internal data model used by the different client applications. We use
8 | several dedicated models to represent our data layer. With a slightly complicated data
9 | transformation pipeline.
10 |
11 | ```kroki type=plantuml
12 | @startuml
13 | skinparam componentStyle rectangle
14 | component [""""] as Domain
15 | component [""""Request] As Request
16 | component [""""Response] as Response
17 | component [""""View] as View
18 | component [""""Export] as Export
19 | component [""""Data] as Data
20 |
21 | [Response] -r-> [Data]
22 | [Data] <-r-> [Domain]
23 | [Domain] -r-> [Request]
24 | [Domain] <--> [View]
25 | [Domain] <--> [Export]
26 | [Export] -r-> [View]
27 | @enduml
28 | ```
29 |
30 | ## Domain
31 |
32 | The Domain models lies at the center of our data model, and represents encrypted data.
33 |
34 | ## View
35 |
36 | View models represent the decrypted state of the corresponding `Domain` model. They typically match
37 | the `Domain` model but contains a decrypted string for any `EncString` fields.
38 |
39 | ## Data
40 |
41 | The `Data` models are serializable versions of the corresponding `Domain`. In most cases this means
42 | converting `Date` to `string`. It's exclusively used when serializing the `Domain` models to disk
43 | for persisting state or export. This means it also needs to support deserialize older data models,
44 | which is traditionally done by providing good default values.
45 |
46 | ## Export
47 |
48 | Export models built from Domain or View models. Used for importing and exporting Bitwarden data.
49 |
50 | ## Request & Response (Deprecated)
51 |
52 | In the process of being migrated to live next to the the domain's API service. At which point it
53 | will no longer be a central part of our data model.
54 |
55 | ### Api
56 |
57 | Shared API models used to convert from Responses to Data. Essentially an re-usable extension of the
58 | request models.
59 |
--------------------------------------------------------------------------------
/docs/getting-started/clients/cli/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar_position: 5
3 | ---
4 |
5 | # CLI
6 |
7 | :::tip
8 |
9 | If you’re not familiar with the CLI client, the Bitwarden Help Center has lots of
10 | [great documentation](https://bitwarden.com/help/article/cli/) that will help you get oriented.
11 |
12 | :::
13 |
14 | ## Requirements
15 |
16 | Before you start, you must complete the [Clients repository setup instructions](../index.md).
17 |
18 | ## Build instructions
19 |
20 | :::tip Nx commands are preferred.
21 |
22 | We now recommend using Nx commands for building projects. For the cli:
23 |
24 | ```bash
25 | # Build and watch (GPL)
26 | npx nx serve cli --configuration=oss-dev
27 | # Build and watch (Bitwarden)
28 | npx nx serve cli --configuration=commercial-dev
29 | ```
30 |
31 | For complete Nx documentation and all available commands, see
32 | [Using Nx to Build Projects](https://github.com/bitwarden/clients/blob/main/docs/using-nx-to-build-projects.md).
33 | :::
34 |
35 | Build and run:
36 |
37 |
38 |
39 | ```bash
40 | cd apps/cli
41 | npm run build:bit:watch
42 | ```
43 |
44 |
45 |
46 |
47 |
48 | ```bash
49 | cd apps/cli
50 | npm run build:oss:watch
51 | ```
52 |
53 |
54 |
55 | By default, this will use the official Bitwarden servers. You can target your local server by using
56 | the [config command](https://bitwarden.com/help/article/cli/#config). You may need to
57 | [configure node to use your self-signed certificate](https://bitwarden.com/help/article/cli/#using-self-signed-certificates).
58 |
59 | ## Testing and Debugging
60 |
61 | The build is located at `build/bw.js`. You can run this with node, for example:
62 |
63 | ```bash
64 | node build/bw.js login
65 | ```
66 |
67 | It may be more convenient to make the file executable first:
68 |
69 | ```bash
70 | cd build
71 | chmod +x bw.js
72 | ./bw.js login
73 | ```
74 |
75 | To debug the CLI client, run it from a
76 | [Javascript Debug Terminal](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_javascript-debug-terminal)
77 | and place the breakpoints in your Typescript code.
78 |
--------------------------------------------------------------------------------
/docs/architecture/deep-dives/passkeys/naming-convention.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar_position: 4
3 | ---
4 |
5 | # Naming convention
6 |
7 | Since Bitwarden will both store passkeys in users' vaults and support login with passkeys, it is
8 | important to understand how to refer to these two different concepts in code, regardless of how they
9 | are referred to in the marketplace, especially since the term "passkey" is one that is evolving over
10 | time.
11 |
12 | The current convention is:
13 |
14 | - When working with [Provider](implementations/provider) code (i.e storing a credential in the
15 | vault), use `Fido2`.
16 | - Example: `Fido2Credential`, `Fido2Client`.
17 | - When working with [Relying Party](implementations/relying-party) code (i.e. authenticating to
18 | Bitwarden with a passkey), use `WebAuthn`.
19 | - Example: `WebAuthnLogin` for passkey login, `WebAuthn` for the older 2FA log in.
20 | - Use the term `Credential` (and not `Passkey`) when referring to a FIDO2 Credential in code.
21 |
22 | ## FIDO2 vs WebAuthn
23 |
24 | This naming scheme is not based on any hard rules defined in the specifications, but rather on which
25 | parts of FIDO2 are used to build the Provider and Relying Party code.
26 |
27 | Historically, the Provider code was built on both the WebAuthn and CTAP2 specifications and so
28 | `Fido2` was used to refer to it. Today, the Provider code is almost exclusively based on the
29 | WebAuthn specification. However, if Bitwarden chooses to support any authenticator extensions in the
30 | future (e.g. `hmac-secret`), they will likely be defined in the CTAP2 specification.
31 |
32 | In contrast, the Relying Party code is built exclusively on the WebAuthn specification and does not
33 | need to refer to CTAP2 at all, which is why the term `WebAuthn` was chosen. The older 2FA
34 | implementation is also based on the WebAuthn specification, but it is not a "login method" and so it
35 | is not referred to as `WebAuthnLogin`.
36 |
37 | :::info
38 |
39 | The implementation of 2FA login will eventually be consolidated with the newer passkey login
40 | implementation under the `WebAuthn` namespace.
41 |
42 | :::
43 |
--------------------------------------------------------------------------------
/docs/architecture/clients/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar_position: 4
3 | ---
4 |
5 | # Web Clients Architecture
6 |
7 | The Web based clients, henceforth referenced simply as clients, are the _Web Vault_, _Browser
8 | Extension_, _Desktop Application_ (Electron based) and the _CLI_. They all share a common codebase
9 | and a single [Git repository](https://github.com/bitwarden/clients).
10 |
11 | The mono-repository root directory contains three main folders.
12 |
13 | - `apps` - Our different application specific code, consists of `web`, `browser`, `desktop` and
14 | `cli`.
15 | - `bitwarden_license` - Bitwarden Licensed version of the web vault.
16 | - `libs` - Shared code between the different applications.
17 |
18 | `libs` contains the following projects.
19 |
20 | - `Common` - Common code shared between all the clients including CLI.
21 | - `Angular` - Angular specific code used by all the visual clients.
22 | - `Components` - Angular Components Library.
23 | - `Node` - Used to be shared code for CLI and Directory Connector CLI, but since directory connector
24 | no longer uses the same version of libs this module is deprecated.
25 |
26 | ## Package diagram
27 |
28 | Below is a simplified package diagram of the clients repository.
29 |
30 | :::note
31 |
32 | For readability, ubiquitous app dependencies to `common` are hidden.
33 |
34 | :::
35 |
36 | ```kroki type=plantuml
37 | @startuml
38 | skinparam BackgroundColor transparent
39 | skinparam componentStyle rectangle
40 | skinparam linetype ortho
41 |
42 | title Simplified Package Diagram
43 |
44 | component "Bitwarden License" {
45 | component "Bit Web"
46 | }
47 |
48 | component apps {
49 | component "Web Vault"
50 | component "Desktop"
51 | component "Browser Extension"
52 | component "CLI"
53 | }
54 |
55 | component libs {
56 | component "Common"
57 | component "Angular"
58 | component "Node"
59 | }
60 |
61 | [Bit Web] --> [Web Vault]
62 | [Bit Web] --[norank]> [Angular]
63 |
64 | [Web Vault] --> [Angular]
65 |
66 | [Browser Extension] --> [Angular]
67 |
68 | [CLI] --> [Node]
69 |
70 | [Angular] --> [Common]
71 |
72 | [Desktop] --> [Angular]
73 |
74 | [Node] --> [Common]
75 | @enduml
76 | ```
77 |
--------------------------------------------------------------------------------
/docs/architecture/deep-dives/passkeys/glossary.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar_position: 6
3 | ---
4 |
5 | # Glossary
6 |
7 | This page contains some definitions of terms used throughout the passkey documentation. For a more
8 | comprehensive list, see the
9 | [FIDO Alliance Glossary](https://fidoalliance.org/specs/common-specs/fido-glossary-v2.1-rd-20210525.html).
10 |
11 | ## Definitions
12 |
13 |
14 |
Passkey
15 |
Any passwordless FIDO2 credential.
16 |
17 |
Credential
18 |
The technical term for a passkey. The two terms are used interchangeably.
19 |
20 |
Relying Party (RP)
21 |
A web site or other entity that uses a FIDO2 protocol to authenticate users by asking for a passkey.
22 |
23 |
Passkey Provider (PP)
24 |
An app and/or service that is responsible for storing and managing passkeys. Many operating systems include a default passkey provider (first-party), and many also support third-party providers (like Bitwarden).
25 |
26 |
Attestation
27 |
The process used to create a new passkey.
28 |
The process of communicating a cryptographic assertion to a relying party that a key presented during authenticator registration was created and protected by a genuine authenticator with verified characteristics.
29 |
30 |
Attestation Statement
31 |
An optional statement about the exact type (make/model) of the authenticator and its capabilities.
32 |
An optional statement provided by an authenticator which can be used by a Relying Party to identify and verify the provenance of the authenticator. Not to be confused with "attestation" which can be performed without providing a statement about the provenance of the authenticator.
33 |
34 |
Assertion
35 |
The process used to log in.
36 |
The act of proving ownership of the private key, commonly referred to as authentication.
37 |
38 |
Fallback
39 |
Aborting the Bitwarden-side of the authentication process and handing off control to the native browser implementation of WebAuthn, enabling the user to use hardware security keys, etc.
40 |
41 |
--------------------------------------------------------------------------------
/docs/architecture/adr/0007-manifest-v3-browser-memory-caching.md:
--------------------------------------------------------------------------------
1 | ---
2 | adr: "0007"
3 | status: Accepted
4 | date: 2022-07-12
5 | tags: [browser, angular]
6 | ---
7 |
8 | # 0007 - Manifest V3 sync Observables
9 |
10 |
11 |
12 | ## Context and problem statement
13 |
14 | Manifest v3 brings ephemeral contexts to web extensions by disallow a long-lived background process.
15 | This means that we need to store and synchronize state through different popup/service worker/web
16 | worker instances. This is done through `LocalBackedMemoryStorageService`.
17 |
18 | Moving away from StateService to observables has made this harder because observables are
19 | fundamentally tied to the extension instance.
20 |
21 | We need to store these observables to maintain state. State should be loaded on init, updated on
22 | next, and updated via a reload message.
23 |
24 | ## Considered options
25 |
26 | - **Init in constructor and update in UpdateObservables** - This is simple and clean, but lacks the
27 | guarantees that we always will update storage and emit messages. It also doesn't provide a way to
28 | sync data live if a side bar is open and a cipher is saved via the content scripts. We could build
29 | a timer to sync these items periodically from memory.
30 | - **Decorator pattern** - Use a decorator to wrap service constructors. This decorator will
31 | - initialize from `LocalBackedMemoryStorage`
32 | - Subscribe to the observer to update `LocalBackedMemoryStorage` and push event to workers to
33 | update observable from memory
34 | - Push `observable.next` on update event
35 | - Avoid a circular event loop here? (loops occur both on message and on observable)
36 | - message can be fixed with a guid
37 | - TODO: issue with message -> `observable.next` -> subscribe -> storage service is unknown
38 |
39 | ## Decision outcome
40 |
41 | Chosen option: **Decorator Pattern**. This will be more reusable and the cleaner solution going
42 | forward. It needs more thought to determine how to avoid circular events, but once solved, it is
43 | solved.
44 |
45 | ### Positive consequences
46 |
47 | - reusable, clean solution
48 | - adheres to observable best practices
49 |
50 | ### Negative consequences
51 |
52 | - some unknown implementation details may cause bumps along development
53 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "@bitwarden/contributing-docs",
3 | "version": "0.0.0",
4 | "description": "Bitwarden Contributing Docs",
5 | "repository": {
6 | "type": "git",
7 | "url": "git+https://github.com/bitwarden/contributing-docs.git"
8 | },
9 | "author": "Bitwarden Inc. (https://bitwarden.com)",
10 | "license": "SEE LICENSE IN LICENSE.txt",
11 | "bugs": {
12 | "url": "https://github.com/bitwarden/contributing-docs/issues"
13 | },
14 | "homepage": "https://bitwarden.com",
15 | "private": true,
16 | "scripts": {
17 | "docusaurus": "docusaurus",
18 | "start": "./scripts/docusaurus-start.sh",
19 | "start:insecure": "docusaurus start",
20 | "setup:ssl": "./scripts/generate-certs.sh",
21 | "build": "docusaurus build",
22 | "swizzle": "docusaurus swizzle",
23 | "deploy": "docusaurus deploy",
24 | "clear": "docusaurus clear",
25 | "serve": "docusaurus serve",
26 | "write-translations": "docusaurus write-translations",
27 | "write-heading-ids": "docusaurus write-heading-ids",
28 | "typecheck": "tsc",
29 | "prettier": "prettier --write .",
30 | "lint": "prettier --check .",
31 | "prepare": "husky",
32 | "spellcheck": "cspell lint \"**/*.md{x,}\""
33 | },
34 | "dependencies": {
35 | "@docusaurus/core": "3.9.2",
36 | "@docusaurus/preset-classic": "3.9.2",
37 | "@mdx-js/react": "3.1.0",
38 | "docusaurus-lunr-search": "3.6.0",
39 | "prism-react-renderer": "2.4.1",
40 | "react": "19.2.0",
41 | "react-dom": "19.2.0",
42 | "remark-kroki": "0.3.7"
43 | },
44 | "devDependencies": {
45 | "@docusaurus/module-type-aliases": "3.9.2",
46 | "@docusaurus/tsconfig": "3.9.2",
47 | "@types/react": "19.2.2",
48 | "cspell": "9.3.2",
49 | "husky": "9.1.7",
50 | "lint-staged": "16.2.3",
51 | "prettier": "3.6.2",
52 | "typescript": "5.9.2"
53 | },
54 | "browserslist": {
55 | "production": [
56 | ">0.5%",
57 | "not dead",
58 | "not op_mini all"
59 | ],
60 | "development": [
61 | "last 1 chrome version",
62 | "last 1 firefox version",
63 | "last 1 safari version"
64 | ]
65 | },
66 | "engines": {
67 | "node": "~22.14.0",
68 | "npm": "~11.3.0"
69 | },
70 | "lint-staged": {
71 | "*": "prettier --cache --write --ignore-unknown",
72 | "*.md{x,}": "cspell lint"
73 | }
74 | }
75 |
--------------------------------------------------------------------------------
/docs/architecture/security/index.mdx:
--------------------------------------------------------------------------------
1 | # Security
2 |
3 | Outlines the foundational approach Bitwarden takes to ensure the safety and integrity of user data.
4 | It provides a structured framework for understanding Bitwarden's security philosophy, the principles
5 | it adheres to, and the specific requirements it implements to meet its commitments.
6 |
7 | ## Conventions
8 |
9 | ### Keywords
10 |
11 | The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
12 | "RECOMMENDED", "MAY", and "OPTIONAL" in this section are to be interpreted as described in
13 | [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119).
14 |
15 | ### References
16 |
17 | Principles in this documentation are labeled with unique identifiers (e.g., P01, P02, etc.) for easy
18 | reference throughout the document and in related discussions. When referencing a principle, simply
19 | use its identifier (e.g. P01).
20 |
21 | Requirements in this documentation use a shorthand format (e.g. XX.N.y) to indicate their specific
22 | location and context (e.g. VD.3.b).
23 |
24 | ## Structure
25 |
26 | This structure is meant to avoid unnecessary repetition and establish a logical flow from high-level
27 | philosophies to specific actions. It ensures that every requirement is tied to a well-defined
28 | principle, making it clear why it exists and what it is meant to achieve. The document is designed
29 | for both internal stakeholders and external users who seek to understand the company's security
30 | model.
31 |
32 | ### Definitions
33 |
34 | Establishes the foundational terminology used throughout the document. By clearly defining key
35 | concepts -- such as what constitutes "vault data" -- it ensures that the rest of the document is
36 | precise and unambiguous.
37 |
38 | ### Principles
39 |
40 | Describes the overarching philosophies and commitments that guide Bitwarden's approach to security.
41 | These principles are not actionable rules but rather serve as the justifications for the
42 | requirements that follow. They define what Bitwarden aims to achieve in its security posture and why
43 | certain decisions are made.
44 |
45 | ### Requirements
46 |
47 | Building on the principles, the requirements are concrete, actionable steps that Bitwarden is
48 | required to implement. These requirements ensure that the principles are upheld in practice and
49 | provide a measurable way to assess Bitwarden's security efforts.
50 |
--------------------------------------------------------------------------------
/docs/architecture/adr/0012-angular-filename-convention.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: 0012 - Angular filename convention
3 | adr: "0012"
4 | status: Accepted
5 | date: 2022-08-23
6 | tags: [clients, angular]
7 | ---
8 |
9 | # 0012 - Angular Filename convention
10 |
11 |
12 |
13 | ## Context and problem statement
14 |
15 | We currently use a mixed filename convention where some files follows the Angular style guide, and
16 | other files use camelCase. This causes some confusion as to which convention to follow, and we
17 | should standardize on one convention to avoid confusion.
18 |
19 | ## Considered options
20 |
21 | - **Angular coding style guide** - The Angular coding style guide specifies "Separate file names
22 | with dots and dashes".
23 | - **camelCase** - Our own convention has for a long time been to use camelCase.
24 |
25 | ### Decision Outcome
26 |
27 | Use the [**Angular coding style guide**][naming]. More specifically [Style 02-02][style-02-02] and
28 | [Style 02-03][style-02-03].
29 |
30 | These two style rules focuses on using dashes to separate words in the descriptive name, and dots to
31 | separate name from the type. Angular typically has the following types:
32 |
33 | - `service` - Abstract Service
34 | - `component` - Angular Components
35 | - `pipe` - Angular Pipe
36 | - `module` - Angular Module
37 | - `directive` - Angular Directive
38 |
39 | At Bitwarden we also use a couple of more types:
40 |
41 | - `.api` - Api Model
42 | - `.data` - Data Model (used for serializing domain model)
43 | - `.view` - View Model (decrypted domain model)
44 | - `.export` - Export Model
45 | - `.request` - Api Request
46 | - `.response` - Api Response
47 | - `.type` - Enum
48 |
49 | The class names are expected to use the suffix as part of their class name as well. I.e. a service
50 | implementation will be named `FolderService`, a request model will be named `FolderRequest`.
51 |
52 | ### Positive consequences
53 |
54 | - Since most of our code is written in Angular, we should use the Angular coding style guide.
55 | - Not using camelCase will avoid issues with case-sensitive file systems.
56 |
57 | ### Negative consequences
58 |
59 | - We need to update a lot of files to be consistent.
60 |
61 | [naming]: https://angular.io/guide/styleguide#naming
62 | [style-02-02]: https://angular.io/guide/styleguide#style-02-02
63 | [style-02-03]: https://angular.io/guide/styleguide#style-02-03
64 |
--------------------------------------------------------------------------------
/docs/architecture/adr/0004-refactor-state-service.md:
--------------------------------------------------------------------------------
1 | ---
2 | adr: "0004"
3 | status: Accepted
4 | date: 2022-06-30
5 | tags: [clients, angular]
6 | ---
7 |
8 | # 0004 - Refactor State Service
9 |
10 |
11 |
12 | ## Context and problem statement
13 |
14 | This ADR builds upon [Adopt Observable Data Services for Angular][observable].
15 |
16 | The Bitwarden clients currently have a quite complex state architecture, where all the state is
17 | handled by a single service. This has resulted in everything being tightly coupled to the
18 | `StateService` essentially making it a God object.
19 |
20 | Additionally any service or component can directly access any state using the state service. Which
21 | makes it difficult to follow the state lifecycle of each data type, and introduces uncertainty in
22 | how the data is accessed.
23 |
24 | ## Decision outcome
25 |
26 | We should refactor the state service to be a generic storage container.
27 |
28 | - Good: Eliminates the "good" functionality of the state service
29 | - Good: State is maintained by the service which owns it.
30 | - Good: No arbitrary access of data.
31 | - Bad: Brings back arbitrary keys that must be unique.
32 |
33 | ### Example
34 |
35 | ```ts
36 | interface StateService {
37 | getAccountData: (account: Account, key: string, options?: StorageOptions) => Promise;
38 | saveAccountData: (account: Account, key: string, options?: StorageOptions) => Promise;
39 | deleteAccountData: (account: Account, key: string, options?: StorageOptions) => Promise;
40 |
41 | deleteAllAccountData: (account: Account);
42 |
43 | getGlobalData: (key: string, options?: StorageOptions) => Promise;
44 | saveGlobalData: (key: string, options?: StorageOptions) => Promise;
45 | deleteGlobalData: (key: string, options?: StorageOptions) => Promise;
46 | }
47 | ```
48 |
49 | ```ts
50 | // StorageKey is an internal constant, and should be prefixed with the domain.
51 | // DO NOT EXPORT IT.
52 | const StorageKey = "organizations";
53 |
54 | class OrganizationService {
55 | async save(organizations: { [adr: string]: OrganizationData }) {
56 | await this._stateService.saveAccountData(this._activeAccount, StorageKey, organizations);
57 | await this._organizations$.next(await this.decryptOrgs(this._activeAccount, organizations));
58 | }
59 | }
60 | ```
61 |
62 | [observable]: ./0003-observable-data-services.md
63 |
--------------------------------------------------------------------------------
/docs/architecture/deep-dives/database-replicas.md:
--------------------------------------------------------------------------------
1 | # Read-Only Database Replicas
2 |
3 | ## Context
4 |
5 | Bitwarden utilizes
6 | [Azure SQL Hyperscale](https://learn.microsoft.com/en-us/azure/azure-sql/database/service-tier-hyperscale?view=azuresql)
7 | and its
8 | [high-availability replica](https://learn.microsoft.com/en-us/azure/azure-sql/database/service-tier-hyperscale-replicas?view=azuresql#high-availability-replica)
9 | available as a _read_ replica. This allows Bitwarden to double the max worker limit (along with
10 | compute, memory, and network throughput) without needing to scale up the primary database. The HA
11 | replica replicates the primary instance by mirroring the transaction log records.
12 |
13 | ## Vision
14 |
15 | More read-only capabilities should be used in conjunction with read-only replicas, especially after
16 | stored procedures have been tuned and there are prominent performance bottlenecks relating to
17 | read-only queries.
18 |
19 | ## Usage
20 |
21 | We currently use the read-only replica in two areas:
22 |
23 | 1. [Methods within the Dapper repositories](https://github.com/search?q=repo%3Abitwarden%2Fserver+%22using+%28var+connection+%3D+new+SqlConnection%28ReadOnlyConnectionString%29%29%22&type=code)
24 | with `using (var connection = new SqlConnection(ReadOnlyConnectionString))` defined.
25 | 2. Data engineering pipelines that require direct connection to the database.
26 |
27 | ## Gotchas / Considerations
28 |
29 | - [CAP Theorem](https://en.wikipedia.org/wiki/CAP_theorem) applies here. Microsoft does not
30 | guarantee data consistency and
31 | [propagation latency](https://learn.microsoft.com/en-us/azure/azure-sql/database/read-scale-out?view=azuresql#data-consistency)
32 | could vary greatly. For business logic that need consistency, read-only replicas are not a viable
33 | solution.
34 | - Lack of observability -- currently there is limited visibility into query performance metrics as
35 | well as resource utilization on the replica itself.
36 | - Long-running queries on read-only replicas can cause
37 | [blocking](https://learn.microsoft.com/en-us/azure/azure-sql/database/read-scale-out?view=azuresql#long-running-queries-on-read-only-replicas).
38 | - The HA replica is not a backup and should not be treated as such. If a destructive migration had
39 | been run on the primary instance it will be reflected on the HA replica. DR procedures will have
40 | to be carried out in this scenario and there will be data loss.
41 |
--------------------------------------------------------------------------------
/docs/contributing/code-style/web/tailwind.md:
--------------------------------------------------------------------------------
1 | # Tailwind
2 |
3 | Before starting working with Tailwind we recommend that you get familiar with
4 | [Utility-First Fundamentals](https://tailwindcss.com/docs/utility-first). The blog article
5 | [_CSS Utility Classes and "Separation of Concerns"_](https://adamwathan.me/css-utility-classes-and-separation-of-concerns/)
6 | is also a good read to better understand the motivation and goals behind Utility first CSS
7 | frameworks.
8 |
9 | We also recommend using the search functionality of the
10 | [tailwind documentation](https://tailwindcss.com/) to lookup classes and examples.
11 |
12 | ## Tailwind at Bitwarden
13 |
14 | We have defined our own
15 | [tailwind config](https://github.com/bitwarden/clients/blob/main/libs/components/tailwind.config.base.js),
16 | which heavily restricts the color usage as a way to support multiple themes. To achieve this we use
17 | [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) in
18 | combination with the tailwind config. This allows us to support more than the built in dark/light
19 | support in Tailwind.
20 |
21 | To this effort we heavily discourage the use of
22 | [arbitrary values](https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values) with
23 | the only exception being to support existing Bootstrap styles. In which case it should be documented
24 | and added as a tech debt to be tackled as part of the migration away from Bootstrap.
25 |
26 | :::note
27 |
28 | All Tailwind classes need to be prefixed by `tw-` as defined in the tailwind config.
29 |
30 | Example usage: `
...
`
31 |
32 | :::
33 |
34 | ### Components
35 |
36 | Since Tailwind is a Utility-First CSS framework to avoid code duplication which would make the
37 | design difficult to maintain we make heavy use of Angular Components to encapsulate isolated design
38 | blocks. In most cases these blocks are
39 | [presentational components](https://angular-training-guide.rangle.io/state-management/ngrx/component_architecture).
40 |
41 | ### Component Library
42 |
43 | One of the engineering initiatives at Bitwarden is the
44 | [Component Library](https://github.com/bitwarden/clients/tree/main/libs/components) which aims to
45 | encapsulate the most commonly used core components.
46 |
47 | #### Storybook
48 |
49 | We use [Storybook](https://storybook.js.org/) to develop components in isolation. To launch
50 | storybook run the `npm run storybook` command in the root of `clients` repository.
51 |
--------------------------------------------------------------------------------
/docs/getting-started/server/troubleshooting.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar_position: 10
3 | ---
4 |
5 | # Troubleshooting
6 |
7 | ## macOS
8 |
9 | ### AppleCFErrorCryptographicException
10 |
11 | Error:
12 | `Interop.AppleCrypto.AppleCFErrorCryptographicException: The operation couldn't be completed.`
13 |
14 | There could be a couple fixes to this problem, the most likely is you need to restart your device.
15 |
16 | If that doesn't work, you could try force unlocking your login keychain with:
17 |
18 | ```bash
19 | security -v unlock-keychain /Users/$USER/Library/Keychains/login.keychain
20 | ```
21 |
22 | If that doesn't work either, Mac can sometimes set trust settings for your certificates as admin
23 | instead of as user. If you don't see your certificates by running:
24 |
25 | ```bash
26 | security dump-trust-settings
27 | ```
28 |
29 | Then try running:
30 |
31 | ```bash
32 | security dump-trust-settings -d
33 | ```
34 |
35 | If your certificates show up here you will have to export the trust settings to user using the
36 | [security command](https://ss64.com/osx/security.html), as there is no way to specify this in the
37 | Keychain Access Application.
38 |
39 | To do this, run `security trust-settings-export -d ` to export the admin certificates.
40 | Then import them into user with `security trust-settings-import `.
41 |
42 | See the related [Github Issue](https://github.com/dotnet/runtime/issues/59703) for more information.
43 |
44 | ### Error NU1403: Package content hash validation failed
45 |
46 | Following commands should fix the problem:
47 |
48 | ```bash
49 | dotnet nuget locals all --clear
50 | git clean -xfd
51 | git rm \*\*/packages.lock.json -f
52 | dotnet restore
53 | ```
54 |
55 | For more details read
56 | [https://github.com/NuGet/Home/issues/7921#issuecomment-478152479](https://github.com/NuGet/Home/issues/7921#issuecomment-478152479)
57 |
58 | ## Windows
59 |
60 | ### An attempt was made to access a socket in a way forbidden by its access permissions
61 |
62 | This error typically occurs when the application attempts to use a port that is either already in
63 | use or reserved. Newer Windows with Hyper-V reserves many ports 50 000+.
64 |
65 | Luckily it’s possible to manually mark the ports as reversed to prevent Hyper-V from reserving them.
66 | Start a CMD session in an elevated mode and run the following commands, and restart the computer.
67 |
68 | ```bash
69 | net stop winnat
70 |
71 | netsh int ipv4 add excludedportrange protocol=tcp startport= numberofports=1 store=persistent
72 |
73 | net start winnat
74 | ```
75 |
--------------------------------------------------------------------------------
/docs/getting-started/business/directory-connector/index.mdx:
--------------------------------------------------------------------------------
1 | import Tabs from "@theme/Tabs";
2 | import TabItem from "@theme/TabItem";
3 |
4 | # Directory Connector
5 |
6 | The Bitwarden Directory Connector is a a desktop application used to sync your Bitwarden enterprise
7 | organization to an existing directory of users and groups.
8 |
9 | Directory Connector receives fewer updates than the main clients. To reduce maintenance costs, it
10 | has its own copy of our shared Javascript libraries (formerly known as jslib), located in the
11 | `jslib` subdirectory.
12 |
13 | ## Requirements
14 |
15 | - [Node.js](https://nodejs.org/) v20
16 |
17 | - Windows users: To compile the native node modules used in the app you will need the Visual C++
18 | toolset, available through the standard Visual Studio installer (recommended) or by installing
19 | `windows-build-tools` through `npm`. See more at
20 | [Compiling native Addon modules](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#compiling-native-addon-modules).
21 |
22 | # Build Instructions
23 |
24 | 1. Clone the repository:
25 |
26 | ```bash
27 | git clone https://github.com/bitwarden/directory-connector.git
28 | ```
29 |
30 | 2. Install the dependencies:
31 |
32 | ```bash
33 | cd directory-connector
34 | npm ci
35 | ```
36 |
37 | 3. Run the app:
38 |
39 |
40 |
41 |
42 |
43 | ```bash
44 | npm run electron
45 | ```
46 |
47 |
48 |
49 |
50 |
51 | ```bash
52 | npm run build:cli:watch
53 | ```
54 |
55 | You can then run commands from the `./build-cli` folder:
56 |
57 | ```bash
58 | cd ./build-cli
59 |
60 | node ./bwdc.js --help
61 |
62 | # Test sync
63 | node ./bwdc.js test
64 |
65 | # Real sync
66 | node bwdc.js sync
67 | ```
68 |
69 |
70 |
71 |
72 |
73 | ## Syncing from a directory service
74 |
75 | To properly test Directory Connector, you'll need a directory to sync. We have instructions for
76 | setting up:
77 |
78 | - an [Open LDAP Docker image](./open-ldap.md) (recommended)
79 |
80 | - [JumpCloud](./jumpcloud.md)
81 |
82 | These are both LDAP directory services. If you need to test another type, you should be able to find
83 | a platform offering a free tier of that service.
84 |
85 |
86 |
87 | If you need to test Active Directory, contact the Integration Engineering team for remote access to
88 | a test AD instance.
89 |
90 |
91 |
--------------------------------------------------------------------------------
/docs/getting-started/clients/web-vault/webauthn.mdx:
--------------------------------------------------------------------------------
1 | import Tabs from "@theme/Tabs";
2 | import TabItem from "@theme/TabItem";
3 | import CodeBlock from "@theme/CodeBlock";
4 |
5 | # WebAuthn
6 |
7 | :::info
8 |
9 | This page contains additional setup instructions if you need to test WebAuthn authentication
10 | locally.
11 |
12 | :::
13 |
14 | The [WebAuthn](https://webauthn.guide/) spec requires that a valid domain name is used. Since
15 | `localhost` does not satisfy this requirement, you need to configure your local instance to use a
16 | domain name.
17 |
18 | There are multiple ways of doing this. However, the simplest method is to modify the operating
19 | system's host file with a loopback to `127.0.0.1`.
20 |
21 | ## Configuration
22 |
23 | Webpack protects against DNS rebind attacks by blocking hostnames by default. However, we can
24 | specify specific hostnames to be allowed in the web environment configuration JSON files.
25 |
26 | 1. Create a `local.json` file in the `web/config/` folder
27 | 2. Add "bitwarden.test" as an `allowedHosts` entry:
28 |
29 | ```json
30 | {
31 | "dev": {
32 | "allowedHosts": ["bitwarden.test"]
33 | }
34 | }
35 | ```
36 |
37 | :::note
38 |
39 | If you are running the app, you must restart it for the config change to take effect.
40 |
41 | :::
42 |
43 | ### Hosts file
44 |
45 | :::note
46 |
47 | You will need administrator access to edit this file.
48 |
49 | :::
50 |
51 | The location of the host file differs slightly between operating systems.
52 |
53 |
54 |
55 | {`C:\\Windows\\System32\\drivers\\etc\\hosts`}
56 |
57 |
58 | {`/etc/hosts`}
59 |
60 |
61 |
62 | Open the file with the text editor of your choice. And append the following line.
63 |
64 | ```plain
65 | 127.0.0.1 bitwarden.test
66 | ```
67 |
68 | ### User Secrets
69 |
70 | In addition to modifying the host file, the [user secret](../../../contributing/user-secrets.md)
71 | `globalSettings:baseServiceUri:vault` for API and Identity projects in the server needs to be
72 | created or updated to reflect the domain name. For example:
73 |
74 | ```json
75 | {
76 | ...
77 | "globalSettings":{
78 | "baseServiceUri":{
79 | "vault":"https://bitwarden.test:8080"
80 | }
81 | },
82 | ...
83 | }
84 | ```
85 |
86 | ### Testing
87 |
88 | You should now be ready to test WebAuthn on your local instance by going to
89 | [https://bitwarden.test:8080](https://bitwarden.test:8080).
90 |
--------------------------------------------------------------------------------
/docs/architecture/deep-dives/autofill/form-submission-detection.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar_position: 3
3 | ---
4 |
5 | # Form Submission Detection
6 |
7 | ## Why is Form submission detection important?
8 |
9 | Form submission detection is important for several reasons:
10 |
11 | - It allows the Bitwarden extension to prompt the user to add new credentials to their vault,
12 | increasing the user's footprint in Bitwarden.
13 | - It allows us to accurately handle password change detection and help the user keep their data in
14 | sync, providing a better user experience.
15 |
16 | ## Why is Form submission detection difficult?
17 |
18 | The reason why the detection of forms and their submission is difficult because of the flexibility
19 | of modern progressive web apps (PWAs) and single-page applications (SPAs). In classic HTML, a
20 | `