Files Domain

Overview#

An investigator needs to attach a 2 GB video file, a collection of scanned documents, and a forensic disk image to an active case. Routing files of that size through an application server is slow, fragile, and expensive. The Files domain solves this with a two-phase upload: the client requests a pre-signed URL directly from cloud storage, uploads the file without any server in the middle, and then registers the completed upload with the platform. The result is fast, reliable uploads regardless of file size, with full metadata tracking and tenant-isolated storage.

Download access follows the same pattern. Authorised users receive a time-limited pre-signed URL that bypasses the application server for retrieval while still enforcing access control through the URL expiry mechanism.

Key Features#

Two-phase upload workflow with pre-signed URL generation for direct-to-storage transfers
File metadata tracking including name, path, size, MIME type, and creator attribution
Tenant-isolated storage with organisation-specific prefixes to prevent cross-tenant access
Pre-signed download URL generation with time-limited access (1 hour expiry)
File listing and retrieval with tenant scoping
MIME type validation and size tracking
Upload URL expiry (15 minutes) to limit window for unauthorised use

Use Cases#

Uploading large investigation evidence files directly to cloud storage without server proxying, preserving performance at scale
Managing document attachments for investigations and court filing packages
Generating temporary download links for authorised file access that expire automatically
Organising files in tenant-isolated virtual folder hierarchies that prevent cross-organisation access

Industry Context#

Digital forensics teams working on serious crime cases regularly handle files in the tens or hundreds of gigabytes: disk images, CCTV footage, and database exports. Pre-signed URL uploads make these transfers practical at operational scale. Court filing systems require document attachments with metadata provenance. Intelligence agencies use tenant-isolated storage to ensure that files belonging to one national agency cannot be accessed by another tenant sharing the same platform instance. Utility companies attach large sensor log files to maintenance work orders through the same mechanism.

Integration#

The Files domain integrates with User for creator tracking and access control, Organisation for tenant isolation, Evidence for file attachments, Investigation for document management, and Report for attachments. File metadata is stored in PostgreSQL; the actual file bytes reside in cloud object storage.

Open Standards#

AWS S3 Pre-Signed URL API (S3-compatible, AWS Signature Version 4): Upload and download pre-signed URLs are generated using the S3-compatible Cloudflare R2 API, allowing clients to transfer file bytes directly to object storage without routing through the application server.
RFC 7233 (HTTP Range Requests): The streaming endpoint explicitly implements RFC 7233 byte-range parsing, returning HTTP 206 Partial Content responses so that large video and forensic files can be resumed or seeked without re-downloading from the start.
IANA Media Types (MIME): Every file record carries a MIME type that is validated against a controlled allowlist; untrusted types are coerced to application/octet-stream and forced to Content-Disposition: attachment to prevent cross-site scripting via uploaded content.
ISO 8601: Pre-signed URL expiry timestamps and all audit-log entries are serialised in ISO 8601 format, ensuring interoperability with downstream forensic and case-management tooling.
OAuth 2.0 (Scoped Bearer Tokens): Every file endpoint enforces a named OAuth 2.0 scope (files:read / files:export) before generating URLs or streaming content, integrating with the platform's central authorisation server.
GraphQL (June 2018 specification): File metadata queries, upload-URL generation, and upload-completion mutations are all exposed through a typed GraphQL schema, allowing clients to request only the fields they need.
W3C Cross-Origin Resource Sharing (CORS) / Cross-Origin-Resource-Policy (CORP): Streaming and download endpoints emit controlled Access-Control-Allow-Origin, Access-Control-Expose-Headers, and Cross-Origin-Resource-Policy headers so that video and PDF embeds work securely from authorised origins without exposing files to arbitrary third-party sites.
RFC 4122 (UUID): All file, tenant, user, and version identifiers are Version 4 UUIDs, guaranteeing globally unique, collision-resistant references across distributed storage and database records.

Last Reviewed: 2026-02-05 Last Updated: 2026-04-14