Merge branch 'main' into chore/security-patch-jul2026

Author: aaspinwall

packages/addon/README.md

@@ -16,3 +16,117 @@ lerna run build:dev --scope=addon
 This outputs an xpi file at `packages/addon`, you should see something like `tbpro-add-on-0.1.23.xpi`.
 
 You can use this xpi file to install the addon in your Thunderbird for testing.
+
+## Testing as the built-in / system add-on (local comm-central build)
+
+The standalone xpi above runs under the standalone add-on id (`tbpro-add-on@thunderbird.net`).
+To test the add-on the way Thunderbird ships it — as the **built-in / system add-on**
+(id `tbpro-system-add-on@thunderbird.net`, loaded from `resource://builtin-addons/thundermail/`,
+enabled by default, no install flow) — sync a system-id build into a local comm-central checkout and
+rebuild Thunderbird.
+
+The add-on is vendored in comm-central at
+`comm/mail/extensions/builtin-addons/thundermail/extension/` and packaged into `messenger.jar` via
+that directory's `jar.mn`. These scripts refresh that copy from this repo's `dist/`:
+
+```sh
+# Point at your comm-central source root (the dir containing the `comm/` subdir). Required.
+export TB_COMM_SRC=/path/to/your/tb-build/source
+
+# One-shot: build with the system id + rsync into the comm tree
+pnpm --filter addon sync:builtin
+
+# …or watch mode: auto re-syncs on every source change
+pnpm --filter addon dev:builtin
+```
+
+### Pointing the built-in add-on at a local backend
+
+By default a system build bakes in the prod/stage Send hosts from your `.env`. To build the
+**same system add-on** but wired to a locally running Send backend + client, use the `:local`
+variants:
+
+```sh
+# One-shot: system-id build against localhost + rsync into the comm tree
+pnpm --filter addon sync:builtin:local
+
+# …or watch mode
+pnpm --filter addon dev:builtin:local
+
+# (or just build, without syncing)
+pnpm --filter addon build:dev:system:local
+```
+
+These set `ADDON_ENV=local`, which makes `scripts/build.sh` build in Vite's **development** mode
+(so `import.meta.env.MODE === 'development'` — the frontend then probes the local backend for its
+storage type instead of assuming bucket storage, and prod Sentry stays off) and force the localhost
+URLs into the bundle:
+
+- `VITE_SEND_SERVER_URL=https://localhost:8088` (also used for `wss://…/api/ws` uploads)
+- `VITE_SEND_CLIENT_URL=http://localhost:5173`
+- `VITE_OIDC_ROOT_URL=https://auth-stage.tb.pro/realms/tbpro/` (no local Keycloak needed)
+
+They're exported as `VITE_*` process env vars, which Vite's `loadEnv` prioritizes over `.env`, so
+they win over the prod block your `.env` ends with. Override any of them inline if your local ports
+differ, e.g. `VITE_SEND_SERVER_URL=https://localhost:9000 pnpm --filter addon build:dev:system:local`.
+
+**CORS is already handled** — the Send backend auto-allows any `moz-extension://` origin
+(`packages/send/backend/src/origins.ts`), and the built-in/system add-on still runs under a
+`moz-extension://` origin, so its requests pass CORS with no add-on-side change. Just make sure the
+local backend has `SEND_BACKEND_CORS_ORIGINS` set (it throws on startup otherwise) and including
+`http://localhost:5173`.
+
+**The self-signed cert is the real gotcha.** The Send dev stack serves `https://localhost:8088`
+through the tls-dev-proxy (`packages/send/backend/tls-dev-proxy/`) using a self-signed cert.
+Thunderbird's extension `fetch` can't skip cert validation and gets no interactive prompt at
+startup, so an untrusted cert fails the TLS handshake — and Gecko reports that as
+`CORS request did not succeed` with `Status code: (null)` (a misleading message: it is *not* a CORS
+rejection, which would carry a real status and an "Access-Control-Allow-Origin missing" error). Pick
+one of these:
+
+- **Trust the cert at the OS level (recommended — survives `--temp-profile`, keeps `wss` uploads
+  working).** Import the proxy cert into the macOS keychain and enable Gecko's enterprise-roots
+  support per run:
+
+  ```sh
+  sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain \
+    packages/send/backend/tls-dev-proxy/certs/localhost.crt
+  ./mach run --temp-profile --setpref security.enterprise_roots.enabled=true
+  ```
+
+  `enterprise_roots` makes Gecko read the macOS keychain; passing it as a `--setpref` means it
+  applies even to a fresh temp profile.
+
+- **Add a permanent cert exception in a persistent profile.** Thunderbird → Settings → Privacy &
+  Security → Certificates → Manage Certificates → *Servers* → Add Exception → `https://localhost:8088`.
+  Downside: a `--temp-profile` run discards it, which fights the stale-cache advice below — use a
+  named profile (`./mach run -P <profile>`) instead.
+
+- **Skip TLS entirely (fastest; breaks `wss` uploads).** Point the add-on at the plain-HTTP backend
+  on `:8080`. `http://localhost` is a trustworthy secure context in Gecko, so there's no cert and no
+  mixed-content block, and it works with `--temp-profile`:
+
+  ```sh
+  VITE_SEND_SERVER_URL=http://localhost:8080 pnpm --filter addon build:dev:system:local
+  ```
+
+  Caveat: the file-upload WebSocket is hardcoded to `wss://` (`send/frontend/src/lib/helpers.ts`), so
+  uploads fail over plain http; trpc / auth / storage-type / dashboard all work.
+
+Then, in the comm tree, repackage and run:
+
+```sh
+cd "$TB_COMM_SRC"
+./mach build faster      # repackages messenger.jar + regenerates built_in_addons.json
+./mach run --temp-profile  # fresh profile each launch — avoids stale built-in caches
+```
+
+Notes:
+
+- `build:dev:system` rewrites only the built `dist/manifest.json` to the system id (via
+  `scripts/set-system-id.ts`); the source `public/manifest.json` keeps the standalone id.
+- The absolute `url(/fonts/...)` → relative rewrite that the built-in CSS needs (Bug 2036665) is
+  already handled by `scripts/build.sh`, so the synced build passes Thunderbird's
+  `browser_parsable_css.js` static check.
+- Use `--temp-profile` after rebuilds; a stale `addonStartup.json.lz4` / startup cache can otherwise
+  drop or mis-resolve the built-in (Bugs 1651838 / 1964408).

packages/addon/package.json

@@ -1,6 +1,6 @@
 {
   "name": "addon",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "private": false,
   "description": "",
   "keywords": [],
@@ -11,17 +11,23 @@
   "scripts": {
     "build": "NODE_ENV=production ./scripts/build.sh",
     "build:dev": "./scripts/build.sh",
+    "build:dev:system": "ADDON_VARIANT=system ./scripts/build.sh",
+    "build:dev:system:local": "ADDON_VARIANT=system ADDON_ENV=local ./scripts/build.sh",
     "build:dev:watch": "nodemon -e vue,ts,js,json --ignore 'dist*/' --ignore manifest.json --watch './{src,public}/**/*' --watch '../send/frontend/src/**/*' --exec 'pnpm build:dev'",
     "build:watch": "nodemon -e vue,ts,js,json --watch './{src,public}/**/*' --exec 'pnpm build'",
     "ci:validate": "pnpm lint:all; pnpm prettier:all; pnpm run test",
     "deploy-xpi": "bun run ./scripts/deploy_xpi.ts",
     "dev": "vite --host",
+    "dev:builtin": "nodemon -e vue,ts,js,json --ignore 'dist*/' --ignore manifest.json --watch './{src,public}/**/*' --watch '../send/frontend/src/**/*' --exec 'pnpm sync:builtin'",
+    "dev:builtin:local": "nodemon -e vue,ts,js,json --ignore 'dist*/' --ignore manifest.json --watch './{src,public}/**/*' --watch '../send/frontend/src/**/*' --exec 'pnpm sync:builtin:local'",
     "lint:all": "pnpx eslint 'src/**/*.{ts,vue,js}' 'public/api/**/*.js' --fix",
     "prettier:all": "prettier --write .",
     "preview": "vite preview",
     "release": "./scripts/release.sh",
     "setup": "./scripts/setup.sh",
     "sort-package-json": "sort-package-json",
+    "sync:builtin": "pnpm build:dev:system && ./scripts/sync-to-builtin.sh",
+    "sync:builtin:local": "pnpm build:dev:system:local && ./scripts/sync-to-builtin.sh",
     "test": "VITE_TESTING=true vitest run --silent",
     "test:watch": "VITE_TESTING=true vitest --watch",
     "test-debug": "VITE_TESTING=true vitest --inspect-brk --single-thread",

packages/addon/public/manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest_version": 2,
-  "version": "2.0.1",
+  "version": "2.0.2",
   "author": "Thunderbird Team",
   "name": "__MSG_thunderbirdPro__",
   "description": "__MSG_extensionDescription__",

packages/addon/scripts/build.sh

@@ -7,6 +7,50 @@ else
     echo 'Starting development build 🐣'
 fi
 
+# Optional Vite mode forwarded to every `vite build`. Empty by default so the
+# existing builds keep running in Vite's default production mode.
+MODE_ARG=""
+
+### Local backend target (ADDON_ENV=local, via build:dev:system:local).
+### Points the bundle at a locally running Send backend + client instead of the
+### prod/stage hosts baked into the developer's .env.
+if [ "$ADDON_ENV" = "local" ]; then
+    echo 'Targeting local backend (localhost) 🏠'
+    ### Vite `build` defaults to production mode regardless of NODE_ENV. Force
+    ### development so import.meta.env.MODE === 'development': that makes the
+    ### frontend probe the local backend for its storage type (api.ts), sets
+    ### IS_DEV, and keeps prod Sentry off (sentry.ts). Production mode would
+    ### instead assume bucket storage and skip that probe.
+    MODE_ARG="--mode development"
+
+    ### Force localhost URLs. Exported so Vite's loadEnv reads them from
+    ### process.env, where VITE_* vars take precedence over the .env file — whose
+    ### prod block (send.tb.pro / send-backend.tb.pro) would otherwise win via
+    ### last-key-wins. Assigned with := so a developer can still override any of
+    ### them inline (e.g. a different local port) before invoking the build.
+    : "${VITE_SEND_SERVER_URL:=https://localhost:8088}"
+    : "${VITE_SEND_CLIENT_URL:=http://localhost:5173}"
+    ### No local Keycloak: authenticate against the stage identity provider.
+    : "${VITE_OIDC_CLIENT_ID:=desktop}"
+    : "${VITE_OIDC_ROOT_URL:=https://auth-stage.tb.pro/realms/tbpro/}"
+    ### Keep local builds out of the shared Sentry / PostHog projects.
+    : "${VITE_SENTRY_DSN:=}"
+    : "${VITE_POSTHOG_PROJECT_KEY:=}"
+    export VITE_SEND_SERVER_URL VITE_SEND_CLIENT_URL \
+        VITE_OIDC_CLIENT_ID VITE_OIDC_ROOT_URL \
+        VITE_SENTRY_DSN VITE_POSTHOG_PROJECT_KEY
+
+    echo "  VITE_SEND_SERVER_URL=$VITE_SEND_SERVER_URL"
+    echo "  VITE_SEND_CLIENT_URL=$VITE_SEND_CLIENT_URL"
+    echo "  VITE_OIDC_ROOT_URL=$VITE_OIDC_ROOT_URL"
+    ### CORS: the Send backend auto-allows any moz-extension:// origin
+    ### (origins.ts), and the built-in/system add-on still runs under a
+    ### moz-extension:// origin, so its requests pass CORS unchanged. The local
+    ### backend must still have SEND_BACKEND_CORS_ORIGINS set (it throws
+    ### otherwise) and include $VITE_SEND_CLIENT_URL, and Thunderbird must trust
+    ### the self-signed https://localhost cert (used for fetch + wss uploads).
+fi
+
 # Get version from package.json and replace dots with hyphens
 VERSION=$(jq -r .version < package.json | sed 's/\./-/g')
 
@@ -36,7 +80,7 @@ node scripts/subset-fonts.mjs
 echo "================================================================"
 echo "=============== extension UI ==================================="
 ### Extension UI
-vite build --config vite.config.extension.js
+vite build --config vite.config.extension.js $MODE_ARG
 cp -R dist/extension/assets/* dist/assets/
 cp -R dist/extension/*.* dist/
 if [ -d dist/extension/chunks ]; then
@@ -48,7 +92,7 @@ rm -rf dist/extension
 echo "================================================================"
 echo "=============== management page================================="
 ### Management page, commenting out for now
-vite build --config vite.config.management.js
+vite build --config vite.config.management.js $MODE_ARG
 cp -R dist/pages/assets/* dist/assets/
 cp -R dist/pages/*.* dist/
 if [ -d dist/pages/chunks ]; then
@@ -100,14 +144,30 @@ find dist/assets -name '*.css' -exec perl -pi -e \
 echo "================================================================"
 echo "=============== background.js =================================="
 ### Build `background.js` as a library
-vite build --config vite.config.background.js
+vite build --config vite.config.background.js $MODE_ARG
 cp -R dist/background/* dist/
 # cp -R dist/background/*.map dist/f
 # cp -R dist/background/manifest.json dist/
 rm -rf dist/background
 
 rm -rf dist/pages
 
+### When building the system/built-in add-on variant (ADDON_VARIANT=system),
+### rewrite the built dist manifest's prod id to the system add-on id
+### (tbpro-system-add-on@thunderbird.net) so the local build matches the id
+### Thunderbird ships it under and exercises the id-keyed runtime guards
+### (installGate.ts / selfUninstall.ts). Operates on the built copy only — the
+### source public/manifest.json keeps the prod id. Reuses set-system-id.ts, the
+### same script CI uses when repacking the system XPI.
+if [ "$ADDON_VARIANT" = "system" ]; then
+    echo "================================================================"
+    echo "=============== system add-on id ==============================="
+    ### --allow-stage: a dev build's dist manifest carries the STAGE id (set-id.ts
+    ### only runs for prod), so accept STAGE too. CI's prod-XPI repack omits the
+    ### flag and keeps its strict PROD-only guard.
+    bun run scripts/set-system-id.ts dist/manifest.json --allow-stage
+fi
+
 cd dist
 # Create xpi with version number
 zip -r -FS ../tbpro-addon-${VERSION}.xpi *

packages/addon/scripts/set-system-id.ts

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { pathToFileURL } from 'url';
 
-import { ADDON_ID_PROD, ADDON_ID_SYSTEM } from '../src/addonIds';
+import { ADDON_ID_PROD, ADDON_ID_STAGE, ADDON_ID_SYSTEM } from '../src/addonIds';
 
 /**
  * Rewrite a built add-on manifest's production id to the built-in/system add-on
@@ -13,18 +13,42 @@ import { ADDON_ID_PROD, ADDON_ID_SYSTEM } from '../src/addonIds';
  * Throws if the production id is not present, so a manifest that can't be
  * rewritten fails loudly instead of silently shipping a non-system XPI.
  *
- * Usage: bun run scripts/set-system-id.ts <path/to/manifest.json>
+ * `allowStage` relaxes this for local built-in testing only: a plain dev build
+ * (scripts/build.sh with no NODE_ENV) copies the source public/manifest.json,
+ * which carries the STAGE id, so the local `build:dev:system` flow has no PROD
+ * id to rewrite. With `allowStage` the STAGE id is also accepted and a manifest
+ * already on the system id is a no-op (dev rebuilds re-run this). CI never sets
+ * it, so the prod-XPI repack keeps its strict PROD-only guard.
+ *
+ * Usage: bun run scripts/set-system-id.ts <path/to/manifest.json> [--allow-stage]
  * Defaults to this package's public/manifest.json when no path is given.
  */
-export function setSystemId(manifestPath: string): void {
+export function setSystemId(
+  manifestPath: string,
+  { allowStage = false }: { allowStage?: boolean } = {}
+): void {
   const before = fs.readFileSync(manifestPath, 'utf8');
-  const after = before
+  let after = before
     .split(`"id": "${ADDON_ID_PROD}"`)
     .join(`"id": "${ADDON_ID_SYSTEM}"`);
+  if (allowStage) {
+    after = after
+      .split(`"id": "${ADDON_ID_STAGE}"`)
+      .join(`"id": "${ADDON_ID_SYSTEM}"`);
+  }
 
   if (after === before) {
+    // Local dev rebuilds re-run this on a dist manifest that may already carry
+    // the system id; treat that as success rather than failing the build.
+    if (allowStage && before.includes(`"id": "${ADDON_ID_SYSTEM}"`)) {
+      console.log(`Manifest ${manifestPath} already on the system add-on id`);
+      return;
+    }
+    const ids = allowStage
+      ? `prod id "${ADDON_ID_PROD}" or stage id "${ADDON_ID_STAGE}"`
+      : `prod id "${ADDON_ID_PROD}"`;
     throw new Error(
-      `Could not find prod id "${ADDON_ID_PROD}" in ${manifestPath}; ` +
+      `Could not find ${ids} in ${manifestPath}; ` +
         `manifest not rewritten to the system add-on id.`
     );
   }
@@ -42,10 +66,13 @@ function isInvokedDirectly(): boolean {
 }
 
 if (isInvokedDirectly()) {
+  const cliArgs = process.argv.slice(2);
+  const allowStage = cliArgs.includes('--allow-stage');
   const manifestPath =
-    process.argv[2] ?? path.resolve(__dirname, '../public/manifest.json');
+    cliArgs.find((arg) => !arg.startsWith('--')) ??
+    path.resolve(__dirname, '../public/manifest.json');
   try {
-    setSystemId(manifestPath);
+    setSystemId(manifestPath, { allowStage });
   } catch (error) {
     console.error('Failed to set system add-on id:', error);
     process.exit(1);

packages/addon/scripts/sync-to-builtin.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+#
+# Sync a built (system-id) dist/ into a local comm-central checkout's vendored
+# built-in add-on directory, so the add-on can be tested as the real built-in /
+# system add-on (loaded under resource://builtin-addons/thundermail/, enabled by
+# default, no install flow).
+#
+# The add-on is vendored in comm-central at
+#   comm/mail/extensions/builtin-addons/thundermail/extension/
+# and packaged into messenger.jar via that dir's jar.mn. This script refreshes
+# that copy from this repo's dist/, then you rebuild + run from the comm tree:
+#
+#   export TB_COMM_SRC=/path/to/your/tb-build/source
+#   pnpm --filter addon sync:builtin            # build (system id) + sync
+#   cd "$TB_COMM_SRC" && ./mach build faster    # repackage messenger.jar
+#   ./mach run --temp-profile                   # fresh profile avoids stale builtin cache
+#
+# Run `pnpm --filter addon dev:builtin` to auto-sync on every source change.
+#
+# Requires TB_COMM_SRC to point at the comm-central source root (the dir that
+# contains the `comm/` subdir). No default — there can be several build trees.
+
+set -euo pipefail
+
+if [ -z "${TB_COMM_SRC:-}" ]; then
+  echo "ERROR: TB_COMM_SRC is not set." >&2
+  echo "  Set it to your comm-central source root, e.g.:" >&2
+  echo "  export TB_COMM_SRC=/Users/you/WebApps/tb-build/source" >&2
+  exit 1
+fi
+
+DEST="$TB_COMM_SRC/comm/mail/extensions/builtin-addons/thundermail/extension"
+
+if [ ! -d "$DEST" ]; then
+  echo "ERROR: vendored add-on dir not found:" >&2
+  echo "  $DEST" >&2
+  echo "  Check TB_COMM_SRC ('$TB_COMM_SRC') points at the comm-central source root" >&2
+  echo "  and that the thundermail built-in add-on is present in that tree." >&2
+  exit 1
+fi
+
+# scripts/ lives in packages/addon, so dist/ is one level up from here.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DIST="$SCRIPT_DIR/../dist"
+
+if [ ! -f "$DIST/manifest.json" ]; then
+  echo "ERROR: $DIST/manifest.json not found — run the build first (pnpm build:dev:system)." >&2
+  exit 1
+fi
+
+# Guard: the synced build must carry the system add-on id, otherwise the
+# built-in would run under the wrong identity and the id-keyed guards wouldn't
+# be exercised. sync:builtin runs build:dev:system, which sets this.
+if ! grep -q "tbpro-system-add-on@thunderbird.net" "$DIST/manifest.json"; then
+  echo "ERROR: $DIST/manifest.json does not contain the system add-on id." >&2
+  echo "  Build with the system variant: pnpm build:dev:system" >&2
+  exit 1
+fi
+
+echo "Syncing $DIST/ -> $DEST/"
+# --delete so files removed from the build don't linger in the vendored copy.
+rsync -a --delete "$DIST/" "$DEST/"
+
+echo "Synced. Now: cd \"\$TB_COMM_SRC\" && ./mach build faster && ./mach run --temp-profile"