Investigate remaining reserved-path protection gaps after #397/#408

[kriszyp]

Investigative placeholder. Customer applications have historically been able to overload or shadow Harper's internal HTTP paths (e.g. /health, /status), breaking platform observability and operational tooling.

Significant work has already landed in this area:

• HarperFast/harper#397 — Middleware ordering and routing: introduces declarative before / after dependencies, per-route middleware chains, automatic component naming, and explicit declarations like REST after: 'authentication'. Per-route chains in particular limit how broadly a customer middleware can interfere with internal handlers.
• HarperFast/harper#408 — request.withNodeAdapter() for hosting Node middleware (Next.js etc.) without colliding with Harper's request pipeline.

This issue tracks the remaining investigation: after #397 and #408, what reserved-path gaps still exist?

To investigate

• Can a customer component still register a resource/route that shadows /health, /status, or other internal endpoints in a way that prevents the internal handler from running?
• Are there code paths (REST, GraphQL, static, websocket upgrade, raw server.http) where a component-supplied handler can intercept a reserved path before Harper's internal handler runs?
• Is there value in an explicit reserved-path registry that rejects conflicting component registrations at load time with a clear error, regardless of middleware ordering?
• Document the reserved Harper paths so component authors know what is off-limits, even if the routing layer protects them.

Not Ready

Investigation outcome will determine whether further enforcement is needed and what shape it should take. Do not schedule for a release until the investigation produces concrete acceptance criteria.

Related

• CORE-3043 — Customer component can override internal /status endpoint (concrete instance; verify whether still reproducible after Middleware ordering and routing #397/Add withNodeAdapter() to Request for Node middleware adapter pattern #408)
• Internal Slack: thread

---

Tracked in Jira: CORE-3048
Jira fields to mirror: Feature Type: Internal (already set) · Business Impact: Operational efficiency (already set)
Status: Not Ready — investigative.

🤖 Filed by Claude on behalf of Kris.