[P1] Defer unrecognized app-port Authorization until route ownership

[hdbjeff]

Problem

Harper's app-port authentication middleware resolves Authorization before route ownership is known. In Harper 5.2.6, an invalid/non-Harper Basic credential causes security/auth.ts to return 401 immediately. Downstream route matching never runs.

This prevents a Harper application from composing these two valid requirements:

1. Harper authentication and native route ownership run before an application catch-all, so native/public routes such as status and Harper-owned resources never reach application authorization middleware.
2. Unmatched application routes can use their own standard Authorization scheme. In this case WordPress Application Passwords, WooCommerce REST Basic credentials, and Bearer tokens must reach the Woo proxy and origin byte-for-byte.

Hoisting the catch-all with { before: "authentication" } preserves WordPress credentials but lets it claim Harper-owned routes. Ordering it after rest restores native route ownership but Harper rejects WordPress credentials first. URL exemptions, carrier headers, renamed credentials, and middleware header mutation are not acceptable architecture.

Reproduction and exact 5.2.6 code-path evidence are tracked in HarperFast/harper-woo-cache#297 and its draft PR #298. That PR includes tools/repro/harper-auth-ordering.mjs.

Required design

Authentication must run first, but credential rejection must be deferred until route ownership is known:

• Valid Harper credentials authenticate normally and populate the Harper principal.
• Missing credentials continue anonymously as today.
• A syntactically valid but unrecognized credential must not terminate the global middleware chain before routing. Preserve the original Authorization header unchanged and continue with no Harper principal plus an internal authentication-failure state.
• If a downstream Harper-owned route requires a Harper principal, that owning layer returns the normal generic unauthorized response. Invalid credentials must never grant access or downgrade a protected Harper route into a public route.
• If Harper REST/resource matching finds no owner, an application catch-all may receive the untouched header and apply its own authentication scheme.
• Native public routes such as status remain reachable without application-specific edge credentials.
• Internal authentication faults must remain fail-closed. Do not treat storage/configuration/runtime failures as ordinary unknown credentials.

Prefer a generally reusable core contract over Woo- or path-specific behavior. If compatibility requires a setting, it must be explicit, documented, secure by default, and usable by a deployed application/cluster without patching node_modules.

Acceptance criteria

• With auth-first ordering, valid Harper Basic/Bearer credentials still authenticate and protected Harper-owned resources retain existing authorization semantics.
• Invalid Harper credentials sent to a protected Harper-owned route return a generic unauthorized response and never reach a later application catch-all.
• An unrecognized WordPress/Woo Basic credential on a route not owned by Harper reaches the later application catch-all with Authorization byte-for-byte unchanged.
• Bearer credentials owned by the downstream application receive equivalent treatment without breaking Harper refresh-token behavior.
• Missing credentials and native public status/health routes behave normally.
• Internal authentication errors remain fail-closed and do not fall through as unknown credentials.
• Middleware ordering tests cover authentication -> rest -> application catch-all; no path exemption list, carrier header, header rename, or pre-auth credential-stripping shim is introduced.
• A runnable regression test reproduces the 5.2.6 early-401 behavior on the base revision and passes with the fix.
• Configuration schema, security documentation, API/runtime documentation, and release notes explain deferred credential rejection and route-owner enforcement.

Integration dependency

HarperFast/harper-woo-cache#297 / PR #298 must not ship its ordering-only change until this core capability is available in the deployed Harper version and the application enables/uses it. Otherwise /status is repaired by reintroducing the WordPress authentication P1.

Priority

P1. Current production candidate cannot keep both monitored native endpoints and authenticated WordPress/Woo routes working under correct route ownership.

[hdbjeff]

Team Lead Decision

Question: Override verifier result review-not-pass for PR #2419 at head ed68ac7ab00a9544d2f97dcfff247945f4f595c8?
Decision: accepted-with-concerns
Why: The only retained blocker is the broader owner-audit carry-forward tied to MQTT WebSocket authentication completion. Reviewer evidence explicitly marks the MQTT race introduced_by_pr=false and reproduced on base. PR-introduced MCP and static terminal-response gaps are fixed, focused/revert tests pass, QA passes, and current CI is green.
Risk: Existing optional-auth MQTT WebSocket upgrades may still initialize anonymously when HTTP authentication finishes asynchronously; behavior predates this PR.
Follow-up: #2424

(Decision made by team lead automation; durable override: 2419-ed68ac7ab00a9544d2f97dcfff247945f4f595c8-review-not-pass_.json.)