# DIR//LISTER

**Hardened PHP directory lister** with cyberpunk UI, role-based auth, safe uploads, and multi-CDN cache headers.

[![PHP](https://img.shields.io/badge/PHP-7.4%2B%20%7C%208.x-777BB4?logo=php&logoColor=white)](https://www.php.net/)
[![License](https://img.shields.io/badge/license-Proprietary-red)](#license)
[![Version](https://img.shields.io/badge/version-v26.0911-brightgreen)](VERSION)

> Drop-in single-folder app: listing, preview, editor, upload, trash, ZIP, slideshow, audit log — with security defaults oriented for public hosting.

---

## Features

| Area | Capabilities |
|------|----------------|
| **Browse** | Grid / list views, search, breadcrumbs, hidden-file policy |
| **Preview** | Images, video, audio, PDF, Markdown, text/code |
| **Slideshow** | Swiper (lazy-loaded), swipe, pinch-zoom, thumbs, image fallback |
| **Write ops** | Upload, mkdir, rename, editor, delete → trash, ZIP |
| **Auth** | Roles: `viewer` / `editor` / `admin` · bcrypt · CSRF · rate limits |
| **Security** | `realpath` jail, MIME + magic bytes, forbidden extensions, CSP, HSTS |
| **Images** | Optional auto-convert uploads to WebP (GD/Imagick) |
| **Config** | Zero-dependency `.env` (no Composer required) |
| **CDN** | Browser + **Cloudflare** + **Akamai** edge cache headers & purge tags |
| **Perf** | Lazy CDN libs, `content-visibility`, TexMem thumbs, `Perf.autoTune` |

---

## Requirements

- **PHP 7.4+** (8.x recommended)
- Extensions: `json`, `session`, `hash` (standard)
- Optional: `mbstring`, `fileinfo`, `gd` or `imagick`, `zip`
- Apache (`mod_headers` / `mod_expires`) or Nginx
- Writable directory for auth/audit/trash files (or parent dir)

---

## Quick start

```bash
# 1. Copy files to your web root (or a subdirectory)
cp -r dirlister-split/* /var/www/html/files/

# 2. Environment
cp .env.example .env
chmod 600 .env
# edit SITE, HOME_URL, AUTHOR, SOCIAL_JSON, …

# 3. Permissions (example)
chown -R www-data:www-data .
chmod 600 .env

# 4. Open in browser — first visit creates admin (SETUP mode)
```

**Self-test:** `https://your.domain/index.php?selftest=1`

---

## Project layout

```text
.
├── index.php                 # Backend + HTML shell
├── index.css                 # UI styles
├── index.js                  # Frontend app
├── .env                      # Local secrets/config (do not commit)
├── .env.example              # Template
├── .htaccess                 # Apache cache + deny secrets
├── nginx-cache.snippet.conf  # Nginx origin cache headers
├── cloudflare-cache-rules.txt
├── akamai-cache-guide.txt
├── VERSION
└── README.md
```

Protected / excluded by default (also force-hidden even if omitted from `EXCLUDE`):

- `.env*`, `.dirlister_auth.php`, `.dirlister_ket.php`, `.audit.log`

---

## Configuration (`.env`)

Copy `.env.example` → `.env`. Important keys:

| Key | Purpose |
|-----|---------|
| `SITE` / `HOME_URL` | Branding & bounce URL |
| `AUTHOR` / `BRAND_TITLE` / `CONTACT_EMAIL` | UI identity |
| `SHOW_HIDDEN` | List dotfiles |
| `EXCLUDE` | Full hide-list (comma-separated); empty = built-in + `EXCLUDE_EXTRA` |
| `SOCIAL_JSON` | Footer links `[[label,icon,url],…]` |
| `AUTH_FILE` / `AUDIT_FILE` / `TRASH_DIR` | Paths (relative or absolute) |
| `IMAGE_WEBP_*` | Upload conversion |
| `EDITOR_MAX_*` / `ZIP_MAX_*` / `SEARCH_MAX_*` | Limits |
| `RATE_*` / `LOGIN_FAIL_*` | Rate limits & lockout |
| `CDN_*` / `AKAMAI_*` / `CF_*` | Edge cache TTLs & tags |

Optional overlay: `.env.local` (merged on top of `.env`).

> **Never** store admin passwords in `.env` — accounts live in `.dirlister_auth.php` (created via UI).

---

## Roles

| Role | Access |
|------|--------|
| **viewer** | Browse / preview / download |
| **editor** | + upload, mkdir, rename, edit text, ket notes |
| **admin** | + delete, trash, ZIP, audit, user management |

---

## Security notes

- Path resolution via `realpath` + base prefix check (traversal resistant)
- Uploads: extension denylist, `finfo` / magic-byte checks, polyglot heuristics
- Editor: size/line limits; PHP policy for dangerous patterns
- Sessions: `HttpOnly`, configurable `SameSite`, secure cookie on HTTPS
- Security headers: CSP, `nosniff`, `frame-options`, Referrer-Policy, Permissions-Policy
- Rate limits on login & write API

Deploy over **HTTPS**. Restrict PHP execution in upload folders at the web server if you allow high-risk types for admins.

---

## Caching & CDN

### Browser

- HTML / API: `no-store`
- `index.css` / `index.js`: long cache with **`?v=filemtime`** busting

### Cloudflare

See `cloudflare-cache-rules.txt`.

- Bypass: `index.php`, `?api=`, login
- Cache: `css` / `js` (query string included)
- Headers: `Cloudflare-CDN-Cache-Control`, `Cache-Tag`

### Akamai

See `akamai-cache-guide.txt`.

- Honor origin **`Edge-Control`**
- Bypass dynamic; cache static with **full query string** in cache key
- **`Edge-Cache-Tag`** for Fast Purge (`dirlister-static`, …)

```env
CDN_PROVIDER=auto          # auto | cloudflare | akamai | none
CDN_CACHE_STATIC=604800
AKAMAI_EDGE_TTL_STATIC=604800
AKAMAI_DOWNSTREAM_TTL_STATIC=604800
CDN_CACHE_TAG_PREFIX=dirlister
```

---

## Frontend notes

- **Vanilla JS** — no build step
- Heavy libs loaded on demand:
  - [Swiper](https://swiperjs.com/) → slideshow
  - marked + highlight.js → Markdown / code preview
- Font Awesome 6 + Google Fonts (cdnjs / Google)

---

## Development

No bundler. Edit files and hard-refresh (cache bust query updates automatically when file mtime changes).

```bash
php -l index.php
# optional JS sanity
node -e "new Function(require('fs').readFileSync('index.js','utf8'))"
```

---

## Troubleshooting

| Symptom | Check |
|---------|--------|
| Blank page | `php -l index.php`, error log, PHP version |
| CSS/JS 404 | Same directory as `index.php`; rewrite rules |
| Thumbs missing | Writable temp; `fileinfo`; console errors |
| Slideshow plain | Network tab — Swiper CDN blocked by CSP/firewall? |
| ZIP disabled | Install `ext-zip` |
| Login lock | Wait lock window or clear session |

---

## Changelog

See [RELEASE-NOTES.txt](RELEASE-NOTES.txt) and [VERSION](VERSION).

**Current:** `v26.0911` (SUPERPOWER)

---

## License

Proprietary — © author configured in `.env` (`AUTHOR`).  
All rights reserved unless otherwise granted in writing.

Code, design, and branding are not public domain.  
Personal learning is fine; redistributing as your own product is not.

---

## Credits

- Built as **DIR//LISTER** hardened directory index
- UI: cyberpunk / neon terminal aesthetic
- CDN assets: [cdnjs](https://cdnjs.com/) (Cloudflare)

---

<p align="center">
  <sub>DIR//LISTER // hard listings for hostile internets</sub>
</p>