The safest Node.js export flow checks the player or operator's access before it creates a short-lived capability URL, while the original receipt stays immutable in private storage. That gives the client a simple download and keeps authorization in the application where tenant, role, and audit context are available.
Short answer: treat a signed download URL as a delivery credential, not as an authorization system. Resolve an export record, verify access, sign the exact object key for a small time window, and log the decision without logging the URL itself. For a gaming receipt export, that separation matters: delivery should be easy, but a leaked link should have a narrow blast radius.
The before model is familiar: the browser calls a public bucket path, and the application hopes the path is hard to guess. The after model has three steps: an authenticated request asks for an export, the application authorizes that request and signs one object, then the browser downloads directly from private storage. The file is still the original audit artifact. The URL is temporary plumbing.
The boundary is the point.
What should the link be allowed to do?
Start with an export record, not with a filename supplied by the browser. A useful record contains an internal export ID, the immutable object key, the account or jurisdiction it belongs to, the file's media type, and its creation timestamp. The download endpoint receives the export ID, loads that record, and compares its scope with the caller's scope.
This ordering prevents a common mistake: signing first and checking later. Once a valid URL is returned, the storage service can usually validate the signature without knowing why the caller was entitled to the receipt. The application must make that decision while it still has identity and business context.
The signed request should be narrow. Bind it to one object key, one HTTP method, and an expiry such as 60 seconds. If the storage boundary supports response headers, request a download disposition and the stored media type. Do not put player names, email addresses, or raw receipt contents in query parameters. URLs travel through browser history, logs, analytics tools, and referrer paths more often than teams expect.
Keep it narrow.
A short expiry is useful, but it is not a substitute for revocation. If an export must be disabled immediately, keep a server-side export status and issue links only while that status is active. A URL that has already been handed out may remain usable until its expiry, so the expiry window is an explicit access-versus-delivery decision.
How should Node.js export files use signed download links?
The endpoint needs an application-owned authorization boundary and a replaceable signing adapter. The adapter below is intentionally generic: the storage implementation supplies the final signature, while the application controls the object key and policy inputs.
import { randomUUID } from 'node:crypto'; interface ExportRecord { id: string; ownerId: string; objectKey: string; contentType: string; status: 'ready' | 'disabled'; } interface StorageSigner { signDownload(input: { objectKey: string; expiresInSeconds: number; contentType: string; downloadName: string; }): Promise<string>; } interface RequestContext { actorId: string; requestId: string; } async function createReceiptDownload( context: RequestContext, exportId: string, exports: { findById(id: string): Promise<ExportRecord | undefined> }, signer: StorageSigner, audit: { write(event: Record<string, string>): Promise<void> }, ): Promise<{ url: string; expiresInSeconds: number }> { const record = await exports.findById(exportId); if (!record || record.status !== 'ready' || record.ownerId !== context.actorId) { await audit.write({ event: 'receipt_download_denied', requestId: context.requestId, exportId, actorId: context.actorId, }); throw new Error('Export is not available'); } const expiresInSeconds = 60; const downloadName = `receipt-export-${randomUUID()}.json`; const url = await signer.signDownload({ objectKey: record.objectKey, expiresInSeconds, contentType: record.contentType, downloadName, }); await audit.write({ event: 'receipt_download_issued', requestId: context.requestId, exportId: record.id, actorId: context.actorId, expiresInSeconds: String(expiresInSeconds), }); return { url, expiresInSeconds }; } The important line is not the call to signDownload. It is the lookup and scope check immediately before it. The storage adapter can change later without moving authorization into a bucket policy or a browser.
That separation also makes a failure legible. If the caller has no matching export record, the application can record a denial. If the record is valid but the storage service rejects the signature, the transfer failure belongs to a different stage. Treating those as one generic download error makes incident review much harder.
The audit event deliberately records the export ID and request ID, not the full URL. A URL may contain a credential. Keep it out of application logs, tracing attributes, error messages, and client telemetry. If the response is cached anywhere, use private caching rules for the authorization endpoint; the direct file response should follow the storage service's cache semantics and the sensitivity of the receipt.
What breaks in real receipt downloads?
The first failure mode is an object-key confusion bug. A client sends ../other-account/receipt.json, or it swaps an export ID for a raw path. Never concatenate an untrusted path into a storage prefix. Store the canonical key when the export is created, and retrieve that key by the server-owned export ID.
This is where a receipt workflow differs from a generic file browser. The export ID is a business object with an owner and a lifecycle; the object key is an implementation detail. Letting the browser choose either one collapses those two boundaries, and an otherwise correct signature can authorize the wrong file.
The second is a browser policy mismatch. A direct download from another origin may need CORS response headers. CORS is enforced by browsers through HTTP headers, and some cross-origin requests trigger an OPTIONS preflight; it does not grant storage access to an unauthenticated caller. Configure the smallest allowed origin, methods, and headers needed by the download flow. A navigation download and a JavaScript fetch have different browser behavior, so test the actual client interaction instead of testing only the URL in a command-line client.
The third is observability that tracks the wrong thing. Count authorization decisions separately from storage responses. A 200 from storage does not prove the correct account received the file, and a denied application request should be visible even though no storage request occurred. Include request ID, export ID, actor scope, decision, expiry, and storage outcome. Exclude the signature.
The fourth is a false assumption about retries. A 60-second URL may expire while a large export is downloading over a slow connection, depending on how the storage service evaluates expiry. Set the window from file size, network conditions, and threat tolerance, then test near the boundary. Do not quietly turn every link into a day-long bearer credential just because one large file was inconvenient.
Is direct delivery worth the access-control complexity?
Usually, yes for a receipt export that may be several megabytes or more: the application authorizes a small response and the storage layer carries the file bytes. The trade is that the application no longer sees every byte transfer. If you need inline redaction, per-chunk inspection, or immediate revocation after issuance, proxy the download through an authorization-aware service instead. That adds operational work and bandwidth responsibility, but it gives the service control of the full stream.
A practical decision rule is simple. Choose a signed direct download when the original object is already safe to deliver as-is, the authorization decision is stable for the expiry window, and storage access logs are sufficient for transfer evidence. Choose a proxy when policy must be checked during transfer or the object needs transformation. In both designs, preserve the original file, version the export metadata, and make the audit trail point to an immutable export ID.
The two reader objections are predictable. “Can I just make the bucket public?” That removes delivery friction by removing the access boundary, which is a poor fit for receipts. “Can I refresh the link automatically?” Yes, but refresh the authorization endpoint, not the storage URL; each refresh should repeat the status and scope checks and issue a new short-lived capability.
The clean architecture is therefore boring in a useful way: application authorization first, one immutable object second, a bounded capability third, and observability around each decision. Signed URLs simplify delivery. They do not decide who should receive a receipt.
That is the trade.
References
- MDN, “Cross-Origin Resource Sharing (CORS)”: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS
- RFC 9110, “HTTP Semantics”: https://www.rfc-editor.org/rfc/rfc9110
- RFC 6750, “The OAuth 2.0 Authorization Framework: Bearer Token Usage”: https://www.rfc-editor.org/rfc/rfc6750
- OWASP, “Logging Cheat Sheet”: https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html
