Skip to content

Commit b576468

Browse files
vincentsaluccivincentsalucci
authored
Merge branch 'main' into ac/issue-template
2 parents 0977653 + 2883ff6 commit b576468

45 files changed

Lines changed: 1091 additions & 848 deletions

Some content is hidden

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

‎.claude/CLAUDE.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# Bitwarden Directory Connector
2+
3+
## Project Overview
4+
5+
Directory Connector is a TypeScript application that synchronizes users and groups from directory services to Bitwarden organizations. It provides both a desktop GUI (built with Angular and Electron) and a CLI tool (bwdc).
6+
7+
**Supported Directory Services:**
8+
9+
- LDAP (Lightweight Directory Access Protocol) - includes Active Directory and general LDAP servers
10+
- Microsoft Entra ID (formerly Azure Active Directory)
11+
- Google Workspace
12+
- Okta
13+
- OneLogin
14+
15+
**Technologies:**
16+
17+
- TypeScript
18+
- Angular (GUI)
19+
- Electron (Desktop wrapper)
20+
- Node
21+
- Jest for testing
22+
23+
## Code Architecture & Structure
24+
25+
### Directory Organization
26+
27+
```
28+
src/
29+
├── abstractions/ # Interface definitions (e.g., IDirectoryService)
30+
├── services/ # Business logic implementations for directory services, sync, auth
31+
├── models/ # Data models (UserEntry, GroupEntry, etc.)
32+
├── commands/ # CLI command implementations
33+
├── app/ # Angular GUI components
34+
└── utils/ # Test utilities and fixtures
35+
36+
src-cli/ # CLI-specific code (imports common code from src/)
37+
38+
jslib/ # Legacy folder structure (mix of deprecated/unused and current code - new code should not be added here)
39+
```
40+
41+
### Key Architectural Patterns
42+
43+
1. **Abstractions = Interfaces**: All interfaces are defined in `/abstractions`
44+
2. **Services = Business Logic**: Implementations live in `/services`
45+
3. **Directory Service Pattern**: Each directory provider implements `IDirectoryService` interface
46+
4. **Separation of Concerns**: GUI (Angular app) and CLI (commands) share the same service layer
47+
48+
## Development Conventions
49+
50+
### Code Organization
51+
52+
**File Naming:**
53+
54+
- kebab-case for files: `ldap-directory.service.ts`
55+
- Descriptive names that reflect purpose
56+
57+
**Class/Function Naming:**
58+
59+
- PascalCase for classes and interfaces
60+
- camelCase for functions and variables
61+
- Descriptive names that indicate purpose
62+
63+
**File Structure:**
64+
65+
- Keep files focused on single responsibility
66+
- Create new service files for distinct directory integrations
67+
- Separate models into individual files when complex
68+
69+
### TypeScript Conventions
70+
71+
**Import Patterns:**
72+
73+
- Use path aliases (`@/`) for project imports
74+
- `@/` - project root
75+
- `@/jslib/` - jslib folder
76+
- ESLint enforces alphabetized import ordering with newlines between groups
77+
78+
**Type Safety:**
79+
80+
- Avoid `any` types - use proper typing or `unknown` with type guards
81+
- Prefer interfaces for contracts, types for unions/intersections
82+
- Use strict null checks - handle `null` and `undefined` explicitly
83+
- Leverage TypeScript's type inference where appropriate
84+
85+
**Configuration:**
86+
87+
- Use configuration files or environment variables
88+
- Never hardcode URLs or configuration values
89+
90+
## Security Best Practices
91+
92+
**Credential Handling:**
93+
94+
- Never log directory service credentials, API keys, or tokens
95+
- Use secure storage mechanisms for sensitive data
96+
- Credentials should never be hardcoded
97+
- Store credentials encrypted, never in plain text
98+
99+
**Sensitive Data:**
100+
101+
- User and group data from directories should be handled securely
102+
- Avoid exposing sensitive information in error messages
103+
- Sanitize data before logging
104+
- Be cautious with data persistence
105+
106+
**Input Validation:**
107+
108+
- Validate and sanitize data from external directory services
109+
- Check for injection vulnerabilities (LDAP injection, etc.)
110+
- Validate configuration inputs from users
111+
112+
**API Security:**
113+
114+
- Ensure authentication flows are implemented correctly
115+
- Verify SSL/TLS is used for all external connections
116+
- Check for secure token storage and refresh mechanisms
117+
118+
## Error Handling
119+
120+
**Best Practices:**
121+
122+
1. **Try-catch for async operations** - Always wrap external API calls
123+
2. **Meaningful error messages** - Provide context for debugging
124+
3. **Error propagation** - Don't swallow errors silently
125+
4. **User-facing errors** - Separate user messages from developer logs
126+
127+
## Performance Best Practices
128+
129+
**Large Dataset Handling:**
130+
131+
- Use pagination for large user/group lists
132+
- Avoid loading entire datasets into memory at once
133+
- Consider streaming or batch processing for large operations
134+
135+
**API Rate Limiting:**
136+
137+
- Respect rate limits for Microsoft Graph API, Google Admin SDK, etc.
138+
- Consider batching large API calls where necessary
139+
140+
**Memory Management:**
141+
142+
- Close connections and clean up resources
143+
- Remove event listeners when components are destroyed
144+
- Be cautious with caching large datasets
145+
146+
## Testing
147+
148+
**Framework:**
149+
150+
- Jest with jest-preset-angular
151+
- jest-mock-extended for type-safe mocks with `mock<Type>()`
152+
153+
**Test Organization:**
154+
155+
- Tests colocated with source files
156+
- `*.spec.ts` - Unit tests for individual components/services
157+
- `*.integration.spec.ts` - Integration tests against live directory services
158+
- Test helpers located in `utils/` directory
159+
160+
**Test Naming:**
161+
162+
- Descriptive, human-readable test names
163+
- Example: `'should return empty array when no users exist in directory'`
164+
165+
**Test Coverage:**
166+
167+
- New features must include tests
168+
- Bug fixes should include regression tests
169+
- Changes to core sync logic or directory specific logic require integration tests
170+
171+
**Testing Approach:**
172+
173+
- **Unit tests**: Mock external API calls using jest-mock-extended
174+
- **Integration tests**: Use live directory services (Docker containers or configured cloud services)
175+
- Focus on critical paths (authentication, sync, data transformation)
176+
- Test error scenarios and edge cases (empty results, malformed data, connection failures), not just happy paths
177+
178+
## Directory Service Patterns
179+
180+
### IDirectoryService Interface
181+
182+
All directory services implement this core interface with methods:
183+
184+
- `getUsers()` - Retrieve users from directory and transform them into standard objects
185+
- `getGroups()` - Retrieve groups from directory and transform them into standard objects
186+
- Connection and authentication handling
187+
188+
### Service-Specific Implementations
189+
190+
Each directory service has unique authentication and query patterns:
191+
192+
- **LDAP**: Direct LDAP queries, bind authentication
193+
- **Microsoft Entra ID**: Microsoft Graph API, OAuth tokens
194+
- **Google Workspace**: Google Admin SDK, service account credentials
195+
- **Okta/OneLogin**: REST APIs with API tokens
196+
197+
## References
198+
199+
- [Architectural Decision Records (ADRs)](https://contributing.bitwarden.com/architecture/adr/)
200+
- [Contributing Guidelines](https://contributing.bitwarden.com/contributing/)
201+
- [Code Style](https://contributing.bitwarden.com/contributing/code-style/)
202+
- [Security Whitepaper](https://bitwarden.com/help/bitwarden-security-white-paper/)
203+
- [Security Definitions](https://contributing.bitwarden.com/architecture/security/definitions)

‎.claude/prompts/review-code.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Please review this pull request with a focus on:
2+
3+
- Code quality and best practices
4+
- Potential bugs or issues
5+
- Security implications
6+
- Performance considerations
7+
8+
Note: The PR branch is already checked out in the current working directory.
9+
10+
Provide a comprehensive review including:
11+
12+
- Summary of changes since last review
13+
- Critical issues found (be thorough)
14+
- Suggested improvements (be thorough)
15+
- Good practices observed (be concise - list only the most notable items without elaboration)
16+
- Action items for the author
17+
- Leverage collapsible <details> sections where appropriate for lengthy explanations or code
18+
snippets to enhance human readability
19+
20+
When reviewing subsequent commits:
21+
22+
- Track status of previously identified issues (fixed/unfixed/reopened)
23+
- Identify NEW problems introduced since last review
24+
- Note if fixes introduced new issues
25+
26+
IMPORTANT: Be comprehensive about issues and improvements. For good practices, be brief - just note
27+
what was done well without explaining why or praising excessively.

‎.github/CODEOWNERS‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,8 @@
1212
**/*.dockerignore @bitwarden/team-appsec @bitwarden/dept-bre
1313
**/entrypoint.sh @bitwarden/team-appsec @bitwarden/dept-bre
1414
**/docker-compose.yml @bitwarden/team-appsec @bitwarden/dept-bre
15+
16+
# Claude related files
17+
.claude/ @bitwarden/team-ai-sme
18+
.github/workflows/respond.yml @bitwarden/team-ai-sme
19+
.github/workflows/review-code.yml @bitwarden/team-ai-sme

‎.github/renovate.json5‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,17 @@
88
matchManagers: ["github-actions"],
99
matchUpdateTypes: ["minor", "patch"],
1010
},
11-
{
12-
groupName: "Google Libraries",
13-
matchPackagePatterns: ["google-auth-library", "googleapis"],
14-
matchManagers: ["npm"],
15-
groupSlug: "google-libraries",
16-
},
1711
],
1812
ignoreDeps: [
1913
// yao-pkg is used to create a single executable application bundle for the CLI.
2014
// It is a third party build of node which carries a high supply chain risk.
2115
// This must be manually vetted by our appsec team before upgrading.
2216
// It is excluded from renovate to avoid accidentally upgrading to a non-vetted version.
2317
"@yao-pkg/pkg",
18+
// googleapis uses ESM after 149.0.0 so we are not upgrading it until we have ESM support.
19+
// They release new versions every couple of weeks so ignoring it at the dependency dashboard
20+
// level is not sufficient.
21+
// FIXME: remove and upgrade when we have ESM support.
22+
"googleapis",
2423
],
2524
}

0 commit comments

Comments
 (0)