Settlement downloads are privileged data exports

What the public implementation shows

Guevara protects settlement-file queries with a DownloadNSI role, resolves files through stored settlement metadata, returns explicit not-found outcomes, and chooses response content types and download headers by file format.

The query handler mediates between settlement database identity and filesystem content before the API exposes bytes to an operator. This is the implementation fact behind the note; the architectural reading begins from that visible boundary rather than from an assumed production story.

Operating principleA settlement file is not merely static content; it is a privileged financial export with lifecycle and caching risk.

The decision behind the mechanism

Authorization lives on the application query, while metadata lookup and file existence checks prevent arbitrary caller-supplied paths from becoming the download source.

A generic file endpoint can permit path manipulation, stale browser caches, or access to settlement artifacts outside the caller's operational role. The mechanism matters because it gives that failure a named boundary, durable evidence, and a controlled response instead of leaving the outcome to timing or operator guesswork.

• Authorize a dedicated settlement-download claim.
• Resolve server paths from trusted database records only.
• Return explicit missing-record and missing-file outcomes.
• Set safe content disposition, type, and cache policy.

How the control should be operated

Audit every export by user, claim, file ID, period, and result; enforce no-store behavior for sensitive party-level artifacts and verify retention separately.

Operators can retrieve settlement evidence without turning the storage directory into a public content surface. The reusable lesson is not to copy a class or endpoint in isolation, but to preserve the relationship between identity, state, authority, evidence, and operational ownership.