feat(addon): build the system add-on against a local backend

Add a `:local` build path that produces the system/built-in add-on (system
id, dev-mode bundle) wired to a locally running Send backend + client, so the
system-add-on code path can be exercised end-to-end against localhost.

- build:dev:system:local / sync:builtin:local / dev:builtin:local scripts set
  ADDON_ENV=local.
- scripts/build.sh, on ADDON_ENV=local, builds in Vite development mode
  (import.meta.env.MODE === 'development' so the frontend probes the local
  backend for storage type and prod Sentry stays off) and forces localhost
  URLs (VITE_SEND_SERVER_URL/CLIENT_URL, stage OIDC) as exported VITE_* vars,
  which Vite's loadEnv prioritizes over the .env prod block. Each is
  overridable inline for different local ports.
- README documents the workflow, that CORS already works (the backend
  auto-allows moz-extension:// origins), and three ways to get past the
  tls-dev-proxy self-signed cert (OS trust + enterprise roots, a persistent
  profile exception, or targeting the plain-HTTP backend on :8080).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: aaspinwall

packages/addon/README.md

@@ -40,6 +40,79 @@ pnpm --filter addon sync:builtin
 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

packages/addon/package.json

@@ -12,19 +12,22 @@
     "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/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,7 +144,7 @@ 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/