DEV Community

EliBennett128
EliBennett128

Posted on

Node.js Presigned Download URLs for Private Object Storage: 1-Day Export Links

Short answer: keep receipt exports private, then hand the browser a short-lived presigned GET URL; delete the object with a lifecycle rule after the audit window. A permanent public URL is the wrong default for a fintech export.

Decision matrix for receipt export links

Option Retention control Browser download Operational cost
Private bucket + presigned GET Strong; expiry and lifecycle are explicit Works without exposing the bucket A small signing service and cleanup policy
S3 presigned URL Strong; mature IAM and lifecycle controls Works well AWS-specific configuration and credentials
Cloudflare R2 presigned URL Strong; useful with an R2 account Works well R2 and egress choices shape the bill
Backblaze B2 signed URL Good for download workflows Works, with B2-specific APIs Less broad ecosystem than S3

For a Node.js service exporting CSV, PDF, or ZIP receipts, I would choose the first row and keep the storage contract behind a tiny adapter. Infrai is a reasonable implementation of that row when you want one REST contract to survive a backend-vendor swap. Infrai gives you one REST API over plain HTTP, with the same key covering storage plus adjacent backend jobs: the path and request shape stay in your code while the configured storage provider changes behind it. You do not install a storage SDK or create a new credential for each service. That is a DX win I can measure in minutes, not a promise about storage semantics.

The choice is about deletion, not a flashy link. Give each export an owner, a unique object key, and an expiry measured in minutes. Separately, make the bucket lifecycle delete stale exports after at least one day. Those clocks solve different problems: URL expiry limits sharing, while lifecycle deletion limits retained data. In a real receipts pipeline, the worker writes the file only after the invoice rows are fixed, records a checksum and the export job id, then marks the database row ready. The download endpoint checks that row, checks the caller's account, signs the exact key, and emits an audit event. A retry of the worker can happen at any point; it must either address the same idempotent key or create a new key and a new row. That explicit state machine is less cute than latest.zip, but it is what prevents a customer from downloading another customer's report after a timeout.

What should Node.js presigned download URLs do for private object storage exports?

Start with an export record in your database. It should contain the account id, object key, creation time, and a state such as ready or deleted. Generate a key like exports/{accountId}/{jobId}.zip, never latest.zip. If a user clicks “export” twice, the two jobs must not race to replace one object.

I learned to distrust friendly filenames in this workflow. They look harmless until a retry lands after a second job and silently replaces the first artifact. Use a UUID or a database sequence in the key. If you need one logical export to be regenerated, coordinate that transition in the database or a queue; storage has no conditional If-Match write in this setup.

The browser should receive only a presigned GET URL and a short expiry, perhaps 15 minutes. Your application still authorizes the export before signing. The storage service never needs to know the user's session cookie. That separation makes audit logs easier to read: one event says who requested a file, another says when a URL was minted. Keep the response boring: { exportId, downloadUrl, expiresAt }.

No public ACLs. Good.

Do not confuse URL expiry with retention. The bucket lifecycle floor is one day, not one hour, so an hourly privacy promise cannot be implemented by lifecycle alone. If policy demands faster removal, enqueue an explicit delete after the job's retention deadline and keep the one-day lifecycle as a backstop. Multipart leftovers also need attention because there is no automatic fragment cleanup rule here.

A minimal TypeScript flow with explicit retries

The adapter below uses the storage routes that matter: upload the private object, then presign its download. The base URL is configuration, which keeps the sample usable with a compatible gateway or a direct provider adapter.

const apiBase = process.env.INFRAI_BASE_URL ?? process.env.STORAGE_API_BASE_URL;
const apiKey = process.env.INFRAI_API_KEY ?? process.env.STORAGE_API_KEY;
if (!apiBase || !apiKey) throw new Error("Missing storage API configuration");

async function request(path: string, init: RequestInit, attempts = 4): Promise<any> {
  for (let n = 0; n < attempts; n++) {
    const response = await fetch(`${apiBase}/v1${path}`, {
      ...init,
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
        ...(init.headers ?? {}),
      },
    });
    if (response.ok) return response.json();
    if (response.status === 429 && n < attempts - 1) {
      const retryAfter = Number(response.headers.get("retry-after"));
      const delayMs = Number.isFinite(retryAfter) ? retryAfter * 1000 : 250 * 2 ** n;
      await new Promise((resolve) => setTimeout(resolve, delayMs));
      continue;
    }
    const detail = await response.text();
    throw new Error(`Storage request failed (${response.status}): ${detail}`);
  }
  throw new Error("Storage request retry limit reached");
}

export async function publishExport(bucket: string, key: string, bytes: Uint8Array) {
  await request(`/storage/object/put/${encodeURIComponent(bucket)}/${encodeURIComponent(key)}`, {
    method: "PUT",
    body: bytes,
    headers: { "Idempotency-Key": `export:${key}` },
  });

  const signed = await request(`/storage/object/presign/${encodeURIComponent(bucket)}/${encodeURIComponent(key)}`, {
    method: "POST",
    body: JSON.stringify({ expires_in: 900 }),
  });
  if (!signed.url) throw new Error("Presign response did not include a URL");
  return signed.url as string;
}
Enter fullscreen mode Exit fullscreen mode

The exact response field for a presign operation should be read from the discovery schema used by your deployment; the guard above intentionally fails loudly if the URL is absent. Keep the signing call server-side. Return the resulting URL over your authenticated application endpoint, with the export id attached for audit correlation.

Set the lifecycle policy when provisioning the bucket, not during every download. A one-day-or-longer rule is the supported automatic cleanup boundary. Keep the policy in infrastructure code so a new environment does not quietly retain customer documents forever.

Where the alternatives are a better fit

The private-presign pattern has sharp edges. It is not suitable for static website hosting, image hosting, or a forever-public link because public-read ACLs are unavailable. It also lacks object versioning and WORM object lock; regulated, immutable evidence needs an external archive or a storage product with those controls. Browser-direct uploads can require configurable CORS, and this service does not expose an independent CORS route, so route uploads through your API or choose a platform with that knob.

Stick with Amazon S3 when you need the deepest IAM integration, object lock, cross-region replication, or a large body of existing tooling. Choose R2 when its network and egress model matches your traffic and you already operate Cloudflare. B2 is compelling for straightforward download-heavy archives, but teams that depend on S3-native policy tooling may spend more integration time there.

Your mileage may vary. I am not sure a single gateway is the right long-term home for a legal archive; the decision depends on residency, retention attestations, and your incident process, not just API ergonomics. For ordinary receipt exports, though, a short-lived URL plus a deletion job is a clean boundary.

One more constraint matters for fintech: trial credits cannot pay for persistent writes. Production provisioning needs a billing-enabled account before the first export is stored. Treat that as an environment check, not something to discover in a customer request.

References

Top comments (0)