Plugin system & security (the core differentiator)

• OS-process plugin sandbox. Every plugin runs in a separate operating-system process (child_process.fork) — its own memory and event loop — so a crash, memory blow-up, or exploit is contained by the kernel and never takes down the host. Plugins reach the core only through a permission-checked wordjs bridge (structured-clone RPC, no live host references, an exact method allow-list).
• Install-time code scanner. Before a plugin can activate, its JavaScript is parsed and walked for dangerous constructs (eval, exec/spawn, dynamic require, sensitive modules, forbidden process access). It's fail-closed (an unparseable file is rejected) and runs on every plugin — no exemptions. The dependency tree a plugin ships is scanned at the same gate, bounded to 4,000 files, 1 MB per file and 32 levels deep; hitting a bound is itself reported as a finding, and a symlink resolving outside the plugin directory is never followed and reported instead.
• Ask-permission model (default-deny). A plugin's manifest requests scoped capabilities (database, filesystem, settings, users:read, email:provider, notifications:provider, network, …); an admin grants each one per plugin. A call works only if the capability is BOTH declared AND granted. Activation shows the admin exactly what the plugin requests and grants that declared set — only when the plugin has no grant record yet, so a later per-permission revoke survives a re-activation. First-party plugins get no extra privilege — same sandbox, same rules.
• Native kernel confinement on every supported platform (default-on). Each plugin child is also wrapped by the operating system's own sandbox: Landlock + seccomp-bpf on Linux (with no-new-privs), a zero-capability AppContainer on Windows, Seatbelt on macOS. Filesystem authority is scoped to the plugin's own zones, and a plugin without the network grant can't reach the network at all — the kernel refuses it below JavaScript, so it can't touch the internet or your internal services. Each mechanism is probe-gated (a confined child is spawned beside an unconfined control and must actually be refused what it must be refused), and production is fail-closed: if the probe can't certify the host, the isolated plugin doesn't run unless the operator sets sandbox.requireHardening:false. The live mechanism and its state are reported on admin GET /health/details.
• Per-plugin data isolation. Each plugin gets only its own wjp_<slug>_ database tables and a secret-scrubbed view of config — core users/options/sessions and secrets are unreachable. On PostgreSQL/MySQL the database itself enforces this via a per-plugin low-privilege role/user.
• Plugin & theme marketplace. A curated catalog of 31 first-party plugins with one-click, sha256-verified installs through the same hardened, sandboxed pipeline as manual uploads. Themes ride the same mechanism on an independent catalog and their own admin tab, but that catalog was retired and currently builds empty — the themes you get are the four bundled in backend/themes/. Sources are admin-configurable (point it at any HTTPS catalog), and the Reviewed badge is honoured only for entries the official catalog serves — a review claim from any other source is shown as unreviewed. All catalog items are first-party today; third-party submissions are open under the public review policy (marketplace/REVIEW.md), and nobody outside the project has submitted one yet.

Authoring & content

• Visual builder (Verso, built in-house — see The editor below) — drag-and-drop editing, in-place rich text (bold, italic, links with an open-in-new-tab toggle, bullet and numbered lists, clear formatting), a per-block Appearance panel (background colour/gradient/image/glass, border, shadow, typography, hover effects — with tablet/mobile overrides on the box and type metrics: padding, margins, max-width, min-height, font-size, line-height, letter-spacing, alignment and radius; colours, backgrounds, shadows and motion are deliberately one look per block), a searchable block inserter with reusable section patterns, and a device preview that sizes the canvas to the real device width (desktop 1280 / tablet 768 / mobile 375), so the site's actual CSS breakpoints fire.
• Real server-side rendering — public pages are React Server Components, so crawlers and first paint get the real content, per-page metadata (generateMetadata), OpenGraph/Twitter cards, JSON-LD, real 404s, and a no-JS search form.
• SEO, archives and feeds — semantic HTML; public /category/, /tag/, /author/, date and custom-taxonomy archives, paginated by path and rendered through the theme's archive.html; a sitemap.xml that becomes a <sitemapindex> with chunked children above 1,000 URLs (SITEMAP_MAX_URLS in backend/src/core/feeds.ts); robots.txt; and RSS, Atom, JSON Feed, per-category / per-tag / per-author and comments feeds — all served at their public root URLs in every deployment mode.
• Themes — a shared, token-driven CSS framework (--wjs-* design tokens) that auto-styles pages, plus a live customizer at /admin/themes/customize. A theme's optional server-side functions.js runs in the same sandbox as plugins.
• Hooks, filters & shortcodes (WordPress-style), dynamic roles & permissions (database-driven), and UI in español / english / português.
• WordPress (WXR) importer — upload a .xml export to bring over authors, categories/tags, posts/pages (with meta, term relationships, and threaded comments), preserving publish dates. Attachments are downloaded through the same SSRF guard as webhooks (50 MB per file and 1 GB per run by default, resumable, failures reported per item) and menus come across with hierarchy, targets and locations; content and editor-tree URLs are rewritten to the new library. Idempotent and re-runnable.
• Backups — full-site export/restore with retention pruning, plus privacy-first analytics (no cookies, daily-rotated salted IP hashing) and a built-in cron.

Operations

• Gateway — a clustered reverse proxy (one worker per CPU core, capped at 16 — or 4 in development — with automatic respawn of dead workers), health-check eviction, an mTLS internal control channel, and SSE-aware proxying. It also acts as the cluster CA for multi-machine deployments.
• Automatic TLS — Let's Encrypt via HTTP-01 or DNS-01, manual upload, or a self-signed dev fallback; renewal works in single-process mode too.
• Databases — SQLite (default), PostgreSQL, or MySQL 8+/MariaDB, all behind one interface with a migration system to move between them.
• Headless-friendly — scoped API tokens (Authorization: Bearer wjt_…, per-resource scopes), HMAC-signed SSRF-safe webhooks, and token-gated Prometheus metrics.
• Observable — structured pino logging with request correlation ids and credential scrubbing, and a /metrics endpoint carrying request rate, latency histogram, error rate, DB pool and sandbox state. See Observability.
• Native mail server — an optional, fully sandboxed first-party plugin: inbound SMTP, direct-MX delivery, and DKIM signing.

graph TD
    User((User)) --> Gateway[Gateway :3000]
    Gateway --> Frontend[Next.js Frontend :3001]
    Gateway --> Backend[TypeScript Backend :4000]
    Backend --> DB[(SQLite / PostgreSQL / MySQL)]
    Backend --> Plugins{Isolated Plugins}

• Gateway — clustered Node/Express reverse proxy: routing, load-balancing, health-check eviction, mTLS internal channel, SSE-aware proxying, and the cluster CA.
• Backend — the core engine (content, users, roles, the plugin/theme system, mail, certificates, and the sandbox). TypeScript, compiled to JS for production.
• Frontend — the public site and the Next.js admin, including the Verso visual builder.

Monolith runs the backend (with its isolated plugins) and the Next.js frontend in one process on :3000 — no gateway proxy, no cluster — while still handling TLS, security headers, compression, and SEO rewrites locally. Split runs them as three cooperating processes behind the gateway. Separate spreads those three across machines: create-wordjs gateway --host <ip> makes the first box the cluster CA and prints ready-to-paste join commands with single-use, role-bound tokens; each other box enrolls over mutual TLS with no cert hand-copying.

See the Separate-mode guide for the walkthrough.

• Runtime: Node.js (≥ 20.9; Node 20/22 LTS recommended)
• Backend: TypeScript — compiled with tsc for production, ts-node for dev
• Frontend: Next.js (React 19)
• Editor: Verso — in-house; its editor state, drag-and-drop resolver and rich-text engine carry no third-party dependency · Styling: vanilla CSS + Tailwind
• Communication: REST + JWT + scoped API tokens + WebSockets/SSE
• Gateway: Express + Node cluster, http-proxy, mTLS internal channel
• Sandbox: child_process OS-process isolation + native kernel confinement (Landlock/seccomp-bpf, AppContainer, Seatbelt) + acorn code scanning + runtime require proxies + layered memory caps (cgroup / Windows Job Object / RSS-poll) + a reactive per-plugin CPU watchdog (sandbox.cpuBurstSeconds, default 60 s at ≥ 95% of one core)
• TLS: acme-client (Let's Encrypt HTTP-01 / DNS-01)
• Database: SQLite (better-sqlite3 / sql.js), PostgreSQL (pg), or MySQL/MariaDB (mysql2)
• Tooling: ESLint + Prettier, node:test, GitHub Actions CI

npm run install:all       # install root + sub-packages
npm run dev               # split: gateway + backend + frontend
npm run dev:mono          # or everything in one process, one port

Public site on port 3000, admin at /admin. Both modes read gateway/gateway-config.json (not in git; written by npm run setup, the create-wordjs installer, or the gateway on its first boot). dev:mono serves https://localhost:3000 with a self-signed certificate (gateway/ssl-auto.*, shared with the gateway) when that file sets ssl: true, ssl.enabled, or sslAuto, or when gateway/ssl-auto.{key,crt} already exist; on a fresh checkout without it the monolith falls back to plain http://localhost:3000. WORDJS_HTTP=1 forces plain HTTP. The split gateway likewise switches to HTTPS once setup writes ssl.enabled. First-run setup (database + admin user) runs in the browser install wizard. npm run setup (node setup/index.js --install) is a separate, optional step for the split cluster: it generates the mTLS cluster PKI and writes the initial backend/wordjs-config.json / gateway/gateway-config.json (random gatewaySecret/jwtSecret, ports, ssl.enabled: true) — it does not create a database or an admin user.

In production the backend is compiled (tsc → dist/) and run as plain JS. From backend/:

CI (.github/workflows/ci.yml, Node 22) runs the strict type-check, the compiled build, a dependency license gate, an npm audit gate that blocks high/critical production advisories in backend, gateway, frontend and packages/create-wordjs, the unit suite with WORDJS_CI_DB=1 so the driver-conformance tests hard-fail (rather than skip) unless they really ran against the postgres:16 and mysql:8 service containers, integration tests against real postgres:16 + redis:7 containers, a separate two-process multi-node coherence job on shared Postgres + Redis, a coverage ratchet (c8 for the backend, vitest coverage for the frontend) that fails a run dropping below the committed floor, a job that builds the Docker image, boots it and completes the installer inside the container, and the frontend lint/type-check/tests/build. A separate scheduled workflow (.github/workflows/dependency-audit.yml) re-runs that audit across all six workspaces — root and setup included — every day at 04:41 UTC and opens or updates an issue when one of them fails.