DEV Community

NicodemusChristensen2675
NicodemusChristensen2675

Posted on

Private User Documents: Direct Browser Presigned Uploads Beat Node.js Proxies

For private user documents, let the browser direct-upload each file with a presigned URL instead of sending large PDF or DOCX bodies through a Node.js proxy; for a tenant-scoped product image export, reverse that preference and build one brokered bundle. The broker costs an extra background job and one more stored object, but it gives the application one authorization decision, one auditable artifact, and one progress signal. Use individual download links only when a person needs a few images immediately. Short answer: use presigned browser uploads for incoming documents, bundle bulk exports, and sign individual downloads for small selections.

Option Pick it when Access-control shape Delivery and operations
Per-object signed links A user selects a small, known set Authorize every requested key before signing Fast start; many links, requests, and partial failures
Brokered export bundle A tenant requests a catalog-sized export Authorize once, then bind a manifest and result to the tenant Delayed start; one status trail and one downloadable artifact

This is an access-control decision disguised as a storage decision. Direct browser upload still belongs in the design: the API authorizes an object key, then the browser transfers bytes to private object storage. Export is the reverse path, but symmetry is a trap. A bulk download has different failure modes from one upload, so it deserves its own control plane.

Should a browser direct-upload user documents with a presigned URL?

A signed URL delegates a narrow storage operation for a limited period. That is useful. For a PDF or DOCX upload, the API can authenticate the user, choose a private object key, constrain the intended operation, and let the browser carry the large file bytes. The Node.js process stays on the control path instead of the data path. But the same pattern does not prove that every key in a client-supplied export array belongs to the current tenant, and it does not turn 800 independent downloads into one coherent result.

That distinction matters.

Picture the flow in words: browser asks API; API checks tenant membership; API resolves logical asset IDs to storage keys; signer creates temporary links; browser fans out requests. Every arrow after the resolution step can finish at a different time. A tab can close halfway through. One link can expire after 799 succeed. The application then has to explain what “complete” means.

There is a sharper security pitfall. Never construct a key by joining a trusted tenant ID to an unchecked filename and call that authorization. Resolve opaque asset IDs through a tenant-scoped query. The signer should receive only records that survived that query.

Per-object delivery is still the cleaner choice for a product editor opening three thumbnails or downloading one original. It avoids building an archive the user did not ask for. Keep the selection capped by an application rule, issue short-lived links only after authorization, and record the asset ID rather than the full signed URL. Query strings are credentials; logs are a bad home for them.

Pick brokered bundles for tenant-wide work

An export broker turns an open-ended browser fan-out into a state machine: queued, running, ready, failed, or expired. The API creates an immutable manifest from a tenant-scoped database query. A worker reads exactly that manifest, streams objects into an archive, writes the archive under an export-specific key, and marks the job ready. Only then may the API create a temporary download link.

The important word is immutable. If a product image is replaced while the worker runs, the manifest still says which object version or content identity belongs in this export. Without that boundary, retrying a job can silently produce a different bundle under the same export ID. Imagine an 800-image catalog where object 417 changes after the first worker attempt fails: a retry that performs a fresh catalog query creates a mixed-time snapshot, even though the user sees one export ID. Freezing the resolved inputs avoids that ambiguity. It also gives an operator something exact to inspect when the source count and archive entry count disagree.

The manifest is the authorization snapshot. It should contain opaque asset identifiers and resolved storage keys selected by the server, never arbitrary keys submitted by the browser. Bind the job row, manifest, result object, and status lookup to the same tenant ID. Defense in depth becomes concrete here: a mistaken result key is rejected again at download authorization.

For large source objects, multipart upload is a transfer mechanism, not an access model. It can make interrupted uploads resumable, but the application must still own initiation, allowed key selection, completion, and abandonment policy. Keep the storage bucket private. Treat a client-reported MIME type such as application/pdf or the DOCX media type as a hint until server-side validation accepts the object for its intended workflow. This is the first explicit trade-off: multipart transfers add coordination and cleanup, so a single-part presigned upload is the better choice when files already fit the application's tested size and timeout limits.

Implement the control plane, then make it observable

Start with small interfaces. They keep storage signing, tenant authorization, and job persistence separate, which makes the dangerous boundary reviewable.

type ExportState = "queued" | "running" | "ready" | "failed" | "expired";

type ExportJob = {
  id: string;
  tenantId: string;
  requestedBy: string;
  assetIds: readonly string[];
  state: ExportState;
  resultKey?: string;
};

interface AssetCatalog {
  findOwned(tenantId: string, assetIds: readonly string[]): Promise<
    readonly { id: string; objectKey: string }[]
  >;
}

interface ExportStore {
  create(job: ExportJob): Promise<void>;
  findOwned(tenantId: string, exportId: string): Promise<ExportJob | null>;
}

interface PrivateObjects {
  signDownload(objectKey: string, expiresInSeconds: number): Promise<string>;
}
Enter fullscreen mode Exit fullscreen mode

The create handler must detect missing or foreign asset IDs before queueing. A count mismatch is enough to reject the request without revealing which IDs belong to another tenant.

async function createExport(input: {
  tenantId: string;
  actorId: string;
  assetIds: readonly string[];
  catalog: AssetCatalog;
  exports: ExportStore;
  enqueue: (exportId: string) => Promise<void>;
  newId: () => string;
}): Promise<{ exportId: string; state: "queued" }> {
  const uniqueIds = [...new Set(input.assetIds)];
  if (uniqueIds.length === 0) throw new Error("empty_export");

  const owned = await input.catalog.findOwned(input.tenantId, uniqueIds);
  if (owned.length !== uniqueIds.length) throw new Error("asset_not_available");

  const exportId = input.newId();
  await input.exports.create({
    id: exportId,
    tenantId: input.tenantId,
    requestedBy: input.actorId,
    assetIds: owned.map((asset) => asset.id),
    state: "queued",
  });
  await input.enqueue(exportId);
  return { exportId, state: "queued" };
}
Enter fullscreen mode Exit fullscreen mode

Keep download issuance boring. Look up by both tenant and export ID, require ready, and sign the server-owned result key. Five minutes is a concrete starting policy in this example, not a universal optimum; choose the real value from archive size, user network conditions, and the damage window for a leaked URL.

async function issueExportDownload(input: {
  tenantId: string;
  exportId: string;
  exports: ExportStore;
  objects: PrivateObjects;
}): Promise<{ url: string; expiresInSeconds: number }> {
  const job = await input.exports.findOwned(input.tenantId, input.exportId);
  if (!job || job.state !== "ready" || !job.resultKey) {
    throw new Error("export_not_ready");
  }

  const expiresInSeconds = 300;
  const url = await input.objects.signDownload(job.resultKey, expiresInSeconds);
  return { url, expiresInSeconds };
}
Enter fullscreen mode Exit fullscreen mode

Now instrument transitions, not just HTTP responses. Emit one structured event when a job changes state. Useful dimensions are deliberately bounded: state, archive format, and worker version. Put tenant and export IDs in trace fields or logs where access is controlled, rather than metric labels that can explode cardinality.

Track queue delay, build duration, source-object count, source bytes, result bytes, and failure reason. Alert on user harm: old queued jobs, a sustained rise in failed jobs, or ready jobs whose result object cannot be found. A raw count of 500 responses misses stalled workers because no browser request is active while the queue ages.

One crisp dashboard row is enough to begin: queue age at the top, completion and failure rates next, then build-duration and byte distributions. Link each failed transition to a trace by export ID. Do not log signed URLs. An export that remains queued while HTTP success rates look perfect is the concrete pitfall this layout exposes; request-only monitoring cannot see work that nobody has started.

Quiet failures count.

Test the boundaries that matter

The happy path is the least interesting test. Exercise cross-tenant asset IDs, duplicate IDs, deletion after manifest creation, a worker retry after partial output, expiry before a slow download begins, and two concurrent requests for the same export. Assert that no response distinguishes “belongs to another tenant” from “does not exist.”

Then test the browser boundary. Direct uploads need an explicit CORS policy for the application origin and methods the browser will use; CORS does not replace authorization. Multipart tests should cover an interrupted part, repeated completion, and abandoned-upload cleanup. Archive tests should verify deterministic entry naming and reject names that could escape a destination directory when extracted.

Deployment deserves one practical rule: introduce new job states and worker behavior in a backward-compatible order. Deploy readers that tolerate the new state before writers emit it. Roll back workers without making queued manifests unreadable.

Compliance labels do not erase this work. FedRAMP is a US government-wide program for security assessment, authorization, and continuous monitoring of cloud products and services. If that regime applies, the system boundary and evidence requirements need dedicated review; a storage feature name alone cannot establish compliance.

Limits of the bundle choice

The bundle approach has real limitations. It duplicates data temporarily, adds queue latency, requires retention cleanup, and produces a stale snapshot. It is not a good fit when the user needs a live view or two files; per-object links are simpler there. Direct browser upload also has a boundary: use an application proxy instead when the server must transform or inspect the byte stream synchronously before accepting it, and accept the proxy's bandwidth and scaling cost as part of that decision.

No universal winner exists.

For a tenant-wide product catalog, those costs buy a clearer contract: one authorized snapshot, one observable job, one expiring artifact. Set explicit limits on asset count and total bytes, expire result objects, and make regeneration a new export ID. That is the condition boundary. No vendor choice fixes a missing one.

Sources

Top comments (0)