Token-based URL signing for secure file serving.
Generates and verifies secure tokens that prevent file enumeration attacks. Each file instance receives a unique 4-character token based on MD5 hashing.
Token Generation
Token = first 4 chars of MD5(file_uuid:instance_name + secret_key_base)
This ensures:
- Prevents file enumeration (can't guess URLs)
- Each instance has unique token
- Token changes if secret changes
- Secure comparison prevents timing attacks
- No user-guessable patterns
Examples
iex> file_uuid = "018e3c4a-9f6b-7890-abcd-ef1234567890"
iex> PhoenixKit.Modules.Storage.URLSigner.signed_url(file_uuid, "thumbnail")
"/file/018e3c4a-9f6b-7890-abcd-ef1234567890/thumbnail/a3f2"
iex> PhoenixKit.Modules.Storage.URLSigner.verify_token(file_uuid, "thumbnail", "a3f2")
true
iex> PhoenixKit.Modules.Storage.URLSigner.verify_token(file_uuid, "thumbnail", "xxxx")
falseSummary
Functions
Generate the 4-character token for a file instance.
Conditionally adds a "dzi" deep-zoom manifest URL to a urls map.
Generate a signed URL for a file instance.
Verify a token is valid for the given file and instance.
The content version a file URL carries: the first 16 hex characters of the served instance's checksum (pass the instance or the checksum).
Functions
Generate the 4-character token for a file instance.
Used internally by signed_url/2 and verify_token/4.
Arguments
file_uuid(binary) - File UUID v7instance_name(binary) - Variant name
Returns
A 4-character hex string token.
Examples
iex> PhoenixKit.Modules.Storage.URLSigner.generate_token("018e3c4a", "thumbnail")
"abc1"Conditionally adds a "dzi" deep-zoom manifest URL to a urls map.
Returns the map unchanged unless the file is an image and the
storage_tile_generation_enabled setting is on. The signed manifest URL
(/tiles/<token>/<file_uuid>-<version>.dzi) is what Tessera fetches to
stream tiles; the token and the version live in the path (not a query
string) so they survive Tessera's manifest → tile URL derivation.
Pass version: — the file's original instance, or its checksum — so the
tiles are cached for good and an edit moves them to new URLs. Without it
the legacy unversioned manifest (<file_uuid>.dzi) is emitted, which the
server resolves to the current version and never lets a cache keep.
This is the single source of truth for the "dzi" URL — every viewer that
builds a file urls map (media browser, detail page, lightbox) pipes
through it so the deep-zoom layer is wired consistently.
Generate a signed URL for a file instance.
Arguments
file_uuid(binary) - File UUID v7instance_name(binary) - Variant name (e.g., "thumbnail", "medium", "large")
Returns
A relative URL path with prefix: {url_prefix}/file/{file_uuid}/{instance_name}/{token}
Examples
iex> PhoenixKit.Modules.Storage.URLSigner.signed_url("018e3c4a-9f6b-7890", "thumbnail")
"/phoenix_kit/file/018e3c4a-9f6b-7890/thumbnail/abc1" # With default prefixVerify a token is valid for the given file and instance.
Arguments
file_uuid(binary) - File UUID v7instance_name(binary) - Variant nametoken(binary) - 4-character token from URL
Returns
Boolean indicating if token is valid.
Examples
iex> file_uuid = "018e3c4a-9f6b-7890"
iex> token = PhoenixKit.Modules.Storage.URLSigner.generate_token(file_uuid, "thumbnail")
iex> PhoenixKit.Modules.Storage.URLSigner.verify_token(file_uuid, "thumbnail", token)
true
iex> PhoenixKit.Modules.Storage.URLSigner.verify_token(file_uuid, "thumbnail", "xxxx")
falseThe content version a file URL carries: the first 16 hex characters of the served instance's checksum (pass the instance or the checksum).
A URL with a version is content-addressed: FileController serves it with
a year-long immutable lifetime only while it names the bytes the variant
holds now, and redirects to the current version otherwise — so a cached
copy can never be different bytes (an edited or redacted image). Build URLs
with signed_url(uuid, variant, version: instance) wherever the instance
is at hand; an unversioned URL still works and is revalidated.