Onionify

About Onionify

Onionify is an independent WordPress plugin that enables websites to operate seamlessly through onion services (.onion). It adds safe, standards-compliant integration for onion access by:

• Rewriting runtime URLs when requests arrive via .onion.
• Preventing canonical redirects that could push onion visitors to the clearnet.
• Optionally sending the official Onion-Location HTTP header.
• Applying optional privacy-hardening measures for onion traffic only: CSP, COEP, X-Frame-Options, oEmbed and resource hints control.

Conforms to WordPress.org rules: no core modifications, uses filters and actions only, supports multisite with per-site mappings and network defaults, and includes optional WP-CLI integration.

Onionify is not affiliated with or endorsed by the Tor Project.

About the author

Ivijan-Stefan Stipic

Senior web developer and WordPress plugin author with 20+ years of experience across PHP, MySQL, JavaScript, and WooCommerce integrations. Focused on secure, standards-based engineering and practical tooling for real-world production needs. Creator and maintainer of multiple WordPress plugins and custom enterprise solutions.

Full-Stack Backend Frontend REST API OAuth MySQL MariaDB Nginx Apache PSR-4 Composer MVC OOP PHP 8 cURL JSON XML AJAX jQuery Vue.js Node.js CLI WordPress Core Plugin Development Theme Development WooCommerce Gateway Custom Integrations Security Auditing Optimization Caching Redis Performance Tuning DevOps Linux Server Bash Automation OpenAI ESP32 IoT Microcontroller SEO Web Marketing Branding Leadership Team Management Project Architecture Scalability Security Engineering Clean Code Code Review Documentation

For custom work and consulting please use the contact channel in the Support section below.

This documentation provides all technical and operational details for Onionify, including setup, configuration, and integration guidance for WordPress sites served via .onion.

Key features

• Detects .onion requests and safely rewrites generated WordPress URLs to the configured onion host at runtime.
• Does not modify database home or siteurl values. Rewrites occur at runtime only.
• Multisite support: per-site onion mapping and configurable network defaults.
• Optional Onion-Location header from clearnet to advertise the onion mirror.
• Optional privacy hardening for onion visitors: CSP, COEP, X-Frame-Options, disable oEmbed, tighten resource hints.
• Optional Tor exit verification using the public exit list (opt-in only).
• WP-CLI commands to list, map, and manage onion host configurations.
• Developer filters: onion_is_onion_request, onion_verify_exit_list.
• Defensive code, compatible with PHP 7.4-8.x.

Installation

1. Upload the onionify folder to /wp-content/plugins/.
2. Activate the plugin in WordPress Admin under Plugins.
3. Single-site: Settings -> Onionify. Enter your .onion host (host only, e.g. abcd1234xyz.onion) and adjust optional hardening.
4. Multisite: Network Admin -> Onionify. Use Mapping to map each site to its onion host, and configure Network Defaults if desired.
5. Optional: enable Tor exit verification via wp-config or a filter. See External services below.

Configuration

Tip: Start with Strict. If something breaks, try Relaxed. Use Custom only if you understand CSP syntax.

CSP modes and examples

Minimal secure WordPress (no external CDN)

default-src 'self';
script-src 'self';
style-src 'self' 'unsafe-inline';
img-src 'self' data:;
font-src 'self' data:;
connect-src 'self';
frame-src 'self';
frame-ancestors 'self';
base-uri 'self';
form-action 'self';

Relaxed (allows inline JS)

default-src 'self';
script-src 'self' 'unsafe-inline';
style-src 'self' 'unsafe-inline';
img-src 'self' data:;
font-src 'self' data:;
connect-src 'self';
frame-src 'self';

Using a specific CDN

img-src 'self' https://cdn.example.com data:;
font-src 'self' https://cdn.example.com data:;

Multisite behavior

• Per-site mapping: Network Admin -> Onionify allows mapping blog_id to onion host.
• Network Defaults: set default onion host, CSP mode, and hardening toggles inherited by sites unless overridden.
• Precedence: Per-site explicit setting -> Network Default -> Plugin internal default.

WP-CLI quick usage

# List configuration (multisite mapping or single-site status)
wp tor-onion list

# Map a blog to an onion host (use 0 for single-site)
wp tor-onion map <blog_id|0> abcd1234xyz.onion

# Toggle hardening, oEmbed, and CSP mode
wp tor-onion set --hardening=on --oembed=off --csp=strict
wp tor-onion set --hardening=off --oembed=on --csp=relaxed

External services

The plugin can optionally fetch the official Tor exit relay list to verify inbound requests.

• Service: Tor Project - Exit addresses list
• Endpoint: https://check.torproject.org/exit-addresses

What it is used for

When exit verification is enabled, the plugin downloads the public list of Tor exit relays to check inbound requests.

What data is sent and when

A normal HTTP GET from your server to the Tor endpoint. No user PII is sent. The request includes a generic User-Agent and your server IP is visible as with any HTTP request. Cached for up to 24h and only performed if explicitly enabled.

How to enable or disable

// Option 1: wp-config.php
define('TOS_VERIFY_TOR_EXIT', true);

// Option 2: a mu-plugin or theme functions.php
add_filter('onion_verify_exit_list', '__return_true');

If your environment sets WP_HTTP_BLOCK_EXTERNAL, the plugin respects it unless the host is whitelisted via WP_ACCESSIBLE_HOSTS.

Frequently asked questions

How to set up a WordPress site with a .onion address?

First, configure a Tor hidden service on your server. This step is outside WordPress. Edit the Tor configuration file (usually /etc/tor/torrc) and add:

HiddenServiceDir /var/lib/tor/hidden_service/
HiddenServicePort 80 127.0.0.1:80

Restart Tor and read the generated hostname in /var/lib/tor/hidden_service/hostname. That is your new .onion address.

In WordPress Admin open:

• Settings -> Onionify for single-site, or
• Network Admin -> Onionify for multisite

Enter your onion host (for example abcd1234xyz.onion). Onionify will handle URL rewriting and privacy adjustments for onion traffic. To advertise your onion mirror from the clearnet site, enable Send Onion-Location from clearnet.

Note: Onionify does not create or manage the Tor hidden service. It configures WordPress to correctly respond to requests coming from your .onion address.

Will this make my site available only through an onion address?

No. The plugin does not modify hosting, DNS, or routing. It adjusts WordPress behavior only when requests originate from an onion address. Exclusive onion hosting requires additional server and network configuration beyond this plugin.

I use a CDN like Cloudflare - will this work?

Yes. The plugin inspects common headers such as CF-Connecting-IP and X-Forwarded-For to help detect onion-origin requests behind CDNs. A filter onion_is_onion_request is provided for custom integrations. Ensure your CDN passes the correct client IP headers.

What happens if I enable Custom CSP but make a mistake?

If a Custom CSP is invalid or overly restrictive, parts of your site, including wp-admin, may break. The plugin sends exactly the policy you provide. Test on staging first and fall back to Strict or Relaxed if needed.

Does the plugin change database home or siteurl values?

No. Onionify rewrites URLs dynamically at runtime. Database values remain unchanged.

How do I enable or disable the exit-address verification check?

It is disabled by default. To enable:

// Enable via wp-config.php
define('TOS_VERIFY_TOR_EXIT', true);

// Or via filter in a mu-plugin or theme
add_filter('onion_verify_exit_list', '__return_true');

Privacy, security, and limitations

• Onionify adjusts WordPress behavior based on access method (clearnet vs. onion) by handling URLs, selected headers, CSP, and resource hints.
• It does not anonymize or conceal server infrastructure details such as hosting IPs or DNS records. It is not designed to provide anonymity or infrastructure concealment.
• External requests are disabled by default. The optional exit verification is opt-in and cached for 24h when enabled.
• Best practice for onion privacy is to host assets locally and avoid third-party CDNs where possible.

Support

For any inquiries, plugin support, or custom development requests, please contact the author directly.

Commercial partnerships, plugin integrations, or enterprise consulting are handled personally by the author. Please provide detailed context when reaching out so your inquiry can be addressed efficiently.

Development and contributions

Contributions, issues, and feature requests are welcome. The development repository is hosted on GitHub:

Open GitHub repository

Quick start

# Clone
git clone https://github.com/InfinitumForm/onionify.git
cd onionify

# Install dev tools (optional)
# phpcs --standard=WordPress --extensions=php ./src

# Build zip (example)
# zip -r onionify.zip . -x ".git/*" ".github/*" ".DS_Store"

Guidelines

• Follow WordPress Coding Standards and PSR-4 autoloading used in the plugin.
• Keep changes backward-compatible for WP 6.0+ and PHP 7.4+.
• Open an issue before large changes; small PRs are preferred and easier to review.
• Security reports: please contact the author directly via the email in the Support section.

License

GPLv2 or later. See https://www.gnu.org/licenses/gpl-2.0.html.