README

A simple, configuration-driven PHP package to protect files and directories with a username/password login form. It's designed to be self-contained, requiring no database or external dependencies, making it easy to drop into any PHP project.

The script handles serving a file from a private directory after a user successfully authenticates. If the user is not authenticated, it presents a clean, self-contained login form.

Features

• Standalone: No database or framework required.
• Secure by Default: Uses password_hash for passwords, random_bytes for CSRF tokens, and hash_equals for timing-attack-safe comparisons.
• Configuration Driven: All settings (paths, credentials, tokens) are managed in a single PHP array.
• Rate Limiting: Basic protection against brute-force login attempts.
• Secure Session Management: Sets secure cookie flags (HttpOnly, Secure, SameSite=Strict).
• Token-based Access: Restricts access to specific URL tokens to prevent enumeration of protected files.

Requirements

• PHP 7.4 or higher.
• Composer for dependency management.

Installation

1. Clone this repository or download the files into your project.
2. Run composer install to generate the vendor/autoload.php file. The project itself has no external dependencies but follows the PSR-4 autoloading standard.

Install the package via Composer:

composer require atj4me/secure-file-downloader

Usage

1. Place the files you want to protect inside the directory you specified in private_path.

2. To access a file, use a URL like this: https://yourdomain.com/path/to/getFile.php?token=some_valid_token&file=your_file.pdf

   • token: Must be one of the tokens from your valid_tokens configuration.
   • file: The name of the file you want to access.

If the user is not authenticated, they will be presented with a login form. Upon successful login, the file will be served.

1. Directory Structure

For best security, your private files and session data should be stored outside of your public web root.

/your-project-root/
├── private/
│   └── files/
│       └── my-secret-document.pdf
├── sessions/               <-- A writable directory for session data
├── public_html/            <-- Your web server's public root
│   ├── getFile.php         <-- The public entry point for this package
│   └── vendor/             <-- Composer dependencies
├── composer.json
└── generate_hash.php       <-- The password hash generator script

2. Generate a Password Hash

Use the generate_hash.php script from your command line to create a secure hash for your password.

php generate_hash.php 'your-super-secret-password'

Output:

Password Hash:
$2y$10$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Copy the resulting hash. You will need it for the configuration in the next step.

3. Create the Entry Point (getFile.php)

This is the only file that needs to be publicly accessible. It configures and runs the downloader. Place it in your public web directory (e.g., public_html/getFile.php).

<?php

declare(strict_types=1);

// Adjust the path to the vendor directory as needed
require_once __DIR__ . '/../vendor/autoload.php';

use AtjX\SecureFileDownloader\SecureDownloader;

$config = [
    // REQUIRED: The absolute path to the directory containing your private files.
    'private_path' => __DIR__ . '/../private/files',

    // REQUIRED: Credentials for accessing the files.
    'credentials' => [
        'username' => 'admin',
        // Paste the hash you generated in the previous step
        'password_hash' => '$2y$10$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
    ],

    // REQUIRED: A list of valid tokens that will be part of the clean URL.
    // Example URL: https://your-site.com/downloads/some_valid_token/my-secret-document.pdf
    'valid_tokens' => ['some_valid_token', 'another_token'],

    // OPTIONAL: Session settings.
    'session' => [
        // A writable directory for session files, outside the web root.
        'save_path' => __DIR__ . '/../sessions',
    ]
];

try {
    $downloader = new SecureDownloader($config);
    $downloader->handleRequest();
} catch (Exception $e) {
    // In a production environment, you would log this error and show a generic error page.
    if (!headers_sent()) {
        header('HTTP/1.1 500 Internal Server Error');
    }
    error_log('SecureDownloader Error: ' . $e->getMessage());
    echo '<h1>500 Internal Server Error</h1><p>A configuration error occurred. Please check the server logs.</p>';
    exit;
}

Configuration Options

All settings are passed via the $config array to the SecureDownloader constructor.

How It Works

1. A user navigates to getFile.php?token=some_valid_token&file=my-secret-document.pdf.
2. The script validates that the token and the file extension are in the allowed lists from the configuration.
3. It checks for a valid, authenticated session.
4. If Authenticated: The script verifies the file exists, is within the private directory, and then streams it to the browser with the correct Content-Type header.
5. If Not Authenticated: The script displays a self-contained HTML login form.
6. The user submits the login form. The script validates the CSRF token, checks the credentials, and implements rate limiting.
7. On successful login, a session is created, and the user is redirected to the file download (by re-handling the request).

SEO-Friendly URLs (Optional)

To make the URLs cleaner and more user-friendly, you can use URL rewriting. If you are using an Apache web server, you can create an .htaccess file in the same directory as getFile.php and add the following rules.

This will transform a URL from this: .../getFile.php?token=some_valid_token&file=your_file.pdf

Into this more friendly format: .../some_valid_token/your_file.pdf

.htaccess configuration:

RewriteEngine On
RewriteRule ^([^/]+)/([^/]+)$ getFile.php?token=$1&file=$2 [L]

Note: Depending on your server configuration and where the script is located, you might need to add a RewriteBase directive. For example, if your script is in a subdirectory /secure-downloads/, you would add RewriteBase /secure-downloads/ after RewriteEngine On.

License

This project is licensed under the MIT License.