Technical Blueprint: Gallery Protect System

/nphotos/auth.php: The central engine. Handles session_start(), verifies credentials against users.txt, and serves the Orange Login UI. Now logs 🔴 LOGOUT actions before destroying sessions.

/nphotos/config.php: Configuration hub. Sets $MY_FOLDER_ID = "nphotos" and physical path constants. Required for every PHP script.

/nphotos/protect.php: Content Gatekeeper. Specifically for /protected_html/. Includes the Dynamic Logout logic which unsets last_page and redirects back to the current URI.

/nphotos/change_password.php: User Utility. Updates users.txt via LOCK_EX and forces a re-login to ensure credential synchronization.

/nphotos/user_info.php: AJAX endpoint for h5ai. Read-only session identity provider.

/nphotos/monitor.php: Admin Dashboard. Includes Auto-Trim (2000 lines), Smart Dates, and Scrollable History (Last 100 hits).

/nphotos/logout.php: Global session terminator. Supports ?from_monitor=1 context.

/nphotos/users.txt: Case-insensitive user database (user:pass). Restricted access.

/nphotos/global_activity.log: Activity log (timestamp|folder|user|ip|action|login_start).

/nphotos/avatar: Directory to place pictures of users (username.jpg or username. png) to be used to show a small picture in the logoff widget

/protected_html: Targeted directory for custom HTML projects. Uses protect.php to wrap content fragments (e.g., _content.php) with the gallery's security session.

/nphotos/albums: Directory for all the original h5ai stuff including your album directories and the modifications done for this project.

/nphotos/albums/_h5ai/public/ext/custom_ui.js: Injection script for h5ai

/nphotos/albums/_h5ai/private/conf/options.json: json for the h5ai injection

/nphotos/incl_docs/: The SSI included files of this documentation, included by docs.shtml

1. Copy all files and sub directories to your target directory (which should be placed in your site root).
2. Edit all the above files and replace any hard coded occurences of "nphotos" in the target to the name of the your directory, do not forget the .htacess files showed in section 16. If you integrate with h5ai do not forget to update the related files showed in section 16. In future releases of this package the edit of the php files will be avoided.
3. Check config.php where the variable $MY_FOLDER_ID should be set to the name of your directory .
4. If you plan to use the h5ai integration, replace the album subdirectories with your content of pictures or other content files.
5. If you plan to use only or also use the protected_html directory integration. Edit all the contained files and replace any hard coded occurences of "nphotos" to the name of the folder id.
6. Check and allow the webserver to read and write to: users.txt, global_activity.log and the /albums/_h5ai/public/cache and subfolders (thumbs by h5ai are cashed here)
   
7. Test your set-up!

The system operates on a Synchronous Gatekeeping strategy. Instead of a heavy SQL database, it uses the server's memory (Sessions) and the file system (.htaccess) to create a multi-layered perimeter.

A. Layer 1: The Request Interceptor (.htaccess)

Protection begins before PHP even initializes. The server level handles the "Hard Perimeter":

• Direct Traffic: Apache intercepts 403 Forbidden errors and reroutes unauthorized traffic to auth.php.
• Resource Stealth: Explicitly prevents browser-level access to users.txt and global_activity.log. Even if a user is logged in, the server denies direct HTTP requests to these data files.

B. Layer 2: Namespace Isolation & Session Logic

To allow multiple independent galleries (e.g., /nphotos/ and /vacation/) to exist on the same server without "cross-talking," the system uses Namespace Isolation. Every session key is prefixed with a unique folder ID.

// Variables are dynamically built using $MY_FOLDER_ID
$auth_key = "auth_" . $MY_FOLDER_ID;         // Validation Token
$user_key = "active_user_" . $MY_FOLDER_ID;  // Identity Token
$path_key = "last_page_" . $MY_FOLDER_ID;    // Return-Path Memory

The "Kill" Protocol: Every protected page includes the auth.php engine at Line 1. If the $auth_key is missing or expired (default 24h), the script executes exit;. This kills the process instantly, ensuring no content bytes are sent to the browser until authentication is confirmed.

C. Layer 3: The Flat-File Database (users.txt)

The "Safe" is a simple, high-speed text parser that follows strict integrity protocols:

• Explode Logic: PHP reads the database into memory and uses explode(':', $line). This allows for rapid credential lookups without a persistent database connection.
• Atomic Integrity: Password changes utilize LOCK_EX (Exclusive Lock). This prevents "Race Conditions" where simultaneous updates could result in a zero-byte (empty) user file.
• Sanitization: UserIDs are normalized via strtolower(), while passwords maintain strict case-sensitivity and Unicode/Swedish character support.

D. Content Gatekeeping Methods

The protection is applied differently based on the content type:

• Native Injection (h5ai): By injecting the include at the very top of the h5ai index, the entire gallery application is "wrapped" inside the security logic.
• The Gatekeeper (protect.php): For custom HTML, it acts as a proxy, masking _content.php fragments and providing the REQUEST_URI back to the login form so users return exactly where they left off after logging in.

E. The Request Lifecycle (Visual Flow)

A. Path & Redirect Issues

• Issue: Nested folders redirecting to the root instead of the login gate.
  Fix: Ensure $_SERVER['REQUEST_URI'] is used in the login form action to capture the full deep-link path.
• Issue: 404 Errors on assets in sub-galleries.
  Fix: Check $MY_FOLDER_ID in config.php; if it doesn't match the actual folder name, the system will look in the wrong namespace.

B. UI & Widget Persistence (The "Edge" Problem)

Because the system uses AJAX to fetch user info for the h5ai widget, aggressive browser caching (especially in Microsoft Edge) can cause old code or typos to persist even after server-side fixes.

• The "Hard Refresh" Protocol: If changes to custom_ui.js or custom_style.css do not appear, force the browser to bypass its cache:
  • Windows/Linux: Press Ctrl + F5 or Ctrl + Shift + R.
  • Mac (Safari/Chrome): Press Cmd + Shift + R.
• Version Bumping: For a permanent fix across all users, increment the version string in options.json (e.g., "custom_ui.js?v=10.62").

h5ai custom_ui.js

/nphotosjj/albums/_h5ai/public/ext/custom_ui.js

h5ai options.json

/nphotosjj/albums/_h5ai/private/conf/options.json (Refer to Section 12 for the specific configuration)

The change_password.php utility and auth.php UI implement a v10.60 Unicode-Aware Validation layer to support Swedish national characters while maintaining strict database integrity.

A. Security Filters & Character Logic

• The mb_strlen Rule: Uses mb_strlen($p, 'UTF-8') to ensure actual characters are counted. This correctly identifies "brö" as 3 characters (failing the 4-char limit), whereas standard strlen would incorrectly see 4 bytes.
• Delimiter Protection: Explicitly blocks the : character to prevent breaking the flat-file explode() logic in the user database.
• Unicode Regex: Uses the /u modifier /^[^\s:]+$/u to permit åäöÅÄÖ while strictly blocking spaces, tabs, and newlines.

B. Universal UI Toggle (The "Eye" Logic)

The system utilizes a parameter-based JavaScript function to handle multiple password fields (Login, Old, New, Confirm) without ID conflicts:

// auth.php - Universal Toggle Function
function togglePass(fieldId, eyeId) {
    var p = document.getElementById(fieldId);
    var e = document.getElementById(eyeId);
    if (!p || !e) return;
    
    p.type = (p.type === "password") ? "text" : "password";
    e.innerText = (p.type === "password") ? "👁️" : "🙈";
}

C. Processing & File Integrity

// change_password.php - Atomic Write with Error Logging
if ($updated) {
    if (file_put_contents($USER_FILE, implode("\n", $new_content), LOCK_EX)) {
        // Log success for monitor.php
        file_put_contents('global_activity.log', $log_line, FILE_APPEND | LOCK_EX);
    }
}

D. Protected Accounts

Accounts marked with a * suffix in users.txt are recognized as "Read-Only" by the change utility. The script strips the * for login comparison but detects it during change requests to block unauthorized password modifications to admin accounts.

When duplicating this system to a new directory (e.g., from /nphotosjj/ to /travel/), use this checklist to ensure all hardcoded paths are updated. Search and Replace is your best tool for this process.

A. The PHP Layer

• config.php: Update $MY_FOLDER_ID = "newfolder"; to match the new directory name.
• auth.php: Verify any hardcoded header("Location: ...") redirects.
• logout.php: Ensure the redirect logic points to the new base URI.

B. The Apache Layer (.htaccess)

• Root /.htaccess: Update ErrorDocument 403 /newfolder/auth.php?error=403.
• /albums/.htaccess: Update the Redirect 302 path in the Hotlink Protection section to point to the new access_denied.php.
• System Core .htaccess: Ensure DirectoryIndex paths point to the correct _h5ai location if absolute paths were used.

C. The h5ai Bridge

• options.json: Check the "resources" section. Ensure "scripts" and "styles" paths are relative or updated.
• custom_ui.js: Verify the fetch() URL.
  Recommended: Use ../../../user_info.php to make the script folder-agnostic.

D. Permission Audit

• Data Files: Ensure users.txt and global_activity.log are writable (chmod 664/666) in the new location.
• Cache: Delete all files inside /_h5ai/public/cache/ in the new folder to force h5ai to generate new thumbnails specific to the new content.