Pulp Engine v0.25.0 — Release Notes

Security hardening

This release adds five opt-in configuration controls that reduce reliance on “operator must deploy this perfectly” for key security surfaces.

No breaking changes. All new env vars are optional with backward-compatible defaults. Existing deployments work unchanged.

---

What changed

CORS allowlist (CORS_ALLOWED_ORIGINS)

Previously, the API accepted cross-origin browser requests from any origin (@fastify/cors with origin: true). There was no product-level way to restrict this.

Setting CORS_ALLOWED_ORIGINS to a comma-separated list of trusted origins restricts which browser origins may make cross-origin requests:

CORS_ALLOWED_ORIGINS=https://editor.example.com,https://app.example.com

Origins must include the scheme and exact hostname. Use CORS_ALLOWED_ORIGINS=* to explicitly opt into open access without a startup warning. When the variable is not set, all origins are still allowed (backward-compatible) with a [PulpEngine] startup warning.

---

Swagger UI gating (DOCS_ENABLED)

The Swagger UI (/docs, /docs/json, /docs/yaml) is now conditional. Set DOCS_ENABLED=false to skip registration — all /docs* routes return 404. Default: true (backward-compatible).

Disabling the docs in production reduces the exposed API surface for deployments where the interactive UI is not needed by operators.

---

Metrics bearer token (METRICS_TOKEN)

GET /metrics can now require bearer token authentication. When METRICS_TOKEN is set, any request without Authorization: Bearer <token> receives 401 Unauthorized. When unset, the endpoint remains open (backward-compatible) with a production startup warning.

Generate a token with openssl rand -hex 32. Update your Prometheus scraper job to pass the Authorization header.

# prometheus.yml scrape config
- job_name: pulp-engine
  bearer_token: <METRICS_TOKEN value>
  static_configs:
    - targets: ['api:3000']

The rate-limiting exemption on /metrics is unchanged — Prometheus scrapers should not be throttled.

---

Reverse proxy trust and HTTPS enforcement (TRUST_PROXY + REQUIRE_HTTPS)

The API’s documentation has always stated that POST /auth/editor-token must be served over HTTPS, because the request body contains the raw API_KEY_EDITOR value. Until now this was a documented requirement with no product-level enforcement.

Two new controls close this gap:

• TRUST_PROXY=true: sets Fastify’s trustProxy option so request.protocol reads from X-Forwarded-Proto instead of always being http. Required for REQUIRE_HTTPS to work correctly behind a reverse proxy.
• REQUIRE_HTTPS=true: rejects POST /auth/editor-token with 400 Bad Request when request.protocol is not https. A descriptive error message guides operators to set TRUST_PROXY=true if the enforcement is silently ineffective.

A startup warning is emitted if REQUIRE_HTTPS=true without TRUST_PROXY=true (the enforcement would be ineffective).

A production startup warning is emitted when REQUIRE_HTTPS is not set, advising operators to enable it once TLS is in place.

---

Startup warnings for insecure production defaults

The API now emits a [PulpEngine] startup warning for each open surface when NODE_ENV=production and the corresponding variable is not configured:

• CORS_ALLOWED_ORIGINS not set → warns that all origins are allowed
• METRICS_TOKEN not set → warns that /metrics is unauthenticated
• REQUIRE_HTTPS not set → warns that credentials may be sent over plain HTTP

These warnings do not block startup and do not affect behavior. They inform operators of surfaces that can be tightened.

The startup log now also includes a security block:

{
  "security": {
    "corsOriginsConfigured": true,
    "docsEnabled": false,
    "metricsTokenRequired": true,
    "trustProxy": true,
    "requireHttps": true
  }
}

---

New env vars

Variable	Default	Effect
CORS_ALLOWED_ORIGINS	unset (allow all + warn)	Comma-separated list of trusted origins, or *
DOCS_ENABLED	true	Set false to disable Swagger UI
METRICS_TOKEN	unset (open + warn)	When set, /metrics requires bearer token auth
TRUST_PROXY	false	Enables Fastify trustProxy for accurate X-Forwarded-Proto
REQUIRE_HTTPS	false	When true, rejects POST /auth/editor-token over non-HTTPS

---

Backward compatibility

All five variables are optional. Existing deployments that do not set them receive identical behavior to v0.24.0 (plus startup warnings in production where applicable). There are no breaking changes to the API surface, token format, stored data, or database schema.

---

Upgrading

1. Pull v0.25.0.
2. No database migrations needed for any storage mode.
3. Restart the API.
4. Review the [PulpEngine] startup warnings and configure the security vars at your own pace. See deployment guide § Production security checklist.