Imprint: Signed, Expiring Image Rendering with Dynamic Watermarks in Ruby

January 21, 2026

Distributing images securely is a recurring challenge in modern web applications. Whether for previews, confidential documents, or paid content, developers often need to ensure that images are not reused, hotlinked, or accessed indefinitely.

Imprint is a Ruby gem that addresses this problem by providing signed, time-limited image rendering with dynamic watermarks, allowing images to be served securely through expiring tokens.

The gem is framework-agnostic, lightweight, and designed to integrate naturally with Ruby and Rails applications without imposing routing or controller assumptions.

Motivation

Traditional image delivery mechanisms rely on static URLs, which makes them vulnerable to:

• Unauthorized sharing
• Hotlinking
• Long-lived access to sensitive assets
• Lack of contextual or dynamic watermarking

Imprint introduces a different approach: images are rendered on demand, using cryptographically signed tokens that encode both the source image and the watermark to apply, along with an expiration timestamp.

Once the token expires, the image becomes inaccessible.

Core Concepts

Imprint is built around three simple ideas:

1. Signed tokens Each render request is protected by an HMAC-signed token that prevents tampering.
2. Expiration Tokens include an expiration timestamp (exp), ensuring time-limited access.
3. Dynamic rendering Images are rendered on demand using the GD graphics library, allowing watermarks to be applied dynamically.

The gem does not define routes, controllers, or HTTP behavior. Those concerns remain the responsibility of the host application.

Installation

Add the gem to your Gemfile:

gem "imprint-image"

Then install:

bundle install

Imprint depends on the GD graphics library. Make sure libgd is available in your system.

Basic Usage

Generating a signed render token

token = Imprint.sign(
  source: "/tmp/source.png",
  watermark: "CONFIDENTIAL",
  expires_in: 60
)

This produces a signed token encoding:

• the source image path
• the watermark text
• the expiration timestamp

Verifying a token

payload = Imprint.verify(token)

If valid and not expired, this returns a Hash:

{
  "source"    => "/tmp/source.png",
  "watermark" => "CONFIDENTIAL",
  "exp"       => 1769010018
}

Expired or invalid tokens return nil.

Rendering an image from a token

output_path = Imprint.render_from_token(token)

This generates a new image file (typically under /tmp) with the watermark applied and returns the path to the rendered image.

Rails Integration

Imprint is designed to integrate cleanly with Rails without forcing routing decisions.

A minimal controller example:

class ImprintController < ApplicationController
  def show
    output = Imprint.render_from_token(params[:token])
    return head :not_found unless output && File.exist?(output)
    send_file output, type: "image/png", disposition: "inline"
  end
end
And a corresponding route:

get "/imprint/render/:token", to: "imprint#show", format: false 

This allows images to be served via signed, expiring URLs such as:

/imprint/render/<signed-token>

Security Model

• Tokens are HMAC-signed to prevent tampering
• Expiration is enforced at verification time
• Image paths and watermark text cannot be altered without invalidating the signature
• Rails secrets are used automatically when available

This makes Imprint suitable for preview images, protected content, internal dashboards, and paid media workflows.

Design Philosophy

Imprint deliberately avoids:

• Hardcoded routes
• Controllers inside the gem
• HTTP assumptions
• Framework lock-in

Instead, it provides a small, focused API that can be composed into different architectures.

Use Cases

• Confidential document previews
• Paid image previews
• Internal dashboards
• Temporary access to generated images
• Watermarked exports

Project Links

• RubyGems: https://rubygems.org/gems/imprint-image
• Source code: https://github.com/ggerman/imprint

Conclusion

Imprint offers a pragmatic, Ruby-native approach to secure image delivery. By combining signed tokens, expiration, and dynamic rendering, it enables developers to control access to visual assets without relying on external services or complex infrastructure.