Merge branch 'main' into ps/include-end-to-end-encryption-in-security-principles

Author: quexten

.github/workflows/labeler.yml renamed to .github/workflows/label.yml

@@ -1,16 +1,18 @@
-name: "Pull Request Labeler"
+name: Label
 
 on:
-  pull_request_target: {}
+  pull_request:
 
 jobs:
-  labeler:
-    name: "Pull Request Labeler"
+  label:
+    name: Label
+    runs-on: ubuntu-22.04
     permissions:
       contents: read
       pull-requests: write
-    runs-on: ubuntu-22.04
+
     steps:
-      - uses: actions/labeler@8558fd74291d67161a8a78ce36a881fa63b766a9 # v5.0.0
+      - name: Label pull request
+        uses: actions/labeler@8558fd74291d67161a8a78ce36a881fa63b766a9 # v5.0.0
         with:
           sync-labels: true # Remove labels if matches are removed

.github/workflows/scan.yml

@@ -29,7 +29,7 @@ jobs:
           ref: ${{ github.event.pull_request.head.sha }}
 
       - name: Scan with Checkmarx
-        uses: checkmarx/ast-github-action@03a90e7253dadd7e2fff55f5dfbce647b39040a1 # 2.0.37
+        uses: checkmarx/ast-github-action@184bf2f64f55d1c93fd6636d539edf274703e434 # 2.0.41
         env:
           INCREMENTAL:
             "${{ contains(github.event_name, 'pull_request') && '--sast-incremental' || '' }}"
@@ -45,7 +45,7 @@ jobs:
             --output-path . ${{ env.INCREMENTAL }}
 
       - name: Upload Checkmarx results to GitHub
-        uses: github/codeql-action/upload-sarif@9278e421667d5d90a2839487a482448c4ec7df4d # v3.27.2
+        uses: github/codeql-action/upload-sarif@d68b2d4edb4189fd2a5366ac14e72027bd4b37dd # v3.28.2
         with:
           sarif_file: cx_result.sarif
 
@@ -65,10 +65,9 @@ jobs:
           ref: ${{  github.event.pull_request.head.sha }}
 
       - name: Scan with SonarCloud
-        uses: sonarsource/sonarcloud-github-action@383f7e52eae3ab0510c3cb0e7d9d150bbaeab838 # v3.1.0
+        uses: sonarsource/sonarqube-scan-action@bfd4e558cda28cda6b5defafb9232d191be8c203 # v4.2.1
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           args: >
             -Dsonar.organization=${{ github.repository_owner }} -Dsonar.projectKey=${{

custom-words.txt

@@ -9,6 +9,7 @@ bitwardensecret
 bytemark
 Casbin
 clickjacking
+codebases
 CODEOWNERS
 CQRS
 CTAP2
@@ -20,6 +21,7 @@ HKDF
 hotfix
 hotfixed
 hotfixes
+Hyperscale
 iframes
 inet
 IntelliJ

docs/architecture/adr/0014-typescript-strict.md

@@ -144,5 +144,24 @@ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Null
 const foo = null ?? "default string";
 ```
 
+#### Use `!` on required `@Input` parameters
+
+Typescript's property initialization has no knowledge of Angular's guarantees. That means that
+
+```ts
+@Input({ required: true }) options: WebAuthnOptions;
+```
+
+will error as `options` is not initialized in the constructor. The suggested fix is to use the
+non-null assert operator, `!`.
+
+```ts
+@Input({ required: true }) options!: WebAuthnOptions;
+```
+
+Once [required input signals][requiredInputs] are out of dev preview for us (Angular 19), we can
+transition to using them and initialize these kinds of parameters in the class body or constructor.
+
 [null]: https://www.typescriptlang.org/tsconfig#strictNullChecks
 [plugin]: https://github.com/allegro/typescript-strict-plugin
+[requiredInputs]: https://angular.dev/guide/components/inputs#required-inputs

docs/architecture/deep-dives/database-replicas.md

@@ -0,0 +1,40 @@
+# Read-Only Database Replicas
+
+## Context
+
+Bitwarden utilizes
+[Azure SQL Hyperscale](https://learn.microsoft.com/en-us/azure/azure-sql/database/service-tier-hyperscale?view=azuresql)
+and its
+[high-availability replica](https://learn.microsoft.com/en-us/azure/azure-sql/database/service-tier-hyperscale-replicas?view=azuresql#high-availability-replica)
+available as a _read_ replica. This allows Bitwarden to double the max worker limit (along with
+compute, memory, and network throughput) without needing to scale up the primary database. The HA
+replica replicates the primary instance by mirroring the transaction log records.
+
+## Vision
+
+More read-only capabilities should be used in conjunction with read-only replicas, especially after
+stored procedures have been tuned and there are prominent performance bottlenecks relating to
+read-only queries.
+
+## Usage
+
+We currently use the read-only replica in two areas:
+
+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)
+   with `using (var connection = new SqlConnection(ReadOnlyConnectionString))` defined.
+2. Data engineering pipelines that require direct connection to the database.
+
+## Gotchas / Considerations
+
+- [CAP Theorem](https://en.wikipedia.org/wiki/CAP_theorem) applies here. Microsoft does not
+  guarantee data consistency and
+  [propagation latency](https://learn.microsoft.com/en-us/azure/azure-sql/database/read-scale-out?view=azuresql#data-consistency)
+  could vary greatly. For business logic that need consistency, read-only replicas are not a viable
+  solution.
+- Lack of observability -- currently there is limited visibility into query performance metrics as
+  well as resource utilization on the replica itself.
+- Long-running queries on read-only replicas can cause
+  [blocking](https://learn.microsoft.com/en-us/azure/azure-sql/database/read-scale-out?view=azuresql#long-running-queries-on-read-only-replicas).
+- The HA replica is not a backup and should not be treated as such. If a destructive migration had
+  been run on the primary instance it will be reflected on the HA replica. DR procedures will have
+  to be carried out in this scenario and there will be data loss.

docs/architecture/index.md

@@ -8,10 +8,6 @@ In this section we will cover the high level architecture of Bitwarden, how it i
 focusing initially on how the server and clients interact with each other, before diving into the
 details of the server and clients.
 
-Since the web based clients mostly behave the same we will primarily cover the web vault, but also
-client specific areas for the browser extension, desktop application and CLI. The Mobile application
-has its own codebase.
-
-The documentation of our architecture is primarily done using an interactive tool called IcePanel.
-It's recommend to start with one of the interactive
-[tours](https://s.icepanel.io/jCGiag2SENoQIU/EACm) of our application structure.
+Since the web-based clients mostly behave the same, we will focus on the web vault while calling out
+client-specific areas for the browser extension, desktop application and CLI. The mobile
+applications have their own codebases.

docs/architecture/mobile-clients/android/index.md

@@ -59,13 +59,13 @@ The lowest level of the data layer are the "data source" classes. These are the
 that include data persisted in [Room](https://developer.android.com/jetpack/androidx/releases/room)
 / [SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences),
 data retrieved from network requests using [Retrofit](https://github.com/square/retrofit), and data
-retrieved via interactions with the [Bitwarden SDK](https://github.com/bitwarden/sdk).
+retrieved via interactions with the [Bitwarden SDK](https://github.com/bitwarden/sdk-internal).
 
 Note that these data sources are constructed in a manner that adheres to a very important principle
 of the app: **that function calls should not throw exceptions** (see the
-[style and best practices documentation](styles-best-practices.md#best-practices--kotlin) for more
-details.) In the case of data sources, this tends to mean that suspending functions like those
-representing network requests or Bitwarden SDK calls should return a
+[style and best practices documentation](/docs/contributing/code-style/android-kotlin.md#best-practices--kotlin)
+for more details.) In the case of data sources, this tends to mean that suspending functions like
+those representing network requests or Bitwarden SDK calls should return a
 [Result](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-result/) type. This is an important
 responsibility of the data layer as a wrapper around other third party libraries, as dependencies
 like Retrofit and the Bitwarden SDK tend to throw exceptions to indicate errors instead.
@@ -369,7 +369,7 @@ components. If there is any new unique UI component that is added, it should alw
 it should be made a shareable component.
 
 Refer to the
-[style and best practices documentation](styles-best-practices.md#best-practices--jetpack-compose)
+[style and best practices documentation](/docs/contributing/code-style/android-kotlin.md#best-practices--jetpack-compose)
 for additional information on best practices when using Compose.
 
 #### State-hoisting

docs/architecture/mobile-clients/ios/index.md

@@ -60,7 +60,7 @@ data sources as well as higher-level "repository" and "service" classes.
 The lowest level of the core layer are the data model objects. These are the raw sources of data
 that include data retrieved or sent via network requests, data persisted with
 [CoreData](https://developer.apple.com/documentation/coredata/), and data that is used to interact
-with the [Bitwarden SDK](https://github.com/bitwarden/sdk).
+with the [Bitwarden SDK](https://github.com/bitwarden/sdk-internal).
 
 The models are roughly organized based on their use and type:
 

docs/architecture/sdk/dependencies.md

@@ -0,0 +1,73 @@
+# Dependencies
+
+The SDK is structured as several standalone crates. Each crate can have their own dependencies and
+versions of dependencies. It's worth reading the [Dependency Resolution][dep-res] article in the
+Cargo Book to better understand how dependencies are resolved in Rust.
+
+## Avoid adding dependencies
+
+The SDK takes a conservative approach to adding dependencies. The number of direct and indirect
+dependencies you have are directly related to the time it takes for a clean build. Dependencies also
+permanently increase the base maintenance cost of the project as they require frequent updates to
+keep up with security patches and new features.
+
+To that effort we **must** be conservative with adding dependencies. And we ask that you consider
+the following when evaluating a new dependency:
+
+- Do we already have a dependency or transient dependency that does the same thing? If so we
+  _should_ use that instead.
+- How complex is the desired functionality?
+  - How much time would it take to implement the functionality yourself?
+  - Is it likely to change?
+- How much of the dependency will we be using?
+  - Are you only using a small part of the dependency?
+  - Are you using the dependency in a way that is not intended?
+- How well maintained is the dependency?
+  - How often are new versions released?
+  - How many open issues does the dependency have?
+- Audit the dependency tree.
+  - How many dependencies does the dependency have?
+  - How many of those dependencies are we already using?
+
+If we only ever need a small fraction of the functionality we should consider implementing it
+ourselves.
+
+## Ranges
+
+For any library we always use ranges for dependencies. This allows other crates to depend on the the
+SDK without requiring the exact same versions. The Cargo lockfile ensures dependencies are
+consistent between builds.
+
+### Explicit ranges
+
+We use explicit ranges for dependencies, i.e. we specify the minimum and maximum version of a
+dependency. This helps avoiding confusion around how Cargo expands implicit versions.
+
+```toml
+# Bad
+serde = "1.0.0"
+serde = "1"
+serde = ">1"
+
+# Good
+serde = ">1.0, <2.0"
+```
+
+## Workspace dependencies
+
+To provide a more developer-friendly experience for managing dependencies we define commonly used
+dependencies in our workspace `Cargo.toml`. This allow us to update dependencies across the
+workspace by modifying a single file.
+
+Internal dependencies i.e. dependencies that are part of the same workspace **must** be defined
+using workspace definitions.
+
+```toml
+# Bad
+bitwarden-core = { version = "1.0", path = "../bitwarden-core" }
+
+# Good
+bitwarden-core = { workspace = true }
+```
+
+dep-res: https://doc.rust-lang.org/cargo/reference/resolver.html

docs/architecture/sdk/index.md

@@ -17,9 +17,9 @@ internal private items.
 
 ## Architecture
 
-The Bitwarden SDK is structured as a single [Git repository](https://github.com/bitwarden/sdk) with
-multiple internal crates. Please review the `README` in the repository for up to date information
-about the different crates.
+The Bitwarden SDK is structured as a single
+[Git repository](https://github.com/bitwarden/sdk-internal) with multiple internal crates. Please
+review the `README` in the repository for up to date information about the different crates.
 
 We generally strive towards extracting features into separate crates to keep the `bitwarden-core`
 crate as lean as possible. This has multiple benefits such as faster compile-time and clear
@@ -98,9 +98,7 @@ WebAssembly module that can be used in JavaScript / TypeScript. To ensure compat
 browsers that do not support WebAssembly, we also generate a JavaScript module from the WebAssembly
 that can be used as a fallback.
 
-The WebAssembly module is published on [npm](https://www.npmjs.com/package/@bitwarden/sdk-wasm) and
-prerelease builds are published on
-[GitHub Packages](https://github.com/bitwarden/sdk/pkgs/npm/sdk-wasm).
+The WebAssembly module is published on [npm](https://www.npmjs.com/package/@bitwarden/sdk-internal).
 
 ### C bindings
 

docs/architecture/sdk/versioning.md

@@ -10,7 +10,9 @@ There may be certain functionality that is actively being developed and is not y
 cases, they should be marked as such and gated behind a `unstable` feature flag. Consuming client
 applications should avoid merging changes that depend on these features into `main`.
 
-To track breaking changes, we use a [changelog file in the `bitwarden` crate][changelog]. This file
-should be updated with noteworthy changes for each PR.
+## Public APIs
 
-[changelog]: https://github.com/bitwarden/sdk/blob/main/crates/bitwarden/CHANGELOG.md
+To track breaking changes to the public APIs for Secrets Manager, we use a [changelog file in the
+`bitwarden` crate][changelog]. This file should be updated with noteworthy changes.
+
+[changelog]: https://github.com/bitwarden/sdk-sm/blob/main/crates/bitwarden/CHANGELOG.md

docs/architecture/security/principles/01-locked-vault-is-secure.mdx

@@ -0,0 +1,21 @@
+# P01 - A locked vault is secure
+
+Clients must ensure that highly sensitive vault data cannot be accessed in plain text once the vault
+has been locked, even if the device becomes compromised after the lock occurs. Protections are not
+guaranteed if the device is compromised before the vault is locked.
+
+## Technical Considerations
+
+Achieving this principle depends on the limitations of the platform and environment. For instance,
+in environments like JavaScript, where memory management is not fully under the control of the
+client, there may be residual plaintext in memory after the vault is locked. While ideal protection
+cannot be guaranteed in such cases, efforts must be made to minimize these risks through techniques
+such as clearing memory buffers and leveraging platform security features when available.
+
+## Key storage mechanisms must provide adequate protection
+
+Mechanisms used for storing encryption keys when the vault is locked, such as PINs or auto-login,
+must provide an appropriate level of security. If encryption keys are stored in less secure
+environments (e.g. in the OS's keyring), the associated risks must be carefully considered and
+mitigated to ensure that unauthorized access to the vault remains limited, even when convenience
+features are used.

docs/architecture/security/principles/02-limited-security-on-semi-compromised.mdx

@@ -0,0 +1,17 @@
+# P02 - Limited security for vaults on semi-compromised devices
+
+:::info Note
+
+This principle applies only to unlocked vaults. Refer to [P01](./locked-vault-is-secure) for details
+on protections for locked vaults.
+
+:::
+
+A semi-compromised device is one where malware exists in User Space but has not breached Kernel or
+OS-level protections. On such devices, clients must leverage available protections to prevent
+malware from accessing plaintext vault data while the vault is unlocked.
+
+- **Technical controls** (e.g., data compartmentalization or HSMs): Clients should maximize the use
+  of Kernel/OS-level protections or other available system mechanisms to safeguard vault data.
+- **Administrative controls** (e.g., biometrics, 2FA, approval flows): Clients should balance
+  security and usability, avoiding excessive complexity in the user flow.

docs/architecture/security/principles/03-no-security-on-fully-compromised.mdx

@@ -0,0 +1,21 @@
+# P03 - No security on fully compromised systems
+
+:::info Note
+
+This principle applies only to unlocked vaults. Refer to [P01](./locked-vault-is-secure) for details
+on protections for locked vaults.
+
+:::
+
+:::info Note
+
+Bitwarden does not currently support Trusted Execution Environments (TEEs). While TEEs could
+potentially provide a secure processing space for vault data on compromised devices, their use is
+limited by the environments in which Bitwarden operates. For this reason, TEEs are not considered
+when defining what constitutes a fully compromised device.
+
+:::
+
+When hardware or OS-level integrity is fully compromised, vault data may become accessible to
+attackers. While Bitwarden continuously strives to provide robust protections, certain threats fall
+beyond the reach of software-based security measures.

docs/architecture/security/principles/04-controlled-access.mdx

@@ -0,0 +1,7 @@
+# P04 - Controlled access to vault data
+
+Clients must ensure that vault data, whether at rest or in use, is accessible only to authorized
+parties and always under the user's explicit control. Even when unlocked, access to vault data must
+be carefully restricted to specific contexts, such as autofill or explicit user actions. Isolation
+mechanisms must be employed, particularly in environments prone to unauthorized access—such as
+browsers—to prevent exposure to third parties without the user's consent.

docs/architecture/security/principles/05-minimized-impact-of-security-breaches.mdx

@@ -0,0 +1,11 @@
+# P05 - Minimized impact of security breaches
+
+Even with robust security measures in place, user error or unforeseen vulnerabilities can lead to
+various security breaches, including the compromise of encryption keys or data leaks. Bitwarden
+should take available actions to help users limit the damage caused by such breaches, both in scope
+and duration. This includes:
+
+- Detecting and invalidating compromised device sessions.
+- Rotating encryption keys to reduce the risk of “harvest now, decrypt later” attacks (forward
+  secrecy).
+- Ensuring that any data added after a breach remains secure, maintaining post-compromise security.

docs/architecture/mobile-clients/android/styles-best-practices.md renamed to docs/contributing/code-style/android-kotlin.md

@@ -1,6 +1,8 @@
-# Code Style Guidelines
+---
+title: Android & Kotlin
+---
 
-## Contents
+# Android & Kotlin
 
 The following outlines the general code style and best practices for Android development. It is
 expected that all developers are familiar with the code style documents referenced here and have