File Uploads and Object Storage

Pathrule3 Rules • 1 Memory • 1 Skill

File uploads and object storage form an asynchronous trust boundary spanning authorization, transfer, validation, malware scanning, metadata, lifecycle, and download delivery. This bundle defines bounded upload intents, opaque keys, quarantine and publish states, safe content handling, and cleanup. Unlike REST API Design, it owns blob security and lifecycle rather than the general shape and semantics of HTTP resources.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

test-file-upload-pipeline

src/

api/

Create a bounded upload intent before transfer

Authorize every download and serve safe content metadata

uploads/

Quarantine bytes until independent validation completes

An upload is a two-phase resource

Rules

Create a bounded upload intent before transfer/src/apihighstrictThe server authorizes owner, purpose, size, content class, object key, operation, and expiry before any client writes bytes.

1	The server authorizes owner, purpose, size, content class, object key, operation, and expiry before any client writes bytes. A broad presigned request or shared storage credential lets clients choose arbitrary keys, overwrite objects, exceed quotas, or upload a type the product never intended to process. Enforce this boundary in /src/api so invalid work stops before it reaches another subsystem or creates an externally visible side effect.
2
3	- Generate an opaque server-owned object key that includes no filename, email, tenant secret, or trusted path fragment from the client.
4	- Bind the upload authorization to one tenant, subject, purpose, object key, method, maximum size, allowed content class, and short expiry.
5	- Reserve quota and an upload record before transfer, then release it when the intent expires or validation fails.
6	- Use multipart upload only through a tracked session with bounded part count, total size, completion, abort, and cleanup behavior.
7
8	Verification: Attempt key changes, method changes, oversized bodies, expired intents, cross-tenant reuse, duplicate completion, and abandoned multipart sessions; confirm storage and quota remain correct.

Quarantine bytes until independent validation completes/src/uploadshighstrictNew objects remain unavailable to users and processors until server-side type, structure, policy, and malware checks pass.

1	New objects remain unavailable to users and processors until server-side type, structure, policy, and malware checks pass. Filename extensions, Content-Type headers, and browser previews are attacker-controlled hints and cannot establish that content is safe to serve or parse. Enforce this boundary in /src/uploads so invalid work stops before it reaches another subsystem or creates an externally visible side effect.
2
3	- Read the stored bytes from quarantine and validate signature, parseability, declared class, size, decompression limits, and product-specific structure.
4	- Run malware or content-disarm controls appropriate to the allowed type without sending sensitive files to an unapproved external scanner.
5	- Process risky formats in an isolated, resource-bounded worker with no ambient credentials or unnecessary network access.
6	- Publish by changing durable application state or copying to a delivery boundary only after every required check succeeds.
7
8	Verification: Upload polyglots, mismatched extensions and signatures, malformed archives, decompression bombs, scanner timeout, and clean fixtures; confirm only clean objects become addressable.

Authorize every download and serve safe content metadata/src/apihighstrictObject possession and object-store URLs never replace application authorization, response isolation, and content disposition policy.

1	Object possession and object-store URLs never replace application authorization, response isolation, and content disposition policy. A predictable key or leaked long-lived URL can bypass tenant access, while active content rendered inline can execute in the application's trusted origin. Enforce this boundary in /src/api so invalid work stops before it reaches another subsystem or creates an externally visible side effect.
2
3	- Resolve the object through application metadata, authorize the current principal and tenant, then issue a narrow short-lived download or stream it through the service.
4	- Set a server-controlled safe filename and Content-Disposition according to whether the type may render inline.
5	- Serve user-controlled active content from an isolated origin with restrictive headers rather than the application's authenticated origin.
6	- Log access with object and subject identifiers without placing secret URLs or personal filenames in routine telemetry.
7
8	Verification: Try cross-tenant IDs, guessed keys, revoked ownership, expired links, header injection filenames, and active HTML or SVG; confirm denial and origin isolation.

Memories

An upload is a two-phase resource/src/uploadsObject storage can contain bytes before the application has validated, accepted, or made them visible, so existence is not completion.

1	Object storage can contain bytes before the application has validated, accepted, or made them visible, so existence is not completion. Track intent-created, transferring, uploaded, validating, ready, rejected, expired, and deleted states with idempotent transitions.
2
3	Keep object events as evidence that may trigger validation, not proof that the intended principal completed the intended upload. Reconcile records and storage when events are missing, duplicated, or reordered. Expose only ready objects to product queries and schedule cleanup for every terminal non-ready state. Keep the decision explicit at /src/uploads; moving it into an incidental caller makes behavior depend on which route happened to execute first.
4
5	See /src/jobs for reconciliation and scanning and /src/api for download authorization. That related boundary consumes this decision and carries the evidence that proves it still holds.

Skills

test-file-upload-pipeline/rootTest file uploads across authorization, transfer, validation, scanning, publication, delivery, and cleanup failure paths.

1	---
2	name: test-file-upload-pipeline
3	description: Test file uploads across authorization, transfer, validation, scanning, publication, delivery, and cleanup failure paths.
4	---
5
6	# Test File Upload Pipeline
7
8	Run this procedure whenever the governed surface changes or its operational evidence becomes stale.
9
10	1. Create clean, malformed, oversized, mislabeled, polyglot, active-content, archive-bomb, malware-test, duplicate-name, and zero-byte fixtures for every allowed class.
11	2. Attempt cross-tenant keys, expired and replayed intents, changed methods, multipart abuse, concurrent completion, and quota races through the real storage integration.
12	3. Inject storage, event, parser, scanner, worker, database, and publish failures before and after each durable transition, then replay events and jobs.
13	4. Verify only ready objects are downloadable, active content is isolated, rejected and abandoned bytes expire, quotas reconcile, and audit events reveal no secret URL or personal filename.
14
15	Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory.

Why this pattern

Agents trust filenames and MIME headers, publish objects before scanning, put user names into storage keys, or issue broad presigned URLs with no ownership or lifecycle state.

Built for Backend teams accepting user files into cloud or self-hosted object storage.

Keeps your assistant from:

Executable or deceptive content published from client-declared metadata
Cross-tenant overwrite or download through predictable object keys
Abandoned multipart uploads and quarantined objects retained forever

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25