s3mover/docs/PRD.md

# Product Requirements Document

## Product

**Name:** S3 Mover  
**Document version:** 0.1  
**Date:** 2026-03-26  
**Status:** Draft  

## Overview

S3 Mover is a web application for securely managing files across one or more S3-compatible buckets. The system provides a React frontend and Go backend, with SQLite as the system of record for users, bucket access, invitations, audit logs, and authentication-related metadata.

The existing proof of concept demonstrated that a Go backend can enumerate files and perform upload, download, and delete operations against S3-compatible object storage. This product extends that proof of concept into a production-oriented multi-user application with user management, per-user bucket credentials, invitation-based onboarding, mandatory 2FA, audit logging, and Docker deployment.

## Problem Statement

The proof of concept is functionally viable, but it is not suitable for real users because:

- There is no user management or role-based access control.
- Storage credentials are configured globally instead of per user and per bucket.
- There is no secure onboarding flow.
- There is no multi-factor authentication.
- There is no audit trail for file operations.
- Sensitive bucket configuration is not yet modeled as protected server-side data.

The product must evolve into a secure internal application that allows administrators to manage users and user-specific bucket credentials, while allowing standard users to operate only on the buckets assigned to them.

## Goals

- Provide secure user authentication using email, password, and TOTP-based 2FA.
- Support administrator-led invitation onboarding via Resend email.
- Allow administrators to manage users and assign one or more bucket configurations to each user.
- Keep all sensitive bucket credentials server-side only.
- Provide file browsing and upload, download, and delete capabilities for the assigned bucket(s) of a logged-in user.
- Record auditable logs of bucket operations.
- Persist system data in SQLite.
- Package the application for Docker deployment.

## Non-Goals

- End-user self-registration.
- SSO, SAML, or OAuth identity providers in the first release.
- Bucket creation or infrastructure provisioning.
- Advanced IAM policy editing or credential rotation workflows.
- Object versioning, lifecycle management, or ACL management.
- Bulk file operations beyond single upload, download, and delete.
- Fine-grained per-prefix authorization within a bucket in the first release.

## Users and Roles

### Administrator

The administrator manages the system and has access to all administrative functions.

Capabilities:

- Log in with email, password, and TOTP
- View all registered users
- View details for an individual user
- Invite a new user by email
- Delete a user account
- Add one or more bucket credential sets to a user
- Remove a bucket credential set from a user
- View audit logs for all file operations

### Standard User

The standard user interacts only with buckets assigned to their account.

Capabilities:

- Complete invitation onboarding
- Set a strong password
- Enroll a TOTP authenticator during first-time setup
- Log in with email, password, and TOTP
- View the list of assigned buckets in a left sidebar
- Select a bucket and view its contents
- Upload, download, and delete files within assigned buckets

## Key User Journeys

### 1. Administrator Invites a User

1. Administrator logs into the application.
2. Administrator navigates to the user management page.
3. Administrator creates a new user by entering at least an email address.
4. System creates a pending user record and a time-limited invitation token.
5. System sends an invitation email through Resend.
6. Email contains a secure link to the onboarding page.

### 2. User Accepts Invite and Creates Credentials

1. User clicks the invitation link.
2. System validates the invitation token.
3. User is prompted to set a strong password.
4. User is required to enroll a TOTP authenticator before activation completes.
5. User confirms setup by entering a valid TOTP code.
6. System activates the account and marks the invitation as consumed.

### 3. User Logs In

1. User enters email address and password.
2. System validates credentials.
3. User is prompted for a TOTP code.
4. System issues a JWT after successful second-factor verification.
5. User is redirected to the main application.

### 4. User Operates on a Bucket

1. User logs in successfully.
2. User sees a sidebar listing assigned buckets.
3. User selects a bucket.
4. System displays the bucket name and endpoint at the top of the page.
5. System shows a paginated file list with 15 items per page.
6. User uploads, downloads, or deletes files.
7. System records an audit log entry for each file operation.

### 5. Administrator Manages Bucket Credentials for a User

1. Administrator navigates to a user detail page.
2. Administrator adds a bucket credential set for that user.
3. Administrator enters:
   - AWS access key ID
   - AWS secret access key
   - AWS region
   - bucket name
   - S3-compatible endpoint
4. System stores those credentials securely in SQLite.
5. User gains access to that bucket after next authorized fetch or session refresh.
6. Administrator may remove a bucket configuration from the user later.

## Functional Requirements

## FR-1 Authentication

- The system shall support login using email address and password.
- The system shall require TOTP as a second factor for all users.
- The system shall issue JWTs for authenticated API access.
- The system shall reject access to protected routes without a valid JWT.
- The system shall support logout by invalidating the client session.

## FR-2 Invitation and Onboarding

- Only an administrator may create a new user.
- Creating a user shall generate an invite email sent through Resend.
- The invite shall contain a secure, time-limited, single-use token.
- The invite flow shall require the user to set a strong password.
- The invite flow shall require TOTP setup before account activation.
- An invited user shall not be able to log in until onboarding is complete.

## FR-3 User Management

- The administrator shall have a page listing all users.
- The user list shall include at minimum email address, status, role, created date, and last login date if available.
- The administrator shall be able to click into a user detail page.
- The administrator shall be able to delete a user account.
- Deleting a user shall revoke future access immediately.

## FR-4 Bucket Assignment

- A user shall be assigned at least one bucket credential set to access storage.
- A user may have multiple bucket credential sets.
- Each bucket credential set shall be unique to the user and shall not be shared by design.
- The administrator shall be able to create, view metadata for, and remove bucket assignments for a user.
- Sensitive values such as access keys and secrets shall not be shown back to the browser after creation, except where explicitly required for a masked administrative UX.

## FR-5 Bucket Browsing and File Operations

- A logged-in user shall see assigned buckets in a left sidebar.
- Selecting a bucket shall show:
  - bucket name
  - endpoint
  - paginated file listing
- Pagination shall be fixed at 15 items per page.
- The system shall support upload, download, and delete operations for files in the selected bucket.
- The system shall support S3-compatible providers, not just AWS S3.

## FR-6 Audit Logging

- The system shall log all user file operations.
- Each log entry shall include at minimum:
  - timestamp
  - user ID
  - user email
  - bucket identifier
  - file key
  - operation type
- The operation type shall support at minimum:
  - upload
  - download
  - delete
- Only administrators shall be able to view logs.

## FR-7 Administrative Access Control

- Only administrators shall be able to:
  - invite users
  - view all users
  - view user details
  - manage user bucket assignments
  - delete users
  - view audit logs

## FR-8 Deployment and Runtime

- The application shall run in Docker.
- The backend shall be implemented in Go.
- The frontend shall be implemented in React.
- SQLite shall be the primary application database.

## Security Requirements

- Sensitive bucket credentials shall never be sent to the browser.
- Sensitive bucket credentials shall never be included in JWT payloads.
- JWTs shall be signed server-side with a configurable secret or private key.
- Passwords shall be stored only as strong salted hashes.
- TOTP secrets shall be stored securely server-side.
- Invite tokens shall be stored hashed or otherwise protected server-side and shall expire.
- The application shall enforce HTTPS in deployed environments.
- The application shall implement CSRF protections if JWTs are stored in cookies.
- The application shall implement rate limiting or equivalent brute-force protection for authentication endpoints.
- All sensitive configuration shall be provided through environment variables or secret injection at runtime.
- Administrative and user actions shall be authorized server-side for every request.

## UX Requirements

### Authentication

- The application shall provide:
  - login page
  - TOTP challenge page
  - invitation acceptance page
  - password setup form
  - TOTP enrollment page with QR code and manual key fallback

### Main User Application

- The main authenticated layout shall include:
  - left sidebar for bucket selection
  - top area showing selected bucket name and endpoint
  - file listing view
  - pagination controls
  - upload action
  - download action
  - delete action

### Administration

- The administrator area shall include:
  - user list page
  - user detail page
  - add bucket assignment flow
  - audit log page

## Data Model Requirements

The following logical entities are required.

### users

- id
- email
- role
- status
- password_hash
- totp_secret
- totp_enabled
- invited_at
- activated_at
- last_login_at
- created_at
- updated_at

### invitations

- id
- user_id
- email
- token_hash
- expires_at
- consumed_at
- created_by_user_id
- created_at

### user_bucket_credentials

- id
- user_id
- display_name
- aws_access_key_id
- aws_secret_access_key
- aws_region
- s3_bucket
- aws_endpoint_url
- use_path_style
- created_at
- updated_at

### audit_logs

- id
- user_id
- user_email
- bucket_credential_id
- bucket_name
- endpoint
- file_key
- operation
- created_at
- request_ip
- user_agent

### sessions or token metadata

Implementation may use stateless JWTs only, but the design should allow optional storage for token revocation, refresh sessions, or login tracking if needed.

## Recommended Status Values

### User status

- invited
- active
- disabled

### Role

- admin
- user

### Audit operation

- upload
- download
- delete

## API Requirements

The final API shape may change, but the following resources are expected.

### Authentication

- `POST /api/auth/login`
- `POST /api/auth/totp/verify`
- `POST /api/auth/logout`
- `GET /api/auth/me`

### Invitations

- `POST /api/admin/users/invite`
- `GET /api/invitations/:token`
- `POST /api/invitations/:token/accept`

### Administration

- `GET /api/admin/users`
- `GET /api/admin/users/:userId`
- `DELETE /api/admin/users/:userId`
- `POST /api/admin/users/:userId/buckets`
- `DELETE /api/admin/users/:userId/buckets/:bucketCredentialId`
- `GET /api/admin/audit-logs`

### User bucket access

- `GET /api/me/buckets`
- `GET /api/me/buckets/:bucketCredentialId/files?page=1&pageSize=15`
- `POST /api/me/buckets/:bucketCredentialId/files`
- `GET /api/me/buckets/:bucketCredentialId/files/:key`
- `DELETE /api/me/buckets/:bucketCredentialId/files/:key`

## Business Rules

- Every non-admin user must authenticate with password plus TOTP.
- An invitation may only be used once.
- A bucket credential set belongs to exactly one user.
- A user may have zero bucket assignments during setup or after administrative changes, but a user must have at least one assignment to perform storage operations.
- The server shall resolve storage access from the selected bucket credential ID and not from any client-supplied raw credential values.
- The browser may know a bucket display name, bucket name, and endpoint, but not secret credentials.

## Technical Requirements

### Backend

- Go HTTP API
- SQLite persistence
- JWT authentication middleware
- Password hashing using a modern algorithm such as Argon2id or bcrypt
- TOTP support using a standard authenticator-compatible implementation
- Resend integration for invitation emails
- S3-compatible client abstraction for storage operations
- Audit log persistence for all storage mutations and downloads

### Frontend

- React application
- Authenticated routing
- Admin-only views and user views
- Sidebar bucket navigation
- Paginated bucket file list with page size fixed to 15
- Forms for onboarding, login, TOTP verification, user management, and bucket assignment

### Infrastructure and Deployment

- Single Docker image or Docker Compose-based local runtime
- Persistent storage volume for SQLite database
- Environment-based configuration for JWT secret, Resend API key, and bootstrap admin settings

## Reporting and Logging Requirements

- Application logs shall capture authentication failures, invitation events, administrative changes, and storage operation failures.
- Audit logs shall be queryable by administrators.
- Audit log views should support filtering by:
  - date range
  - user
  - bucket
  - operation

## Constraints

- SQLite is the required datastore for the initial production-ready version.
- The frontend must not directly communicate with S3-compatible storage using raw bucket credentials.
- All storage operations must be proxied through the Go backend.
- Sensitive settings must remain server-side.

## Assumptions

- The first release supports one administrator bootstrap path via environment configuration, migration seed, or initial setup command.
- Invitation emails will be transactional emails sent through Resend.
- TOTP apps such as 1Password, Google Authenticator, or Authy are acceptable authenticators.
- The application is intended for trusted organizational users rather than open public sign-up.

## Open Questions

- How should the first administrator account be bootstrapped?
- Should administrators also be able to perform bucket operations, or only manage users and logs?
- Should deleted users be hard-deleted or soft-deleted for audit retention?
- Should bucket secrets be encrypted at rest in SQLite using an application-level encryption key?
- Should JWTs be short-lived access tokens only, or should the system also support refresh tokens?
- What are the password strength rules beyond “strong password”?
- What is the invite expiration window?
- Should audit logs include failed file operations in addition to successful ones?
- Is account disablement required in addition to deletion?
- Are per-user bucket display names needed in the UI, or is raw bucket name sufficient?

## Success Criteria

- Administrators can invite, onboard, and manage users without manual database changes.
- Standard users can access only their assigned buckets.
- Bucket credentials never appear in browser network payloads or rendered UI.
- Users must complete TOTP enrollment before account activation.
- All file uploads, downloads, and deletes are auditable by administrators.
- The application runs successfully in Docker with SQLite persistence.

## Proposed Delivery Phases

### Phase 1: Identity and Administration Foundation

- SQLite schema and migrations
- bootstrap administrator
- login, password hashing, JWT issuance
- TOTP enrollment and verification
- invite flow with Resend
- admin user list and user detail pages

### Phase 2: Bucket Assignment and Secure Access

- per-user bucket credential storage
- admin create and remove bucket credentials
- authenticated bucket list API
- user sidebar and selected-bucket view
- secure server-side storage operations using assigned credentials

### Phase 3: Auditability and Production Hardening

- audit log persistence and admin log viewer
- Docker packaging
- operational logging and error handling
- rate limiting and security hardening
- UX polish and edge-case handling