Core Concepts

This page is the conceptual map for OptStuff: what the product is optimizing for, which abstractions exist and why, how a request is authorized, and how policy layers stack. For the concrete HTTP pipeline (parse → verify → rate limit → domains → fetch), see How It Works. For step-by-step signing math and examples, see URL Signing.

What OptStuff Is

OptStuff is a secure image transformation service.

You provide:

• A source image URL
• A set of transformation operations (for example width, format, quality)

OptStuff returns:

• An optimized image that matches those operations

The design centers on one idea: transformations are not an open API. They are expressed as a signed URL that only your backend can mint. OptStuff validates that contract on every request before it fetches or transforms anything.

The Problem OptStuff Addresses

Production images usually live on a CDN as remote URLs (img, srcset, framework loaders). Without a signed realtime optimizer, the browser typically calls the CDN or an open transform URL whose width/format knobs are visible in the path or query—often assembled in the frontend to ship faster.

Why that hurts: anyone can replay or tweak those URLs; there is no stable server trust boundary, so governance drifts, abuse is hard to cap, and audit/revoke is painful when rules live in UI code.

With OptStuff, the canonical file stays on the CDN. Your app server mints a signed URL (sk_... never ships to the client); OptStuff verifies and applies policy, then fetches the remote source and returns an optimized response.

You gain: smaller payloads (right format/size at request time), one transform contract across apps, and project-level control (domains, keys, limits)—optimization is not an open API.

Teams, Projects, and API Keys

OptStuff separates who owns configuration from what each HTTP request is allowed to do.

Team

Organizational ownership and admin boundary (billing, members, projects).

Project

A runtime policy boundary for one app or environment: which source domains may be fetched, which caller contexts (for example Referer) are acceptable, and how keys for that slice of traffic are scoped.

API Key Pair

The split is deliberate: the client can carry identity (pk_...) without carrying signing authority (sk_...).

The Signed URL as the Contract

Every allowed transformation is encoded in a single URL shape. Conceptually, it answers: which project, which operations, which source, which key, and whether the server authorized this exact combination.

https://<base>/api/v1/<projectSlug>/<operations>/<source>?key=<pk_...>&exp=<optional>&sig=<signature>

Under the hood, sig is an HMAC over a defined signing string that binds path, operations, source, expiry, and key identity. The exact string, encoding, and edge cases are in URL Signing — you do not need those bytes on this page to understand the model: if sig does not verify, OptStuff does not treat the request as authorized.

Runtime Trust Model

At runtime, your app server and OptStuff play distinct roles: one mints authority, the other verifies it and enforces policy.

How the URL reaches the browser (step 3) is an integration choice, not part of OptStuff's core contract:

• Direct: embed the full URL in HTML, JSON, or similar.
• Via your backend: a route signs and returns a redirect or a URL string; the browser then issues an ordinary GET to OptStuff's /api/v1/... with key and sig (and optional exp).

Invariant: OptStuff does not honor arbitrary transformation parameters from an untrusted client. Authorization-by-signature means unsigned or tampered requests are rejected regardless of how pretty the path looks.

Permission Layers (Fail Closed)

Validation is layered so that each stage can deny the request before expensive work. Together they express: is this key still valid, was this URL legitimately signed, is this caller/source allowed, and is usage within limits?

Layer 1: Team / project ownership (who may administer configuration)
Layer 2: Project policy (caller + source domain allowlists)
Layer 3: API key policy (expiry, revocation, rate limits)
Layer 4: Request integrity (signature verification + optional exp / TTL)

These layers are designed to fail closed: when any check fails, the request is denied. Configuration patterns for domains are in Domain Allowlists; referer behavior in Referer Security Model; limits in Rate Limiting.

What You Need to Use the Service

In production, four things must all be true:

1. A policy boundary — a project with domain rules (allowedRefererDomains, allowedSourceDomains) that match how your app and images are hosted.
2. A trust boundary — an API key pair with sk_... only on the server.
3. A signing step — backend code that builds the signing input and produces sig (see URL Signing).
4. A delivery path — the client must eventually GET a signed /api/v1/... URL (embedded, returned from your API, or after a redirect).

If any one is missing, requests are either rejected or you have accidentally removed the security property OptStuff is built around.

Next Steps

• How It Works: Request lifecycle and validation order
• What Is HMAC?: MAC versus hashing, encryption, and how sig fits in
• URL Signing: Payload, exp, and HMAC details
• Domain Allowlists: Policy configuration patterns
• Custom next/image Loader: next/image with signing and redirect
• Quick Start: End-to-end implementation walkthrough