Both describe a full offline mail replica with a persistent cursor-based sync
engine. That scope was dropped in favour of "a SQLite index we can prompt
against" - see the notes prepended to each file for what shipped instead
(lib/mail-index/** + app/api/offline/{reindex,search}).
Kept rather than deleted because several findings are still accurate and still
load-bearing: the SQLCipher binding investigation, the PRAGMA-key
silent-no-op landmine, the safeStorage Linux basic_text hazard, the
hosted-deployment gate, and the codebase survey.
The review's note also records the disposition of every CRITICAL/HIGH finding.
Most became MOOT rather than fixed - C2, C3, C4, H1 and H2 were all
consequences of a long-lived worker holding credentials, and the new shape has
no worker. C1 (the Docker build breakage) and H2's env-vs-fd point were fixed
as specified, and the review's two corrections to the design (the
cipher_version check needing a non-empty string, getSelectedStorageBackend
being Linux-only) are both in the shipped code.
Also recorded: two things the design got wrong beyond the scope change - its
claim that the chosen process needs no new secret handling (the review was
right) and its assumption that Next's file tracing would carry the native
module (it does not).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Adds integration/tests/12-electron-mail-index.spec.ts (3 tests, all passing
against the real Stalwart fixture) and fixes what running it exposed. None of
these were visible from reading the code.
1. JMAP session fetch never followed a redirect. Stalwart 307-redirects
/.well-known/jmap to /jmap/session, and fetchJmapSession used
`redirect: 'manual'` and treated any non-2xx as failure - so every reindex
died with "JMAP session fetch failed (307)". Now follows up to 3 hops and
REFUSES to follow off-origin, because the user's credentials ride on every
hop; a blind `redirect: 'follow'` would hand the Authorization header to
whatever host a misconfigured session pointed at. Same bound and same
reasoning as lib/auth/verify-jmap-auth.ts.
2. The fd-3 key channel could only be adopted once per process, but its state
was module-scoped. Next re-evaluates route modules, so a second instance hit
`Could not open fd 3: Error: open EEXIST` from libuv. State moved to a
Symbol on globalThis - the one place in a Node process that survives module
re-evaluation.
3. Next's output file tracing does NOT carry @signalapp/sqlcipher's prebuilds/
into .next/standalone. It traced the package's JS and its node-gyp-build
dependency, but node-gyp-build resolves the .node binary by scanning a
directory at runtime, which no static tracer can follow - so `require()`
would have failed in every packaged build. scripts/assemble-standalone.mjs
now copies it, alongside the public/ and .next/static copies it already does
for the same "standalone output omits things" reason. All six platform/arch
prebuilds are copied, not just this host's, because electron-builder
cross-builds the x64 and arm64 macOS targets from one runner.
The three tests, and why it takes three - two constraints made a single
configuration impossible, and both were measured rather than assumed:
* The renderer cannot reach this fixture from a production build. Its CSP
pins connect-src to `'self' https: wss:` and the fixture's Stalwart is
plain HTTP. NODE_ENV=development at RUNTIME does not help: `next build`
INLINES process.env.NODE_ENV into the compiled middleware, so proxy.ts's
`isDev` is frozen at build time (observed: a standalone server started with
NODE_ENV=development still served the production CSP).
* The fd-3 channel cannot survive `next dev`, which forks its server with an
IPC channel that claims fd 3 (EEXIST); fd 4 there is not a pipe either
(ENOTTY).
So: PIPELINE drives the real standalone server over HTTP from Node with a
real fd-3 key channel (no browser, so no CSP) and asserts a real SMTP
delivery is findable by a word from its BODY, with a real snippet and
contextBlock, idempotent catch-up, working type filters, and - reading the
raw bytes of the .db AND its -wal - that nothing is recoverable in cleartext.
TRIGGER proves the event-driven wiring: a real delivery makes the renderer
POST /api/offline/reindex off its live push. WIRING launches the real shell
with no ELECTRON_LOAD_URL and asserts the routes are reachable (401, not 404
or 503) with real safeStorage behind them.
Each test now gets its own --user-data-dir. That is load-bearing, not hygiene:
Electron reuses one profile across launches, and a leftover jmap_stalwart_ctx
cookie from an earlier run made the WIRING test's 401 assertion pass as a 200.
Verified: typecheck clean; unit suite 2379 tests with the SAME 3 pre-existing
failures as the base commit b15098a6 (2 builtin-themes, 1 jmap-client-
resilience) and 48 net new passing; both `docker build`s succeed; the
hosted-deployment gate returns 404 with an empty body and materialises no file
in the production image; e2e/electron-smoke 4/4; 11-electron-notification
still passes.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
48 assertions. The pure extractors and toFtsMatchQuery need no database; the
store tests run against REAL SQLCipher and skip themselves when the optional
native binding is absent (e.g. Alpine/musl), which is the same guard the
runtime uses.
The two that matter most:
* "writes an ENCRYPTED file" reads the raw bytes back and asserts a canary
string is absent. This is the assertion that catches `PRAGMA key` silently
doing nothing - a plain-SQLite binding leaves the mailbox in cleartext with
no error anywhere, so a functional test alone would pass.
* "upserting the same id REPLACES the FTS row" - the FTS table is maintained by
hand (standalone, not external-content), so a missed delete leaves the OLD
body permanently searchable. The test asserts the old text stops matching,
not just that the new text starts.
Also covered: FTS5 MATCH injection (its grammar is not protected by SQL
parameter binding, so a bare quote would 500 the search route), account-scoped
keys not merging two accounts' identical JMAP ids, title-over-body bm25
weighting, and the hosted-deployment env gate rejecting a relative path.
Note: lib/__tests__/builtin-themes.test.ts has 2 pre-existing failures on this
branch (theme author "VNC" vs. expected "Built-in", from the earlier rebrand) -
verified failing identically at b15098a6, before any of this work.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
An on-device, SQLCipher-encrypted full-text index the app can retrieve from to
feed an LLM ("prompt against"), for the Electron desktop shell only.
Shape: no persistent background worker and no resident credential. Indexing is
a normal request-scoped API route, triggered by the renderer's EXISTING live
JMAP push connection - so it reacts to each delivery/change rather than polling.
- lib/mail-index/binding.ts guarded require of the optional native binding
- lib/mail-index/paths.ts the VNCMAIL_DESKTOP_STORE_DIR gate + hashed paths
- lib/mail-index/store.ts schema, upsert, FTS5 search, encryption assertion
- lib/mail-index/extract.ts PURE JMAP-object -> document extractors
- lib/mail-index/jmap.ts minimal stateless server-side JMAP client
- lib/mail-index/key.ts per-job key fetch over the inherited fd
- lib/mail-index/reindex.ts the job + slot->account resolution
- electron/key-service.ts safeStorage wrap/unwrap, served over fd 3
- app/api/offline/reindex POST, event-driven + catch-up
- app/api/offline/search GET, the retrieval surface (hits + contextBlock)
- lib/mail-index-client.ts renderer client; StateChange -> index call
- components/settings/local-index-settings.tsx status + manual catch-up
Decisions worth knowing:
* `@signalapp/sqlcipher` is an OPTIONAL dependency with a guarded runtime
require. It publishes six N-API prebuilds and NO build sources, and both
Dockerfiles are node:24-alpine (musl, no matching prebuild) - as a hard
dependency it would break the production image and the integration fixture's
webmail container, neither of which wants this feature.
* Credentials come from the existing per-slot encrypted `jmap_stalwart_ctx`
cookie via lib/stalwart/credentials.ts - the same helper /api/settings and
/api/push/preview already use. It carries a ready-made header for basic AND
bearer accounts, so the indexer never touches the OAuth refresh-token cookie;
a server-side refresh would rotate a token into a response nobody reads and
silently log the user out.
* The encryption key crosses main -> server over an INHERITED FILE DESCRIPTOR,
never an environment variable: env is readable by any process running as the
same OS user, which would defeat using the OS keychain at all. Fetched per
job and zeroed after, so there is no long-lived key copy.
* safeStorage's Linux `basic_text` backend (no keyring) is treated as refusal,
not degradation - it "encrypts" with a hardcoded public password, which would
look like an encrypted mailbox while providing nothing.
getSelectedStorageBackend() is Linux-only and platform-guarded.
* Every store open asserts `PRAGMA cipher_version` returns a non-empty STRING,
not merely a row: a non-cipher binding returns ZERO ROWS, so a row-count check
would pass vacuously while writing the mailbox to disk in cleartext.
* Files are indexed by name/path/date/size only - NOT by extracted content.
Text extraction from arbitrary PDFs/office documents is a separate problem.
* Account-scoped composite keys `(jmap_account_id, content_type, id)` are kept
even though there is one file per account: one login exposes delegated/shared
JMAP accounts too, and JMAP ids are unique only within an account.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Adapts the mobile client's finalized, twice-reviewed JMAP delta-sync design
(vncmail-native's docs/DELTA-SYNC-ENGINE-DESIGN.md, revision 3) to Electron's
runtime rather than re-deriving JMAP sync theory. Every section is tagged
[reused] / [adapted] / [new] so a reader can tell which is which; the
protocol-level parts (three state machines, cursor provenance with branded
types, error taxonomy, pinned reconcile sweep floor, I1-I13, F1-F49) are
reused by citation, not restated.
Three decisions were genuinely open here and are resolved with evidence:
1. Process placement: the engine + SQLite live in the standalone Next.js
server process, on a worker thread. The per-account credentials are
already there in httpOnly AES-GCM cookies, so nothing secret crosses a
process boundary - and a Node process can put an Authorization header on
a WebSocket upgrade, which is exactly what makes RFC 8887 push
unreachable from the renderer today (lib/jmap/client.ts:6038-6059).
Hosting it in main.ts was rejected because it can only be built by
moving credentials into a process that currently holds none - the change
that same comment explicitly declined. A WASM/OPFS renderer engine was
rejected because it needs 'wasm-unsafe-eval' added to the product-wide
CSP in proxy.ts, and its only encrypted backends are small third-party
WASM builds.
2. SQLCipher ships on day one, via @signalapp/sqlcipher (N-API prebuilds,
verified loading in Electron 43.2.0 in both process modes with no
rebuild; real SQLCipher 4.10.0; encrypted header, wrong key rejected,
FTS5 present; AGPL-3.0-only like this repo). The mobile design's
plaintext-first phase existed only because Expo Go cannot load
SQLCipher, and that constraint has no Electron analogue. node:sqlite is
rejected (no encryption - PRAGMA key is a SILENT no-op that leaves the
mailbox in cleartext - and stability 1.2/RC in the Node 24 that Electron
43 bundles); better-sqlite3-multiple-ciphers is rejected (Electron
prebuilds stop at ABI 146, Electron 43 needs 148, so a C++ toolchain on
every machine, and that lag recurs at every Electron major).
3. Keys use Electron's built-in safeStorage, not keytar, with a mandatory
getSelectedStorageBackend() check: on Linux without a keyring,
isEncryptionAvailable() returns true while using a public hardcoded
password, which is worse than an honest failure.
Also records what this repo has that the mobile one doesn't (a real Stalwart
integration fixture, so the highest-value tests are cheap) and what it
lacks (no /changes wrappers, no offline cache, no outbox - so v1 desktop
offline is read-only by decision, and the mobile design's D1-D8 defects are
not inherited).
Everything not verifiable in this environment is flagged for a Stage A
verify-first gate rather than presented as fact - notably whether an
unsigned build keeps its macOS Keychain item across an electron-updater
upgrade, and whether Next's output file tracing carries the native
prebuilds into .next/standalone.
No source file is touched by this commit.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Phase 1 step 7 of VNCprodbuild. integration/tests/11-electron-notification.spec.ts
launches the actual Electron shell, logs in as alice against this repo's
existing docker-compose Stalwart fixture, injects a message over real SMTP
(same helpers/smtp.ts sendMail() 02-mail-sync.spec.ts uses), and asserts a
native notification fires via electron/main.ts's __notificationCallCount
test hook - proving the full real pipeline, not just the synthetic IPC call
step 3's smoke test exercises: SMTP -> Stalwart -> JMAP push
(lib/jmap/client.ts) -> stores/email-store.ts's handleStateChange ->
handleNewEmailNotification -> the page effect -> lib/electron-bridge.ts ->
the contextBridge/IPC bridge -> electron/main.ts's Notification call.
Runs against a `next dev` server (electron/main.ts's new ELECTRON_LOAD_URL
escape hatch), not the standalone build, because this fixture's Stalwart is
deliberately plain HTTP and production's CSP correctly refuses non-TLS
connections - the identical trade-off integration/webmail.Dockerfile already
makes for the browser-based suite. New playwright.integration-electron.config.ts
+ global-setup-electron.ts (brings up only the `stalwart` compose service,
not `webmail`, which this suite never touches and which may not even be
startable on a given host - see its own header comment) keep this fully
separate from the main dockerized integration run, which has no Electron
binary compatible with that container's platform; playwright.integration.config.ts
gets a matching testIgnore so a plain `npm run test:integration` never tries
to sweep this file in. Wired as `npm run test:integration:electron`.
On "the real WebSocket path": confirmed against this fixture's actual
`stalwartlabs/stalwart:v0.16` (same as the sandbox server) that its
/jmap/ws requires the same Authorization header as every other JMAP
endpoint on the handshake itself, which the browser WebSocket API cannot
attach - so the WS attempt reaches the network correctly (see the CSP fix
in the previous commit) but always fails auth here, and the circuit
breaker falls back to SSE within about a second. That fallback is what
delivers the push this test observes - documented in detail in the spec's
header comment, including why asserting the WS handshake itself succeeds
here would be asserting something that cannot be true from a browser
against this specific server.
Known flakiness, root-caused not eliminated (see
playwright.integration-electron.config.ts's retries: 2 and its comment):
`next dev`'s on-demand route compilation + Fast Refresh occasionally races
the SSE stream during the login -> inbox transition and drops that one push
event with no error anywhere - reproduced by running the identical test
repeatedly against an already-warm stack (IT_NO_DOCKER=1): identical
request sequence logged every time, but the outcome wasn't always the same.
This is specific to the dev-server workaround this test needs for the
plaintext-Stalwart fixture, not a bug in the feature it's verifying - the
WS circuit breaker and SSE fallback fire exactly as designed in every run's
own logs, pass or fail.
Verified: passed cleanly standalone multiple times; with retries: 2 in
place, passed within the retry budget on every attempt made.
Two real bugs in the previous WS-push commit, both found while building the
integration test for it (not theoretical - each reproduced and verified
before and after the fix):
1. proxy.ts's production CSP (`connect-src 'self' https:`) has no `wss:`
term, so `new WebSocket(...)` was blocked before any network attempt at
all - confirmed by listening for `securitypolicyviolation` against the
real reference server (stalwart.sandbox.vnc.de, HTTPS): the WS feature
was entirely inert in a production build, for every server, not just
ones with an incompatible auth model. Fixed by adding `wss:` alongside
`https:` in production - no new trust surface, since `https:` here
already allows fetch/XHR to any TLS host (needed for
ALLOW_CUSTOM_JMAP_ENDPOINT / multi-server setups), so extending that same
model to WebSocket is consistent, not a new precedent. Verified after the
fix: the same probe now reaches the network and gets a real (expected)
auth rejection from Stalwart instead of a CSP block.
2. lib/jmap/client.ts's circuit breaker (5 attempts, 1s/30s backoff) could
take up to ~31s to give up on WS and fall back to SSE. Against a server
that fails the handshake instantly and deterministically every time (the
auth-header limitation documented in the previous commit), that's ~31s
of NO live push at all - WS hasn't succeeded and hasn't given up yet, so
SSE never starts connecting, and any mail delivered in that window was
silently missed (SSE only streams changes from the moment it connects,
no catch-up). Reproduced directly: a real SMTP delivery sent during that
window never reached the notification bridge.
Fixed two ways:
- Tightened the ladder to a 200ms base / 5s cap / 3-attempt circuit
breaker (worst case ~1.75s instead of ~31s) - still genuine
exponential-with-jitter backoff, just tuned for a failure mode that's
fast and deterministic rather than slow and flaky. A slow/real
network issue is unaffected: a hanging attempt is still bounded by
the browser's own WebSocket connect timeout, not by these constants.
- setupPushNotifications() now primes a polling baseline
(fetchCurrentStates()) in parallel with the WS attempt, and
fallbackFromWebSocket() diffs against it (checkForStateChanges())
BEFORE connectSSE()/startPollingFallback() get a chance to erase that
opportunity. This is what actually closes the gap rather than just
shrinking it: it catches a change that happened to the primary
account during the (now much shorter) WS retry window.
electron/main.ts also gets a test-only escape hatch (ELECTRON_LOAD_URL): set
it to skip spawning the standalone server and load that URL instead. Real
users and every packaging/CI path never set it - added because verifying
the fixes above against this repo's own local Stalwart fixture (deliberately
plaintext HTTP - integration/webmail.Dockerfile makes the identical
trade-off for the browser-based suite) needs a dev-mode Next.js server
(proxy.ts only widens connect-src for plain http/ws in dev), not the
production standalone build electron/main.ts normally boots.
next.config.ts: added 127.0.0.1 to allowedDevOrigins alongside the existing
LAN entry - electron/main.ts always loads its window at 127.0.0.1, so a
dev-mode Electron run (only used by the escape hatch above) needs it in this
allowlist the same as any other cross-origin dev client would.
Verified: full lib/__tests__ JMAP suite still green (158/158); npm run
test:electron still green (4/4); the raw WebSocket probe against the real
sandbox now reaches the network post-fix instead of being CSP-blocked.
Phase 1 step 6 of VNCprodbuild, resolving the step-5 DECISION gate (human
confirmed: WebSocket push, not polling, not quit-to-tray).
lib/jmap/client.ts: getWebSocketUrl() discovers the push endpoint from the
session's own urn:ietf:params:jmap:websocket capability (mirrors
getEventSourceUrl()'s existing pattern) - not hardcoded to any one server,
rewritten to the client's own host the same way apiUrl/downloadUrl/
eventSourceUrl already are (rewriteWebSocketUrl(), scheme-aware since ws/wss
can never share an origin string with the client's http/https serverUrl).
setupPushNotifications() now tries WS first when advertised, falling back to
the existing SSE/polling chain when not. connectWebSocket() subscribes via
WebSocketPushEnable and routes incoming StateChange frames through the exact
same stateChangeCallback that SSE/polling already feed - so
stores/email-store.ts's handleStateChange (mailbox/email refresh, scheduled
mail, calendar, filters) and handleNewEmailNotification (the new-mail toast/
sound signal) all work unchanged regardless of which transport delivered the
change.
Reconnect/backoff: exponential with full jitter (1s base, 30s cap - unlike
SSE's fixed 3s retry, explicitly requested since a long-lived WebSocket can
be dropped by sleep/network-switch/idle-proxy repeatedly in a row). An
app-level heartbeat (Core/echo every 30s, force-reconnect after 90s of
silence) catches connections that report readyState OPEN long after the
underlying path is actually gone, mirroring the existing SSE ping monitor.
Circuit breaker (wsConsecutiveFailures/wsPermanentlyDisabled): gives up on
WS after 5 CONSECUTIVE handshake failures (never reaching "open" - a
connection that opened fine and dropped later doesn't count) and falls back
to SSE/polling for the rest of the client instance's life. This is not
theoretical - verified empirically against the actual sandbox server this
was built against:
curl -i -H "Connection: Upgrade" -H "Upgrade: websocket" \
-H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: ..." \
-H "Sec-WebSocket-Protocol: jmap" https://stalwart.sandbox.vnc.de/jmap/ws
-> 401 Unauthorized, WWW-Authenticate: Bearer/Basic
Stalwart's /jmap/ws requires the same HTTP Authorization header as every
other JMAP endpoint on the upgrade request itself, and the browser
WebSocket constructor cannot attach custom headers to that handshake (a
WHATWG spec restriction - credentials-in-URL is also explicitly rejected).
Every connection attempt from this renderer-side client will therefore fail
against Stalwart specifically and fall back to SSE (which keeps working
exactly as before - zero regression). Implemented for real anyway, not
stubbed: it's fully spec-correct and activates automatically against any
server whose WS endpoint doesn't share this auth model (e.g. behind a
cookie-authenticating proxy), and the alternative (opening it from
Electron's main process via a header-capable client, which would need raw
credentials piped over IPC from the renderer) is a materially bigger
security-sensitive change than what was scoped here. Documented in detail
in the code comments above the new fields.
lib/jmap/client-interface.ts + lib/demo/demo-client.ts: getWebSocketUrl()
added to the interface (demo client returns null, matching
getEventSourceUrl's existing stub).
app/(main)/[locale]/page.tsx: the existing "new mail arrived" effect (which
already plays a sound, transport-agnostically, whenever
stores/email-store.ts sets newEmailNotification for a genuine new top-of-
inbox message) now also calls lib/electron-bridge.ts's
showElectronNotification() when isElectronShell() - firing the native
notification bridge built in the step-3 commit, gated on the same
emailNotificationsEnabled setting the sound already uses. Fallback title/
body text ("New mail" / "(no subject)") matches public/sw.js's existing
push-notification fallback strings rather than introducing new i18n keys
for a rarely-hit edge case.
Verified: full lib/__tests__ JMAP suite green (158/158 across 13 files,
excluding one pre-existing unrelated flaky test - jmap-client-resilience's
ping-failure-reconnect-ordering assertion uses real timers and fails
~75% of the time on both this branch's base commit and this change,
confirmed by running the untouched baseline the same way). npm run
test:electron still green (4/4) after a full rebuild.
Consolidates the repo map, architecture recap, full decision log, Phase 1/2
status, remaining roadmap, and known landmines into one canonical reference,
so this doesn't live only in chat history or session memory.
Phase 1 step 8 of VNCprodbuild. New workflow, additive to the existing
docker-publish*.yml/standalone-release.yml (which only ever built the
Docker image / standalone tarball, never the desktop shell).
Matrix over macos-latest/windows-latest/ubuntu-latest. Each leg: npm ci,
build:standalone, build:electron, then npm run test:electron (the Phase 1
step 2 smoke test) as a REQUIRED gate before packaging or any
artifact-upload step - a platform-specific regression fails the leg it
breaks instead of slipping through because only one OS was ever
smoke-tested. Linux needs an explicit Xvfb install first (no display
server on that runner by default); macOS/Windows runners have one.
Triggers on release-published (packages + publishes to that release via
electron-builder's --publish always, matching standalone-release.yml's
`gh release upload` precedent but through electron-builder's own GitHub
publish provider) and workflow_dispatch (packages only, uploads a build
artifact instead, --publish never).
Ships unsigned - CSC_IDENTITY_AUTO_DISCOVERY: "false" stops electron-builder
from probing for a macOS identity that doesn't exist (VNCprodbuild step 9:
no Apple Developer ID or Windows cert yet, both human-owned purchases).
Structured so signing needs no rewrite later - just add CSC_LINK/
CSC_KEY_PASSWORD (macOS) and/or WIN_CSC_LINK/WIN_CSC_KEY_PASSWORD (Windows)
as repo secrets once those exist.
Phase 1 step 7 of VNCprodbuild. electron/main.ts calls
autoUpdater.checkForUpdatesAndNotify() once the app is ready, only for
packaged builds (app.isPackaged) - dev/test runs have no latest.yml and
would just log a noisy 404 on every launch. electron-builder.config.js gets
a matching `publish` block pointing at this repo's own GitHub Releases
(brvncde-dotcom/vncmail-plus) - the skill's recommendation over standing up
a new distribution channel, since the repo is already private. Flagged as
the "light decision" the skill calls it, not blocking.
Deliberately defensive: no code signing yet (step 9), so update
verification can fail on macOS in particular. Wrapped in try/catch +
autoUpdater's "error" event so a failed check is logged and swallowed, never
fatal - this is background maintenance, not something the user should be
blocked on.
Verified with a --dir packaged build: checkForUpdatesAndNotify() throws
ENOENT for app-update.yml (expected - that file is only emitted by a full
`electron-builder build`, not --dir) and the error handling swallows it
cleanly; the standalone server still boots and serves the app normally.
npm run test:electron still green (4/4) - autoUpdater is a no-op in the
unpacked dev/test path this suite exercises.
Phase 1 step 6 of VNCprodbuild. electron-builder.config.js now has real
targets: mac (dmg, zip; x64+arm64), Windows (nsis; x64), Linux (AppImage,
deb; x64). Still no code signing (step 9 - needs an Apple Developer ID and
optionally a Windows cert, both human-owned purchases).
Icon wired from public/icon-512x512.png (the existing PWA manifest icon) -
electron-builder generates .icns/.ico from it automatically. This is a
stand-in, not a dedicated app icon: it's only 512x512 (the macOS icns's
largest slot wants 1024x1024+), and public/branding/Bulwark_Icon_App.svg
looks like the actual intended master for this, but it's a vector file and
this environment has no SVG rasterizer (rsvg-convert/ImageMagick/Inkscape)
to export it at high res. Flagged in the config's comments; someone with
the right tooling (or a designer) should export that SVG at 1024x1024+ and
swap the `icon` path.
Caught and fixed a real bug by actually running a --dir build rather than
just trusting the config: app-builder-lib's extraResources copy
unconditionally drops any directory literally named "node_modules" sitting
at the copy root (node_modules/app-builder-lib/out/util/filter.js), so the
naive `from: ".next/standalone"` silently stripped the standalone server's
own node_modules and the packaged app crashed with "Cannot find module
'next'" on launch. Fixed by copying from one level up (`from: ".next"` with
a `standalone/**/*` filter) so "node_modules" is never the literal copy
root. Verified by launching the packaged --dir mac build directly - it
boots the standalone server and serves the app with no errors, same as the
unpackaged dev flow.
Phase 1 step 3 of VNCprodbuild. electron/preload.ts's contextBridge now
exposes window.vnc.showNotification(title, options), routed via
ipcRenderer.invoke("vnc:show-notification") to a new ipcMain.handle in
electron/main.ts that calls Electron's own Notification API. This is the
desktop shell's native notification path - it sits alongside, not in place
of, the browser/PWA's service-worker push path (public/sw.js's push/
notificationclick handlers + lib/web-push.ts), which is untouched.
lib/electron-bridge.ts gives the renderer a `isElectronShell()` +
`showElectronNotification()` wrapper so app code can detect the shell and
use the native path instead of/alongside SW push - not wired to any real
mail-delivery trigger yet, that's Phase 1 steps 4-6 (JMAP realtime
capability investigation, the background/foreground strategy decision, and
implementing it).
Extended e2e/electron-smoke.spec.ts to prove the IPC plumbing actually
fires end-to-end: calls window.vnc.showNotification from the renderer and
asserts the round-trip resolves (not that a real OS toast appears - not
observable in CI). Verified locally: the call resolves {"shown":true} on
this machine, confirming it genuinely reaches Electron's Notification API
and back, not just that window.vnc exists.
Also fixes a real bug caught by this step's typecheck: the smoke test's
Playwright Page variable was named `window`, shadowing the DOM global
inside every evaluate() callback and silently breaking their types. Renamed
to `appWindow`.
All 4 smoke-test assertions green: npm run build:electron && npm run
test:electron.
Phase 1 step 2 of VNCprodbuild. e2e/electron-smoke.spec.ts uses Playwright's
_electron.launch() to boot the real skeleton (dist-electron/main.js from
step 1) and asserts:
- the login screen renders (same input[type="text"]/[type="password"]
selectors as e2e/login.spec.ts's browser-based check)
- zero uncaught page errors fire during load
Sets JMAP_SERVER_URL (any non-empty value) so the app reaches
lib/setup/state.ts's "env-managed" state and serves the normal login screen
instead of 302ing to the first-run /setup wizard - no live mail server or
mock JMAP build flag needed just to prove the shell renders.
playwright.electron.config.ts is deliberately separate from
playwright.config.ts: it has no `webServer` block, since this suite's app
boots its own server and would otherwise race pointlessly with `npm run dev`
starting on :3000 for the browser-based e2e/*.spec.ts suite.
Wired as `npm run test:electron`. Verified green locally (2 passed) after
`npm run build:standalone && npm run build:electron`; every later step in
the Electron rollout must keep this passing before moving on.
Follow-up to 218a584f - these edits (electron npm scripts, "main" field,
electron/electron-builder/electron-updater deps, dist-electron/**
gitignore) were made alongside that commit but got left unstaged when it
landed. No behavior change beyond what that commit already described.
Phase 1 step 1 of VNCprodbuild: electron/main.ts boots the same Next.js
"standalone" server artifact the Dockerfile already produces (next.config.ts's
output: "standalone") as a child process on a random localhost port, then
opens a BrowserWindow at it. electron/preload.ts is a contextBridge stub
(window.vnc.isElectron) for now.
scripts/assemble-standalone.mjs copies public/ and .next/static into
.next/standalone, mirroring what the Dockerfile does by hand, since `next
build` deliberately leaves both out of the standalone output.
scripts/build-electron.mjs bundles main.ts/preload.ts to CommonJS via esbuild
(already a devDependency).
New npm scripts: build:standalone, build:electron, electron:dev.
electron-builder.config.js is intentionally minimal - no signing, no
platform targets yet, just enough to prove the concept end to end.
Also fixes a pre-existing repo-wide lint gap: vnc/plugins/smime is an
independent sub-package (own package.json/esbuild build, browser-only
globals) that was never added to eslint's ignores alongside repos:: and
examples/**, so `npm run lint` - and the husky pre-commit hook - was failing
on every commit regardless of what changed. Excluded it the same way those
are, and added node globals for scripts/**/*.mjs so the new build helpers
above lint cleanly too.
Verified manually: npm run build:standalone && npm run build:electron &&
electron . boots the server and opens a window with no errors.
User manually imported bernd.rodler.p12 through the real Settings >
S/MIME > Import key dialog on localhost:3100 - real native file picker,
real PKCS#12 passphrase, real storage passphrase. Succeeded.
This closes the last unverified layer. Every step of the delivery path
is now proven end to end: crypto correctness, parser hardening against
hostile input, admin install, client activation under the B-04 gate,
and now UI key import.
Also fixes a stale line in the audit doc that still listed finding 5
as open after it was fixed in a4155aa3.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Finding 5 — the MIME parser runs on attacker-controlled input: the inner
content recovered after decrypt/verify is whatever the sender put there.
Upstream had no depth limit on nested multiparts and no size cap anywhere.
Verified against the unpatched upstream parser with the same input:
UPSTREAM CRASHED: RangeError - Maximum call stack size exceeded
UPSTREAM: 65MB accepted (no size cap)
So this was a live decrypt-time DoS reachable by anyone who can send mail.
Caps added: depth 20, parts 500, bytes 64 MB — generous enough that no
legitimate message comes close (real mail nests 3-4 levels). Past a limit a
subtree degrades to a leaf rather than throwing, so one pathological branch
doesn't discard the legitimate parts above it. Oversize input is refused
outright rather than truncated: half a MIME tree parses into misleading
nonsense, and showing part of a message is worse than saying no. Both
bodyStructure walkers in smime-detect.js are capped too — those run on
server-supplied structure BEFORE any decrypt/verify gate.
Finding 4 — hardened, not eliminated, per the agreed scope. Unlocked
CryptoKeys still live in durable IndexedDB rather than memory; moving them
would mean refactoring how the plugin shares state across iframes and
risking the unlock->decrypt path just verified.
What changed instead:
- Removed the lockOnLogout opt-out from the logout/account-switch wipes. A
non-extractable key cannot be exported but can still be USED, so a handle
outliving the session lets anyone with the browser profile decrypt mail
without knowing the passphrase. That is not a preference to toggle off.
- Added a best-effort wipe on pagehide and beforeunload to narrow the window
in which a usable handle exists on disk. Best-effort by nature: an
IndexedDB write may not complete during teardown and neither event fires
on a crash — which is precisely why the boot wipe in activate() remains
the load-bearing control.
- Deliberately NOT wiping on visibilitychange: tabbing away would drop the
unlock and force a passphrase re-entry every time, which trains users into
turning S/MIME off entirely.
- Dropped the now-dead lockOnLogout setting from the manifest. A toggle that
silently does nothing is worse than no toggle.
Tests: 49 unit assertions + 28 round trip. The round trip now feeds genuinely
hostile MIME through the real parser (5000-level nesting, 5000 siblings,
65 MB) and still confirms a normal multipart/alternative parses correctly.
Full crypto round trip unchanged and passing, so neither fix broke S/MIME.
Findings 6, 7, 8 and 9 remain open.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds roundtrip.mjs, which drives the plugin's own modules directly — no
browser, no DOM — and proves the three audit fixes did not break S/MIME.
24 assertions, all passing, against the self-signed spike certificates:
PKCS#12 import (both identities, RSA-2048, kdf=600000)
key encrypted at rest (32-byte salt, 12-byte IV)
unlock yields NON-EXTRACTABLE keys; wrong passphrase rejected
sign -> verify: signature valid, signer email matches From
encrypt -> decrypt by the intended recipient, plaintext matches
sender can read their own Sent copy
downgraded message produces no plaintext
Two results worth recording.
Finding 1 is confirmed against a genuine CMS structure, not just a mock:
the spike certs are self-signed, smimeVerify reports signatureValid AND
signerEmailMatch true AND selfSigned true, and the gate refuses the
auto-import. That is exactly the cert-substitution attack, blocked. The
same status with selfSigned:false passes, so the gate is not simply
refusing everything.
Finding 2 is confirmed end to end: our own encrypt path produces
AES-256-GCM, decrypt reports contentAuthenticated:true, so HTML renders
without suppression. Only legacy inbound CBC degrades to text.
The section-8 assertion is deliberately loose. Swapping the 9-byte
AES-GCM OID for the 8-byte 3DES OID also invalidates the enclosing DER
lengths, so ASN.1 validation rejects the message before the allowlist is
reached — either way no plaintext is produced, and the assertion says
which path fired rather than pretending it tested the allowlist. The
allowlist itself is asserted precisely in verify-fixes.mjs, which now
carries 36 assertions including checks that fail if a legacy CBC OID
reappears or the mail path stops using the native engine.
Browser-side spike result: the patched plugin installs through the admin
channel, resolves to the privileged tier, and activates with
"hooks=5, slots=3" and no refusals — so the B-04 gate does not block it.
Its S/MIME settings section renders and survives SPA navigation. Key
import via the UI could not be automated (native file picker), which is a
harness limit rather than a product defect; roundtrip.mjs covers that
path directly instead.
Findings 4, 5 and 6 remain open.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Upstream applied no content-encryption check at all on decrypt, and ran
every decryption through the liner engine — which registers DES-CBC,
3DES-CBC and RC2-CBC. Those OIDs exist in crypto-engine.js for PKCS#12
password-based encryption; the CMS content path merely reused the same
engine and inherited them. A crafted message could therefore be decrypted
under a broken cipher, and unauthenticated plaintext was handed straight
to the renderer — the EFAIL precondition.
The obvious fix would have been wrong. Accepting only AEAD breaks most
real S/MIME mail: RFC 5751 makes AES-128-CBC the MUST-implement content
cipher, Outlook and Thunderbird default to CBC, and AES-GCM in CMS
(RFC 5084) is barely deployed. An AEAD-only allowlist is a functionality
catastrophe wearing a security fix's clothes.
Three layers instead:
1. Allowlist the AES family and refuse everything else, with the gate
running before any private key is touched. CBC stays for interop;
DES/3DES/RC2 are refused.
2. Take the mail path off the legacy engine. Normal decryption now uses
nativeEngine(); the liner engine is reachable only when a genuine
legacy RSAES-PKCS1-v1_5 key is in play. This removes the weak ciphers
structurally rather than by policy — native WebCrypto handles RSA-OAEP
key transport and AES-CBC/GCM content perfectly well.
3. Refuse to render unauthenticated plaintext as HTML. CBC output is
malleable and HTML is EFAIL's exfiltration channel. The host does block
remote content by default (allowExternalContent starts false), but that
is a user/admin setting this plugin cannot observe, so we don't lean on
it. New renderUnauthenticatedHtml setting (default false) is the
documented opt-out. Our own encrypt path always uses AES-GCM, so mail
we send renders fully; only legacy inbound CBC degrades to text.
Built from source with the repo's own pipeline (esbuild, 1.69 MB) and
packaged to smime-vnc.zip (0.27 MB). All four fixes verified present in
the built bundle. Build output is gitignored — never vendor a prebuilt
bundle, which was the upstream mistake.
Correcting an earlier assumption: this bundle does NOT trip the B-01
pattern scanner (zero matches on all five patterns), so the override is
not needed to install it. B-01 remains correct — it closed a real
entrypoint-only coverage gap — but it isn't load-bearing here.
verify-fixes.mjs now carries 36 assertions covering all three fixes,
including source checks that fail if a guard is removed, if a legacy CBC
OID reappears in the allowlist, or if the mail path stops using the
native engine.
Findings 4 (unlocked keys persisted to IndexedDB), 5 (parser DoS) and 6
(PKCS1v1.5 oracle surface) remain open.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
S-01 audited bulwarkmail/plugins/smime @ 91085a3 (2,935 lines). Nine
findings, two HIGH. No backdoor and no exfiltration path anywhere in the
bundle — the problems are trust-model and input-validation gaps. Full
report in vnc/audits/SMIME-PLUGIN-AUDIT-2026-08-04.md.
Fork is source-only. The upstream smime.zip is a 1.77 MB prebuilt bundle
whose manifest reads 1.0.1 while the source reads 1.0.2, so auditing
src/ would not audit what that zip installs. We build from source.
Finding 1 (HIGH) — certificate substitution. maybeAutoImportSigner gated
on signatureValid alone, but smimeVerify runs checkChain:false, so that
only proves "signed by whoever holds this key", not that the claimed
identity is real. Self-sign a cert asserting victim@example.com, send one
signed message, and it was stored as the encryption target for that
address — the user's next Encrypt to the victim went to the attacker.
Now requires signerEmailMatch === true and !selfSigned. Both values were
already computed and displayed as untrusted in the banner; only the
import path ignored them. Tests for `true` explicitly so an undefined
match (missing From header) fails closed.
Finding 3 (MED-HIGH) — CRLF header injection. Escaping reached only
Subject and attachment filename; display names, raw addresses,
Message-ID, In-Reply-To, References and attachment Content-Type were
emitted verbatim, and formatAddress escapes only backslash and quote.
In-Reply-To/References/display names are copied from inbound mail when
replying or forwarding, so the value is attacker-supplied. Sanitising
inside formatHeader covers all 17 call sites by construction; the three
headers assembled directly get stripCrlf explicitly.
Also adds auth:observe to the manifest. The plugin registers
onAfterLogout/onAccountSwitch — real hooks (lib/plugin-hooks.ts:362-363)
— without declaring the permission, so under B-09 the session-key wipe
would silently stop running.
verify-fixes.mjs carries 19 assertions including source checks that fail
if either guard is removed or a new unsanitised interpolated header
appears. That last one immediately caught the interpolated smime-type
Content-Type header, which manual review had dismissed as static.
Finding 2 (unauthenticated CBC accepted on decrypt) is NOT fixed. This
is not safe for real mail yet — sandbox accounts only.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The overrideWarnings escape hatch added alongside the bundle scan was
API-only: an admin uploading a crypto plugin through the web form hit a
400 with canOverride and had no way to act on it, which left S/MIME and
PGP bundles uninstallable through the UI.
Hold the rejected file client-side and show the findings — pattern per
file — with "Install anyway" and "Cancel". Proceeding re-posts the same
file with overrideWarnings, so the decision stays explicit and lands in
the audit log. The route now echoes accepted findings back on success so
the confirmation says how many were waved through rather than reporting a
bare install.
Also replaces a dead `data.warnings` read with the live `findings` field;
the route never returned `warnings` on success, so that branch never ran.
Completes B-01.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Two problems with the upload scanner, pulling in opposite directions.
It only scanned the entrypoint, so a bundle with `eval()` in a second
file passed outright — verified against a synthetic bundle whose
vendor/openpgp.js tripped three patterns while index.js stayed clean.
At the same time, a hard 400 on eval()/new Function()/innerHTML= makes
every crypto plugin uninstallable: minified openpgp.js and pkijs
legitimately contain all three. That blocks S/MIME and PGP entirely.
Scan every .js/.mjs in the bundle and return structured findings
({file, patterns[]}) plus canOverride, so the admin can see exactly what
tripped and where. An explicit overrideWarnings=true proceeds and writes
a plugin.install.scan_override audit entry recording which patterns in
which files were accepted — not merely that an override happened.
This route is already admin-authenticated, so the scan is defence in
depth against an accidental or compromised upload, not a trust boundary.
Treating it as the latter is what made crypto plugins uninstallable.
Also log the B-04 and B-01 divergences in vnc/VNC-CHANGES.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
`info.hooks` is self-reported by the sandboxed bundle, and the loader
registered any recognised hook name without checking permissions. An
untrusted, null-origin plugin could therefore claim `onRenderEmailBody`
and replace the rendered body of any opened email without ever holding
`email:render-takeover` — the permission was enforced only by the
one-time consent dialog, i.e. it gated what the user was *asked*, not
what the host *allowed*.
Add HOOK_PERMISSIONS covering the hooks that can read message content,
alter outgoing mail, or observe key state: render takeover, the three
send-interception hooks, bulk-content hooks, attachment upload, and the
four S/MIME hooks. Hooks absent from the map stay unrestricted (UI
observation, toasts, navigation), so ordinary plugins are unaffected.
Refused hooks fail closed and log the missing permission by name — a
silently inert hook is far harder to diagnose than a refused one.
Export hasPermission() from host-api rather than reimplementing the rule
in the loader, so the hook gate and the RPC gate cannot drift apart.
Remaining ~200 hooks are tracked as B-09.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add optional logoLightUrl/logoDarkUrl to InstalledTheme + resolveThemeLogo()
helper; set logos on vnclagoon + src themes; login page and nav-rail prefer the
active theme's logo, falling back to the global config logo. So switching theme
switches the whole brand. 0 type errors.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Extend the vnclagoon skin: solid navy login card, cyan hairline border, a thin
cyan accent strip on top, soft cyan glow (dark), and an ambient cyan wash behind
the card on the login page. Scoped to the login card's unique class combo.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add builtin-vnclagoon theme (cyan #00D4FF accent on navy #0A0E1A, DM Sans body
+ Syne headings, self-hosted OFL fonts); set as default theme policy; default
mode dark. Add VNCmail wordmark SVGs (on-dark/on-light) + wire logo/company via
k8s secret template. Placeholder wordmark — swap official styleguide SVG.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Self-contained guide: exactly what to deploy (7 objects + image), 3 cluster
values to match against bulwark, copy-paste apply order, verify, update/rollback,
troubleshooting table. Plain kubectl apply (no GitOps).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Bulwark is stateful (local /app/data) — Vercel serverless (read-only fs)
crashes it. Deploy as a container with 4 persistent volumes on microk8s,
alongside bulwark.sandbox.vnc.de. Adds deploy/k8s/ (namespace, pvc, deployment,
service, ingress, secret template, runbook) + rewrites setup doc off Vercel.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Fix contradiction: production branch is main (Vercel default), dev auto-deploys
previews, promote = ff-only merge dev→main on explicit go-live. Upstream synced
into dev, not main.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Remove withMicrofrontends wrap + @vercel/microfrontends dep. Grouping is
organizational (separate Vercel team), not a microfrontends group. App
serves at its own root again (NEXT_PUBLIC_BASE_PATH removed on Vercel).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Wrap next.config with withMicrofrontends; add @vercel/microfrontends.
Served at /mail under the suite shell (via NEXT_PUBLIC_BASE_PATH set on the
Vercel project). Logged in vnc/VNC-CHANGES.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Fork of bulwarkmail/webmail for deploy on Vercel as project vncmail-plus.
Adds vnc/ customization layer (branding, overrides, VNC-CHANGES log),
Vercel env template, and VNCMAIL-SETUP.md runbook. No upstream files touched.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
If you have a large number of tags, getTagCounts would not be able to get the
unread counts because it did not respect maxCallsInRequest, even though the
value was actually read out, it was just ignored. There are also other places
where the limits were not respected.
Batching is now generalized in a helper that also takes maxObjectsInSet, which
also was ignored, into account and is applied to all functions.
In addition, the dev mock now also advertises and enforces the limits, so these
issues can get picked up during development.
Possible closes#699
Possibly closes#399
