# Private media storage

Use one existing private R2 or S3-compatible store without changing the media library.

## Choose one store

Without storage settings, Catalog uses the native `MEDIA` R2 binding. Point that
binding's `bucket_name` at your existing private bucket; no S3 credentials are needed.
Uploads, background imports, replacements, use protection and media URLs keep the
same behavior. Storage choice does not select an image CDN or transformation service:
`MEDIA_ORIGIN` and `MEDIA_TRANSFORM` still configure delivery separately.

For AWS S3 or a compatible endpoint, set these **server-side** Worker vars:

```json
{
  "MEDIA_STORE": "s3",
  "MEDIA_S3_ENDPOINT": "https://s3.eu-central-1.amazonaws.com",
  "MEDIA_S3_BUCKET": "merchant-private-media",
  "MEDIA_S3_REGION": "eu-central-1",
  "MEDIA_MANAGED_ROOT": "orbcatalog/test/"
}
```

Install `MEDIA_S3_ACCESS_KEY_ID` and `MEDIA_S3_SECRET_ACCESS_KEY` as Worker secrets.
`MEDIA_S3_SESSION_TOKEN` is an optional secret for temporary credentials; rotation
and renewal remain the operator's responsibility. Locally use an ignored `.dev.vars`.
Never put these values in vars, URLs, logs, browser code or the repository. The S3
mode does not need a `MEDIA` binding and never falls back to one after an error.
The native mode can be selected explicitly with `MEDIA_STORE=r2`.

The endpoint must be an HTTPS origin without a path, query, fragment or embedded
credentials. Requests use path-style bucket addressing and header-based AWS SigV4,
not public or presigned URLs; redirects are refused. Use your bucket's actual region
and regional endpoint. For R2's S3 API use your account's jurisdiction-appropriate
endpoint and region `auto`; a same-account native binding is simpler. Keep data in
the EU. Nothing creates a bucket, account, domain, policy or public-access setting.

## Reserve the managed root

`MEDIA_MANAGED_ROOT` defaults to `orbcatalog/`. Reserve this previously unused prefix
for Catalog alone; choose a separate root per catalog/environment sharing a bucket.
It must end in `/` and contain only nonempty segments of letters, digits, `_` or `-`.
Choose it before importing: changing the store or root is not a migration and does
not scan, copy or adopt old objects.

Catalog stores originals at `{root}{mediaId}`, replacement staging at
`{root}replacing/{mediaId}/{digest}/{attempt}` and generated variants at
`{root}renditions/{mediaId}/{opaque-validator}/{width}.webp`. Registered originals
stay at their existing keys; only their protected JSON locators are written at
`{root}locators/{mediaId}.json`. Library URLs do not
contain the root. Cleanup can list only a single file's rendition prefix;
all writes/deletes are root-relative. Existing keys outside the root, including
similarly named sibling prefixes, are never overwritten or deleted by managed cleanup.
Objects under the reserved root belong to Catalog; do not place unrelated files there.

Selecting a bucket alone does not register its existing originals in the library.
There is no bucket browser, scan, bulk copy or direct browser upload. Private-key
registration and delivery are separate from store configuration. Already-public
CDN files can instead use [public media links](/docs/integrate/catalog-sources#keep-images-on-an-existing-cdn).

## Authorize registration

Registration is disabled by default, including on a new Startup catalog. To enable
it, provide `MEDIA_REGISTRATION_GRANTS` as a server-side JSON object. Each key is
an authenticated Source's stable ID, not its name, key, or product-field ownership.
Each selection is either an exact `key` or a directory `prefix` ending in `/`:

```json
{
  "MEDIA_STORE_ID": "merchant-images-eu",
  "MEDIA_REGISTRATION_GRANTS": {
    "src_akeneo000002": [{ "prefix": "products/" }, { "key": "campaigns/winter-hero.jpg" }]
  }
}
```

**This grants consent to public library delivery**, not just private
storage access. Grant only selected shopper-image namespaces. Prefix matching is
exact and directory-bounded: `products/` does not allow `products-backup/`. Keys
inside the managed root are always refused, even if a selection would allow them.
No Source grant permits listing, raw-byte replacement or deletion. Source requests
cannot choose a store, endpoint, bucket, public URL or permissions. Provider IAM and
these application grants are separate protections; restrict both.

Removing a grant prevents further registration by that Source. It does not withdraw
existing library entries or published uses; those keep the ordinary use protection
and 30-day library retention behavior.

For the native R2 binding, `MEDIA_STORE_ID` is mandatory when opting into registration
and must remain configured for delivery after grants are removed. A fresh catalog
needs neither setting. R2 bindings do not disclose their bucket identity to this adapter, so this
ID must identify the physical bucket across deployments and credential changes.
Keep it when rebinding the same bucket; **change it when binding a different bucket**.
Do not reuse an ID for another physical store. Changing it is not a migration.
The S3 mode derives registration identity from the normalized endpoint origin and
exact bucket name; a configured native ID cannot alias a different S3 endpoint or
bucket. Keep the endpoint stable when it still denotes the same physical store.

Use [Source `registerMedia()`](/docs/integrate/catalog-sources#register-selected-private-objects)
with bounded metadata rows. The server checks each permitted object's HEAD without
copying or reading its bytes. Dimensions are supplied by the Source. All registered
originals remain read-only; metadata edits, unregistering and retention cleanup
never delete them. A small indexed identity record remains after a library entry
is forgotten so registering that same store/key again reuses its media ID.

## Use an owned replacement

An editor with content-edit authority opens the file in **Media** and chooses
**Use owned copy**, then selects new image bytes. The staff API is
`PUT /panel/media/{mediaId}/owned-copy`, with the image as its body. It creates no
second library file: the same ID, uses, name, folder, alt text and focal point remain.
The new bytes must preserve the image's proportions (1% rounding tolerance) and must
not belong to another managed library file; `media_exists` identifies that file instead.
The registered original is never overwritten, deleted or granted management rights.

`GET /panel/media/{mediaId}` reports `replacement`: `owned-copy` for registered files,
`in-place` for managed files, and `none` for public external references. This is a
description of the file, not an authorization grant; the server checks staff authority
and current state again on writes. Ordinary `PUT /panel/media/{mediaId}` still refuses
registered originals with `media_readonly`. Sources cannot call the adoption endpoint
or grant themselves management. Repeating adoption with the same bytes is harmless;
different bytes after adoption return `media_changed`, rather than overwriting a
concurrent editor's replacement. Open the file again to use ordinary replacement.

Before any storage operation, each replacement attempt commits a private SQL grant
and delayed abandonment task together. The grant expires after 15 minutes: this permits
abandonment, not an assumption that provider requests have finished. Its unique staging
key first receives a small initial marker with create-if-absent. Only an acknowledged,
bounded read of that exact marker supplies the validator for the conditional image PUT.
The library transaction consumes the active, unexpired grant and transfers accepted
bytes to its durable install task, or refused bytes to a discard task. The install task
conditionally installs the image, removes the old locator, cleans old variants and
queues the media purge. A delayed refusal cannot remove another attempt's required bytes.

Terminal tasks replace only their own stages with a fixed small fence, never delete
them. Abandonment revokes the grant under the same library lock, then releases the
transaction before fencing storage. Acknowledgment or a bounded read of the exact fence
allows the journal row to go; provider failures remain retryable without a finite
completion promise. Distinct initial/fence bytes and atomic conditional writes prevent
late marker or image PUTs from recreating full images, including after file forgetting.
Retain these tiny fences permanently: they are essential lifetime fencing metadata,
not disposable temporary objects. Object count and storage/operation costs grow with
replacement attempts, even after library files are forgotten. Do not apply deletion
lifecycle rules to this prefix. No staging list, bucket scan or journal sweep is used.
This guarantees the current object is a fence; bucket version history may retain old
full-byte versions and remains the operator's responsibility.
Resending the current digest supplies a fresh owned stage, so a retry can repair a
missing stage without changing library identity or metadata.
If a stage is absent or is no longer the expected image, a bounded read must verify the installed original's
SHA-256 digest, size and type before the task can complete; an opaque ETag is no proof.
Failure leaves retryable work, not a mutation of the raw original. The Source's durable
store/key mapping remembers editorial adoption. Resends return the current owned ID
and dimensions without comparing the replacement with the original's metadata. They
restore an adopted file during its undo period, but after final forgetting they are
explicitly rejected with `media_metadata_conflict`; the raw original cannot resurrect
the removed owned file.

## Replacement freshness

### Upgrade integrations

Deploy Catalog and its admin together. Update any integration that constructs
`ProductMedia` to preserve the required `digest` returned by uploads or library reads:
the full SHA-256 for owned bytes, `null` for linked or registered files. Storefronts
that use delivered `url` and `srcset` values need no URL-building change. Custom
URL builders must use the versioned addresses below; the old unversioned routes
are removed, not redirected. External PIM URLs are unchanged.

If upgrading a deployment from before managed prefixes, first copy its known Catalog-owned
originals into the reserved `MEDIA_MANAGED_ROOT`, verifying each against its database digest.
Selecting the root does not move objects. Do not scan or adopt unrelated bucket contents.

### Delivery policy

Owned originals use `/media/{mediaId}/{sha256}` and Cloudflare renditions append
`/{width}`. Both answer `public, max-age=31536000, immutable` in browser and edge
headers, including HEAD and 304. The full digest avoids shortening the content identity.
A replacement changes the URL, not the bytes behind an existing URL. An old or wrong
digest returns 404 after replacement; a cache may still answer the original bytes.
Missing versions are not cached, so a read while installation is pending cannot poison
the new address.

Product, category and library delivery resolve the digest from the authoritative media
row. Media-tag purges refresh documents containing image URLs; immutable image responses
need no purge. OrbPage reads these delivered URLs, and OrbCart uses the same rendition
builder for its line images. Metadata edits do not change an owned image's URL.

Registered private originals are mutable and have no content digest: their `/current`
URLs retain **30-second browser and edge lifetimes**, with
`must-revalidate, stale-while-revalidate=0, stale-if-error=0`. Adoption switches delivery
to a digest URL. Public external URLs stay exact and retain their host's policy.
Independent `bunny`/`imgproxy` caches must preserve the versioned source address.

The migration queues media installation tasks for existing owned files. These tasks
verify the stored bytes and atomically install digest metadata before versioned delivery
can serve them. Drain this work before exposing the upgraded catalog. A library write
confirms its transaction, not completion of a failed or delayed storage task. An image
already painted in an open page does not refresh itself; document caching policies
are unchanged. Local checks are not a deployed-provider SLA.

## Deliver registered images

The registration transaction queues the existing media task. Once it runs, originals
use `/media/{mediaId}/current` and Cloudflare variants use
`/media/{mediaId}/current/{width}`. Library thumbnails, product images and `srcset` use these
same addresses. There is no expiring URL, redirect to storage, or original-byte copy.
The private bucket is **not** the public delivery entrypoint: `MEDIA_ORIGIN` must
reach Catalog's media handler (or the configured transformation service in front of
it), never the raw bucket or its managed root.

On a miss with private registration enabled, an installed managed original takes
precedence over a locator, including a delayed locator task's transient write after
adoption. Otherwise Catalog reads the small locator from private storage, parses its bounded
JSON, checks its store identity against the active physical store, then streams the
registered object's bytes. A mismatched identity, invalid locator or missing object
fails closed. No raw key, locator, endpoint or credential is returned. There is no
public manifest, bucket listing, or arbitrary-key route. Normal original and variant
delivery does not read Postgres. Generated variants remain inside the managed root;
their keys encode the complete opaque original ETag without punctuation collisions.

Postgres still owns registration, metadata, uses and deletion permissions. The locator
is only a rebuildable delivery projection, never input to a mutation decision. The
media task rereads the authoritative row on every retry and after writing a locator,
so a delayed task reconciles current registration/forgetting rather than replaying
an old locator payload. Metadata edits that affect delivery run the same task.
Replaying a file's existing `media` task rebuilds its locator from Postgres without
reading or copying the original. There is no separate projection authority or rebuild
pipeline; bulk recovery must enqueue/replay those tasks in bounded batches.

Unregistering retains delivery during the ordinary 30-day undo period, as with uploaded
files. Restore uses the same locator; final forgetting removes it and managed variants,
never the registered original. Re-registering a forgotten store/key rebuilds the
projection under its stable media ID. A failed task remains queued with backoff; wait
for delivery readiness after importing or rebuilding, not merely the registration response.
CDN/browser copies can outlive origin cleanup until their cache lifetime ends.

Transform choices are unchanged: `none` serves originals only; `cloudflare` uses the
Images binding and keeps variants in managed storage; `bunny` and `imgproxy` keep
their existing external URL/transformation conventions and need an operator-configured
service that can fetch the controlled original URL. Selecting S3 or CloudFront does
not deploy or provide a self-hosted transformer. Already-public CDN references remain
their exact supplied URLs and never enter this locator/proxy path.

## Cloudflare recipe: private R2, public Catalog delivery

1. Bind the existing private EU R2 bucket as `MEDIA`, reserve the managed root, and
   configure the stable `MEDIA_STORE_ID` plus selected registration grants. Keep
   the ID and binding when removing grants to stop new registration.
2. Keep R2's public development URL disabled **and** disable/remove public bucket
   custom-domain access. They are independent access paths. Never expose the root
   containing private locator JSON. The R2 binding, not an anonymous bucket URL,
   authorizes storage reads and managed writes.
3. Set `PUBLIC_URL` to the approved public Catalog delivery address. Without an
   override, `MEDIA_ORIGIN` is its `/media` path. With a separate media hostname,
   route only the supported media paths to the same handler; do not attach that
   hostname directly to R2. Domain/zone/route changes require owner approval.
4. Use `MEDIA_TRANSFORM=none`, or configure the Images binding with `cloudflare`.
   The existing Workers Cache integration reads the targeted Cloudflare cache
   header and purges the media tag. Another zone cache needs its own matching
   cache/purge setup; a custom hostname alone is not proof that caching works.
5. Respect origin browser/edge TTLs; disable conflicting cache overrides and Always
   Online for media. Verify the actual cache configuration rather than assuming a
   targeted header overrides a Cache Rule.

Supported delivery is GET/HEAD, conditional ETag reads, and the closed variant-width
ladder when Cloudflare Images is configured. This is public shopper-image delivery,
not authenticated downloads. The storage origin remains private even though Catalog's
media URL intentionally answers anonymously. R2's S3 API is also usable with signed
server-side credentials through the configured subset below; it does not need a
public bucket URL.

Official sources, checked 12 November 2026:
[R2 public-access paths](https://developers.cloudflare.com/r2/buckets/public-buckets/),
[R2 Workers API](https://developers.cloudflare.com/r2/api/workers/workers-api-reference/),
[Images binding](https://developers.cloudflare.com/images/transform-images/bindings/).

## CloudFront recipe: private S3, Catalog as custom origin

1. Keep the existing regional EU S3 bucket private, with S3 Block Public Access and
   no anonymous-read policy or website endpoint. Configure Catalog's server-side
   SigV4 credentials with only the read/managed-root operations below. Catalog,
   not CloudFront, reads this private bucket in this recipe.
2. Point a CloudFront **custom HTTPS origin** at Catalog, with media behavior paths
   forwarded unchanged to `/media/{mediaId}/{version}` and `/media/{mediaId}/{version}/{width}`. Permit
   viewer GET/HEAD only, require HTTPS, and do not forward viewer credentials or
   expose panel/sync routes through a media-only distribution. Set `MEDIA_ORIGIN`
   to the distribution's approved `/media` address. The Catalog delivery entrypoint
   is deliberately public; this recipe does not claim CDN-only access to that
   entrypoint. Direct **storage** access is what must be denied.
3. Use a reviewed custom policy with `Minimum TTL=0`, `Default TTL=0`,
   `Maximum TTL=31536000`, or disable caching until measured. CloudFront reads the
   ordinary `Cache-Control`: one year for digest URLs and 30 seconds for `/current`.
   Do not strip the latter's explicit `stale-if-error=0`. Configure error caching as zero. Do not forward
   arbitrary query strings into the cache key for these parameter-free paths.
   Test ETag revalidation with the actual policy.
4. CloudFront does **not** automatically honor `Cloudflare-CDN-Cache-Control`,
   `CDN-Cache-Control` or Catalog's `Cache-Tag` purges. This runtime has no CloudFront
   invalidation adapter. A second Cloudflare cache at the custom origin is another
   freshness layer. Disabling CloudFront caching does not eliminate browser caching.
   Replacement measurements and provider invalidations remain
   separate acceptance work; do not infer them from these delivery fixtures.

CloudFront does not supply Catalog transformations: `none` remains original-only,
and `cloudflare` still needs Catalog's Images binding. Other transform services keep
their existing contracts; this recipe installs none.

**This custom origin is not an S3 OAC origin.** AWS S3 origin access control applies
when CloudFront actually uses a supported regular AWS S3 bucket origin, signs requests
(`always`), and the bucket policy scopes `s3:GetObject` to that distribution's service
principal/SourceArn. It does not apply to a Catalog HTTP origin, an S3 website endpoint,
R2, or arbitrary S3-compatible endpoints. Direct S3 OAC delivery of raw keys is not a
replacement for Catalog's media-ID locator route, and exposing its managed root would
leak locator JSON. Existing independently managed public CDN links are a separate model.

Official sources, checked 12 November 2026:
[S3 Block Public Access](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-block-public-access.html),
[CloudFront S3 OAC scope](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html),
[CloudFront TTLs and origin headers](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html).

Cache-policy sources, checked 12 November 2026:
[Cloudflare header precedence](https://developers.cloudflare.com/cache/concepts/cdn-cache-control/),
[Cloudflare stale directives and Always Online](https://developers.cloudflare.com/cache/concepts/cache-control/).

## Required provider operations

This is a defined subset, not a promise that every S3 feature or vendor works:

| Operation                        | Required behavior                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HeadObject` / native `head`     | Existing objects return byte length, `Content-Type` and quoted `ETag`; missing objects return 404/null. Permission errors are failures, not missing files.                                                                                                                                                                                                             |
| `GetObject` / native `get`       | Stream the bytes with the same metadata; never buffer a whole original to serve it.                                                                                                                                                                                                                                                                                    |
| `PutObject` / native `put`       | Store the supplied bytes and `Content-Type`. `If-Match` atomically refuses stale targets; `If-None-Match: *` atomically refuses existing targets (HTTP 412/native null). AWS missing If-Match targets, concurrent deletion and current delete markers return 404 `NoSuchKey`, also a conditional refusal. Other 404s and conflicts (409) remain failures, not success. |
| `ListObjectsV2` / native `list`  | Honor the exact prefix and opaque continuation cursor. S3 uses `encoding-type=url`, decodes keys once, and preserves tokens as opaque XML text.                                                                                                                                                                                                                        |
| `DeleteObject` / native `delete` | Delete exactly the named managed keys; deleting a missing key succeeds. No bucket or version-history deletion.                                                                                                                                                                                                                                                         |

Lists request 100 keys per page and stop with an error beyond 1,000 keys or 20 pages.
Each S3 listing body is capped at 512 KiB. Repeated/missing continuation tokens,
malformed listings and keys outside the requested prefix fail closed. Deletes accept
at most 1,000 keys: native R2 uses a bounded batch; S3 sends individual deletes
sequentially, with no unbounded fan-out. Normal cleanup concerns one library file,
not the size of the merchant's bucket. Partial deletion is safe to retry.

An ETag is an **opaque validator, not a content digest**: multipart uploads and
encryption can make it unlike an MD5. Catalog's byte digest remains independent.
Keys containing spaces, Unicode, literal `%`, `+`, `?`, `#` and `&` are encoded as
key data, not URLs. S3 keys with a complete `.` or `..` path segment or a backslash
are outside this adapter's supported subset.

First managed installation uses atomic create-if-absent, never an unconditional
overwrite after a missing HEAD. Conditional refusal rereads authoritative state before
retrying. Provider operation references:
[S3 PutObject preconditions](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html),
[R2 conditional operations](https://developers.cloudflare.com/r2/api/workers/workers-api-reference/#conditional-operations).

Conditional-write 404 bodies are parsed only up to 16 KiB. Only a valid XML error
with code `NoSuchKey` is normalized to a refused conditional write; a missing bucket,
permission error, empty/malformed response or oversized body remains a redacted
failure. An unconditional 404 is never a conditional refusal.

Grant only `GetObject` for originals the operator intends to register, and
`GetObject`, `PutObject`, `DeleteObject` within the reserved managed root.
On AWS, missing `HEAD`/`GET` requests return 404 only when the principal has
`s3:ListBucket` permission on the bucket; otherwise AWS can answer 403. Restricting
`ListBucket` solely to cleanup prefixes can therefore break missing-original and
missing-rendition checks. The AWS setup requires bucket-level `s3:ListBucket`
without a cleanup-only `s3:prefix` condition, alongside the scoped object grants.
This allows the credential holder to enumerate bucket key names, though Catalog
itself still lists only the bounded per-file cleanup prefixes. If that disclosure
is unacceptable, use a separate private bucket/native binding rather than treating
403 as absence. Confirm any narrower policy against the intended provider before
acceptance; permission failures are never swallowed. Bucket policies and credentials
must enforce the object limits; the adapter does not install them.
Do not grant account-wide administration. ACL changes, multipart upload APIs,
directory buckets, requester-pays, retention overrides, encryption headers and
version-history management are not implemented. Bucket-default encryption is left
to the provider; versioned buckets may retain old bytes after a normal delete.

## Acceptance boundary

The local storage-boundary test exercises native R2 through Wrangler's local
`workerd` binding and a synthetic S3 HTTP fixture: missing reads, metadata, streamed
reads, accepted/rejected conditional writes, replacement staging, pagination beyond
100 keys, encoded keys/tokens, bounded cleanup and preservation of foreign keys.
It also checks failed access, conflicts, redirects, malformed listings and redacted
transport errors. Neither fixture is a live provider probe.

**Live AWS S3 and R2 S3 acceptance remains blocked** until approved EU synthetic
fixtures and credentials are available. Run the same operation sequence, including
stale conditional refusal and foreign-key preservation, before enabling another
compatible provider. CloudFront/private delivery acceptance is separate and has not
been established by these tests. No live resources are created by the local tests.

The delivery flows additionally prove stable original/variant URLs, GET/HEAD/304,
distinct opaque validators, zero SQL statements on image delivery, store-mismatch
refusal before raw reads, projection retries/rebuild, retention cleanup, and exact
external-CDN URLs using storage/image-service fixtures. They do not prove provider
access policies, CDN cache behavior, invalidation or a measured freshness bound.

**Protected-origin/CDN acceptance remains blocked** without explicitly authorized
EU synthetic provider fixtures, credentials and delivery endpoints. For each recipe,
record (without secrets/raw private keys) the provider, region, configured cache policy,
timestamp and results of: anonymous storage GET/HEAD denied; signed server HEAD/GET
successful; registered public original GET/HEAD/304 successful; each advertised variant
successful where supported; missing/invalid IDs unable to retrieve raw keys/locators;
store mismatch denied; original preserved after unregister/forget; cold/warm CDN reads
and replacement revalidation observed with Age/cache-status/ETag and elapsed time.
Distinguish actual origin and CDN responses from local fixtures. Do not create resources
or alter bucket/account policies merely to complete this checklist without approval.