Safebucket Documentation

Safebucket is an open-source file-sharing platform designed so that files never touch the application server. Instead, clients upload and download directly to/from S3-compatible storage using presigned URLs. The system focuses on managing metadata, access control, and audit logging while allowing users to provide their own identity provider and infrastructure.

Key architectural features include:

• SSO-first: User authentication is handled via OIDC providers.
• Bucket-scoped access: Permissions are managed via buckets with roles: owner, contributor, and viewer.
• Swappable Infrastructure: Components for storage, databases, events, caching, and notifications can be replaced based on preference (e.g., AWS S3 vs. MinIO, NATS vs. SQS).

Safebucket on AWS consists of a basic infrastructure layer and an optional ECS deployment layer.

Basic Infrastructure:

• S3 Bucket: Primary storage with AES256 encryption and SQS event notifications.
• RDS PostgreSQL (15.4): Database with GP3 encrypted storage and automated backups.
• ElastiCache Redis (7): Caching and session storage with user-based authentication.
• SQS Queues: Dedicated queues for S3 events and general application notifications.
• Networking: Default VPC with private subnets for RDS and Redis; Security Groups restricting access to ports 5432 (Postgres) and 6379 (Redis).

ECS Deployment (Fargate):

• Application Load Balancer: Handles public traffic (ports 80, 443, 8025).
• Service Discovery: Used for internal communication between services.

Safebucket provides a robust authentication system featuring:

• Local Authentication (Argon2id hashing)
• OIDC Integration (Google, GitHub, Keycloak, etc.)
• LDAP/Active Directory Integration
• Role-Based Access Control (RBAC)
• Encrypted tokens: HS256-signed JWS wrapped in JWE
• Server-tracked sessions: Session IDs are validated against a cache on every request for immediate logout/revocation.

Safebucket supports multiple activity providers to store and query user activity logs (such as file uploads, downloads, and deletions).

• Filesystem: Uses local file-based storage with the Bleve embedded search engine. It requires no external services and is recommended for simple, light setups with a small footprint.
• Loki: Uses Grafana Loki for log aggregation. It is recommended for scalable or production-grade deployments.

Safebucket implements a secure-by-default AWS architecture:

• Network Isolation: RDS and ElastiCache are placed in private subnets with no public internet access; security groups restrict access to VPC CIDR blocks.
• Data Protection: S3 uses AES256 server-side encryption and blocked public access. RDS and ElastiCache use encryption at rest and in transit (TLS).
• Access Control: The application uses IAM roles instead of static access keys. Redis uses user-based authentication.

Safebucket uses built-in roles to manage permissions. Role assignment happens automatically based on the authentication method used:

• Local Users: Assigned User role by default.
• OIDC Users: Assigned User role by default.
• Admin User: Assigned Admin role automatically.

Built-in Roles:

• Guest: Read-only access to shared resources.
• User: Can create and share buckets, and upload files.
• Admin: Full system access and user management.

SafeBucket supports any S3-compatible storage provider through the generic s3 storage type, provided the provider supports presigned PUT policies and CORS.

Note: Dedicated storage types (RustFS, MinIO, AWS S3, GCP) are preferred over the generic S3 type because they are event-driven, providing real-time notifications for uploads/deletions and more efficient trash management via lifecycle policies.

Safebucket uses event providers for asynchronous processing of notifications, file operations, and storage events.

• Production: Use NATS JetStream, Google Cloud Pub/Sub, or AWS SQS.
• Development/Testing: Use the Memory provider (in-process event queue using Go channels; supports single-instance only).
• Azure: Azure Storage Queues is available for Azure-native messaging.

Safebucket allows sharing files, folders, or entire buckets via public links. Recipients do not need a Safebucket account to download.

Available Options:

• Scopes: Individual files, a folder, or a whole bucket.
• Restrictions: Optional expiration date, maximum view count, and password protection.
• Reverse Share: Available for folder and bucket shares; allows external users to upload files back to the system. This can be further restricted by maximum upload count and per-file size limits.

Safebucket provides several deployment templates depending on the environment:

• local/full: Full stack via Docker Compose (PostgreSQL, RustFS, Valkey, NATS, Loki, Mailpit).
• local/lite: Minimal Docker Compose setup.
• dev: Infrastructure services only (Safebucket run from source).
• aws: Terraform modules for ECS Fargate, RDS, ElastiCache, S3, SQS, and CloudWatch.