Add Private Media feature: attachments private by default

[mikelittle]

Summary

Adds the Private Media feature: uploaded media is private by default and only becomes publicly accessible when it's used in published content (or manually overridden, or marked as a site icon, or grandfathered in via the legacy migration).

The goal is to stop authors accidentally leaking unpublished assets — drafts, embargoed PR images, in-progress edits — by URL-guessing or scraping. Once a post is published, all media it references is flipped to public automatically. Once it's unpublished, anything that's no longer referenced anywhere flips back to private.

Opt-in. To enable on a site, add the following to your composer.json:

{ "extra": { "altis": { "modules": { "media": { "private-media": true } } } } }

The feature is always off on the Global Media Library site, even when enabled in configuration. The wp private-media … commands are only registered while the feature is enabled.

Update after review: ACL state was originally stored by repurposing the attachment's post_status; following review feedback it now lives in a dedicated _altis_media_acl post meta so attachments stay at WP's default inherit status and the feature leaves no runtime footprint when disabled. See commit 4601f74 for full rationale.

Update 2026-05-19: the default was flipped from true to false — the feature now ships off and must be explicitly enabled per site. See commit 881de23.

How it works

The feature lives in Altis\Media\Private_Media, bootstrapped from inc/private_media/namespace.php. Bootstrap is deferred until muplugins_loaded because some checks (get_site_meta, is_global_site) aren't available earlier.

Visibility resolution

visibility.php defines a single canonical function — check_attachment_is_public() — that resolves whether an attachment should be public. The decision is priority-based, evaluated in this order:

1. Force-private override → private (absolute precedence)
2. Force-public override → public
3. Used in any published post → public
4. Legacy attachment (legacy_attachment flag in metadata, set by the migration command) → public
5. Site icon → public
6. No _altis_media_acl meta (predates the feature) → public — safety net so enabling private media on a site with existing uploads doesn't silently break them before migrate runs.
7. Default → private

Overrides are stored in attachment metadata under altis_override_visibility ('public', 'private', or absent for automatic). The resolved state is persisted in _altis_media_acl post meta (values 'private' / 'public-read', the literal S3 ACL strings) and is the source of truth for both the UI badges and the actual S3 ACL.

The function is wrapped in a per-request static cache (is_attachment_private_cached) because S3 Uploads' s3_uploads_is_attachment_private filter calls it ~200x per page on a media-heavy view, which used to cause 30-second media library timeouts.

Post lifecycle

post_lifecycle.php hooks transition_post_status and save_post to track which attachments are referenced by which published posts:

• On publish — scans the post content for attachment references via Content_Parser, plus the featured image, plus anything added by the private_media/post_attachment_ids filter. For each referenced attachment, calls add_post_reference() and re-evaluates its visibility. If it should now be public, the attachment's _altis_media_acl meta flips to public-read and its S3 ACL flips to match. The full ID list is stashed on the post in altis_private_media_post meta so unpublish can compare against it.
• On unpublish/trash — reads the stashed ID list, removes each post→attachment reference, and re-evaluates each attachment. If nothing else references it (and there's no override), the meta flips back to private and the S3 ACL follows.
• On edit — diffs the new attachment list against the stored one. Removed attachments lose their reference; new attachments gain one.

Storing the state in post meta rather than post_status means the parent post's transition_post_status cascade isn't re-fired on each touched attachment (which used to OOM on bulk publishes when srcset regen kicked in), and attachments stay at WP's default inherit status so the cap system, admin queries, and third-party plugins behave normally.

Content parser

content_parser.php extracts attachment IDs and URLs from post content. It handles:

• Image blocks — wp:image {"id":N} and <img class="wp-image-N">
• Gallery blocks — wp:gallery {"ids":[...]}
• Cover blocks — wp:cover {"id":N} plus the background image URL
• Media & Text blocks — wp:media-text {"mediaId":N}
• Video blocks — wp:video {"id":N} and the <video> poster attribute
• Audio blocks — wp:audio {"id":N}
• File blocks — wp:file {"id":N} (for PDFs and downloadable files)
• Naked URLs — anything inside the upload baseurl, resolved via attachment_url_to_postid()

extract_attachments_from_content() returns a deduplicated list of [attachment_id, modified_url] tuples. The private_media/post_attachment_ids filter lets sites add custom sources (gallery custom fields, ACF image lists, etc.).

Sanitisation

sanitisation.php hooks wp_insert_post_data to strip AWS signing query params from attachment URLs before content is saved to the database. This is essential: when previewing a draft we sign every private image URL, but those signatures expire and shouldn't be persisted. The sanitiser handles:

• Slashed content (wp_unslash → process → wp_slash round-trip — wp_insert_post_data receives slashed input).
• HTML-encoded & between query params (normalises before splitting).
• Both raw HTML attribute values and JSON-escaped (\/) forms in block comment attributes.

Signed URLs (preview / draft / file blocks)

signed_urls.php makes private images visible in contexts where they aren't yet "public" via the lifecycle:

• Draft preview — hooks the_content (only when is_preview()). Walks attachments via Content_Parser, calls wp_get_attachment_url() (already returns a presigned URL for private attachments via S3 Uploads' filter), then for images routes through tachyon_url() so Tachyon receives the AWS params as top-level query params and replays the signed S3 fetch server-side.
• REST API drafts — hooks rest_prepare_{post_type} and signs URLs in content.raw (the block editor reads from raw, not rendered, and the sanitiser will strip the params again on save).
• Video posters — replace_private_poster_urls() does the same for <video poster="..."> attributes, looked up via attachment_url_to_postid().
• PDF cover images — handled via the canonical-S3 rewrite escape (see below).
• File blocks — block-comment JSON URLs are signed alongside HTML attribute URLs so Gutenberg reads signed URLs from the block attributes on reload.

Two important guards:

1. disable_srcset_in_preview returns an empty wp_calculate_image_srcset in preview / REST contexts, because every srcset variant would need its own signature and responsive image switching can't pick the right one anyway.
2. rewrite_presigned_url_to_canonical_s3 (filter on s3_uploads_presigned_url, priority 999) rewrites the URL host to the canonical regional S3 endpoint (bucket.s3.region.amazonaws.com) so the Host-bound signature matches the request — UNLESS the path is an image extension (.jpg, .png, .gif, .webp), in which case we leave it alone so it can route through Tachyon. Images go through Tachyon for both auth and resizing; non-images (PDF, MP4, etc.) get the canonical-S3 form so the browser hits S3 directly with a valid signature.

Admin media library UI

ui.php adds the visible bits:

• Visibility column in list view — manage_media_columns / manage_media_custom_column. Renders one of four states: Private, Public, Public (forced), Private (forced).
• Grid view badges — wp_prepare_attachment_for_js adds privateMediaOverride and privateMediaIsPublic to the JS attachment model; assets/private-media.css renders an absolute-positioned badge in each tile (lock icon for private, globe for forced public, no badge for naturally public).
• Row actions — Make Public, Make Private, Remove Override (whichever apply, depending on current override state). Each is a nonced GET to upload.php?action=private_media_set_* handled by handle_row_actions().
• Bulk actions — three discrete actions (Set Visibility: Force Public / Force Private / Automatic) handled inline via handle_bulk_actions-upload, applying the chosen override to each selected attachment in the same request as the bulk-form submission (so WP core's bulk-media nonce is the only nonce in play).
• Modal sidebar — attachment_fields_to_edit adds an Attachment Status display, a Visibility Override dropdown, a Used In list of post links, and a Legacy flag if applicable. Edits save via attachment_fields_to_save and via an AJAX handler for in-modal changes.
• Post row actions — Publish image(s) and Unpublish image(s) on the Posts/Pages list, which call handle_publish / handle_unpublish directly for that one post (useful for repairing a single post without running fix_attachments).

PDF cover and video poster sub-size signing

wp_get_attachment_url($pdf_id) returns a presigned URL on the regional S3 host. WP core's image_downsize derives sub-size URLs by taking dirname() of that URL and substituting the cover JPEG filename, dropping the query string in the process — so the cover URL is unsigned. S3 Uploads' wp_get_attachment_image_src filter then tries to sign it via add_s3_signed_params_to_attachment_url, which calls get_s3_location_for_url. That helper only matches the legacy bucket.s3.amazonaws.com/ form (no region) and the upload baseurl — the regional S3 URL matches neither, so the URL passes through unsigned and the browser hits 403, collapsing the grid tile to ~16px wide.

To work around this without modifying S3 Uploads:

• sign_non_image_subsize_url() is hooked on wp_get_attachment_image_src at priority 11 (after S3 Uploads at 10). For private non-image attachments, it normalises the URL host to the upload baseurl form, then re-runs S3 Uploads' signing — which now resolves and produces a presigned URL bound to the cover JPEG's actual S3 key.
• add_visibility_to_js() re-signs URLs in $response['sizes'] and $response['image']['src'] for the same reason, since wp_prepare_attachment_for_js builds those URLs through paths that don't all flow through wp_get_attachment_image_src.

The same code path handles video poster images. There's a related upstream bug filed against humanmade/s3-uploads requesting that get_s3_location_for_url recognise regional S3 URLs natively, after which this workaround can be removed.

Site icon

site_icon.php automatically marks the configured site icon as forced-public (it needs to be reachable on every page). An explicit force-private override on the site icon takes precedence — that's a deliberate footgun if you want it.

WP-CLI

class-cli-command.php exposes three commands. All support --dry-run. The commands are only registered while the feature is enabled in configuration:

• wp private-media migrate [--dry-run] — one-time, run when first enabling on a site with existing content. Marks every existing attachment as legacy_attachment and records _altis_media_acl = public-read on it so it stays accessible. Iterates with proper forward pagination in dry-run mode (the bug where dry-run hung was fixed in bbde9b6).
• wp private-media set_visibility <public|private> <id|filename> [--dry-run] — sets a manual override on a single attachment, equivalent to the row action. Resolves attachments by numeric ID or by filename via _wp_attached_file postmeta.
• wp private-media fix_attachments [--start-date=<date>] [--end-date=<date>] [--dry-run] [--verbose] — repair tool. Walks every published post in a date range (default last 30 days, post date not modified date), re-scans content for attachments, re-records references, and re-evaluates visibility. Use after content imports, SQL edits, or filter changes. Defaults to allowed post types (anything with editor support), falling back to post/page.

Configuration filters

Filter	Purpose
private_media/allowed_post_types	Post types whose content is scanned for attachment references
private_media/post_meta_attachment_keys	Postmeta keys that contain attachment IDs (defaults: featured image)
private_media/post_attachment_ids	Final attachment-ID list per post — add custom gallery/ACF sources here
private_media/update_s3_acl	Test seam: short-circuit S3 ACL changes (return non-null)
private_media/purge_cdn_cache	Test seam: short-circuit CDN purge (return non-null)
private_media/do_purge_cdn_cache	Action fired when CDN cache should be purged for an attachment

Files

• inc/private_media/ — 10 PHP source files (visibility, post_lifecycle, content_parser, sanitisation, signed_urls, site_icon, ui, class-cli-command, cli, namespace)
• assets/private-media.{js,css} — grid badges and modal sidebar wiring
• inc/namespace.php and load.php — bootstrap integration; load.php registers the private-media default (now false).
• docs/private-media.md + docs/assets/*.png — full user documentation including 7 screenshots, with grid view as the primary mode (matching the Altis default)

Automated tests

Integration: 81 tests across 9 files in tests/integration/PrivateMedia/:

File	Tests	Coverage
BootstrapTest	4	Opt-in gate resolution: empty config / explicit false / falsy values / explicit true
VisibilityTest	16	Priority resolution: overrides, used-in-published, legacy, site icon, pre-feature, default; cache invalidation
ContentParserTest	19	All block formats: image, gallery, cover, media-text, video, audio, file, naked URLs
PostLifecycleTest	13	publish/unpublish/trash/edit transitions, removed-attachment diffing
SanitisationTest	10	Slashed content, & normalisation, JSON-escaped URLs in block comments
OverrideTest	7	Set/get/remove override, precedence, idempotence
BulkActionsTest	5	Three bulk actions (force public/private, remove override), unrelated-action passthrough, per-attachment cap check
SiteIconTest	4	Site icon auto-public, force-private precedence
SignedUrlsTest	3	Preview signing, REST signing, srcset disable

Run with: composer dev-tools codecept run integration -p vendor/altis/media/tests/

Each test that touches S3 uses S3MockTrait to short-circuit private_media/update_s3_acl so the suite runs without an S3 client. The suite requires the host project to enable private-media: true in its composer.json — the product-dev test environment does this.

Acceptance: PrivateMediaCest (4 cases) in tests/acceptance/. These exercise the admin UI end-to-end via WPWebDriver. They cannot be run from CI in the same job as integration tests because they require a Chrome container and a TTY, so they're run manually:

composer dev-tools codecept run acceptance -p vendor/altis/media/tests/

Recommended manual tests

The local stack covers the lifecycle and UI thoroughly via the automated suite. The areas worth eyeballing manually before merge are the ones that depend on real S3 and real Tachyon/CDN behaviour, which the local setup mocks or stubs.

On a local stack (composer server start)

1. Upload an image, a video, an audio file, and a PDF. Confirm all four show up with lock badges in the grid view.
2. Insert two of the images into a new post and publish it. Confirm those two attachments lose their lock badges (now naturally public) and the others remain private.
3. Force one image public via the row action. Confirm it shows the globe badge and Public (forced) in list view.
4. Force the PDF private via the row action. Confirm it stays private (in addition to being unused) and shows Private (forced) in list view.
5. Unpublish the post from step 2. Confirm both images flip back to private and re-acquire lock badges.
6. Re-publish, then bulk-select via list view → Set Visibility: Force Public. Confirm the selected attachments flip to public and a "N attachment(s) updated" notice appears.
7. Run wp private-media migrate --dry-run then wp private-media migrate. Confirm dry-run completes (the previously-broken hang).
8. Run wp private-media fix_attachments --dry-run --verbose. Confirm the per-post output looks sane.

On a real AWS environment

These cover paths that depend on actual S3, CloudFront, and Tachyon — they cannot be exercised locally.

1. Direct presigned URL via CloudFront — curl a presigned URL on the deployed domain. Should return 200. (Previously failing on platform-test.aws.hmn.md due to a CloudFront Host-header forwarding gap — verify the platform team's fix is in place by comparing against the existing client production, where it works.)
2. Draft preview of a post with private images — open a draft, click Preview, confirm images render via Tachyon presign params. Not 404, not empty body.
3. Editor image insertion — insert a private image into a Gutenberg post, save, close, re-open. Image should still be visible (signed via content.raw in the REST response).
4. Publish → S3 ACL flip — upload a fresh private image, embed it in a post, publish, then curl the direct S3 URL. Should return 200 public. Repeat for unpublish.
5. PDF in published post — confirm PDFs become accessible on publish (PDFs aren't Tachyon-able, so this exercises the canonical-S3 path).
6. Bulk publish OOM regression — publish a post that references many attachments. Confirm no memory blow-up (the wp_update_post → direct $wpdb->update fix).
7. Stale metadata cache regression — edit an image's alt text or dimensions and reload the post. Confirm metadata reflects the update (the Cropper static-cache $unfiltered=true fix).
8. Site icon — confirm the favicon stays accessible on all pages with the feature enabled.
9. PDF / video grid rendering — upload a PDF and a video that has a poster image. Confirm both render with their cover/poster thumbnails and lock badges in both grid and list views. (This is the path covered by the recent 8c7dbcf cover-sub-size signing fix.)
10. wp private-media migrate on a site with pre-existing uploads — run dry-run first, then for real. Confirm legacy uploads stay accessible after migration.
11. wp private-media fix_attachments — run against a date range that includes recently-imported posts. Confirm the reference list and visibility are reconciled correctly.
12. wp private-media set_visibility public <id> — set against a real S3 attachment and confirm the ACL flips.

[mikelittle]

@wisyhambolu I fixed the bulk action stuff. It was just wrong (Claude problem). Also added some tests to check the functionality too.

[jerico]

We had a customer before that have Tachyon disabled. I'm wondering if we should also consider that, add a check if the Tachyon function exists.

[mikelittle]

We had a customer before that have Tachyon disabled. I'm wondering if we should also consider that, add a check if the Tachyon function exists.

Gonna check this next.

[mikelittle]

Most of it will work without Tachyon. And there is a check, function_exists( 'tachyon_url' ). But to switch out the use of Tachyon completely (it currently is assumed for previews) we will hit the issue where the S3 bucket is accessed from two different hostnames: internally in the code, vs with the external hostname. We would have to rewrite image URLs to the S3 bucket URLs, like we already do for other non-image URLs in preview.

[mikelittle]

Updated to handle the case where Tachyon is disabled.

[rmccue]

Overall looking pretty good, although I spotted a few bugs with it, and some sharp edges for usability.

Spotted two blockers: uploading images directly to the Media Library seems to make them public, via the attachment page. Specifically:

1. Open Media page
2. Drag an image in to upload it
3. Observe "Attachment Status: Private" and the lock icon in the list
4. Open the image's modal, and open the "View attachment page" in a new window.

Additionally, the REST API seems to have the image available at /wp-json/wp/v2/media - both source_url and the description have the signed URL available, despite the UI displaying "Private".

This might be a UI bug rather than a data bug, as I think actually the image is meant to be public in this scenario?

[mikelittle]

Spotted two blockers: uploading images directly to the Media Library seems to make them public, via the attachment page. Specifically:

1. Open Media page
2. Drag an image in to upload it
3. Observe "Attachment Status: Private" and the lock icon in the list
4. Open the image's modal, and open the "View attachment page" in a new window.

I couldn't reproduce this. See attached video.

private-media-1-hb.mp4

But I did find a different bug: the link to the full-sized image is not encoded with the correct S3 bucket hostname.
Fixing that now.

That bug (attachment page link) is now fixed.