atj4me/secure-file-downloader

A simple package to serve files securely behind a login.

dev-main 2025-07-18 18:33 UTC

Requires

• php: >=7.4

MIT

• Ajith Thampi Joseph

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.

Key	Type	Required	Default	Description
private_path	string	Yes	null	The absolute path to the directory containing your private files.
credentials	array	Yes	[]	An array containing the username and password_hash.
valid_tokens	array	Yes	[]	An array of strings. The token in the URL query must match one of these.
valid_extensions	array	No	['pdf', 'doc', 'docx', 'rtf', 'txt']	Allowed file extensions. Requests for other extensions will result in a 404 error.
session	array	No	[...]	Session settings, including name, lifetime (in seconds), and save_path.
rate_limiting	array	No	[...]	Login rate limiting settings, including attempts and lockout_seconds.
security_headers	bool	No	true	If true, sends security-related headers like X-Frame-Options. Set to false if handled elsewhere.
cache_control	bool	No	false	If false, sends headers to prevent browser caching of the file. Set to true to allow caching.

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.