# Protected File Transfer A small PHP 8.3 web module that replaces FTP for one trusted user or a very small fixed set of users. The design is intentionally simple: server-rendered pages, filesystem-first storage, and a narrow security boundary. ## User Guide ### What this is for Use this app when you want a browser-based replacement for FTP on web hosting, but only for a trusted operator and only inside one approved file area. ### What is available now - Secure sign-in and sign-out - One-time initial provisioning of the trusted username/password - Protected shell page - Protected file browser for the approved root area - Breadcrumb navigation inside the approved root - Single-file upload into the approved root - Authorized file download through PHP - Rename for files and folders inside the approved root - Delete for files and folders inside the approved root - Append-only audit logging outside the web root ### First-time setup On the first launch after deployment, open the setup page in the browser and create the initial trusted account. If you are working in a local environment with PHP CLI available, the optional bootstrap script is still present: ```bash php bin/setup-auth.php ``` The web setup is the supported server-side flow for OVHcloud-style deployments without CLI access. It creates the protected runtime auth config outside the web root and then disables itself. ### Normal use 1. Open `login.php`. 2. Sign in with the trusted username and password. 3. Use the protected shell page to reach the file browser. 4. Upload, download, rename, or delete only inside the approved root area. 5. Sign out when done. ### Important user-facing rules - Do not expect public file links. - Do not expect inline file editing. - Do not expect bulk operations. - Do not expect a full admin console. ## Technical Documentation ### Validated decisions - PHP 8.3 is the target runtime. - The UI is server-rendered HTML, not a SPA. - The app uses explicit entry scripts rather than mandatory framework routing. - The deployment target is OVHcloud on an Apache-like webserver. - `public/` is the document root. - `app/`, `config/`, and `storage/` stay outside the web root. - Files are stored on the filesystem, not in a database. - Downloads must go through PHP authorization checks, not direct public file paths. - The MVP uses a single trusted user or a very small fixed user set. - The initial auth config is created once with a first-launch web setup flow. - A CLI provisioning script remains available for local or fallback use. - Rewrite rules are optional, not required for the MVP. ### Directory layout - `public/` - Public entry scripts only. - Expected Apache document root. - `app/` - Private application logic. - `config/` - Private configuration files. - `config/auth.local.php` is generated by provisioning and should stay out of version control. - `storage/` - Private file storage root for managed content. ### Security model - Passwords are stored as hashes only. - Sessions are hardened with `HttpOnly`, `SameSite=Lax`, and strict mode. - Login regenerates the session ID. - Logout destroys the session and clears the cookie. - Idle timeout is enforced. - CSRF tokens protect state-changing forms. - Path traversal is blocked server-side. - Requests outside the approved root are rejected. - Direct web access to storage must be blocked by deployment layout, not by obscurity. ### Current implementation state Implemented: - `app/bootstrap.php` - `app/auth.php` - `app/path.php` - `config/auth.php` - `bin/setup-auth.php` - `public/index.php` - `public/login.php` - `public/logout.php` - `public/app.php` - `public/files.php` - `public/upload.php` - `public/download.php` - `public/rename.php` - `public/delete.php` - `app/audit.php` Current behavior: - The app refuses normal use until `config/auth.local.php` exists. - The one-time web setup page creates that local auth config. - The protected shell is available after login. - The file browser supports approved-root browsing and file actions inside the allowed root. - Upload, download, rename, delete, and audit logging are implemented with server-side validation. - Denied access, traversal, and relevant security events are audited. ### Deployment notes for OVHcloud / Apache - Point the Apache document root at `public/`. - Keep private code and storage outside the document root. - Do not require `.htaccess` for core security. - If prettier URLs are added later, keep rewrites optional and confined to `public/`. ### QA deployment checklist 1. Deploy to a private or isolated environment first. 2. Confirm Apache points its document root at `public/`. 3. Verify `app/`, `config/`, and `storage/` are not publicly reachable. 4. Run the first provisioning flow once, with only the trusted operator present. 5. Confirm the local auth config is created outside the web root and cannot be re-run. 6. Verify login, browse, upload, download, rename, delete, and audit logging end-to-end. 7. Only then widen exposure to broader QA access. ### Team operating instructions The coordination model for this project is: 1. Product Owner defines the MVP scope and acceptance criteria. 2. Architect turns the scope into the simplest secure deployment and code design. 3. Developer implements one functionality at a time. 4. Test Creator writes test cases after the functionality is defined. 5. Test Executor validates the implementation. 6. Reviewer checks correctness, security, and scope fit. Additional working rules: - Keep the work sequential by feature. - Do not start the next feature until the current one is stable enough. - Document agent actions in markdown files under `.agent/`. - Keep generated documentation traceable with provenance comments. ### Deferred beyond MVP - Bulk or multi-file workflows. - Direct file-editing workflows. - Public file links. - Inline previews. - Archive-based download bundles. - A full admin console. ## Notes - This repository is intentionally small and conservative. - The safest MVP path is a private, authenticated, filesystem-backed tool with no public file exposure. - If the trusted user set grows later, access control should be revisited before adding new features.