=== Hippius Media Offloader ===
Contributors: hippius
Tags: media, offload, cdn, cloud storage
Requires at least: 5.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Distributed media storage for WordPress, powered by Hippius and Arion.

== Description ==

Hippius Media Offloader lets you migrate your WordPress media library to Hippius — a distributed cloud storage platform where every file is encrypted, replicated across an independent network, and verifiable on-chain.

Files are stored on Arion, Hippius's own distributed storage engine. Your media is split into 30 shards (10 data + 20 parity) using Reed-Solomon erasure coding, then placed across the network with the CRUSH algorithm. Up to 20 nodes can fail simultaneously and your files still rebuild perfectly.

The plugin communicates with Hippius through the S3-compatible API — the same API you'd use to talk to AWS S3. No code changes, no proprietary SDK, no IPFS configuration.

**What this plugin does**

* Migrates existing WordPress media files in bulk to Hippius
* Automatically offloads new uploads in the background
* Replaces local media URLs with Hippius URLs in your posts and pages
* Lets you keep local copies as backups, or delete them to save disk space
* Tracks migration status, errors, and storage usage from a single dashboard

**What this plugin does not do**

* It does not act as a CDN — for global content delivery use a CDN in front of Hippius
* It does not back up your WordPress database — only media files
* It does not encrypt files client-side. Hippius encrypts objects server-side using NaCl + KMS — miners only see encrypted bytes. For client-side end-to-end encryption, use the Hippius Desktop App

== Before You Start ==

**System requirements**

* WordPress 5.0 or higher
* PHP 7.4 or higher
* cURL PHP extension enabled
* HTTPS enabled on your WordPress site (strongly recommended)

**What you'll need from Hippius**

* A Hippius account (free to create at console.hippius.com)
* Credits in your account to cover storage usage
* S3 Access Key ID (starts with `hip_`)
* S3 Secret Access Key
* Hippius API token (optional — only required for in-dashboard credit balance checks)

**Important.** Keep your **Secret Access Key** safe. It is shown only once at creation and cannot be retrieved later. If you lose it, you'll need to generate a new key pair.

== Installation ==

You can install Hippius Media Offloader in two ways.

**Option A — From the WordPress plugin directory (recommended)**

1. Log in to your WordPress admin dashboard.
2. Go to **Plugins → Add New**.
3. Search for **Hippius Media Offloader**.
4. Click **Install Now**, then **Activate**.

**Option B — Manual upload**

1. Download the plugin zip from `wordpress.org/plugins/hippius-media-offloader/`.
2. In WordPress admin, go to **Plugins → Add New → Upload Plugin**.
3. Select the zip file and click **Install Now**.
4. Activate the plugin from the **Plugins** screen.

**After activation**

A new menu item **Hippius Media** will appear in your WordPress admin sidebar. That's the plugin's home base.

== Get Your Hippius Credentials ==

Before configuring the plugin, you need to create your Hippius account and generate your S3 credentials. This takes about 2 minutes.

**Step 1 — Create your Hippius account**

1. Go to `console.hippius.com`
2. Sign up with Google or GitHub OAuth.

**Note.** No wallet, no seed phrase, no browser extension required. Just OAuth.

**Step 2 — Add credits**

1. In the console, go to **Billing**.
2. Add credits using credit card (Stripe) or TAO.

Credits are consumed as the plugin stores and serves your media. 1 credit = $1 USD.

**Step 3 — Create your S3 credentials**

1. In the console, go to **S3 Storage**.
2. Click **Create Master Token**.
3. Save your **Access Key ID** (starts with `hip_`) and **Secret Key** somewhere safe.

**Critical.** Your Secret Key is shown only once. Copy it immediately to a password manager. It cannot be recovered if lost.

**Step 4 — Create the bucket (manual)**

The plugin does not automatically create buckets. You need to create your media bucket manually before configuring the plugin.

1. In the console **S3 Storage** section, create a new bucket.
2. Choose a name (e.g. `wp-media` or your-site-name).
3. Set the bucket policy to **public** if you want media to be accessible without authentication (recommended for most WordPress sites).

**Step 5 — (Optional) Generate an API token**

If you want the plugin to display your remaining credit balance inside the WordPress dashboard, generate an API token:

1. Go to **Settings → API Keys** in the Hippius console.
2. Generate a new API token and save it.

This is optional — the plugin works fully without it. The token is used only to display balance information in your admin dashboard.

== Configure the Plugin ==

Go to Hippius Media in your WordPress admin sidebar. The configuration page has several fields.

**Configuration fields**

= Access Key ID =
Paste the Access Key ID you generated above. It starts with hip_.

= Secret Access Key =
Paste your Secret Access Key. This field is masked in the UI for security.
Leave blank to keep an existing Secret Access Key — useful when updating other settings.

= API Token (optional) =
Paste your API token if you generated one. This is used only to display your account credit balance inside the WordPress dashboard.

= S3 Endpoint =
The Hippius S3 endpoint URL. Default: `https://s3.hippius.com`

For better latency, you can use a regional endpoint instead:

* Europe: `https://eu-central-1.hippius.com`
* US: `https://us-east-1.hippius.com`

All regions serve the same data — pick whichever is closest to your WordPress server.

= Bucket Name =
The name of the bucket you created in the Hippius console. Default: `WP-Media`

**Important.** The bucket must already exist in the Hippius console before you set it here. The plugin will not auto-create buckets.

**Migration options**

= Keep Local Files =
When checked, original media files stay on your WordPress server after migration. When unchecked, local files are deleted after successful upload to Hippius, freeing up disk space.

**Recommendation.** Keep this checked when you first start migrating. Once you've verified everything works and your media is correctly served from Hippius, you can disable it to save server disk space.

= Auto-Migrate New Uploads =
When enabled, any new media file uploaded to WordPress is automatically migrated to Hippius in the background. Recommended once initial setup is verified.

== Test the Connection ==

Before migrating any files, test that the plugin can reach Hippius with your credentials.

1. Save your configuration.
2. Click **Test Connection**.
3. Wait for the response.

**Possible results**

* Connection successful — credentials accepted, bucket reachable. You're ready to migrate.
* Connection failed — see the Troubleshooting section for the exact error and how to fix it.

== Migrate Your Media ==

You have two migration modes: bulk (for existing files) and auto (for new uploads). You can use either or both.

**Bulk migration — for existing files**

If your WordPress site already has media files in the library, use bulk migration to move them all to Hippius in one operation.

1. Go to **Hippius Media → Bulk Migration**.
2. Click **Start Migration**.
3. Watch the progress bar — the plugin processes files in batches and shows real-time progress.

**Note.** Bulk migration runs in the background. You can leave the page or close the tab — migration continues. Come back later to check progress.

**What happens during migration**

* Each file is uploaded to your Hippius bucket via the S3-compatible API.
* WordPress media URLs are updated to point to the Hippius URL (transparent to visitors).
* If "Keep Local Files" is unchecked, the local file is deleted after successful upload.
* Each file is registered with a unique content hash stored on the Hippius blockchain — verifiable on-chain.

**Auto migration — for new uploads**

Once auto-migration is enabled, you don't need to do anything else. Every new file you (or any author on your site) uploads to the WordPress Media Library is automatically offloaded to Hippius in the background.

To enable it:

1. Go to **Hippius Media → Settings**.
2. Check **Auto-Migrate New Uploads**.
3. Save.

== Verify Migration & Monitor Usage ==

The plugin dashboard gives you a live overview of what's been migrated and your storage usage.

**Statistics**

* Total Media Files — number of files in your WordPress media library
* Migrated Files — files successfully stored on Hippius
* Not Migrated Files — files still only local

**Usage**

* Total Hippius Storage — how much data you've stored on Hippius
* Local Storage Used — how much local disk your media still consumes
* Potential Savings — what you'd save in local disk if you disabled "Keep Local Files"
* Migration Progress — percentage of media library migrated

**Verify a file is really on Hippius**

To check that a specific file is actually stored on Hippius:

1. Open the WordPress Media Library and edit the file.
2. Check the file URL — it should point to your Hippius bucket, not to wp-content/uploads.
3. You can also check the **Debug Log** inside the plugin for upload confirmation entries showing the file's content hash.

== Frequently Asked Questions ==

= What is Hippius? =

Hippius is a distributed cloud storage platform. Your files are split, encrypted, spread across an independent network of nodes, and verifiable on-chain. It's the simplicity of mainstream cloud — without having to trust a single provider.

= What is Arion? =

Arion is Hippius's own distributed storage engine. It uses Reed-Solomon erasure coding (10 data shards + 20 parity shards = 30 total) and the CRUSH placement algorithm. Your files reconstruct perfectly even if up to 20 nodes fail simultaneously.

= Do my files leave WordPress encrypted? =

Communication between WordPress and Hippius uses HTTPS. Once on Hippius, files are encrypted server-side using NaCl envelope encryption — miners only see encrypted bytes, never your content. For true end-to-end client-side encryption on media, use the Hippius Desktop App in parallel.

= Where are my credentials stored? =

Your Access Key ID, Secret Access Key, and API token are stored in WordPress's standard options API, with admin-only access. The Secret Access Key field is masked in the UI and never exposed via JavaScript or to the front-end.

= Will this affect my website performance? =

In most cases it improves performance. Hippius serves files through a distributed network of nodes, reducing load on your origin server and freeing up your hosting bandwidth. For global audiences, you can also put a CDN in front of Hippius.

= What happens to my existing media files? =

Existing files remain untouched until you actively migrate them. You can bulk-migrate everything, or only enable auto-migration for new uploads and leave the legacy files local.

= Can I revert back to local storage? =

If you kept local copies during migration, deactivating the plugin restores WordPress's default behavior of serving from wp-content/uploads. There's no automated reverse-migration that downloads files back from Hippius — keep local copies if you want safe reversibility.

= What if migration fails for some files? =

The plugin logs each failure with a clear reason. You can retry failed migrations manually from the dashboard.

= Does the plugin support all WordPress file types? =

Yes — images, videos, audio, documents (PDF, DOC, XLS, etc.), archives, and any other WordPress-supported media type. Custom file types can be added through WordPress filters.

= Can I use multiple buckets? =

The plugin uses one bucket per site. If you need multiple buckets (e.g. for different content types), you can run multiple WordPress sites each pointing at a different bucket.

== Troubleshooting ==

If something doesn't work, check the **Error Log** and **Debug Log** at the bottom of the plugin page first — they usually pinpoint the exact issue.

**"Test Connection" fails with 403 / Access Denied**

Possible causes:

* Wrong Access Key ID or Secret Access Key — double-check both, no leading/trailing spaces.
* The bucket name doesn't match an existing bucket in your Hippius account.
* Your account has no credits — check your balance in the Hippius console.

**"Test Connection" fails with timeout or DNS error**

* Your server cannot reach the Hippius endpoint. Check that outbound HTTPS traffic is allowed.
* Try changing the S3 Endpoint to a regional one (eu-central-1 or us-east-1).

**Some files fail to migrate**

Check the Error Log for the specific error per file. Common causes:

* File is too large — Hippius supports large files, but your PHP setup may have upload limits. Increase upload_max_filesize and post_max_size in your PHP configuration.
* File is corrupted or unreadable on the local disk.
* Network timeout during upload — retry the failed file from the dashboard.

**Migrated media doesn't appear on the front-end**

* Clear your WordPress cache (and any CDN cache in front of WordPress).
* Verify the bucket policy is set to public if you want the media accessible without authentication.
* Check that the URLs in your posts have been updated — the plugin handles this automatically, but cached pages may still hold the old URLs.

**Credit balance shows 0 or doesn't update**

* Make sure you've added your API token in the plugin settings (not just the S3 keys).
* Click the **Check Balance** button to force a refresh.

**How to read the Debug Log**

The Debug Log shows every URL override decision made by the plugin. Useful entries:

* Original file match — the plugin found a matching Hippius file for a given URL.
* No size match found — the plugin used the original-size CID as fallback.
* Fallback URL — the URL that was actually served.

== Support & Resources ==

**Plugin support**

* WordPress.org forum: `wordpress.org/support/plugin/hippius-media-offloader/`

**Hippius documentation**

* Official docs: `docs.hippius.com`
* S3 API reference: `docs.hippius.com/storage/s3/integration`
* How storage works (Arion): `docs.hippius.com/learn/storage-systems`

**Hippius console**

* Account, billing, credentials: `console.hippius.com`

**Community**

* Community forum: `community.hippius.com`

== Screenshots ==

1. WordPress plugin search results showing Hippius Media Offloader.
2. Hippius Media menu item in WordPress admin sidebar.
3. Hippius console sign-up page.
4. Billing page with credit top-up.
5. S3 Storage page with Master Token creation.
6. Hippius Media settings page (configuration section).
7. Test Connection button and success message.
8. Bulk Migration screen with progress bar.
9. Statistics and Usage section of the plugin dashboard.
10. Error Log and Debug Log sections.

== Changelog ==

 = 1.0.2 =
* Fixed front-end images (thumbnail, medium, medium_large, etc.) resolving to incorrect S3 paths
* Fixed admin Media Library grid thumbnails failing to load (image_downsize override)
* Fixed responsive srcset attributes pointing to broken URLs
* Added deterministic S3 URL reconstruction as a fallback when per-size object URL metadata is missing, instead of relying on the public IPFS gateway
* Fixed image src always falling back to the full-size image URL instead of the correct per-size URL

= 1.0.1 =
* Rebranded from IPFS to Hippius distributed storage powered by Arion
* Removed IPFS Gateway URL configuration field
* Updated all storage labels and descriptions throughout the plugin
* Replaced all IPFS terminology with Hippius/Arion equivalents

== Upgrade Notice ==

= 1.0.2 =
Important fix: resolves broken images on the front-end and in the Media Library for sites migrated to Hippius storage. Recommended for all users.