Pulp Engine v0.14.0 — Editor Credential Scope

Summary

Adds a narrower editor scope (API_KEY_EDITOR) so the visual editor no longer needs an admin-scoped credential in the browser. Set VITE_API_KEY to API_KEY_EDITOR instead of API_KEY_ADMIN. The browser retains full editor functionality while losing the ability to trigger production renders, delete templates, or restore versions — operations the editor never performs.

---

What changed

New env var: API_KEY_EDITOR

Variable	Scope	Route access
API_KEY_EDITOR	editor	Template management (read/create/update), asset management, POST /render/preview/*

All configured keys must be distinct strings.

Updated authorization matrix

Route group	Paths	Required scope
Public	GET /health, GET /assets/:filename	(no auth)
Render	POST /render, POST /render/html	render or admin
Preview	POST /render/preview/html, POST /render/preview/pdf	preview, editor, or admin
Template management (read/write)	GET, POST, PUT on /templates/*	editor or admin
Template delete	DELETE /templates/:key	admin only
Template version restore	POST /templates/:key/versions/:version/restore	admin only
Asset management	POST /assets/upload, GET /assets, DELETE /assets/:id	editor or admin
All other authenticated routes	Any route not matched above	admin

Route scope enforcement is now method-sensitive for template routes. Future routes fail closed to admin unless explicitly classified.

Startup validation extended

• API_KEY_EDITOR is included in the distinct-value check: it must differ from API_KEY_ADMIN, API_KEY_RENDER, and API_KEY_PREVIEW.
• API_KEY_EDITOR cannot be set alongside the deprecated API_KEY (same rule as all other scoped keys).

---

Migration

No breaking changes. Existing deployments continue to work without any configuration changes.

To adopt the narrower editor credential:

1. Generate a new secret: openssl rand -hex 32
2. Add API_KEY_EDITOR=<secret> to your server environment.
3. Set VITE_API_KEY=<same-secret> in the editor’s environment (apps/editor/.env.local or equivalent).
4. Remove the old VITE_API_KEY=<API_KEY_ADMIN-value> from the editor’s config.
5. Restart the API.

The visual editor does not call POST /render or POST /render/html, so removing admin access from the browser causes no functional regression.

---

Breaking changes

None.

---

Files changed

File	Change
apps/api/src/config.ts	Added API_KEY_EDITOR to Zod env schema
apps/api/src/plugins/auth.plugin.ts	Added editor to Scope type; rewrote requiredScopes() with method-sensitivity and explicit asset arm; fail-closed fallback; updated credential map, duplicate check, deprecation warning
apps/api/src/__tests__/auth-scopes.test.ts	New editor scope describe block (9 tests); 2 new startup validation tests; EDITOR_KEY constant; 3 updated app() helpers
.env.example	Added API_KEY_EDITOR entry and bullets; updated VITE_API_KEY comment
README.md	Added API_KEY_EDITOR row to scoped credentials table
docs/api-guide.md	Updated scoped credentials table and authorization matrix; resolved “current limitation” in Editor auth section; updated migration steps
docs/deployment-guide.md	Added API_KEY_EDITOR env var row; updated reverse proxy note, migration steps, and deployment checklist
docs/runbook.md	Added API_KEY_EDITOR to pre-deployment credential checklist
docs/editor-guide.md	Updated credential setup to reference API_KEY_EDITOR instead of legacy API_KEY
docs/release-v0.14.0.md	This file