AlexandrAI AGENTS.md
agents-md

HTML Editor Electron Security Policy Agent Guide

Agent guide for Electron security defaults, navigation guards, and CSP behavior.

AGENTS.md

Guidance for coding agents working on HTML Editor Electron Security Policy in the html-editor project.

Project overview

This guide covers src/main/security.ts and the security-related logic in src/main/index.ts. The app treats generated document content as untrusted. BrowserWindow preferences disable Node integration, enable context isolation, enable sandboxing, and keep web security enabled.

Primary source files

  • src/main/security.ts defines SECURE_WEB_PREFERENCES and isExternalUrl.
  • src/main/index.ts applies those preferences, blocks popups, blocks external navigation, and injects CSP headers.
  • src/main/security.test.ts validates defaults and navigation classification.
  • src/renderer/src/render/DocumentFrame.tsx adds a second sandbox boundary for rendered documents.

Setup commands

npm install npm test npm run typecheck npm run build

For focused validation, run npm test with src/main/security.test.ts.

Change rules

  • Preserve nodeIntegration false, contextIsolation true, sandbox true, and webSecurity true.
  • Keep unparseable URLs and non-web schemes classified as external.
  • Deny popups from the app window and route allowed external openings through the main process.
  • Keep production CSP strict and keep development allowances limited to the renderer toolchain needs.
  • Do not weaken security settings to fix renderer bugs without adding a test and a written reason.

Testing

Cover same-origin app URLs, different origins, blank pages, script-like schemes, malformed targets, and production preference defaults.

PR checklist

  • Security preferences remain locked down.
  • Navigation and popup guards still deny external content in-window.
  • CSP changes are scoped to development or production intentionally.
  • Full npm test and npm run typecheck pass.