rsc-universal 0.1.1

package/skills/e2e-testing/scripts/verify.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+#
+# verify.sh - read-only static lint for emitted Playwright test/config text.
+#
+# Usage:
+#   /path/to/verify.sh [TARGET_DIR]   # defaults to .
+#
+# Greps the produced .ts/.js/.mjs/.cts test+config text for this skill's banlist.
+# NO browser run, NO network, NO writes. Pure string checks.
+#
+# Banlist (each is a flake/anti-pattern this skill teaches against):
+#   1. waitForTimeout(            -> sleep-based wait
+#   2. xpath= or raw // locators  -> brittle XPath
+#   3. page.$(  / page.$$(        -> legacy element handles over locators
+#   4. expect(await              -> read-once assertion smell
+#   5. a playwright.config.* that lacks BOTH `trace` and `retries`
+#
+# Exit codes: 0 = clean OR nothing to check (empty/clean target);
+#             1 = a banned pattern was found.
+
+set -euo pipefail
+
+target="${1:-.}"
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+
+if [ ! -d "$target" ]; then
+  printf '%serror:%s target dir not found: %s\n' "$RED" "$RESET" "$target" >&2
+  exit 2
+fi
+
+# Count candidate source files up front so an empty/clean target exits cleanly.
+# Skip node_modules and Playwright's own output/report dirs - lint authored code only.
+find_sources() {
+  find "$target" \
+    \( -name node_modules -o -name '.git' -o -name 'playwright-report' \
+       -o -name 'blob-report' -o -name 'test-results' \) -prune -o \
+    -type f \( -name '*.ts' -o -name '*.js' -o -name '*.mjs' -o -name '*.cts' \) -print0 \
+    2>/dev/null
+}
+
+if [ "$(find_sources | tr -dc '\0' | wc -c)" -eq 0 ]; then
+  skip "no .ts/.js test or config files under $target - nothing to lint (clean pass)"
+  exit 0
+fi
+
+failed=0
+checked=0
+
+# grep -n on a single file; report each hit indented. Returns 0 if a hit found.
+flag() { # $1 = pattern (fixed string), $2 = file, $3 = message
+  local hits
+  hits=$(grep -nF -- "$1" "$2" 2>/dev/null || true)
+  if [ -n "$hits" ]; then
+    fail "$3 in $2"
+    printf '%s\n' "$hits" | sed 's/^/        /'
+    failed=1
+  fi
+}
+
+# Regex variant (for XPath // and page.$/$$ shapes).
+flag_re() { # $1 = ERE pattern, $2 = file, $3 = message
+  local hits
+  hits=$(grep -nE -- "$1" "$2" 2>/dev/null || true)
+  if [ -n "$hits" ]; then
+    fail "$3 in $2"
+    printf '%s\n' "$hits" | sed 's/^/        /'
+    failed=1
+  fi
+}
+
+while IFS= read -r -d '' file; do
+  checked=$((checked + 1))
+
+  # 1. sleep-based waits
+  flag 'waitForTimeout(' "$file" "waitForTimeout (sleep-based wait)"
+
+  # 2. XPath: explicit xpath= engine, or a locator string beginning with //
+  flag 'xpath=' "$file" "xpath= locator engine"
+  flag_re "(locator|getByTestId|click|fill)\([\"'\`]//" "$file" "raw // XPath locator"
+
+  # 3. legacy element handles
+  flag_re "page\.\\\$\\\$?\(" "$file" "page.\$ / page.\$\$ element handle (use locators)"
+
+  # 4. read-once assertion smell
+  flag 'expect(await ' "$file" "expect(await ...) read-once assertion"
+
+  # 5. config files must declare both trace and retries
+  case "$file" in
+    *playwright.config.*)
+      has_trace=$(grep -c 'trace' "$file" 2>/dev/null || true)
+      has_retries=$(grep -c 'retries' "$file" 2>/dev/null || true)
+      if [ "${has_trace:-0}" -eq 0 ] || [ "${has_retries:-0}" -eq 0 ]; then
+        fail "playwright config missing trace and/or retries: $file"
+        failed=1
+      else
+        ok "config declares trace + retries: $file"
+      fi
+      ;;
+  esac
+done < <(find_sources)
+
+if [ "$failed" -ne 0 ]; then
+  printf '%sverify failed:%s banned Playwright anti-patterns above.%s\n' "$RED" "$RESET" "$RESET" >&2
+  exit 1
+fi
+
+printf '%s[ ok ] %d file(s) lint clean - no banned e2e anti-patterns.%s\n' "$GREEN" "$checked" "$RESET"
+exit 0

package/skills/electron/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: electron
+description: "Use when building, hardening, or shipping a cross-platform desktop app with Electron — wiring the main/renderer/preload process model, exposing OS capabilities to a web UI over typed IPC, locking down an insecure shell, or packaging with code signing and auto-update. Triggers: 'build a desktop app for Mac/Windows/Linux from my web app', 'let my renderer read a file safely', 'audit my Electron security (nodeIntegration, sandbox, CSP)', 'my preload exposes ipcRenderer and the renderer can require(\"fs\")', 'Squirrel.Mac won\\'t auto-update my app', 'migrate off @electron/remote and BrowserView', 'empaquetar mi app de escritorio para Windows y Mac con firma de código y auto-actualización', 'empaquetar app d\\'escriptori amb auto-actualització'. NOT a smaller Rust-backed shell on the OS native webview (that is tauri)."
+tags: [electron, desktop, ipc, security, packaging, auto-update, code-signing]
+recommends: [tauri, react, nodejs, github-actions, secure-coding]
+origin: risco
+---
+
+# Electron — desktop shell, typed IPC, hardening, signing
+
+> Build, harden, and ship cross-platform desktop apps. Treat the renderer as hostile
+> territory and the IPC channel as an attack surface — that is the dominant failure mode
+> in real Electron apps, so the whole skill is organized around it.
+
+This skill owns the **desktop shell**: process model, IPC, security, packaging, signing,
+auto-update. It does **not** own the web UI inside the window (`../react/SKILL.md` if it
+existed), the Node backend logic, or the CI runner matrix.
+
+## The mental model — three processes, one rule
+
+An Electron app is three kinds of process. Code lives in exactly one; putting it in the
+wrong one is the root cause of most security holes.
+
+| Process  | Runtime              | Trust         | One per | Does                                              |
+|----------|----------------------|---------------|---------|---------------------------------------------------|
+| main     | Node.js, full OS API | trusted       | app     | windows, menus, tray, dialogs, fs, child procs    |
+| renderer | Chromium, no Node    | **untrusted** | window  | your web UI; can run attacker JS if you load remote content |
+| preload  | isolated world, runs before page JS | semi-trusted | window | the **only** bridge: `contextBridge` exposes a tiny API |
+
+**The governing rule: the renderer is untrusted, the main process holds all privilege, and
+the preload is the only sanctioned bridge between them.** Everything below is a corollary.
+
+## Start right
+
+Scaffold with **Electron Forge** (`@electron/forge`) — first-party, all-in-one
+(scaffold → package → make → publish), and it gets new Electron features first.
+
+```bash
+npm init electron-app@latest my-app -- --template=vite-typescript
+cd my-app && npm start
+```
+
+**Pin to a supported major.** Electron ships a new major every 8 weeks (tracking Chromium)
+and supports only the **latest 3 majors**. As of June 2026 the stable line is **Electron 42**
+(Chromium M148, Node 24); 43 lands 2026-06-30. Shipping on an EOL major means unpatched
+Chromium CVEs — check `package.json` and bump if behind.
+
+Project layout keeps the boundary visible:
+
+```text
+src/
+  main.ts       # main process — owns everything privileged
+  preload.ts    # the bridge — contextBridge only
+  renderer/     # your web UI (untrusted)
+  ipc/types.ts  # IPC contract shared by main + preload
+```
+
+## The security baseline — non-negotiable
+
+Modern Electron defaults are already secure (`nodeIntegration:false`,
+`contextIsolation:true`, `sandbox:true` since Electron 20). **Assert them explicitly anyway**
+so a careless edit can't silently weaken the window:
+
+```ts
+const win = new BrowserWindow({
+  webPreferences: {
+    preload: path.join(__dirname, 'preload.js'),
+    nodeIntegration: false,        // renderer gets NO require/process — never flip true
+    contextIsolation: true,        // preload + page run in separate JS worlds
+    sandbox: true,                 // renderer in an OS sandbox; preload uses a limited API
+    webSecurity: true,             // keep same-origin policy; never disable to "fix CORS"
+    allowRunningInsecureContent: false, // no mixed http content on https pages
+  },
+});
+```
+
+One why per flag: each removes a documented way for renderer-side script to reach Node or
+the OS. Flipping any of them to the insecure value is what `verify.sh` fails on.
+
+**CSP via response headers, not a `<meta>` tag** — meta CSP can't restrict the initial
+document and is trivially bypassed for some directives. Set it in the main process:
+
+```ts
+session.defaultSession.webRequest.onHeadersReceived((details, cb) => {
+  cb({ responseHeaders: { ...details.responseHeaders,
+    'Content-Security-Policy': ["default-src 'self'; script-src 'self'"] } });
+});
+```
+
+**Lock navigation.** A renderer that can navigate to attacker content gets the renderer's
+privileges. Deny unexpected navigation and block new windows:
+
+```ts
+app.on('web-contents-created', (_e, contents) => {
+  contents.on('will-navigate', (e, url) => {
+    if (new URL(url).origin !== 'https://app.local') e.preventDefault();
+  });
+  contents.setWindowOpenHandler(() => ({ action: 'deny' })); // no tab-jacking
+});
+```
+
+Open real external links deliberately, after allow-listing the protocol:
+
+```ts
+function openExternal(url: string) {
+  const { protocol } = new URL(url);
+  if (protocol === 'https:' || protocol === 'mailto:') shell.openExternal(url);
+}
+```
+
+**Which branch are you on?**
+
+- **Local-only UI** (you bundle the HTML/JS): CSP + `sandbox:true` + nav lockdown is enough.
+- **Loads any remote/third-party content**: also add Electron Fuses (disable run-as-node,
+  encrypt cookies, ASAR integrity) and treat every embedded origin as hostile.
+
+Fuses and the full hardened example live in `references/security-and-ipc.md`.
+
+## Typed IPC the right way
+
+IPC is the seam between untrusted renderer and privileged main. Get it wrong and you've
+handed the OS to whatever script runs in the page.
+
+**Never expose `ipcRenderer` (or any of its methods) across the bridge.** Sending the whole
+module now yields an *empty object* on the other side — a deliberate footgun removal — and
+exposing its methods lets the page call any channel with any payload.
+
+```ts
+// Bad — preload.ts: hands the renderer a universal IPC weapon (also: empty object now)
+contextBridge.exposeInMainWorld('api', ipcRenderer);
+```
+
+```ts
+// Good — preload.ts: ONE function per channel, each wrapping a specific call
+import { contextBridge, ipcRenderer } from 'electron';
+contextBridge.exposeInMainWorld('api', {
+  readConfig: () => ipcRenderer.invoke('config:read'),
+  saveNote: (text: string) => ipcRenderer.invoke('note:save', text),
+  onSync: (cb: () => void) => ipcRenderer.on('sync:done', cb), // events: send/on
+});
+```
+
+**Prefer `ipcMain.handle` + `ipcRenderer.invoke`** (request/response, returns a Promise) for
+anything that returns data. Reserve `send`/`on` for fire-and-forget events (progress, push
+notifications). **Validate every argument in main** — a renderer message is an HTTP request
+from an untrusted client:
+
+```ts
+ipcMain.handle('note:save', (_e, text: unknown) => {
+  if (typeof text !== 'string' || text.length > 10_000) throw new Error('bad input');
+  return saveNote(text); // never path.join(userInput) or eval it
+});
+```
+
+Share the contract as TypeScript types across both sides (`ipc/types.ts`) so a channel
+rename breaks the build, not production. Full main + preload + `window.api` d.ts example:
+`references/security-and-ipc.md`.
+
+## Native capabilities — renderer asks, main acts
+
+The renderer can't (and must not) touch the OS directly. When the UI needs a native menu,
+tray icon, file dialog, system notification, custom `protocol://` handler, or a
+`child_process`, the renderer **invokes an IPC channel** and the **main process performs the
+action** and returns a result. Same one-function-per-channel discipline as above.
+
+For embedding web content in a region of a window, use **`WebContentsView`** —
+`BrowserView` is deprecated since Electron 30. They share shape (both take `webPreferences`;
+`setBounds`/`getBounds`/`webContents` carry over), so migration is mechanical.
+
+## Packaging, signing, auto-update
+
+Two real toolchains:
+
+| Need                                            | Use              |
+|-------------------------------------------------|------------------|
+| New app, first-party alignment, features first  | **Electron Forge** (ASAR integrity, universal macOS, scaffold→make→publish) |
+| Differential/staged updates, multi-provider (GitHub/S3), richer config | **electron-builder** + `electron-updater` |
+
+**Code signing is a prerequisite for auto-update, not optional polish.** macOS auto-update
+(Squirrel.Mac) **refuses** to update an app that isn't signed *and* notarized; Windows
+updates need an Authenticode-signed installer. So the order is always: sign → notarize →
+publish → auto-update. Full Forge and builder configs, notarytool steps, Windows
+Authenticode, and `electron-updater` + GitHub Releases wiring: `references/packaging-and-updates.md`.
+
+The CI matrix that *runs* these builds across three OSes is `github-actions`' job; this skill
+defines *what* to build and sign.
+
+## Migration smells — and the fix
+
+| Smell in the code                          | Why it's dangerous                          | Fix                                              |
+|--------------------------------------------|---------------------------------------------|--------------------------------------------------|
+| `nodeIntegration: true`                    | Page JS gets `require('fs')`, full Node     | Set `false`; move the capability behind IPC      |
+| `contextIsolation: false`                  | Page can rewrite the preload's globals      | Set `true` (default)                             |
+| `@electron/remote` import                  | Sync main-object access = renderer→main RCE | Replace with explicit `ipcMain.handle` channels  |
+| `new BrowserView(...)`                     | Deprecated since 30, will be removed        | `new WebContentsView(...)`                        |
+| `exposeInMainWorld('api', ipcRenderer)`    | Universal IPC weapon (empty object now)     | One function per channel                          |
+
+## Anti-patterns
+
+| Anti-pattern                                          | Why it's wrong                                              | Do instead                                            |
+|-------------------------------------------------------|------------------------------------------------------------|-------------------------------------------------------|
+| `nodeIntegration: true`                               | Any XSS in the renderer becomes OS-level RCE               | `false` + IPC for every privileged op                 |
+| `contextIsolation: false`                             | Renderer can tamper with preload internals                 | `true` (the default)                                  |
+| `sandbox: false` without a reason                     | Drops the OS sandbox around the renderer                   | `true`; only relax for a measured, isolated need      |
+| Exposing `ipcRenderer`/its methods over the bridge    | Page can call any channel with any payload                 | One typed function per channel                        |
+| No arg validation in `ipcMain.handle`                 | Renderer is an untrusted client; you trust its input       | Type-check + bound every arg before acting            |
+| `webSecurity: false` to "fix CORS"                    | Disables same-origin policy app-wide                       | Keep `true`; proxy/handle CORS in main                |
+| CSP only in a `<meta>` tag                            | Doesn't cover the initial document; bypassable             | Set CSP in `onHeadersReceived`                         |
+| Loading a remote URL into a Node-enabled window       | Remote site runs with your app's privilege                 | Bundle UI locally; sandbox + nav lockdown for remote  |
+| Auto-update with an unsigned/un-notarized build       | Squirrel.Mac silently refuses; no updates ship             | Sign + notarize (mac), Authenticode (win) first       |
+| Shipping on an EOL Electron major                     | Unpatched Chromium CVEs in your users' hands               | Stay within the latest 3 majors                       |
+| Heavy CPU work in the main process                    | Blocks the event loop → the whole UI freezes               | `utilityProcess`/worker, or do it in the renderer     |
+| Keeping `@electron/remote`                             | A known renderer→main escalation path                      | Migrate to explicit IPC                               |
+
+## Verify
+
+Run `scripts/verify.sh /path/to/your-electron-project` to grep a target for insecure
+patterns (`nodeIntegration: true`, `contextIsolation: false`, `sandbox: false`,
+`@electron/remote`, `new BrowserView`, `exposeInMainWorld(..., ipcRenderer)`). It's read-only
+and exits non-zero on any finding. With no argument it self-checks this skill's own example
+snippets for the secure baseline. See `references/security-and-ipc.md` for the full checklist.

package/skills/electron/evals/README.md

@@ -0,0 +1,13 @@
+# electron evals
+
+`cases.yaml` is the source of truth. There is no fully automated runner: triggering and
+capability are graded **semantically** by an agent harness (an agent with the catalog's sibling
+names available for routing) plus a human or judge-agent spot-check, because "did it route to
+tauri" and "did it set the secure baseline" are intent judgments, not string matches. For
+triggering, feed each `should_trigger` / `should_not_trigger` prompt to a fresh session 3–5
+times and record whether the electron skill fires (and, for near-misses, whether it hands off to
+the named `route_to` sibling). For capability, answer each scenario once with the skill and once
+without, then score against its `must_include` rubric — the skill passes only if the with-skill
+answer covers the rubric and clearly beats the baseline. The one mechanical check is
+`scripts/verify.sh`: run it against any code the capability case produces to confirm the
+hardening is real (it exits non-zero on any insecure pattern).

package/skills/electron/evals/cases.yaml

@@ -0,0 +1,38 @@
+skill: electron
+
+should_trigger:
+  - prompt: "Build a desktop app for Mac and Windows from this web UI with Electron."
+    why: "Cross-platform desktop shell from web UI is core Electron."
+  - prompt: "Let my Electron renderer read a file safely."
+    why: "Safe OS capability exposure through preload/IPC belongs here."
+  - prompt: "Audit my Electron security: nodeIntegration, sandbox, CSP and preload."
+    why: "Electron security baseline is a central responsibility."
+  - prompt: "Package my Electron app with code signing and auto-update."
+    why: "Packaging, signing and auto-update are Electron shipping concerns."
+  - prompt: "Mi preload expone ipcRenderer y el renderer puede require('fs')."
+    why: "Spanish Electron preload/renderer security hole triggers this skill."
+
+should_not_trigger:
+  - prompt: "Build a smaller Rust-backed desktop shell with native webview."
+    route_to: "tauri"
+    why: "Tauri is explicitly not Electron."
+  - prompt: "Fix this React component state bug in the renderer UI."
+    route_to: "react"
+    why: "Renderer UI framework bugs are not Electron shell concerns."
+  - prompt: "Write a Node CLI script."
+    route_to: "nodejs"
+    why: "Pure Node.js scripting has no Electron process model."
+  - prompt: "Set up GitHub Actions matrix for releases."
+    route_to: "github-actions"
+    why: "CI workflow mechanics are a separate skill, though Electron may inform requirements."
+
+capability:
+  - scenario: "A user has an Electron renderer with nodeIntegration true and wants file access plus auto-update."
+    must_include:
+      - "Explains main/renderer/preload process boundaries and treats renderer as untrusted."
+      - "Keeps nodeIntegration false, contextIsolation true and sandbox true."
+      - "Exposes a narrow typed API through contextBridge in preload."
+      - "Routes privileged file operations through validated IPC to the main process."
+      - "Avoids exposing raw ipcRenderer or fs to the renderer."
+      - "Mentions packaging/signing/auto-update requirements separately from app code."
+      - "Flags supported Electron major/security patch posture."

package/skills/electron/references/packaging-and-updates.md

@@ -0,0 +1,122 @@
+# Packaging, signing & auto-update
+
+Two toolchains. **Electron Forge** is first-party and feature-first; **electron-builder** has
+the richer update/config surface via `electron-updater`. Pick one — don't mix.
+
+## Decision
+
+| You want…                                                       | Pick             |
+|-----------------------------------------------------------------|------------------|
+| New app, first-party alignment, newest Electron features first   | Electron Forge   |
+| ASAR integrity + universal macOS out of the box                  | Electron Forge   |
+| Differential downloads, staged rollouts, multi-provider feeds    | electron-builder |
+| The deepest config surface for exotic installer needs            | electron-builder |
+
+## Electron Forge config (`forge.config.ts`)
+
+```ts
+import type { ForgeConfig } from '@electron/forge-shared-types';
+import { MakerSquirrel } from '@electron-forge/maker-squirrel';   // Windows
+import { MakerDMG } from '@electron-forge/maker-dmg';             // macOS
+import { MakerDeb } from '@electron-forge/maker-deb';             // Linux
+import { PublisherGithub } from '@electron-forge/publisher-github';
+import { FusesPlugin } from '@electron-forge/plugin-fuses';
+import { FuseV1Options, FuseVersion } from '@electron/fuses';
+
+const config: ForgeConfig = {
+  packagerConfig: {
+    asar: true,
+    osxUniversal: { mergeASARs: true }, // single binary for Intel + Apple Silicon
+    osxSign: { identity: 'Developer ID Application: Your Co (TEAMID)' },
+    osxNotarize: {
+      appleId: process.env.APPLE_ID!,
+      appleIdPassword: process.env.APPLE_APP_PASSWORD!, // app-specific password
+      teamId: process.env.APPLE_TEAM_ID!,
+    },
+  },
+  makers: [new MakerSquirrel({}), new MakerDMG({}), new MakerDeb({})],
+  publishers: [
+    new PublisherGithub({ repository: { owner: 'you', name: 'my-app' } }),
+  ],
+  plugins: [
+    new FusesPlugin({
+      version: FuseVersion.V1,
+      [FuseV1Options.RunAsNode]: false,
+      [FuseV1Options.EnableCookieEncryption]: true,
+      [FuseV1Options.OnlyLoadAppFromAsar]: true,
+    }),
+  ],
+};
+export default config;
+```
+
+```bash
+npm run make      # build installers for the current OS
+npm run publish   # build + upload to the configured publisher
+```
+
+## electron-builder config (`electron-builder.yml`) + updater
+
+```yaml
+appId: com.yourco.myapp
+asar: true
+mac:
+  hardenedRuntime: true
+  gatekeeperAssess: false
+  notarize: true            # builder calls notarytool for you
+win:
+  target: nsis
+  signtoolOptions:
+    sign: ./scripts/sign.js # Authenticode signing hook
+publish:
+  provider: github
+  owner: you
+  repo: my-app
+  releaseType: release
+```
+
+```ts
+// main.ts — auto-update via electron-updater (pairs with electron-builder)
+import { autoUpdater } from 'electron-updater';
+
+app.whenReady().then(() => {
+  autoUpdater.checkForUpdatesAndNotify(); // checks the GitHub Releases feed
+});
+autoUpdater.on('update-downloaded', () => autoUpdater.quitAndInstall());
+```
+
+Staged rollout: publish `latest.yml` with a `stagingPercentage` so only a fraction of clients
+pick up the new version until you're confident, then raise it.
+
+## macOS signing + notarization
+
+1. **Sign** with a *Developer ID Application* certificate and the hardened runtime enabled.
+2. **Notarize** the signed app with `notarytool` (Apple scans it for malware):
+   ```bash
+   xcrun notarytool submit MyApp.dmg \
+     --apple-id "$APPLE_ID" --team-id "$APPLE_TEAM_ID" \
+     --password "$APPLE_APP_PASSWORD" --wait
+   ```
+3. **Staple** the ticket so the app validates offline: `xcrun stapler staple MyApp.dmg`.
+
+**Why it's mandatory for updates:** Squirrel.Mac refuses to apply an update whose new build
+isn't properly signed + notarized. Skip it and auto-update silently does nothing.
+
+## Windows Authenticode
+
+Sign the installer and the app `.exe` with an Authenticode certificate (an EV or OV cert from
+a CA; cloud HSM signing is increasingly required):
+
+```bash
+signtool sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 \
+  /a MyAppSetup.exe
+```
+
+Squirrel.Windows / NSIS auto-update relies on the signature matching across versions, so use
+the same publisher identity for every release.
+
+## Secrets
+
+Certificates, Apple app-specific passwords, and signing keys are CI secrets — never commit
+them. Storage/rotation policy belongs to `secure-coding`; this reference only covers where the
+Electron flow consumes them (`process.env`, CI secret store).

package/skills/electron/references/security-and-ipc.md

@@ -0,0 +1,158 @@
+# Security & IPC — full hardened example
+
+The SKILL.md gives the rules; this is the copy-paste reference that puts them together.
+
+## Hardened `main.ts`
+
+```ts
+import { app, BrowserWindow, ipcMain, session, shell } from 'electron';
+import path from 'node:path';
+
+const APP_ORIGIN = 'https://app.local'; // or 'file://' for a fully local bundle
+
+function createWindow() {
+  const win = new BrowserWindow({
+    width: 1100,
+    height: 720,
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+      nodeIntegration: false,
+      contextIsolation: true,
+      sandbox: true,
+      webSecurity: true,
+      allowRunningInsecureContent: false,
+    },
+  });
+  win.loadFile(path.join(__dirname, 'renderer/index.html'));
+}
+
+app.whenReady().then(() => {
+  // CSP as a response header — covers the initial document, unlike a <meta> tag.
+  session.defaultSession.webRequest.onHeadersReceived((details, cb) => {
+    cb({
+      responseHeaders: {
+        ...details.responseHeaders,
+        'Content-Security-Policy': [
+          "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'",
+        ],
+      },
+    });
+  });
+  createWindow();
+});
+
+// Navigation lockdown — applies to every webContents the app creates.
+app.on('web-contents-created', (_e, contents) => {
+  contents.on('will-navigate', (e, url) => {
+    if (new URL(url).origin !== APP_ORIGIN) e.preventDefault();
+  });
+  contents.on('will-attach-webview', (e) => e.preventDefault()); // no <webview> tags
+  contents.setWindowOpenHandler(({ url }) => {
+    if (url.startsWith('https://')) shell.openExternal(url);
+    return { action: 'deny' }; // never open a new in-app window to arbitrary content
+  });
+});
+```
+
+## IPC handlers with validation (`main.ts`, continued)
+
+Every handler treats its arguments as hostile. Validate type, bound size, and never feed an
+attacker string into `path.join`, `child_process`, or `eval`.
+
+```ts
+import { z } from 'zod';
+
+const SaveNote = z.object({ id: z.string().uuid(), text: z.string().max(10_000) });
+
+ipcMain.handle('note:save', async (_e, raw: unknown) => {
+  const { id, text } = SaveNote.parse(raw); // throws → rejects the renderer's invoke()
+  return db.notes.upsert(id, text);
+});
+
+ipcMain.handle('config:read', async () => readUserConfig()); // no input to validate
+```
+
+## `preload.ts` — one function per channel
+
+```ts
+import { contextBridge, ipcRenderer } from 'electron';
+import type { Api } from './ipc/types';
+
+const api: Api = {
+  readConfig: () => ipcRenderer.invoke('config:read'),
+  saveNote: (id, text) => ipcRenderer.invoke('note:save', { id, text }),
+  onSync: (cb) => {
+    const handler = () => cb();
+    ipcRenderer.on('sync:done', handler);
+    return () => ipcRenderer.removeListener('sync:done', handler); // give callers cleanup
+  },
+};
+
+contextBridge.exposeInMainWorld('api', api);
+```
+
+## Shared contract (`ipc/types.ts`)
+
+```ts
+export interface Config { theme: 'light' | 'dark'; }
+
+export interface Api {
+  readConfig(): Promise<Config>;
+  saveNote(id: string, text: string): Promise<void>;
+  onSync(cb: () => void): () => void; // returns an unsubscribe fn
+}
+```
+
+## Renderer global typing (`renderer/global.d.ts`)
+
+```ts
+import type { Api } from '../ipc/types';
+declare global {
+  interface Window { api: Api; } // window.api is now fully typed in the renderer
+}
+export {};
+```
+
+Renderer usage stays type-safe and capability-scoped:
+
+```ts
+const cfg = await window.api.readConfig();
+await window.api.saveNote(crypto.randomUUID(), 'hello');
+```
+
+## Electron Fuses
+
+Fuses flip security bits in the packaged binary itself, so they hold even if the JS is
+tampered with. Apply at build time (e.g. via `@electron/fuses`):
+
+```ts
+import { FuseV1Options, FuseVersion, flipFuses } from '@electron/fuses';
+
+await flipFuses(appPath, {
+  version: FuseVersion.V1,
+  [FuseV1Options.RunAsNode]: false,                 // no ELECTRON_RUN_AS_NODE bypass
+  [FuseV1Options.EnableCookieEncryption]: true,     // encrypt the cookie store at rest
+  [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false, // no NODE_OPTIONS injection
+  [FuseV1Options.EnableNodeCliInspectArguments]: false,        // no --inspect debug port
+  [FuseV1Options.OnlyLoadAppFromAsar]: true,        // refuse to run unpacked app code
+  [FuseV1Options.LoadBrowserProcessSpecificV8Snapshot]: false,
+});
+```
+
+## The full security checklist (each item, with the why)
+
+- [ ] `nodeIntegration: false` — renderer must not get `require`/`process`; XSS would become RCE.
+- [ ] `contextIsolation: true` — page and preload run in separate worlds; page can't rewrite the bridge.
+- [ ] `sandbox: true` — OS-level sandbox around the renderer process.
+- [ ] `webSecurity: true` — keep same-origin policy; disabling it to "fix CORS" opens the whole app.
+- [ ] `allowRunningInsecureContent: false` — no mixed http content on an https page.
+- [ ] CSP set via `onHeadersReceived`, not a `<meta>` tag — covers the initial document.
+- [ ] `will-navigate` denies origins outside your app — navigation grants attacker content your privilege.
+- [ ] `setWindowOpenHandler` denies new windows; external links go through `shell.openExternal` after protocol allow-listing.
+- [ ] `will-attach-webview` denied (or `webviewTag: false`) — `<webview>` is a fresh attack surface.
+- [ ] Every `ipcMain.handle` validates and bounds its args — the renderer is an untrusted client.
+- [ ] No `ipcRenderer` (or its methods) exposed over `contextBridge` — one function per channel only.
+- [ ] No `@electron/remote` — it's a direct renderer→main escalation path; use explicit IPC.
+- [ ] Electron Fuses applied (run-as-node off, cookie encryption on, ASAR integrity on).
+- [ ] App is on one of the latest 3 Electron majors — older = unpatched Chromium CVEs.
+- [ ] No attacker-controlled string reaches `path.join`, `child_process`, `shell.openExternal`, or `eval`.