# Security notes

This guide is for the person who installs and runs the shop. It describes what
ProofKit does on its own, what the server has to do, and what to check when
something goes wrong. It does not replace a host's security advice.

## Threat model

ProofKit assumes untrusted input from three directions: anyone who can reach a
product page can attempt an upload, anyone holding an emailed proof link can
attempt an approval, and shop staff with `manage_woocommerce` can read and act
on every proof. It also assumes shared hosting, where `.htaccess` may be
ignored, other sites or processes may be able to read the filesystem, and
access logs and backups live outside the shop's control. The risks that matter
are: artwork fetched without authorisation, a proof approved by the wrong
person, a file that executes in a browser, and losing the evidence of what was
approved. A hostile server administrator is out of scope.

## What the plugin already does

- **Approval tokens are hashed and single-use.** The raw value is 32 random
  bytes; the database stores only its SHA-256 hash. Validation is
  constant-time, checks the proof, scope and expiry, and marks the token used
  on success.
- **Upload descriptors are signed and short-lived.** A descriptor carries the
  path, original name, MIME type, size, SHA-256 and expiry, and is signed with
  HMAC-SHA256 using a WordPress salt. It is valid for 72 hours, and the
  referenced file is only purged after 96 hours if no proof uses it.
- **Storage is content-addressed and private by path.** Files live under
  `{ab}/{cd}/{sha256}.{ext}` in the private directory. Existing hashes are
  never overwritten, and paths are checked against traversal and symlinks.
- **Uploads are validated by content, not by filename.** Extension allow-list,
  `wp_check_filetype_and_ext()`, magic-byte/MIME comparison, double-extension
  rejection, and size caps. Per-product limits are enforced server-side, with
  the global limit as the hard ceiling.
- **Hashes are checked before a file is sent or downloaded.** A mismatch or a
  missing file stops the send; a download returns an error rather than the
  wrong bytes.
- **The event log has no edit or delete screen.** Status changes append rows
  (uploaded, sent, viewed, downloaded, download blocked, approved, changes
  requested, superseded). Automatic retention is the only path that removes
  proof data without an explicit opt-in; it records the purge in the error log
  before deleting rows.
- **Admin actions require both a capability and a nonce.** Sending, uploading
  a proof, downloading and resending all require `manage_woocommerce` and a
  per-operation nonce (`proofkit_send_proof`, `proofkit_upload_proof`,
  `proofkit_resend_proof`, `proofkit_download_proof`). Downloads are submitted
  by POST, so the nonce is not placed in a long-lived GET URL.
- **Rate limits.** Uploads are limited to 20 per hour per logged-in user or
  hashed IP (shop managers are exempt). Approval submissions are limited to 20
  per hour per IP and proof. View events are throttled per token.
- **No telemetry.** No analytics, remote assets, phone-home or external API.
  The only outbound traffic is the proof email, sent through the site's mailer.

## Nginx is not protected by .htaccess

This is the one server setting that is easy to miss. Apache reads `.htaccess`;
Nginx does not. ProofKit writes `.htaccess`, `index.php`, `web.config` and an
`nginx.conf.example` into the private directory, but on Nginx only the PHP
streaming endpoint protects the files until you deny the path.

Add this to the `server` block that serves WordPress:

```nginx
location ^~ /wp-content/uploads/proofkit-private/ {
    deny all;
    return 403;
}
```

Test the configuration, then reload Nginx:

```sh
sudo nginx -t
sudo systemctl reload nginx
```

Use `sudo nginx -s reload` or your init system's equivalent if you do not use
systemd. Then open `https://your-site.example/wp-content/uploads/proofkit-private/`
in a browser: it must return 403, not a directory listing, a download, or a
redirect to a login page.

If WordPress is installed in a subdirectory, or the uploads directory has been
moved, adjust the path to match. If a CDN or separate static file server
fronts the site, make sure it does not serve this path either.

## Apache, LiteSpeed and IIS

Apache and LiteSpeed use the generated `.htaccess`; IIS uses the generated
`web.config`. Test the directory URL anyway, especially on Apache with
`AllowOverride None`, where `.htaccess` files are ignored. The PHP endpoint is
the intended boundary; the deny rule is the second lock, not a replacement.

## Moving the private directory

Not available in v1. The location is derived from WordPress's uploads
directory (`wp-content/uploads/proofkit-private/`), and there is no ProofKit
setting, filter or constant to relocate it. Treat an out-of-web-root location
as a planned improvement and rely on the Nginx deny rule for now.

## Backups

Include `wp-content/uploads/proofkit-private/` in the same backup set as the
database, and restore them together. Each proof row stores a relative path and
a SHA-256, and every send or download re-checks the hash:

- Database restored without the files: proofs exist but sends fail and
  downloads return an error, because the originals are gone.
- Files restored without the database: the files are orphaned. Maintenance
  deletes unreferenced files after 96 hours.

Back up before upgrades and before uninstalling with delete-data enabled. On
multisite, every site has its own directory under its own uploads path.

## SVG

SVG is off by default. Leave it off unless the shop trusts its customers and
genuinely needs vector uploads. Even when enabled, SVG is download-only: it is
never previewed inline on the proof page and is always served as an attachment
with frame denial. The upload check screens for common script patterns, but
that is a filter, not a sanitiser. The download-only rule is the real control.
Ask customers for PDF when possible.

## Approval links travel in the query string

A proof link looks like
`/?proofkit_proof=1&proof_id=..&order_id=..&token=..`. The token is therefore
visible to access logs, browser history, proxy logs and anyone who sees a
screenshot. The page sends `X-Robots-Tag: noindex, nofollow`,
`Referrer-Policy: no-referrer` and `Cache-Control: no-store`, which limits
search indexing and caching but does not hide the URL.

- Approval is single-use: using the link to approve or request changes consumes
  the token.
- Links expire after the **Proof link expiry** setting, 30 days by default
  (1–365).
- Uploading a newer version supersedes the older proof and revokes its links,
  so an old email stops working.

Do not paste proof links into support tickets, chat, screenshots or URL
shorteners. If staff need to discuss a proof, use the order number and version
instead. If a link does leak, upload a new version for that line item to void
it, then send the new proof.

## Multisite

Each site has its own tables (with that site's prefix), its own settings and
its own private directory, normally
`wp-content/uploads/sites/<id>/proofkit-private/`. A proof on one site is not
visible on another, and each site runs its own daily maintenance.

Uninstall follows the same split. Deleting the plugin from a single site
removes that site's data only. Deleting it from the Network Admin walks the
sites in the network and removes each site's tables, options, transients and
private directory when **Delete all ProofKit data** was enabled. If you are
retiring the whole network, verify each site's directory is gone before
assuming the uninstall was complete.

## Incident checklist

1. **Stop the link.** Upload a new version of the proof for the affected line
   item. Earlier versions become superseded, all of their tokens are revoked,
   and the old email links stop working. Then send the new proof if the
   customer still needs to approve.
2. **Contain the account.** If a staff account may be compromised, change its
   password, review who has `manage_woocommerce`, and revoke sessions. A
   compromised shop account can read every proof and act on any order.
3. **Read the event log.** Open the order's ProofKit panel. Uploads, sends,
   resends, views, downloads, approvals, change requests and supersedes are
   listed with actor, time and a salted IP hash. Compare the hash across events
   rather than trying to reverse it.
4. **Treat an exposed file as public.** If an artwork file was fetched by
   someone who should not have it, the bytes are out. Tell the customer and
   decide whether the job can still run.
5. **Do not delete the order to clean up.** Deleting a WooCommerce order does
   not remove its proofs. Deleting data removes the evidence. Keep it until the
   retention period has passed, and take an export or backup first if you must
   remove it early.
6. **Check the server.** Look for direct requests to
   `/wp-content/uploads/proofkit-private/` in the access log. A stream of 200
   responses means the Nginx deny rule (or the `.htaccess` equivalent) is
   missing.

## What ProofKit does not protect against

- A compromised admin or shop-manager account. `manage_woocommerce` is enough
  to read, upload, send and download.
- A hostile or careless hosting provider, server administrator, or backup
  system that exposes the database or files.
- Malware, another vulnerable plugin, or a theme on the same site. Code running
  in WordPress can read the private directory and the database directly.
- A customer approving the wrong file, or a forwarded proof link used by
  someone else before it expires or is superseded.
- Print colour, substrate, resolution, bleed, font or trapping errors. The
  plugin records approval; it does not check the artwork.
