v0.041 - v0.049
Architecture: Hub & Spoke (Cowboy Protocol)
- Multi-Target Deployment Topology — Replacing local folder isolation with a dedicated Mirror Server strategy via sftp.json:
- ROOT_CHANNEL (Primary): Direct pipeline to Production Live Server. Maps local public_html → remote public_html.
- MIRROR_ROOT_CHANNEL (Replica): Direct pipeline to Secondary Mirror Server. Acts as the "Crash Test Dummy" for destructive testing.
- Key Management: Unified identity strategy using Ed25519 SSH keys authorized across both Master and Mirror environments.
- Version Control (The Vault) — Formalized GitHub integration:
- Initialized private repository with .gitignore hardening to prevent credential leakage (sftp.json, .vscode/, .DS_Store).
- Established "Main" branch strategy for configuration state and protocol documentation.
- Kernel Simplification — REMOVED
runBios.php.
- Logic folded into index.php (Phase 4: The Fork) and diagonally.php.
- Boot chain flattened: Prepend (Instrumentation) → Index (Routing/Portal) → App/Diagnostics.
- Added Portal Logic: index.php now handles /dimensions/* routes to serve internal protocols and tools.
The "Ghost" System (server_fallback.php)
A PHP-driven emulation layer that simulates Web Server (Apache/Nginx) behavior when the primary config fails or is bypassed.
- Runtime Hardening & INI Enforcement — Forcing safe execution limits regardless of php.ini state:
- Security:
display_errors=0, log_errors=1.
- Resources:
memory_limit=512M, max_execution_time=300 (Tooling Profile).
- Output:
zlib.output_compression=0 (Prevents double-compression issues).
- Security Headers Injection — Applied at the PHP level for defense-in-depth:
- HSTS:
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload.
- Clickjacking:
X-Frame-Options: DENY.
- MIME Sniffing:
X-Content-Type-Options: nosniff.
- CSP Baseline:
Content-Security-Policy (default-src 'self' data: 'unsafe-inline').
- Routing Emulation — Pure PHP implementation of .htaccess rewrite rules:
- Canonical Redirects: Enforces HTTPS and strips www. subdomain.
- Legacy Redirects: Maps ?page=x query strings to pretty URLs /x.
- Traffic Blockers: Denies access to Dotfiles (except .well-known) and internal system folders.
- Asset Guards & Recovery — Granular control over static files served via PHP:
- Hotlink Protection: Validates HTTP_REFERER against allowed domains. Blocks cross-origin image requests.
- Static Recovery Engine: If the webserver fails to serve an asset, PHP takes over:
- Validates path containment (prevents directory traversal).
- Detects MIME type via finfo_file (with extensive extension fallback map).
- Generates
ETag (SHA1 of path+mtime+size) and Last-Modified.
- Supports
304 Not Modified and HEAD requests.
- Applies aggressive caching headers (immutable, max-age=31536000) for whitelisted assets.
Diagnostics (Muladhara / diagonally.php)
- Deep Inspection Tools — Added new handlers to the z_diag_registry:
/__scry: Full environment scan (Loaded Extensions, Critical INI values, Opcache Hit Rate, SAPI details).
/__net: Network topology analysis (Trusted Proxy detection, Cloudflare headers CF-RAY/CF-VISITOR, Forwarded-For chain analysis).
/__storagecheck: Automated I/O test (Write/Read/Unlink) to verify filesystem permissions in STORAGE_PATH.
/__opcache: Detailed memory usage and hit/miss statistics.
- Apache Mirror Directives — Ported .htaccess logic into reusable PHP functions:
block_dotfiles_except_well_known()
block_direct_php_requests() (Only allows index.php).
redirect_trailing_slash_if_not_dir() (Normalizes URLs).
Debug Overlay (BugChoppa)
- Class Architecture — Refactored into
final class Bugchoppa:
- Static Singleton pattern initialized via ::boot().
- Error/Exception handlers registered automatically (onError, onException, onShutdown).
- OOM Protection: Pre-allocated memory reserve ($memReserve) to ensure fatal errors can still render.
- Stateless Control (No Cookies) — Toggles via Query String:
?__dbg=on/off: Master switch.
?__dbg_ex=on/off: Converts Warnings to Exceptions (Strict Mode).
?__dbg_tr=on/off: Enables backtraces for non-fatal warnings.
- Visual Interface — High-fidelity HTML injection:
- Redaction Engine: Automatically masks sensitive keys (password, token, auth, key) in GET/POST dumps.
- Upload Summary: Inspects $_FILES array and decodes error codes (e.g., UPLOAD_ERR_INI_SIZE) into human-readable messages.
- Theming: Custom color palette (Header #9F2B68, Body #50C878) defined in z_debug_overlay_opts().
v0.031 - v0.04
Server / Entry Rules
.htaccess — locked the public surface area down to a single PHP entrypoint:
- Disabled content negotiation + directory listing:
Options -MultiViews -Indexes
- ACME challenge is always allowed first (never boots app):
RewriteRule ^\.well-known/acme-challenge/ - [L]
- Static assets bypass PHP entirely when they exist:
RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^ - [L]
- Prevents index rewrite loops and allows direct access to
index.php:
RewriteRule ^index\.php$ - [L]
- Hard-blocks any other direct PHP execution attempt:
RewriteRule \.php$ - [R=404,L]
- Everything else routes to
index.php and stamps an env marker for rewrite detection:
RewriteRule ^ index.php [QSA,L,E=SERVER_BOOT_FILE:ACTIVE]
- Retained cPanel/LiteSpeed handler configuration (ea-php83 lsphp)
Prepend Boot Chain (true “first touch”)
user.ini — enabled prepend execution at the server level:
- Configured:
auto_prepend_file=.../activatePrepend.php
- Forced production-safe output behavior while still logging everything internally:
display_errors=0
error_reporting=E_ALL
- Expanded upload + runtime ceilings for heavier ops / tooling:
upload_max_filesize=512M, post_max_size=516M, max_file_uploads=50
max_execution_time=300, max_input_time=300, memory_limit=512M
activatePrepend.php — earliest-possible instrumentation + overlay enablement:
- Defines the global timing origin as early as possible:
Z_EDGE_T0 = hrtime(true)
- Tags where timing began:
Z_EDGE_T0_SRC = 'prepend'
- Declares prepend state for downstream verification:
Z_PREPEND_LOADED = 1
Z_PREPEND_FILE = __FILE__
- Emits prepend verification headers when safe:
X-Prepend-Loaded: 1
X-Prepend-File: activatePrepend.php (basename)
- Loads
bugChoppa.php and boots overlay if available:
require __DIR__ . '/Bugchoppa.php';
z_overlay_mark('prepend'); (provenance stamp)
Bugchoppa::boot(z_debug_overlay_opts());
Edge Controller + Timing Visibility
runBios.php — standardized timing origin handling across all entry paths:
- If prepend already set the timing origin, BIOS respects it (no redefinition)
- If timing exists but no source label exists, BIOS backfills:
Z_EDGE_T0_SRC = 'unknown'
- Emits a visibility header to confirm timing origin per request:
X-Edge-T0-Src: prepend|runBios|unknown
runBios.php — confirmed rewrite marker integration continues working with the new env marker:
SERVER_BOOT_FILE / REDIRECT_SERVER_BOOT_FILE detection remains authoritative
- Root
/ DirectoryIndex fallback detection remains supported (ACTIVE(DIRINDEX))
- Observed timing sample (
/__timing):
- Total edge time:
0.531 ms
- Parse stage:
0.473 ms
- Marker stage:
0.003 ms
- Marker state:
ACTIVE
- SAPI:
litespeed, server reports Apache, PHP 8.3.28
- Note:
static_gate_ms is null on diag requests because /__* dispatch exits before the static-gate timestamp is recorded.
Index Fallback Safety Net
index.php — added a safe fallback overlay boot path if prepend fails:
- Only triggers when
Z_PREPEND_LOADED is missing
- Defines fallback identity:
Z_PREPEND_LOADED = 0
Z_PREPEND_FILE = __FILE__
- Emits fallback verification headers:
X-Prepend-Loaded: 0
X-Prepend-File: index-fallback
- Loads overlay implementation and marks provenance:
require __DIR__ . '/Bugchoppa.php';
z_overlay_mark('index-fallback');
Bugchoppa::boot(z_debug_overlay_opts());
index.php — version bumped on landing page:
v0.041
Overlay Implementation + Provenance
bugChoppa.php — refactored into a reusable overlay “module” used by BOTH prepend and index fallback:
- Central options source:
z_debug_overlay_opts() defines overlay toggles + theme
- New provenance + header stamper:
z_overlay_mark($src)
- Defines constants:
Z_OVERLAY_BOOT_SRC,
Z_OVERLAY_BOOT_FILE,
Z_OVERLAY_BOOT_TS
- Emits:
X-Overlay-Boot-Src,
X-Overlay-Booted
- Direct-access protection:
blocks requests where
bugChoppa.php is executed directly (returns 404)
- Overlay supports single-request toggles (no cookies) via query params:
__dbg, __dbg_ex, __dbg_tr
- Overlay keeps output safe:
- Forces
display_errors=0 while still capturing errors
- Captures warnings/notices, uncaught exceptions, and fatal shutdown errors
- Optional warning traces when exception-conversion is off
- Redacts sensitive keys in GET/POST dump
v0.021 - v0.03
Index / Edge
- Kept the edge controller minimal: paths → request parse → rewrite marker → static fallback → special endpoints → HTML
- Moved all
/__* diagnostics out of index.php into /muladhara/diagonally.php (registry + auth + handlers)
- Only loads diagnostics code when needed:
if (str_starts_with($pathDecoded, '/__')) require_once ...
- Otherwise skips the whole diag module (faster + cleaner)
- Preserved portable request normalization + safety checks:
- Trailing-slash normalization (except
/)
rawurldecode() + null-byte rejection
- Cheap header capture (
getallheaders() fallback)
- Preserved “portable mode” static serving (only when rewrite is INACTIVE):
- realpath prefix guard inside
PUBLIC_REAL
- 403 on directory listing unless
index.html/index.htm
- Blocked serving PHP as static (404)
- MIME via
finfo, ETag/Last-Modified, 304, HEAD support
- Kept “cheap endpoints” as no-boot fast-paths:
/.well-known/acme-challenge/*
/robots.txt and /sitemap.xml placeholders
- Kept timing stamps (
Z_EDGE_T0 + stage stamps) for edge profiling
Server (Apache / .htaccess)
- Maintained no negotiation / no listing:
Options -MultiViews -Indexes
- ACME bypass stays first:
/.well-known/acme-challenge/ never boots PHP
- Server serves real files/dirs directly (assets skip PHP):
RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^ - [L]
- Prevented index loop:
RewriteRule ^index\.php$ - [L]
- All other routes →
index.php with env marker:
RewriteRule ^ index.php [QSA,L,E=SERVER_BOOT_FILE:ACTIVE]
- cPanel/LiteSpeed PHP handler retained (ea-php83 lsphp)
muladhara/diagonally.php
- Introduced a dedicated diagnostics module (single include) with:
z_diag_registry() mapping /__* → handler + auth + methods
z_diag_dispatch() as the only entrypoint from index.php
- Auth system formalized:
public (no auth)
basic (browser popup) with CGI/LiteSpeed header fallback
token (env-driven) returning 404 on failure (future-ready)
- Credentials moved to env-first strategy:
ZAILAJA_DIAG_USER, ZAILAJA_DIAG_PASS, ZAILAJA_DIAG_TOKEN
- Hardcoded placeholders remain as dev fallback only
- Handlers kept modular and cheap:
- Public:
/__ping, /__health, /__version
- Protected:
/__env, /__paths, /__headers, /__staticcheck, /__list, /__timing
v0.0 - v0.02
Index / Edge
- Kept the front controller edge-first: cheap requests before any app boot
- Added dev HTML no-cache headers (
noCacheHtml()) for instant refresh
- Added portable boot utilities:
boot_fail(), norm_dir(), define_once(),
plus JSON/text response helpers
- Built portable path discovery from
__DIR__:
PUBLIC_PATH, PUBLIC_REAL, APP_PATH,
STORAGE_PATH, DIAG_PATH, ASSET_PATH
(with optional constant binding)
- Added request parsing + normalization pipeline:
REQUEST_URI → PHP_URL_PATH → trim trailing slash (except /) → rawurldecode()
- Added null-byte rejection on decoded paths
- Added lightweight header capture (uses
getallheaders() when available; falls back to HTTP_*)
- Added rewrite marker detection:
SERVER_BOOT_FILE / REDIRECT_SERVER_BOOT_FILE,
plus ACTIVE(DIRINDEX) detection for root /
- Added portable static fallback server (runs only when rewrite marker is inactive):
- Safe realpath prefix guard (prevents traversal outside
PUBLIC_REAL)
- Directory listing blocked (403) unless
index.html/index.htm exists (mirrors -Indexes)
- Blocked serving PHP files as static (404)
- MIME detection via
finfo (falls back to application/octet-stream)
- Static caching validators:
ETag + Last-Modified with 304 support
- HEAD request support for static responses
- Added ACME passthrough support (
/.well-known/acme-challenge/*) as guaranteed no-boot fast-path
- Added edge endpoints (
/robots.txt, /sitemap.xml) as minimal placeholders (no boot)
- Added diagnostics system (/__*) with registry + dispatcher (easy to move to tools later):
- Public:
/__ping, /__health, /__version
- Protected (Basic Auth for now):
/__env, /__paths, /__headers, /__staticcheck, /__list, /__timing
- Added micro-timing instrumentation using
hrtime(true):
Z_EDGE_T0, plus stage stamps for parse/marker/static-gate
Server (Apache / .htaccess)
- Disabled content negotiation and directory listing (
-MultiViews -Indexes)
- Enabled rewrite engine and added ACME bypass rule
- Skipped rewrite for existing files/dirs (lets Apache/LiteSpeed serve assets directly; avoids booting PHP)
- Prevented rewrite loop on
index.php
- Added rewrite-to-index rule that sets env marker (
E=SERVER_BOOT_FILE:ACTIVE)
- Noted behavior: root
/ may execute index.php via DirectoryIndex without triggering rewrite marker