DEV Community

XenonCross2718
XenonCross2718

Posted on

Object Storage API Explained — 3 Direct Browser Validation Boundaries (2026)

Short answer: let the application authorize an upload, let the browser send the bytes directly to object storage with a narrowly scoped and expiring capability, and let a verified callback trigger validation before the file can be downloaded.

For an edtech system accepting private assignments, the least complex safe design has three boundaries: intent, bytes, and acceptance. The application owns intent. Object storage receives bytes. A callback starts acceptance checks. An expiring download link is issued only for an accepted object, never merely because an upload request succeeded.

That distinction matters more than the choice of library. A browser success screen proves very little: it doesn't prove that the expected learner uploaded the expected content, that the stored object matches the declared size, or that a later download should be allowed. Treating upload completion as authorization quietly turns a convenient data path into an access-control path.

How should browser uploads handle auth validation and storage callbacks?

Start with an authenticated application request that describes an upload intent: tenant, learner, assignment, declared media type, declared byte length, and a client-generated idempotency key. The backend checks enrollment, assignment state, quota, and policy before creating an opaque object key. The browser must not choose a meaningful path such as schools/7/students/42/report.pdf; names leak context and make accidental cross-tenant reuse easier to miss in review.

If authorization passes, the backend returns a short-lived upload capability tied to that object key and the intended write operation. The exact signing mechanism is an implementation choice. The invariant is narrower: possession should permit one bounded action for a bounded time, not general access to a bucket or tenant. Keep permanent storage credentials out of browser code.

Then the browser transfers the bytes directly. A successful transfer moves the workflow to uploaded, not ready. Storage metadata or a callback can provide evidence that an object now exists, but acceptance still belongs to the application. The validation worker compares the stored size and content type with policy, performs whatever file inspection the institution requires, and changes the record to ready only after those checks pass.

Finally, a learner or instructor asks the application for a download. The application repeats the authorization decision against current membership and assignment rules, then creates an expiring read capability for the opaque key. Don't persist that signed link as if it were a durable file URL. Its expiry is part of the security model.

This is a small state machine, not a pair of URLs:

State Evidence available Allowed next action
authorized User and assignment policy passed Issue one upload capability
uploaded Storage reports an object at the bound key Queue validation
ready Required validation passed Issue expiring download capabilities
rejected Policy or validation failed Deny download and apply retention policy

Keep authorized records short-lived. If the browser disappears, the system can expire the intent without guessing whether a transfer happened. This also gives support staff a useful answer to “where is the assignment?” without exposing storage internals.

The callback is evidence, not authority

A callback receiver should authenticate the sender using the mechanism selected for that integration, reject stale or replayed messages, and make processing idempotent. HTTP semantics help here: RFC 9110 defines safe and idempotent methods, but an incoming notification commonly causes application work, so the receiver has to supply its own deduplication rule. Store a unique event identifier or a stable tuple such as object key plus version, and make the state transition conditional.

Return codes need deliberate meaning. 401 or 403 can represent failed callback authentication or authorization. 400 fits a malformed payload. A duplicate valid event should normally produce the same accepted outcome as the first delivery instead of creating a second validation job. Exact retry behavior depends on the event source, and I'm not sure there is one useful retry schedule across storage implementations; resolve that choice by documenting the sender's retry contract and testing it under delayed and reordered delivery.

The nasty edge case is ordering. A callback can arrive after the learner refreshes the page, two callbacks can describe the same object, and an older validation result can race a replacement upload. Bind every intent to an immutable object key or version. A worker must update the row it actually validated, with a conditional transition from uploaded to ready, rather than updating “the latest submission” by learner ID. Otherwise, a clean result for attempt one can accidentally release attempt two.

Be conservative here.

The same discipline used for OTP delivery applies: an acknowledgement means a component accepted responsibility, not that the human-visible outcome is complete. Keep separate timestamps for intent creation, observed upload, validation completion, and last download authorization. Those four moments let an operator distinguish an abandoned browser session from a delayed callback without reading private file contents.

A minimal application boundary in Python

The following code sketches the application contract, not a vendor SDK. The storage adapter creates bounded capabilities and reads authoritative object metadata. The repository owns conditional state transitions. Authentication, policy evaluation, callback verification, and file inspection remain explicit dependencies so a framework cannot blur them together.

from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from typing import Protocol
from uuid import uuid4


@dataclass(frozen=True)
class UploadIntent:
    intent_id: str
    tenant_id: str
    object_key: str
    expected_bytes: int
    media_type: str
    state: str


class Storage(Protocol):
    def create_upload_capability(
        self, object_key: str, media_type: str, expires_at: datetime
    ) -> str: ...

    def create_download_capability(
        self, object_key: str, expires_at: datetime
    ) -> str: ...

    def object_metadata(self, object_key: str) -> dict[str, object]: ...


class Intents(Protocol):
    def create_once(
        self,
        tenant_id: str,
        idempotency_key: str,
        object_key: str,
        expected_bytes: int,
        media_type: str,
    ) -> UploadIntent: ...

    def get(self, intent_id: str) -> UploadIntent: ...

    def transition(self, intent_id: str, old: str, new: str) -> bool: ...


def authorize_upload(
    *,
    tenant_id: str,
    learner_id: str,
    assignment_id: str,
    idempotency_key: str,
    expected_bytes: int,
    media_type: str,
    policy,
    storage: Storage,
    intents: Intents,
) -> dict[str, str]:
    policy.require_upload(tenant_id, learner_id, assignment_id, expected_bytes)
    object_key = f"private/{tenant_id}/{uuid4().hex}"
    intent = intents.create_once(
        tenant_id,
        idempotency_key,
        object_key,
        expected_bytes,
        media_type,
    )
    expires_at = datetime.now(timezone.utc) + timedelta(minutes=10)
    capability = storage.create_upload_capability(
        intent.object_key, intent.media_type, expires_at
    )
    return {"intent_id": intent.intent_id, "upload_capability": capability}


def accept_storage_event(
    *, intent_id: str, storage: Storage, intents: Intents, jobs
) -> bool:
    intent = intents.get(intent_id)
    metadata = storage.object_metadata(intent.object_key)
    if metadata["byte_length"] != intent.expected_bytes:
        return intents.transition(intent_id, "authorized", "rejected")
    if intents.transition(intent_id, "authorized", "uploaded"):
        jobs.enqueue_validation(intent_id)
    return True


def authorize_download(
    *, intent_id: str, actor_id: str, policy, storage: Storage, intents: Intents
) -> str:
    intent = intents.get(intent_id)
    policy.require_download(intent.tenant_id, actor_id, intent_id)
    if intent.state != "ready":
        raise PermissionError("object is not available for download")
    expires_at = datetime.now(timezone.utc) + timedelta(minutes=5)
    return storage.create_download_capability(intent.object_key, expires_at)
Enter fullscreen mode Exit fullscreen mode

There are two intentional omissions. First, the example doesn't trust a callback body for byte length; the adapter reads metadata for the bound object. Second, it doesn't infer readiness inside accept_storage_event; inspection runs asynchronously and owns that transition. In production, cap expected_bytes before creating an intent, allowlist media types, verify actual content rather than trusting a filename, and keep rejected objects unavailable while the retention process decides when to delete them.

The code also makes replacement behavior boring. A second submission gets another intent and another opaque key. It cannot overwrite the first attempt, and a late event cannot change the second row. Boring is good.

When is direct delivery worth its access-control cost?

Three broad patterns are reasonable. Proxying all bytes through the application gives one enforcement point and can simplify inspection before storage, but it consumes application bandwidth and couples large transfers to web-server timeouts. Direct browser upload reduces that delivery burden, but it requires careful capability scope, asynchronous state, callback authentication, and a second authorization check before download. A managed upload gateway may consolidate some of that machinery, but it introduces an external policy surface and migration work if its capability or event model does not map cleanly to your records.

Pattern Access-control shape Delivery shape Not suitable when
Application proxy Application evaluates and carries every write Simple browser contract, heavier backend data path Large transfers would contend with interactive API traffic
Direct to storage Application grants a narrow capability and validates later Efficient byte path, more workflow states The team cannot operate callback verification and asynchronous acceptance
Upload gateway Policy spans the application and gateway Less transfer code in the application Compliance review or portability requires one locally controlled enforcement plane

For private classroom work, direct upload is a strong fit when files are large enough to justify bypassing the application and the team can own the state machine. The catch is real: it is not suitable when policy requires the application to inspect every byte before any external storage receives it. Stick with an application proxy in that case. A gateway can fit a small team that accepts the extra trust boundary and has verified how tenant isolation, event authenticity, retention, and audit evidence map to institutional requirements.

Compliance labels do not replace this analysis. FedRAMP provides a government-wide program for security assessment, authorization, and continuous monitoring of cloud products and services, but a program or authorization status cannot decide an application's tenant model, callback replay policy, or download authorization rules. Identify the relevant regulatory and contractual requirements with counsel and security reviewers; then preserve evidence for the controls your system actually performs.

Roll out with denied downloads first

Ship the state machine before enabling browser transfer. In a test environment, create intents, inject authenticated callbacks, replay the same event, deliver events out of order, and confirm that no download capability is issued before ready. Also test an expired upload capability, a changed tenant membership, an oversized object, a mismatched media type, and two submission attempts sharing one idempotency key.

During migration, keep the old upload path available per tenant while recording state transitions and callback latency on the new path. Move a small cohort, compare accepted-object counts with created intents, and alert on intents stuck in authorized or uploaded beyond your documented service window. Logs should contain tenant and intent identifiers, policy decision codes, and event identifiers, but not signed capabilities or private filenames.

Only then enable expiring downloads. The final invariant is concise: storage possession is never enough; the application must still say who may read which accepted object, right now.

References

Further reading

Top comments (0)