src-advisory/SRCmail
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update contributing guidelines and enhance README formatting

Browse Source
This commit is contained in:
Linus Rath
2026-03-13 14:12:20 +01:00
parent 82a790de0f
commit 02808fa4c3
5 changed files with 193 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+9 -2
View File
@@ -7,17 +7,20 @@ Thank you for your interest in contributing to Bulwark Webmail! This document pr
### Development Setup
1. **Fork and clone** the repository:
```bash
git clone https://github.com/bulwarkmail/webmail.git
cd webmail
```
2. **Install dependencies**:
```bash
npm install
```
3. **Set up environment**:
```bash
cp .env.example .env.local
# Edit .env.local with your JMAP server URL
@@ -75,9 +78,10 @@ This project uses **next-intl** for internationalization. Please follow these gu
### Key Rules
1. **Never hardcode user-facing text** - Always use translations:
```tsx
const t = useTranslations('namespace');
return <div>{t('key')}</div>;
const t = useTranslations("namespace");
return <div>{t("key")}</div>;
```
2. **Translation file locations**:
@@ -109,6 +113,7 @@ This project uses **next-intl** for internationalization. Please follow these gu
### Before Submitting
1. **Create a feature branch**:
```bash
git checkout -b feature/your-feature-name
```
@@ -147,6 +152,7 @@ Follow the conventional commits format:
- `chore:` - Maintenance tasks
Examples:
```
feat: add email threading support
fix: resolve attachment download issue
@@ -184,6 +190,7 @@ webmail/
## Questions?
If you have questions about contributing, feel free to:
- Open an issue for discussion
- Check existing issues and pull requests
README.md
+4 -2
View File
@@ -200,6 +200,7 @@ OAUTH_ISSUER_URL= # optional, for external IdPs (Keycloak, Authe
```
Endpoints are auto-discovered via `.well-known/oauth-authorization-server` or `.well-known/openid-configuration`.
</details>
<details>
@@ -210,12 +211,13 @@ SESSION_SECRET=your-secret-key # Generate with: openssl rand -base64 32
```
Credentials encrypted with AES-256-GCM, stored in an httpOnly cookie (30-day expiry).
</details>
## Keyboard Shortcuts
| Key | Action |
|-----|--------|
| ------------- | ----------------------- |
| `j` / `k` | Navigate between emails |
| `Enter` / `o` | Open email |
| `Esc` | Close / deselect |
@@ -231,7 +233,7 @@ Credentials encrypted with AES-256-GCM, stored in an httpOnly cookie (30-day exp
## Tech Stack
| | |
|---|---|
| ------------- | ------------------------------------------------- |
| **Framework** | [Next.js 16](https://nextjs.org/) with App Router |
| **Language** | TypeScript |
| **Styling** | [Tailwind CSS v4](https://tailwindcss.com/) |
ROADMAP.md
+22
View File
@@ -5,12 +5,14 @@ This document tracks the development status and planned features for Bulwark Web
## Completed Features
### Core Infrastructure
- [x] Next.js 16 with TypeScript and App Router
- [x] Tailwind CSS v4 with Oxide engine
- [x] Zustand state management
- [x] Custom JMAP client implementation (RFC 8620)
### Authentication
- [x] Login with JMAP server authentication
- [x] Session management (no password storage for security)
- [x] Username autocomplete with history
@@ -23,6 +25,7 @@ This document tracks the development status and planned features for Bulwark Web
- [x] "Remember me" session persistence for Basic Auth (AES-256-GCM encrypted httpOnly cookie)
### JMAP Server Connection
- [x] Session establishment and keep-alive
- [x] Connection error handling and retries
- [x] CORS error detection with actionable user guidance
@@ -32,6 +35,7 @@ This document tracks the development status and planned features for Bulwark Web
- [x] Shared folders support (multi-account access)
### Email Operations
- [x] Email fetching and display
- [x] Full HTML email rendering
- [x] Compose, reply, reply-all, forward
@@ -48,6 +52,7 @@ This document tracks the development status and planned features for Bulwark Web
- [x] Email threading (Gmail-style inline expansion)
### Real-time Updates
- [x] EventSource for JMAP push notifications
- [x] State synchronization
- [x] Email arrival notifications
@@ -55,6 +60,7 @@ This document tracks the development status and planned features for Bulwark Web
- [x] Mailbox change handling
### User Interface
- [x] Three-pane layout (sidebar, list, viewer)
- [x] Minimalist design system
- [x] Dark and light theme support
@@ -86,6 +92,7 @@ This document tracks the development status and planned features for Bulwark Web
- [x] Screen reader live region announcements (sr-only)
### Internationalization
- [x] English language support
- [x] French language support
- [x] Japanese language support
@@ -98,6 +105,7 @@ This document tracks the development status and planned features for Bulwark Web
- [x] Language preference persistence
### Security & Accessibility
- [x] External content blocked by default
- [x] HTML sanitization with DOMPurify
- [x] User control for loading external content
@@ -114,6 +122,7 @@ This document tracks the development status and planned features for Bulwark Web
- [x] Screen reader sr-only live region for dynamic announcements
### Identity Management
- [x] Multiple sender identities (name, email, signature)
- [x] Sub-addressing support (user+tag@domain.com)
- [x] Per-identity signatures
@@ -123,6 +132,7 @@ This document tracks the development status and planned features for Bulwark Web
- [x] Primary identity (matching login) selected by default in composer
### Address Book & Contacts
- [x] Contact store with JMAP sync and local fallback
- [x] Contact CRUD operations (create, read, update, delete)
- [x] Contacts list view with search/filter
@@ -136,12 +146,14 @@ This document tracks the development status and planned features for Bulwark Web
- [x] i18n support for contacts (all 8 languages)
### Vacation Responder
- [x] JMAP VacationResponse singleton management
- [x] Settings tab with date range and message configuration
- [x] Sidebar indicator when vacation auto-reply is active
- [x] i18n support (all 8 languages)
### Calendar Integration
- [x] JMAP Calendar types (RFC 8984) and client methods
- [x] Calendar capability detection (urn:ietf:params:jmap:calendars)
- [x] Calendar store with Zustand (persist middleware)
@@ -177,6 +189,7 @@ This document tracks the development status and planned features for Bulwark Web
- [x] Event duplication button in modal (clones event +1 day, opens for editing)
### Email Filters
- [x] JMAP Sieve Scripts (RFC 9661) with capability detection
- [x] Visual rule builder (conditions: From/To/Cc/Subject/Header/Size/Body, actions: Move/Copy/Forward/Mark read/Star/Label/Discard/Reject/Keep/Stop)
- [x] Raw Sieve script editor with syntax validation
@@ -189,6 +202,7 @@ This document tracks the development status and planned features for Bulwark Web
- [x] i18n support (all 8 languages)
### Email Templates
- [x] Reusable email templates with local storage persistence
- [x] Category organization (General, Business, Personal, Support, Follow-up, custom)
- [x] Dynamic placeholder variables with auto-fill from composer context
@@ -200,10 +214,12 @@ This document tracks the development status and planned features for Bulwark Web
- [x] i18n support (all 8 languages)
### Email Display
- [x] Proper email layout without horizontal scroll or clipping
- [x] Blocked image container collapsing (no empty spaces in newsletters)
### Testing
- [x] Unit tests for validation utilities (57 tests)
- [x] Unit tests for email sanitization (27 tests)
- [x] Unit tests for color transformation (40 tests)
@@ -226,6 +242,7 @@ This document tracks the development status and planned features for Bulwark Web
- [x] Playwright E2E framework setup
### Deployment
- [x] Runtime environment variables (Docker-friendly configuration)
- [x] Health check endpoint
- [x] Docker support (multi-stage build, docker-compose, standalone output)
@@ -238,26 +255,31 @@ This document tracks the development status and planned features for Bulwark Web
## Planned Features
### Advanced Features
- [ ] Free/busy queries (Principal/getAvailability)
- [ ] Calendar sharing UI (JMAP Sharing RFC 9670)
- [ ] Email encryption (PGP/GPG)
### Performance Optimizations
- [ ] Email content caching
- [ ] Bundle size optimization
- [ ] Service worker for offline support
- [ ] Lazy loading for attachments
### Testing (Remaining)
- [ ] E2E tests with real JMAP server
- [ ] Accessibility testing
- [ ] Performance testing
### Deployment
- [ ] Production build optimizations
- [ ] Monitoring and logging
### Security Enhancements
- [ ] Rate limiting
## Known Issues
docker-compose.yml
+9 -1
View File
@@ -6,7 +6,15 @@ services:
env_file:
- .env.local
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3000/api/health"]
test:
[
"CMD",
"wget",
"--no-verbose",
"--tries=1",
"--spider",
"http://127.0.0.1:3000/api/health",
]
interval: 30s
timeout: 5s
retries: 3
specifications/addon-plugin-theme-concept.md
+34 -31
View File
@@ -37,7 +37,7 @@ This document describes a system that allows the Bulwark Webmail application to
### Rebuild Requirements
| Addon Type | Source | Rebuild Needed? |
|-----------|--------|----------------|
| ---------- | ---------------------------- | ------------------------------------------- |
| Theme | Bundled (`/addons/themes/`) | **Yes** — included at build time |
| Theme | URL (remote) | **No** — CSS loaded via `<link>` at runtime |
| Plugin | Bundled (`/addons/plugins/`) | **Yes** — included at build time |
@@ -57,7 +57,7 @@ Bundled addons are compiled into the app's static assets during `next build`. Ad
## 2. Terminology
| Term | Definition |
|------|-----------|
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Addon** | Any installable extension — umbrella term for themes and plugins. |
| **Theme** | An addon that only customizes visual appearance (colors, fonts, spacing, density). Ships as CSS + a manifest. Contains no executable code. |
| **Plugin** | An addon that adds or modifies functionality. Ships as a JS/TS module + a manifest. May include a theme. |
@@ -80,14 +80,14 @@ Every addon has an `addon.json` at its root:
"description": "A brief description.",
"author": {
"name": "Jane Doe",
"url": "https://example.com"
"url": "https://example.com",
},
"license": "MIT",
"homepage": "https://example.com/my-addon",
// ── Compatibility ──
"engine": {
"webmail": ">=1.0.0" // Required host app version range
"webmail": ">=1.0.0", // Required host app version range
},
// ── Type ──
@@ -101,7 +101,7 @@ Every addon has an `addon.json` at its root:
"theme": {
"variables": "theme.css", // CSS file with variable overrides
"presets": ["light", "dark"], // Which base modes it provides
"preview": "preview.png" // Screenshot for settings UI
"preview": "preview.png", // Screenshot for settings UI
},
// ── Permissions (plugins only) ──
@@ -119,20 +119,14 @@ Every addon has an `addon.json` at its root:
"navigation:tab", // Add a top-level navigation tab
"context-menu:email", // Extend email context menu
"keyboard-shortcuts", // Register keyboard shortcuts
"external-fetch" // Fetch external URLs (declared origins)
"external-fetch", // Fetch external URLs (declared origins)
],
// ── External Origins (if external-fetch permission is declared) ──
"allowedOrigins": [
"https://api.example.com"
],
"allowedOrigins": ["https://api.example.com"],
// ── Slots (declares which UI slots the plugin uses) ──
"slots": [
"sidebar.bottom",
"compose.toolbar",
"viewer.actions"
],
"slots": ["sidebar.bottom", "compose.toolbar", "viewer.actions"],
// ── Settings Schema (plugin-specific preferences) ──
"settings": {
@@ -140,17 +134,17 @@ Every addon has an `addon.json` at its root:
"type": "string",
"label": "API Key",
"description": "Your API key for the service.",
"secret": true
"secret": true,
},
"enabled": {
"type": "boolean",
"label": "Enable integration",
"default": true
}
"default": true,
},
},
// ── i18n ──
"locales": "locales/" // Directory with {locale}.json files
"locales": "locales/", // Directory with {locale}.json files
}
```
@@ -184,7 +178,7 @@ The app already uses CSS custom properties (variables) for all colors, defined i
--font-family-mono: "JetBrains Mono", monospace;
--radius-base: 8px;
--spacing-density: 1; /* 0.8 = compact, 1 = normal, 1.2 = comfortable */
--shadow-elevation-1: 0 1px 3px rgba(0,0,0,0.08);
--shadow-elevation-1: 0 1px 3px rgba(0, 0, 0, 0.08);
}
:root[data-theme="com.example.nord"].dark {
@@ -210,7 +204,7 @@ User selects theme in Settings → Appearance
### 4.3 Theme Capabilities
| Capability | Mechanism |
|-----------|-----------|
| ----------------- | -------------------------------------------------- |
| Colors | Override `--color-*` CSS variables |
| Typography | Override `--font-family-*` variables |
| Spacing/density | Override `--spacing-density` multiplier |
@@ -271,7 +265,9 @@ export function activate(ctx: PluginContext) {
ctx.contextMenu.register("email", {
label: ctx.i18n.t("translateEmail"),
icon: "Languages",
action: (emailId) => { /* ... */ },
action: (emailId) => {
/* ... */
},
});
}
@@ -411,7 +407,8 @@ Next.js `import()` only resolves modules known at build time. To load plugins fr
async function loadRemotePlugin(url: string): Promise<PluginModule> {
// 1. Fetch the plugin's JS bundle as text
const response = await fetch(url);
if (!response.ok) throw new Error(`Failed to fetch plugin: ${response.status}`);
if (!response.ok)
throw new Error(`Failed to fetch plugin: ${response.status}`);
const code = await response.text();
// 2. Validate size limit (500 KB default)
@@ -437,11 +434,11 @@ async function loadRemotePlugin(url: string): Promise<PluginModule> {
// Shared dependencies exposed to plugins — avoids bundling duplicates
const SHARED_DEPS: Record<string, unknown> = {
"react": React,
react: React,
"react/jsx-runtime": jsxRuntime,
"lucide-react": lucideIcons,
"date-fns": dateFns,
"sonner": sonner,
sonner: sonner,
};
```
@@ -531,7 +528,7 @@ function Slot({ name }: { name: string }) {
#### Available Slots
| Slot Name | Location | Use Case |
|-----------|----------|----------|
| ------------------- | -------------------------------------- | ------------------------------------- |
| `sidebar.top` | Top of sidebar, below compose button | Quick-access widgets |
| `sidebar.bottom` | Bottom of sidebar, above storage quota | Extra navigation, widgets |
| `navigation.tabs` | Navigation rail, below contacts icon | New top-level views |
@@ -552,7 +549,7 @@ Plugins can listen to app events and state transitions:
#### Email Hooks
| Event | Payload | Description |
|-------|---------|-------------|
| --------------------------- | ----------------------- | --------------------------------- |
| `email:selected` | `{ emailId, email }` | User selected an email |
| `email:opened` | `{ emailId, email }` | Email viewer rendered |
| `email:compose:open` | `{ mode, replyTo? }` | Composer opened |
@@ -565,7 +562,7 @@ Plugins can listen to app events and state transitions:
#### Calendar Hooks
| Event | Payload | Description |
|-------|---------|-------------|
| ------------------------ | -------------------- | ---------------------- |
| `calendar:event:created` | `{ event }` | New event created |
| `calendar:event:updated` | `{ event, changes }` | Event modified |
| `calendar:event:deleted` | `{ eventId }` | Event deleted |
@@ -574,7 +571,7 @@ Plugins can listen to app events and state transitions:
#### Contact Hooks
| Event | Payload | Description |
|-------|---------|-------------|
| ------------------ | --------------- | ------------------- |
| `contact:selected` | `{ contactId }` | Contact selected |
| `contact:created` | `{ contact }` | New contact created |
| `contact:updated` | `{ contact }` | Contact modified |
@@ -582,7 +579,7 @@ Plugins can listen to app events and state transitions:
#### App Hooks
| Event | Payload | Description |
|-------|---------|-------------|
| -------------------- | -------------- | ---------------------------- |
| `app:ready` | `{}` | App fully loaded |
| `app:theme:changed` | `{ theme }` | Theme switched |
| `app:locale:changed` | `{ locale }` | Language changed |
@@ -610,7 +607,7 @@ Permissions are enforced at the `PluginContext` level — if a plugin didn't dec
### 8.2 Sandboxing Strategy
| Layer | Mechanism |
|-------|-----------|
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Store access** | `PluginContext` exposes only permitted store slices. Write access returns proxied objects — mutations are validated before applying. |
| **DOM access** | Plugin components render inside an `<AddonErrorBoundary>`. They receive a scoped React tree — no direct `document` manipulation. |
| **Network** | `ctx.fetch()` is a controlled wrapper. Requests are only allowed to origins listed in `allowedOrigins`. All other `fetch` / `XMLHttpRequest` calls from plugin code are blocked via CSP headers. |
@@ -621,6 +618,7 @@ Permissions are enforced at the `PluginContext` level — if a plugin didn't dec
### 8.3 Content Security Policy
Theme CSS is sanitized to disallow:
- `url()` references to external domains (only data URIs and same-origin).
- `@import` statements.
- `expression()` or `behavior:` (legacy IE attack vectors).
@@ -651,7 +649,7 @@ function AddonErrorBoundary({ addonId, children }) {
### 9.1 Addon Formats
| Format | Description | Use Case |
|--------|-------------|----------|
| -------------- | --------------------------------------------- | ----------------------------------- |
| **Bundled** | Shipped inside the app's `/addons/` directory | Default themes, first-party plugins |
| **URL** | Loaded from a remote URL at runtime | Self-hosted or third-party addons |
| **Local file** | Loaded from a local path (dev mode only) | Plugin development |
@@ -692,12 +690,14 @@ addons/
### 9.4 Installation Flow
**From URL:**
1. User pastes addon URL into Settings → Addons → "Install from URL".
2. App fetches `{url}/addon.json`, validates schema and compatibility.
3. Manifest is stored in addon registry (`localStorage`).
4. On next activation, the addon's assets are fetched and cached.
**Bundled:**
1. Addons in `/addons/` are auto-discovered at build time.
2. A generated `addon-registry.json` maps addon IDs to their local paths.
3. Bundled addons appear pre-installed (but can be disabled).
@@ -779,6 +779,7 @@ Appearance
```
When a theme is selected, the app:
1. Sets `data-theme` attribute on `<html>`.
2. Loads the theme's CSS file.
3. Persists the choice in `ThemeStore`.
@@ -894,6 +895,7 @@ nord-theme/
```
`addon.json`:
```json
{
"id": "org.nordtheme.bulwark-webmail",
@@ -925,6 +927,7 @@ email-translator/
```
`addon.json`:
```json
{
"id": "com.example.email-translator",