Project Wharf

:toc: left :toclevels: 3 :icons: font :source-highlighter: highlight.js

The Sovereign Web Hypervisor

Wharf is a revolutionary approach to Content Management System (CMS) security that separates administration from runtime. Instead of plugins with full system access running on your live site, Wharf uses an offline controller (the Wharf) and a read-only runtime (the Yacht) connected via a Zero Trust mesh network.

Core Philosophy

The gun should not be in the safe.

Traditional CMS security is like storing the vault’s drill, dynamite, and blueprints inside the vault. If an attacker gets in, they use your own tools against you.

Wharf inverts this:

• The Yacht (Live Site): A neutered runtime. It serves content but cannot install plugins, edit code, or change configuration.

• The Wharf (Controller): Your offline workshop. It holds the keys, runs diagnostics, and makes all administrative decisions.

• The Mooring: A cryptographically secured connection that temporarily allows the Wharf to sync state to the Yacht.

Architecture

      THE WHARF (Offline Controller)               THE YACHT (Online Runtime)
    +--------------------------------+          +------------------------------+
    | [Physical/Local Hardware]      |          | [Cloud/Edge Server]          |
    |                                |          |                              |
    |  1. IDENTITY (The Keys)        |          |  4. THE SHIELD (Rust Agent)  |
    |     • Nitrokey / FIDO2         |          |     • eBPF Force Field       |
    |     • Argon2id + LUKS          |          |     • Header Airlock         |
    |                                |          |     • DB Proxy (AST Aware)   |
    |  2. INTENT (The Brain)         |          |                              |
    |     • Nickel Config Schema     |          |  5. THE PAYLOAD (Legacy)     |
    |     • Nebula CA (Offline)      |          |     • WordPress / Drupal     |
    |     • Rust Compiler            |          |     • Read-Only Filesystem   |
    |                                |          |     • Ephemeral RAM Disk     |
    +---------------+----------------+          +--------------+---------------+
                    |                                          |
                    |         THE MOORING (Zero Trust)         |
                    |                                          |
                    +==========================================+
                    |  • Hidden UDP Port (Nebula Mesh)         |
                    |  • Mutual TLS (mTLS)                     |
                    |  • Invisible to Public Internet          |
                    +==========================================+

Key Features

Database "Virtual Sharding"

The Yacht Agent acts as a SQL proxy, parsing queries using an Abstract Syntax Tree (via sqlparser 0.39, not regex!) to enforce security policies:

• Mutable Tables (Blue Zone): Content like comments and orders—allowed to write

• Immutable Tables (Red Zone): Config like users and plugins—blocked unless from Wharf

• Hybrid Tables (Grey Zone): Mixed content like wp_options—conditional rules

-- ALLOWED: User comment
INSERT INTO wp_comments (comment_content) VALUES ('Great post!')

-- BLOCKED: New admin user
INSERT INTO wp_users (user_login, user_pass) VALUES ('hacker', 'password')
-- Error: Policy violation: write to immutable table 'wp_users'

Persistent Hybrid Keypairs

Both the Wharf CLI and Yacht Agent persist their Ed448 + ML-DSA-87 hybrid keypairs to disk, establishing stable identities across restarts.

Component	Key Location	Permissions
Wharf CLI	~/.wharf/keys/wharf.key	0600 (private), 0644 (public)
Yacht Agent	/etc/wharf/keys/yacht.key	0600

Keys use a custom binary format (WHRF magic + version + length-prefixed key material). Password-encrypted serialization is available via HKDF-SHAKE512 + XChaCha20-Poly1305 for offline storage.

eBPF XDP Firewall

The Yacht Agent supports kernel-level packet filtering via eBPF XDP programs for high-performance network enforcement. Falls back to nftables when CAP_BPF is unavailable.

Filesystem Immutability

The Yacht filesystem is mounted read-only with specific writable "playgrounds":

Path	Type	Purpose
/wp-content/uploads	Persistent, No PHP	User media files
/wp-content/cache	RAM Disk (tmpfs)	Temporary cache—wipes on restart
/wp-content/plugins	OverlayFS	"The Lie"—plugins think they write, but it’s ephemeral

File Integrity Verification

The Yacht Agent verifies incoming BLAKE3 file manifests against on-disk state during the mooring verify phase. Mismatched, missing, and unexpected files are reported back to the Wharf CLI before any rsync transfer.

Prometheus Metrics

The Yacht Agent exposes real-time operational counters at GET /metrics (Prometheus format):

• yacht_queries_total{status="allowed|blocked|audited"} — database proxy traffic

• yacht_mooring_sessions_total — mooring session count

• yacht_integrity_checks_total — integrity verification runs

• yacht_moored — whether the agent is currently moored

Statistics are also available as JSON via GET /stats.

HTTP Header Airlock

A Rust-based HTTP proxy strips dangerous headers and injects security headers:

# Stripped (Information Leakage)
- Server: Apache/2.4.41
- X-Powered-By: PHP/8.1

# Injected (Security Hardening)
+ Cross-Origin-Opener-Policy: same-origin
+ Cross-Origin-Embedder-Policy: require-corp
+ Permissions-Policy: camera=(), microphone=()

Zero Trust Networking (Nebula)

Admin ports are invisible to the public internet. The Yacht’s management API (port 9001) only responds to devices with valid Nebula certificates. Full certificate lifecycle management (CA, signing, IP allocation, revocation) is built into nebula.rs.

Quick Start

Prerequisites

• Rust (via rustup)

• Podman (or Docker)

• Just (command runner)

• Optional: Nebula, named-checkzone (bind-utils)

Installation

# Clone the repository
git clone https://gitlab.com/hyperpolymath/wharf.git
cd wharf

# Initialize the workspace
just init

# Build everything
just build

Basic Usage

# Create zone file variables
cat > vars/example.json << 'EOF'
{
  "domain": "example.com",
  "ip": "192.0.2.1",
  "ipv6": "2001:db8::1",
  "nameserver": "ns1.example.com",
  "nameserver2": "ns2.example.com",
  "rpemail": "hostmaster.example.com",
  "serial": "2025112601",
  "ttl": "3600",
  "nsttl": "86400"
}
EOF

# Build DNS zone files
just build-zones

# Audit the generated zone
just audit-zone dist/example.db example.com

# Detect if dedicated or shared hosting
just detect-env example.com 192.0.2.1

DNS Zone Templates

Wharf includes four DNS templates for different environments:

Template	Use Case	Key Difference
simple.tpl	Modern minimum viable	Basic records + email deliverability (SPF, DMARC, CAA)
shared.tpl	Shared/Virtual hosting	Uses CNAMEs, includes provider SPF, no SSHFP
standard.tpl	Dedicated IP	Explicit FTP A record, full control
maximalist.tpl	Enterprise/Security-focused	DANE, SSHFP, OPENPGPKEY, HTTPS/SVCB, LOC

CMS Adapters

Wharf includes adapters for popular CMS platforms:

WordPress

# Copy the DB proxy drop-in
cp adapters/wordpress/db.php /var/www/html/wp-content/db.php

# The Yacht Agent must be running on 127.0.0.1:3307

Drupal

# Include the settings override
echo "include_once '/opt/wharf/adapters/drupal/settings.php';" >> sites/default/settings.php

WordPress Dashboard Adapter

A thin GPL-2.0 plugin that displays Wharf protection status in wp-admin:

# Copy the adapter plugin into your WordPress plugins directory
cp -r adapters/wordpress-wharf /var/www/html/wp-content/plugins/wharf-adapter

Features:

• Dashboard widget showing query stats (allowed/blocked), firewall mode, signature scheme

• Admin bar indicator (green = protected, grey = agent unreachable)

• 30-second response caching via WordPress transients

• Zero security logic — all enforcement handled by yacht-agent

Configure the agent URL in wp-config.php if non-default:

define('WHARF_AGENT_URL', 'http://agent:9001');

Others

• Joomla (adapter included)

• Moodle (adapter included)

• Generic LAMP (customizable adapter)

Security Model

Signature Scheme Configuration

Wharf supports two signature modes, selectable at startup:

Scheme	Flag	Description
ML-DSA-87 Only (default)	--signature-scheme ml-dsa-87-only	FIPS 204 post-quantum only. Production-safe, peer-reviewed.
Hybrid	--signature-scheme hybrid	Ed448 + ML-DSA-87 dual signatures. Requires ed448-goldilocks audit.

Set in TOML config (yacht-agent.toml or wharf-cli.toml):

signature_scheme = "ml-dsa-87-only"  # or "hybrid"

The default (ml-dsa-87-only) is recommended for production until the ed448-goldilocks library completes its third-party audit.

Cryptographic Primitives

Wharf uses a post-quantum hybrid signature scheme and modern cryptographic primitives:

Primitive	Algorithm	Purpose
Hybrid Signatures	Ed448 + ML-DSA-87 (Dilithium5)	All mooring requests and responses — both must verify
File Integrity	BLAKE3	Fast hashing for filesystem manifests
Provenance Hashing	SHAKE3-512 (FIPS 202)	Long-term provenance and KDF input
Symmetric Encryption	XChaCha20-Poly1305	AEAD for secrets in transit
Key Derivation	HKDF-SHAKE512	Derive per-session keys
Password Hashing	Argon2id (512 MiB, 8 iter, 4 lanes)	Wharf controller only — never on Yacht
Random Generation	ChaCha20-DRBG (512-bit seed)	All key generation and nonces

The hybrid signature scheme ensures that both Ed448 (classical) and ML-DSA-87 (post-quantum) signatures must verify. An attacker must break both algorithms — quantum or classical — to forge a signature.

Mooring Protocol

The Wharf controller syncs state to the Yacht via a four-phase HTTP protocol:

1. INIT     Wharf → Yacht   "I want to sync layers X, Y, Z"  (signed)
2. VERIFY   Wharf → Yacht   "Here's my BLAKE3 manifest"       (per layer)
3. RSYNC    Wharf → Yacht   SSH-based file transfer            (delta only)
4. COMMIT   Wharf → Yacht   "Lock it in, create snapshot"     (signed)

All init and commit requests carry hybrid signatures. The Yacht verifies both Ed448 and ML-DSA-87 components before accepting.

The mooring HTTP client uses a 30-second request timeout, 10-second connect timeout, and connection pooling (2 idle connections per host) for resilient communication.

Threat Model

Wharf assumes:

• The live server (Yacht) is hostile territory

• Attackers may have SQL injection or file upload vulnerabilities

• Network is untrusted (even internal networks)

Protections

Attack Vector	Wharf Defense
SQL Injection → New Admin User	Database proxy blocks writes to wp_users
File Upload → PHP Shell	Uploads directory has php_flag engine off
Plugin Backdoor	Plugins directory is read-only (OverlayFS)
Config Tampering	wp-config.php changes trigger instant revert
Network Sniffing	Nebula mesh encrypts all admin traffic
Signature Forgery	Ed448 + ML-DSA-87 hybrid — quantum-resistant
Key Compromise	Argon2id (512 MiB) protects stored keys

Container Deployment

Wharf uses hardened Chainguard container images with the hyperpolymath container toolchain:

Component	Image	Role
Builder	cgr.dev/chainguard/wolfi-base:latest	Compilation and asset building
Runtime (Agent)	cgr.dev/chainguard/static:latest	Minimal distroless runtime
Web Server	cgr.dev/chainguard/nginx:latest	Hardened nginx
Database	cgr.dev/chainguard/mariadb:latest	MariaDB with policy enforcement

Orchestration uses selur-compose with the vordr container runtime, rokur secrets management, and cerro-torre image signing. See infra/selur-compose.yaml.

# Build container images
just container-build

# Deploy with selur-compose
just deploy-selur

# Sign images with cerro-torre
just sign-images

Configuration Reference

Wharf uses Nickel for declarative configuration and TOML for runtime settings:

Policy Files (Nickel)

• configs/fleet.ncl - Define your Yachts

• configs/policies/database.ncl - Database virtual sharding rules

• configs/policies/airlock.ncl - HTTP header rules

• configs/policies/filesystem.ncl - File immutability policies

• configs/policies/auth.ncl - FIDO2 and session policies

• configs/policies/network.ncl - Nebula mesh and firewall rules

Runtime Configuration (TOML)

Configuration is loaded with the following precedence (highest first): CLI args > environment variables > project-local (.wharf/config.toml) > user config (~/.config/wharf/) > system config (/etc/wharf/) > defaults.

• yacht-agent.toml — Yacht Agent runtime settings (db proxy, firewall, API, site root, key store)

• wharf-cli.toml — CLI settings (paths, build, mooring, state, key store)

Justfile Commands

just init              # Initialize workspace
just build             # Compile everything
just moor <target>     # Connect to a Yacht
just audit <target>    # Security audit
just gen-nebula-ca     # Generate mesh CA
just gen-yacht-cert    # Generate Yacht certificate
just gen-email-records # Generate SPF/DKIM/DMARC
just deploy-yacht      # Deploy agent to server

Deployment

See Deployment Guide for a 5-minute quick start with Podman.

cd deploy && sudo ./setup.sh --domain example.com
sudo podman compose -f ../infra/selur-compose.yaml up -d
curl http://localhost:9001/health

Security Challenge

Think you can break it? See Hack This WordPress Site — a fully documented challenge for security researchers to test the Wharf architecture.

Contributing

Contributions are welcome! Please ensure:

1. Code passes just lint and just fmt-check

2. Tests pass with just test

3. Security-sensitive changes are documented

License

Palimpsest-MPL License v1.0 (PMPL-1.0). See LICENSE file for details.

Credits

• Concept by Jonathan D. A. Jewell (@hyperpolymath)

• Built with Rust, Nickel, Nebula, Podman, and Chainguard

---

"The admin panel has no place on the production server."

— Project Wharf Manifesto