Next.js / Advanced: caching modes, lifecycle and release evidence / Lesson 15
Proxy security and trusted external boundaries
Use network-boundary features for scoped routing while keeping authentication, validation and source authority at the real server boundary.
On this page
Lesson goals
- Explain proxy.ts scope and the limits of optimistic session checks.
- Review destination URLs, private data, CSP and upload limits as separate contracts.
A network routing layer is not the whole authorization system
Next 16 uses the proxy.ts convention for the network boundary previously associated with middleware.ts. It can redirect or rewrite before route rendering, but its matcher and optimistic checks do not replace current object policy inside data access and mutations. A prefetch or alternate entry point can interact differently with routing, so do not secure a Server Action solely by assuming a page request passed Proxy. Keep request-bound state out of shared globals and avoid expensive unbounded source work there. Record exact version and deployment behavior instead of treating the rename as proof of universal runtime portability.
Keep coarse routing assumptions in a reviewable record
The JSON is a synthetic security-boundary checklist, not executable proxy configuration. It states that the server data/action layer remains authoritative and public redirect origins are configured. A cookie-presence test is only a navigation hint until the credential is verified. Matchers must cover intended requests without accidentally intercepting assets or unsupported paths, and their behavior should be tested with safe fixtures. Do not copy a broad rewrite or redirect that trusts an arbitrary next URL or Host header. Request metadata is a claim that must fit the deploymentโs verified trust boundary.
{"networkBoundary":"proxy.ts-versioned","coarseChecks":"navigation-only-until-credential-verified","authority":"data-layer-and-each-mutation","redirectOrigin":"trusted-configured-value","privateLogs":"no-tokens-or-payloads","runtime":"verify-platform-support"}The record applies no matcher, redirect or security header. It names independent controls to verify.
Every downstream sink needs its own safe contract
A validated string is not automatically safe as SQL, HTML, a filesystem path, an outbound URL or a response header. Use source-native parameterization, context-appropriate output encoding and server-controlled storage identifiers. If a feature fetches external URLs, constrain schemes, destinations, redirects, bytes and deadlines through a reviewed policy rather than an unchecked server fetch. Limit upload bytes, parts and temporary storage before publication and clean up rejected partial work. No single Next directive or security-header package supplies these business and resource guarantees. Use official advisories and authorized review, not live scans during course authoring.
Expose only deliberate safe failure categories
The local mapper recognizes one validation category and hides every unknown exception behind a generic failure. It ignores an arbitrary status and private message supplied by the error object. A real application can use trusted typed errors and richer domain states, but should not serialize raw source exceptions into rendered pages or action results. The model does not log, authenticate, configure CSP or run Proxy. It tests only public disclosure shape. Keep richer diagnostic context under controlled correlation, and distinguish a safe error body from evidence that no write happened.
function safeFailure(error) {
return error?.code === "INVALID_TITLE" ? {code:"INVALID_TITLE"} : {code:"INTERNAL_ERROR"};
}
console.assert(safeFailure({code:"INVALID_TITLE"}).code === "INVALID_TITLE");
console.assert(JSON.stringify(safeFailure({status:200,message:"private-source"})) === '{"code":"INTERNAL_ERROR"}');Known validation remains specific and unknown source detail is hidden. No Next error boundary or HTTP response is tested.
Review headers, browser trust and deployment separately
CSP, content-type controls, cookie attributes and CORS can strengthen different boundaries but do not replace current authentication or object policy. Nonces and dynamic rendering need the selected CSP integration; do not invent a fixed nonce as a reusable security recipe. Browser read policy is distinct from CSRF and server effect execution. Review remote image patterns and public environment variables alongside server data. This course parses the checklist and runs the mapper only; it does not send network traffic, apply headers, inspect uploads or assess a deployed site. Real security verification needs exact versions, safe synthetic cases and an authorized environment.
Common errors and fixes
Proxy cookie presence is treated as verified authority
- Why it happens
- An optimistic routing hint replaced the authentication protocol.
- How to fix it
- Verify current credentials and enforce object policy at the actual server entry.
- Prevent it next time
- Test direct actions and handlers without relying on the page path.
A safe field becomes an unrestricted outbound URL
- Why it happens
- Validation for one context was assumed safe for every sink.
- How to fix it
- Apply destination-specific scheme, target and resource rules.
- Prevent it next time
- Review redirects and resolved destination policy without probing real targets.
Private exceptions leak through action state
- Why it happens
- Raw source objects were returned as public errors.
- How to fix it
- Project known safe categories and keep internal evidence controlled.
- Prevent it next time
- Assert exact public fields and omission of source messages.
Check your understanding
1. Does a correctly configured Proxy make a private Server Action safe by itself?
Show worked solution
No. The action remains a callable boundary with untrusted input and current object state. Authenticate and authorize there or in its shared domain operation. Proxy can improve routing and coarse admission, but must not become the only protection for alternate entry points, prefetch behavior or stale UI.
2. Why is safeFailure not evidence of a secure deployment?
Show worked solution
It tests one local mapping from two fixtures to public codes. It does not exercise identity, authorization, headers, CSP, source parameterization, route coverage or framework error handling. Keep its useful disclosure evidence narrow and separately verify each actual boundary in the intended authorized environment.
Key takeaways
- Network routing and domain authority are separate security responsibilities.
- Each input sink and public output needs its own reviewed contract.