Skip to content

Commit d82de41

Browse files
jqssunjqssun
committed
Add support for Helium Android
0 parents  commit d82de41

3,004 files changed

Lines changed: 579336 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.checkmarx/config.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
version: 1
2+
3+
# Checkmarx configuration file
4+
#
5+
# https://docs.checkmarx.com/en/34965-68549-configuring-projects-using-config-as-code-files.html
6+
checkmarx:
7+
scan:
8+
configs:
9+
sast:
10+
# Exclude test directories
11+
filter: "**/test/**,!**/androidTest/**,!**/commonTest/**,!**/jvmTest/**,!**/jsTest/**,!**/iosTest/**"

‎.claude/CLAUDE.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Bitwarden Android - Claude Code Configuration
2+
3+
Official Android application for Bitwarden Password Manager and Bitwarden Authenticator, providing secure password management, two-factor authentication, and credential autofill services with zero-knowledge encryption.
4+
5+
## Overview
6+
7+
- Multi-module Android application: `:app` (Password Manager), `:authenticator` (2FA TOTP generator)
8+
- Zero-knowledge architecture: encryption/decryption happens client-side via Bitwarden SDK
9+
- Target users: End-users via Google Play Store and F-Droid
10+
11+
### Key Concepts
12+
13+
- **Zero-Knowledge Architecture**: Server never has access to unencrypted vault data or encryption keys
14+
- **Bitwarden SDK**: Rust-based cryptographic SDK handling all encryption/decryption operations
15+
- **DataState**: Wrapper for streaming data states (Loading, Loaded, Pending, Error, NoNetwork)
16+
- **Result Types**: Custom sealed classes for operation results (never throw exceptions from data layer)
17+
- **UDF (Unidirectional Data Flow)**: State flows down, actions flow up through ViewModels
18+
19+
---
20+
21+
## Architecture
22+
23+
```
24+
User Request (UI Action)
25+
|
26+
Screen (Compose)
27+
|
28+
ViewModel (State/Action/Event)
29+
|
30+
Repository (Business Logic)
31+
|
32+
+----+----+----+
33+
| | | |
34+
Disk Network SDK
35+
| | |
36+
Room Retrofit Bitwarden
37+
DB APIs Rust SDK
38+
```
39+
40+
### Key Principles
41+
42+
1. **No Exceptions from Data Layer**: All suspending functions return `Result<T>` or custom sealed classes
43+
2. **State Hoisting to ViewModel**: All state that affects behavior must live in the ViewModel's state
44+
3. **Interface-Based DI**: All implementations use interface/`...Impl` pairs with Hilt injection
45+
4. **Encryption by Default**: All sensitive data encrypted via SDK before storage
46+
47+
### Core Patterns
48+
49+
- **BaseViewModel**: Enforces UDF with State/Action/Event pattern. See `ui/src/main/kotlin/com/bitwarden/ui/platform/base/BaseViewModel.kt`.
50+
- **Repository Result Pattern**: Type-safe error handling using custom sealed classes for discrete operations and `DataState<T>` wrapper for streaming data.
51+
- **Common Patterns**: Flow collection via `Internal` actions, error handling via `when` branches, `DataState` streaming with `.map { }` and `.stateIn()`.
52+
53+
> For complete architecture patterns, code templates, and module organization, see `docs/ARCHITECTURE.md`.
54+
55+
---
56+
57+
## Development Guide
58+
59+
### Workflow Skills
60+
61+
> **Quick start**: Use the `bitwarden-tech-lead:bitwarden-tech-lead` agent (or `/plan-android-work <task>`) to refine
62+
> requirements and plan,
63+
> then the `bitwarden-software-engineer:bitwarden-software-engineer` agent (or `/work-on-android <task>`) for implementation,
64+
> then `/review-android <PR#>` to review the result.
65+
66+
## Skills & Commands
67+
68+
| Skill | Triggers |
69+
|-------|---------|
70+
| `build-test-verify` | "build", "run tests", "lint", "format", "verify build" |
71+
| `implementing-android-code` | "implement", "write code", "add screen", "create feature" |
72+
| `planning-android-implementation` | "plan implementation", "architecture design", "phased task breakdown" |
73+
| `refining-android-requirements` | "refine requirements", "analyze ticket", "gap analysis" |
74+
| `reviewing-changes` | "review", "code review", "check PR" |
75+
| `testing-android-code` | "write tests", "add test coverage", "unit test" |
76+
77+
| Command | Usage |
78+
|---------|-------|
79+
| `/plan-android-work <task>` | Fetch ticket → refine requirements → design implementation approach |
80+
| `/work-on-android <task>` | Full workflow: implement → test → verify → preflight → commit → review → PR |
81+
| `/review-android <PR#>` | Full review workflow: PR context gathering → Android checklist → output |
82+
83+
---
84+
85+
## Security Rules
86+
87+
**MANDATORY - These rules have no exceptions:**
88+
89+
1. **Zero-Knowledge Architecture**: Never transmit unencrypted vault data or master passwords to the server. All encryption happens client-side via the Bitwarden SDK.
90+
2. **No Plaintext Key Storage**: Encryption keys must be stored using Android Keystore (biometric unlock) or encrypted with PIN/master password.
91+
3. **Sensitive Data Cleanup**: On logout, all sensitive data must be cleared from memory and storage via `UserLogoutManager.logout()`.
92+
4. **Input Validation**: Validate all user inputs before processing, especially URLs and credentials.
93+
5. **SDK Isolation**: Use scoped SDK sources (`ScopedVaultSdkSource`) to prevent cross-user crypto context leakage.
94+
95+
---
96+
97+
## Code Style & Standards
98+
99+
- **Formatter**: Android Studio with `bitwarden-style.xml` | **Line Limit**: 100 chars | **Detekt**: Enabled
100+
- **Naming**: `camelCase` (vars/fns), `PascalCase` (classes), `SCREAMING_SNAKE_CASE` (constants), `...Impl` (implementations)
101+
- **KDoc**: Required for all public APIs
102+
- **String Resources**: Add new strings to `:ui` module (`ui/src/main/res/values/strings.xml`). Use typographic quotes/apostrophes (`"` `"` `'`) not escaped ASCII (`\"` `\'`). Name each resource from its own text content in `snake_case` — not with generic suffixes (`_message`, `_title`). E.g., `one_or_more_email_addresses_are_incorrect`, not `invalid_email_addresses_message`.
103+
104+
> For complete style rules (imports, formatting, documentation, Compose conventions), see `docs/STYLE_AND_BEST_PRACTICES.md`.
105+
106+
---
107+
108+
## Anti-Patterns
109+
110+
In addition to the Key Principles above, follow these rules:
111+
112+
### DO
113+
- Map async results to internal actions before updating state
114+
- Inject `Clock` for time-dependent operations
115+
- Return early to reduce nesting
116+
117+
### DON'T
118+
- Update state directly inside coroutines (use internal actions)
119+
- Use `any` types or suppress null safety
120+
- Catch generic `Exception` (catch specific types)
121+
- Use `e.printStackTrace()` (use Timber logging)
122+
- Create new patterns when established ones exist
123+
- Skip KDoc for public APIs
124+
125+
---
126+
127+
## Quick Reference
128+
129+
- **Code style**: Full rules: `docs/STYLE_AND_BEST_PRACTICES.md`
130+
- **Before writing code**: Use `implementing-android-code` skill for Bitwarden-specific patterns, gotchas, and templates
131+
- **Before writing tests**: Use `testing-android-code` skill for test patterns and templates
132+
- **Building/testing**: Use `build-test-verify` skill | App tests: `./gradlew app:testStandardDebugUnitTest`
133+
- **Before committing**: Use `bitwarden-delivery-tools:perform-preflight` skill, then `bitwarden-delivery-tools:committing-changes` skill for message format
134+
- **Code review**: Use `/review-android` for the full review workflow; `reviewing-changes` skill for checklist-only
135+
- **Creating PRs**: Use `bitwarden-delivery-tools:creating-pull-request` skill for PR workflow and templates
136+
- **Troubleshooting**: See `docs/TROUBLESHOOTING.md`
137+
- **Architecture**: `docs/ARCHITECTURE.md` | [Bitwarden SDK](https://github.com/bitwarden/sdk) | [Jetpack Compose](https://developer.android.com/jetpack/compose) | [Hilt DI](https://dagger.dev/hilt/)

‎.claude/CONTRIBUTING.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Contributing Claude Context to This Repo
2+
3+
Every time you catch Claude making the same mistake twice, explain the same convention in chat, or
4+
hand a teammate a mental map they didn't have — that's knowledge worth encoding. This guide covers
5+
what belongs in this repo's `.claude/`, where to put it, and how to land it alongside the code it
6+
describes.
7+
8+
## When to contribute here vs. elsewhere
9+
10+
Ask: **is this knowledge specific to this codebase, or generic enough to work across repos?**
11+
12+
- **Specific to this codebase** → contribute here, in `.claude/`. Example: "how we add a new module
13+
in this codebase," "how our feature-flag system works."
14+
- **Generic, reusable across repos** →
15+
[`bitwarden/ai-plugins`](https://github.com/bitwarden/ai-plugins) — persona plugins (e.g., a
16+
code-review agent), tool integrations, or shared utilities.
17+
18+
When unsure, keep it here. Promoting up to `ai-plugins` later is easier than pulling it back — see
19+
its [CONTRIBUTING.md](https://github.com/bitwarden/ai-plugins/blob/main/CONTRIBUTING.md) when you're
20+
ready.
21+
22+
## Choose scope, then shape
23+
24+
### 1. Scope — where does it apply?
25+
26+
Claude loads every `CLAUDE.md` and `CLAUDE.local.md` by
27+
[walking up from the working directory](https://code.claude.com/docs/en/memory#how-claude-md-files-load)
28+
— looking in each ancestor directly, not in a nested `.claude/` subdirectory. Files below the
29+
working directory (including nested `.claude/skills/`) are loaded lazily when Claude reads into that
30+
subtree. Use that hierarchy:
31+
32+
- **Applies everywhere in this repo** → root `CLAUDE.md` or `.claude/skills/`
33+
- **Applies only within one app, library, utility, or subtree** → nested `CLAUDE.md` or
34+
`.claude/skills/` in that directory
35+
36+
Push rules as deep as they'll go — keeping app-specific rules local saves context for everyone
37+
else's sessions, not just yours.
38+
39+
For rules that should apply only to certain file types, use
40+
[`.claude/rules/<name>.md` with a `paths:` frontmatter glob](https://code.claude.com/docs/en/memory#organize-rules-with-claude/rules/)
41+
instead of a nested `CLAUDE.md`.
42+
43+
### 2. Shape — how should Claude use it?
44+
45+
| You want to… | Use |
46+
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
47+
| State a rule Claude must always follow in its scope | `CLAUDE.md` |
48+
| State a rule that applies only to certain file globs | `.claude/rules/<name>.md` with `paths:` frontmatter |
49+
| Teach a procedure Claude invokes on demand | `.claude/skills/<name>/SKILL.md` |
50+
| Give Claude a specialized subagent with its own context | `.claude/agents/<name>.md` (YAML frontmatter; `name` + `description` required) |
51+
| Add a user-invocable slash command | `.claude/commands/<name>.md` |
52+
| Trigger a shell script on a Claude Code event | _We have them, but no strict project enforcement yet — register yours in `settings.local.json`._ |
53+
54+
Rule of thumb: **if Claude only needs it sometimes, it's a skill.** Once a `CLAUDE.md` loads, it
55+
stays in context for the rest of the session — keep each one lean, especially the root.
56+
57+
## Security conventions
58+
59+
Skills and agents that touch vault data, authentication, or cryptography must use Bitwarden's
60+
[Core Vocabulary](https://contributing.bitwarden.com/architecture/security/definitions) (Vault Data,
61+
Protected Data, Secure Channel, etc.) and re-state the zero-knowledge invariant inline. **Subagents
62+
run in a fresh context** and do not inherit this repo's `CLAUDE.md` — include the relevant
63+
definitions directly in the agent's system prompt.
64+
65+
## What good contributions look like
66+
67+
- **Grounded in the code.** Real files, real patterns, real commands. If it could apply to any repo,
68+
it belongs in `ai-plugins`.
69+
- **Describes the "what" and "why," not the "who."** Avoid team-persona framing. Describe the domain
70+
and its constraints; the team is an implementation detail.
71+
- **Short and specific.** 2,000 words of general advice isn't a skill.
72+
- **Active voice, direct language.** "Invoke this skill when..." — not "This skill may be invoked
73+
when..."
74+
- **Reviewed like code.** Teams of domain experts own `.claude/` in their areas — they're the ones
75+
shaping how Claude behaves for everyone who works there, so treat changes with the same
76+
seriousness as source.
77+
78+
## Anti-patterns
79+
80+
- **Team-persona agents** ("Team ABC engineer"). If a team's process is unique enough to warrant a
81+
persona, that's an SDLC signal to address, not a persona to encode.
82+
- **Root-level rules that only matter in one subtree.** If the rule only ever applies to a single
83+
subtree, then the rule belongs in a nested `CLAUDE.md` next to that subtree.
84+
- **Duplicating `ai-plugins` content.** Check existing plugin skills before writing a new one.
85+
- **Generic advice disguised as repo-local knowledge.** "Write good tests" isn't repo-specific. "Our
86+
integration tests must hit a real database because…" is.
87+
88+
## Building a contribution
89+
90+
The Claude Code ecosystem moves fast — last session's habits may already be out of date. Here's the
91+
workflow we follow.
92+
93+
### 1. Start with the canonical docs
94+
95+
A quick refresh before you begin goes a long way — the rules shift more often than you'd think:
96+
97+
- [How Claude Code Works](https://code.claude.com/docs/en/how-claude-code-works) — the mental model.
98+
- [Best Practices for Claude Code](https://code.claude.com/docs/en/best-practices) — what Anthropic
99+
recommends.
100+
- [Extend Claude Code](https://code.claude.com/docs/en/features-overview) — what you can build
101+
(skills, agents, commands, hooks).
102+
- [The Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) -
103+
a must read for skill building
104+
105+
### 2. Survey the landscape
106+
107+
A quick skim of both goes a long way:
108+
109+
- This repo's [`.claude/`](.) tree.
110+
- [`bitwarden/ai-plugins`](https://github.com/bitwarden/ai-plugins).
111+
112+
Try to match the voice you see. "Invoke when the user asks to X" — not "This skill may be invoked
113+
when X." Direct, active, specific. Your contribution should read like the neighbors.
114+
115+
### 3. Build iteratively
116+
117+
When you're authoring a skill, start with `/skill-creator:skill-creator`. It runs an iterative loop
118+
— draft → test against evaluations → review outputs → refine — with benchmark stats and a
119+
side-by-side reviewer. You end up with a skill that's been exercised against concrete inputs before
120+
you open the PR.
121+
122+
For agents, commands, hooks, and `CLAUDE.md` entries, start from an existing one in the repo and
123+
adapt it. No need to invent a new structure when a neighbor already solves the shape problem.
124+
125+
### 4. Validate before you push
126+
127+
- Run a local Bitwarden Claude Code review with `/bitwarden-code-review:code-review-local` — it
128+
writes findings to files so you can fix them before pushing, without posting anything to GitHub.
129+
- When you raise the PR, apply the `ai-review` label. Our reusable GitHub workflow watches for it
130+
and runs a Claude Code review automatically; without the label, the review doesn't fire.

0 commit comments

Comments
 (0)