@all1ndev/next-signed-image 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 all1ndev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,207 @@
-# Temporary Holding Version
+# @all1ndev/next-signed-image
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A drop-in [`next/image`](https://nextjs.org/docs/app/api-reference/components/image)
+replacement for image services that only accept URLs signed with a server-side secret:
+[Thumbor](https://www.thumbor.org/), [imgproxy](https://imgproxy.net/), signed imgix,
+Cloudinary or S3 URLs.
+
+- Server components and server-rendered client components get **signed URLs directly**, with
+  no redirect hop, your LCP image included.
+- Client components **hydrate without a mismatch**: the browser reads the signed `srcset` back
+  from the server's `<img>` instead of trying to sign.
+- Only an image that **first renders in the browser** (after a click or a soft navigation)
+  goes through `/api/image`, which signs and answers `302`.
+- The signer and its secret **never reach the browser bundle**.
+
+Requires Next.js 16+, React 19+, App Router.
+
+## Install
+
+```sh
+npm install @all1ndev/next-signed-image
+```
+
+## Usage
+
+### 1. Write the signer
+
+The signer is your own module, so your app keeps its env, its secrets and its source policy.
+It must export `imageSigner`:
+
+```ts
+// src/image-signer.ts
+import { defineImageSigner } from "@all1ndev/next-signed-image/route";
+
+export const imageSigner = defineImageSigner({
+	delivery(src) {
+		const origin = URL.parse(src)?.origin;
+		if (origin === "https://cdn.example.com") return "as-is"; // already display-sized
+		if (origin === "https://photos.example.com") return "sign";
+		return "route"; // refused: /api/image answers 403
+	},
+	sign({ src, width, quality }) {
+		return signWithYourService(src, width, quality, process.env.IMAGE_SIGNING_KEY);
+	},
+});
+```
+
+### 2. Wrap the Next config
+
+```ts
+// next.config.ts
+import { withSignedImages } from "@all1ndev/next-signed-image/config";
+
+export default withSignedImages(
+	{
+		/* your config */
+	},
+	{ signer: "./src/image-signer.ts" },
+);
+```
+
+### 3. Add the route
+
+```ts
+// src/app/api/image/route.ts
+import { createImageRoute } from "@all1ndev/next-signed-image/route";
+
+import { imageSigner } from "@/image-signer";
+
+export const GET = createImageRoute(imageSigner);
+```
+
+### 4. Render images
+
+```tsx
+import { Image } from "@all1ndev/next-signed-image";
+
+<Image src="https://photos.example.com/car.jpg" alt="" width={640} height={480} preload />;
+```
+
+`Image` takes the `next/image` props except `loader` and `unoptimized`. Use it from server and
+client components alike. A static import (`import hero from "./hero.png"`) is a same-origin
+file, so it is served as-is with its intrinsic size, and the signer is never asked.
+
+## The signer contract
+
+```ts
+type ImageSigner = {
+	delivery(src: string): "as-is" | "sign" | "route";
+	sign(image: { src: string; width: number; quality: number }): string;
+};
+```
+
+| `delivery(src)` | Server render                                | `/api/image`                           |
+| --------------- | -------------------------------------------- | -------------------------------------- |
+| `"sign"`        | `sign()` for each width next/image asks for  | `302` to `sign()`                      |
+| `"as-is"`       | the URL itself, `unoptimized`                | `302` to the normalized http(s) URL    |
+| `"route"`       | points at `/api/image` (one broken image)    | `403`                                  |
+
+Same-origin paths (`/public` files, static imports) and `.svg` sources are always served
+as-is, before the signer is asked, because the browser has to reach the same decision without
+it. The route never applies that rule: it trusts only `delivery()`.
+
+`sign()` is called only after `delivery()` returned `"sign"`, so it is the place to enforce
+your source policy again. Sign the normalized URL, not the raw input, and encode it so the
+signed URL holds no space (a `srcset` separates candidates with spaces).
+
+`defineImageSigner` returns the signer unchanged and throws if the module is ever evaluated in
+a browser, standing in for `server-only`, which a client component's SSR pass cannot import.
+
+### Example: Thumbor
+
+With [`thumbor-client`](https://www.npmjs.com/package/thumbor-client) (any HMAC-SHA1
+implementation works):
+
+```ts
+import { defineImageSigner } from "@all1ndev/next-signed-image/route";
+import { createThumbor } from "thumbor-client";
+
+const thumbor = createThumbor({ url: process.env.THUMBOR_URL!, key: process.env.THUMBOR_KEY! });
+const allowed = new Set(process.env.THUMBOR_ALLOWED_SOURCE_ORIGINS!.split(","));
+
+export const imageSigner = defineImageSigner({
+	delivery: (src) => (allowed.has(URL.parse(src)?.origin ?? "") ? "sign" : "route"),
+	sign({ src, width, quality }) {
+		const source = new URL(src);
+		if (!allowed.has(source.origin)) throw new Error(`Not an allowed image source: ${src}`);
+		return thumbor
+			.image(source.href, { encode: true })
+			.resize(width, 0)
+			.quality(quality)
+			.noUpscale()
+			.url();
+	},
+});
+```
+
+The `THUMBOR_*` variables belong to your app. Read them lazily (inside the functions), so a
+build without them still succeeds.
+
+## Sizes and qualities
+
+`withSignedImages` sets `images.deviceSizes`, `imageSizes` and `qualities` (Next's defaults,
+quality 75 only), and the route signs exactly those. To change them, pass **the same object**
+to both, since a width the route rejects breaks every browser-rendered image:
+
+```ts
+// src/image-sizes.ts
+import { defaultImageSizes } from "@all1ndev/next-signed-image/config";
+
+export const sizes = { ...defaultImageSizes, qualities: [50, 75] };
+```
+
+```ts
+withSignedImages(config, { signer: "./src/image-signer.ts", sizes });
+createImageRoute(imageSigner, { sizes });
+```
+
+## How it works
+
+`@all1ndev/next-signed-image` is a conditional export. Server components resolve its
+`react-server` build, which renders once: it runs `getImageProps` with a signing loader,
+renders a plain `<img>` and, for `preload`, calls React DOM's `preload()` (getImageProps
+emits no preload hint of its own). Client components resolve the `default` build, which
+renders twice, on the server and in the browser, and must produce the same attributes both
+times. It decides how to deliver the image once per mount, in a lazy `useState` initializer:
+
+```ts
+serverDelivery(props, imageSigner) ?? // SSR: sign (the signer is a stub in the browser)
+	hydratedDelivery(props, useId()) ?? // hydration: read the server's decision from the DOM
+	browserDelivery(props.src); // browser-only render: as-is, or the /api/image redirect
+```
+
+The server-rendered `<img>` carries `data-image-id` (from `useId`, identical in the server
+render and during hydration) and `data-image-delivery`. While hydrating, the initializer finds
+that `<img>` and pairs its `srcset` URLs with the widths next/image derives from the same
+props. If the two lists differ in length, it falls back to the redirect rather than guess.
+
+The signer reaches the package through the specifier `@all1ndev/next-signed-image/signer`.
+`withSignedImages` aliases it, for Turbopack and webpack, to your module on the server and to
+a stub that exports `undefined` in the browser. Without the alias, it resolves to a module
+that throws a "wrap your next.config with withSignedImages" error.
+
+Every render passes a `loader`: with `images.loader: "custom"` and no `loaderFile`, Next throws
+"missing loader" before it reads `unoptimized`. That also makes a stray `next/image` fail
+loudly instead of reaching `/_next/image`.
+
+## Caveats
+
+- **Extra attributes.** A client `Image` renders `data-image-id` and `data-image-delivery` on
+  its `<img>`.
+- **A DOM read during the first browser render.** Hydration calls
+  `document.querySelector` inside the `useState` initializer. It reads only the element React
+  is about to hydrate, and only once per mount.
+- **Changing `src`.** A client `Image` whose `src` changes after mount goes through
+  `/api/image`: the browser cannot sign.
+- **Env in prerendered shells.** Any server render of a signed source calls your signer, so
+  if it reads env, the usual rules apply (`await connection()` inside a prerendered shell).
+- **`basePath`.** The route path is fixed at `/api/image`, without a `basePath` prefix.
+- **Test runners** must alias `@all1ndev/next-signed-image/signer` to a signer module, as
+  `withSignedImages` does for Next (see `vitest.config.ts` in this repository).
+- **Browser support.** Client code stays within the Safari 16.4 API floor (no `URL.parse`,
+  `Object.groupBy` or `Promise.withResolvers`).
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+import type { NextConfig } from "next";
+import { type ImageSizes } from "./sizes.js";
+export { defaultImageSizes, type ImageSizes } from "./sizes.js";
+export type SignedImagesOptions = {
+    /** The app's signer module, relative to the project root. It exports `imageSigner`. */
+    signer: string;
+    /** Pass the same object to `createImageRoute`: a width the route rejects breaks every image. */
+    sizes?: ImageSizes;
+};
+/**
+ * Points the package's signer specifier at the app's signer on the server and at a stub in the
+ * browser, and makes every image go through a loader (no `/_next/image`).
+ */
+export declare function withSignedImages(nextConfig: NextConfig, { signer, sizes }: SignedImagesOptions): NextConfig;

package/dist/config.js

@@ -0,0 +1,34 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { defaultImageSizes } from "./sizes.js";
+export { defaultImageSizes } from "./sizes.js";
+const SIGNER = "@all1ndev/next-signed-image/signer";
+const BROWSER_SIGNER = "@all1ndev/next-signed-image/signer/browser";
+/**
+ * Points the package's signer specifier at the app's signer on the server and at a stub in the
+ * browser, and makes every image go through a loader (no `/_next/image`).
+ */
+export function withSignedImages(nextConfig, { signer, sizes = defaultImageSizes }) {
+    const { loaderFile: _loaderFile, ...images } = nextConfig.images ?? {};
+    const browserStub = fileURLToPath(new URL("./signer.browser.js", import.meta.url));
+    return {
+        ...nextConfig,
+        images: { ...images, loader: "custom", ...sizes },
+        turbopack: {
+            ...nextConfig.turbopack,
+            resolveAlias: {
+                ...nextConfig.turbopack?.resolveAlias,
+                // `browser` is the only condition Turbopack's resolveAlias supports.
+                [SIGNER]: { browser: BROWSER_SIGNER, default: signer },
+            },
+        },
+        webpack(config, context) {
+            const result = nextConfig.webpack ? nextConfig.webpack(config, context) : config;
+            result.resolve.alias = {
+                ...result.resolve.alias,
+                [`${SIGNER}$`]: context.isServer ? path.resolve(context.dir, signer) : browserStub,
+            };
+            return result;
+        },
+    };
+}

package/dist/delivery.d.ts

@@ -0,0 +1,64 @@
+import { type ImageLoader, type ImageLoaderProps, type ImageProps as NextImageProps } from "next/image";
+export { DEFAULT_QUALITY, defaultImageSizes, type ImageSizes } from "./sizes.js";
+/**
+ * The app's signing policy and key, provider-agnostic. Lives in the app's own module (the one
+ * named by `withSignedImages({ signer })`), exported as `imageSigner`.
+ */
+export type ImageSigner = {
+    /**
+     * How a remote `src` is served: `"as-is"` by its own URL (a file that gains nothing from a
+     * resize), `"sign"` through signed URLs, `"route"` refused (the route answers 403).
+     * Same-origin paths and SVGs never reach it: they are always served as-is.
+     */
+    delivery(src: string): "as-is" | "sign" | "route";
+    /** A signed URL for `src` resized to `width`. Only called after `delivery` returned "sign". */
+    sign(image: {
+        src: string;
+        width: number;
+        quality: number;
+    }): string;
+};
+export type ImageProps = Omit<NextImageProps, "loader" | "unoptimized">;
+/** The URL a `src` points at: a static import's file, or the string itself. */
+export declare function srcUrl(src: ImageProps["src"]): string;
+/** Signed URLs by width. */
+export type SignedWidths = Readonly<Record<number, string>>;
+/**
+ * How an image is served: by its own URL, through the /api/image redirect, or from URLs signed
+ * on the server. `kind` is also the `data-image-delivery` value hydration reads.
+ */
+export type Delivery = {
+    readonly kind: "as-is";
+} | {
+    readonly kind: "route";
+} | {
+    readonly kind: "signed";
+    readonly widths: SignedWidths;
+};
+export declare const AS_IS: Delivery;
+export declare const ROUTE: Delivery;
+export declare const IMAGE_ROUTE = "/api/image";
+/**
+ * Served by URL, never signed, and decidable without the signer so the browser agrees:
+ * same-origin assets (/public, static imports) have no origin a resizer could fetch from, and
+ * SVGs are vectors with nothing to resize.
+ */
+export declare function isServedAsIs(src: string): boolean;
+/** What a render with no server behind it can decide: no key, no signing policy. */
+export declare function browserDelivery(src: string): Delivery;
+/**
+ * How an `Image` rendered on the server is served. A signed source is signed for exactly the
+ * widths next/image requests with these props. `undefined` without a signer (the browser).
+ */
+export declare function serverDelivery(props: Readonly<ImageProps>, signer: ImageSigner | undefined): Delivery | undefined;
+export declare function nextImageDelivery(delivery: Delivery): {
+    loader: ImageLoader;
+    unoptimized?: true;
+};
+/**
+ * Pairs a server-rendered `srcset` with the widths next/image derives from the same props,
+ * which it lists in the same order (`widthsSrcSet` is that srcset with each width as its URL).
+ * `undefined` when the two disagree.
+ */
+export declare function signedWidthsFromSrcSet(srcSet: string, widthsSrcSet: string): SignedWidths | undefined;
+export declare function imageRouteUrl({ src, width, quality }: ImageLoaderProps): string;

package/dist/delivery.js

@@ -0,0 +1,106 @@
+import { getImageProps, } from "next/image";
+import { DEFAULT_QUALITY } from "./sizes.js";
+export { DEFAULT_QUALITY, defaultImageSizes } from "./sizes.js";
+/** The URL a `src` points at: a static import's file, or the string itself. */
+export function srcUrl(src) {
+    if (typeof src === "string")
+        return src;
+    return "default" in src ? src.default.src : src.src;
+}
+export const AS_IS = { kind: "as-is" };
+export const ROUTE = { kind: "route" };
+export const IMAGE_ROUTE = "/api/image";
+const SAME_ORIGIN_PROBE = "https://same-origin.invalid";
+/**
+ * Served by URL, never signed, and decidable without the signer so the browser agrees:
+ * same-origin assets (/public, static imports) have no origin a resizer could fetch from, and
+ * SVGs are vectors with nothing to resize.
+ */
+export function isServedAsIs(src) {
+    return isSameOriginPath(src) || isSvg(src);
+}
+/** What a render with no server behind it can decide: no key, no signing policy. */
+export function browserDelivery(src) {
+    return isServedAsIs(src) ? AS_IS : ROUTE;
+}
+/**
+ * How an `Image` rendered on the server is served. A signed source is signed for exactly the
+ * widths next/image requests with these props. `undefined` without a signer (the browser).
+ */
+export function serverDelivery(props, signer) {
+    if (!signer)
+        return undefined;
+    const src = srcUrl(props.src);
+    if (isServedAsIs(src))
+        return AS_IS;
+    const kind = signer.delivery(src);
+    if (kind === "as-is")
+        return AS_IS;
+    if (kind !== "sign")
+        return ROUTE;
+    const widths = {};
+    getImageProps({
+        ...props,
+        loader: ({ src, width, quality = DEFAULT_QUALITY }) => (widths[width] = signer.sign({ src, width, quality })),
+    });
+    return { kind: "signed", widths };
+}
+// Every path names a loader: with `images.loader: "custom"` and no loaderFile, Next throws
+// "missing loader" before it reads `unoptimized`.
+export function nextImageDelivery(delivery) {
+    if (delivery.kind === "as-is")
+        return { unoptimized: true, loader: imageRouteUrl };
+    if (delivery.kind === "route")
+        return { loader: imageRouteUrl };
+    const { widths } = delivery;
+    return {
+        loader: (props) => widths[props.width] ?? imageRouteUrl(props),
+    };
+}
+/**
+ * Pairs a server-rendered `srcset` with the widths next/image derives from the same props,
+ * which it lists in the same order (`widthsSrcSet` is that srcset with each width as its URL).
+ * `undefined` when the two disagree.
+ */
+export function signedWidthsFromSrcSet(srcSet, widthsSrcSet) {
+    const urls = srcSetUrls(srcSet);
+    const widths = srcSetUrls(widthsSrcSet).map(Number);
+    if (urls.length === 0 || urls.length !== widths.length)
+        return undefined;
+    return Object.fromEntries(widths.map((width, index) => [width, urls[index] ?? ""]));
+}
+// Next joins candidates with ", "; a signed URL must hold no space (encode the source).
+function srcSetUrls(srcSet) {
+    return srcSet
+        .split(", ")
+        .map((candidate) => candidate.trim().split(" ")[0] ?? "")
+        .filter(Boolean);
+}
+// The browser holds no key: /api/image signs and redirects.
+export function imageRouteUrl({ src, width, quality }) {
+    const params = new URLSearchParams({
+        src,
+        w: String(width),
+        q: String(quality ?? DEFAULT_QUALITY),
+    });
+    return `${IMAGE_ROUTE}?${params}`;
+}
+// Resolve as the browser will, not by prefix: `//host`, `/\host` and a tab or newline
+// between the slashes all leave the origin despite the leading slash.
+function isSameOriginPath(src) {
+    if (!src.startsWith("/"))
+        return false;
+    return parseRelative(src)?.origin === SAME_ORIGIN_PROBE;
+}
+function isSvg(src) {
+    return parseRelative(src)?.pathname.toLowerCase().endsWith(".svg") ?? false;
+}
+// Not URL.parse: this runs in the browser, and URL.parse is above the Safari 16.4 floor.
+function parseRelative(src) {
+    try {
+        return new URL(src, SAME_ORIGIN_PROBE);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/image.client.d.ts

@@ -0,0 +1,9 @@
+import { type JSX } from "react";
+import { type ImageProps } from "./delivery.js";
+export type { ImageProps } from "./delivery.js";
+/**
+ * The `default` branch, for client components. Rendered on the server (SSR) it signs;
+ * hydrating, it reuses what the server rendered; only an image that first renders in the
+ * browser goes through the /api/image redirect.
+ */
+export declare function Image(props: Readonly<ImageProps>): JSX.Element;

package/dist/image.client.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { imageSigner } from "@all1ndev/next-signed-image/signer";
+import NextImage, { getImageProps } from "next/image";
+import { useId, useState } from "react";
+import { AS_IS, browserDelivery, nextImageDelivery, ROUTE, serverDelivery, signedWidthsFromSrcSet, srcUrl, } from "./delivery.js";
+/**
+ * The `default` branch, for client components. Rendered on the server (SSR) it signs;
+ * hydrating, it reuses what the server rendered; only an image that first renders in the
+ * browser goes through the /api/image redirect.
+ */
+export function Image(props) {
+    const id = useId();
+    const src = srcUrl(props.src);
+    // Lazy, once per mount: the first browser render must match the server's markup, and
+    // later renders keep that decision rather than falling back to the redirect.
+    const [first] = useState(() => ({
+        src,
+        delivery: serverDelivery(props, imageSigner) ??
+            hydratedDelivery(props, id) ??
+            browserDelivery(src),
+    }));
+    const delivery = first.src === src ? first.delivery : browserDelivery(src);
+    return (_jsx(NextImage, { ...props, ...nextImageDelivery(delivery), alt: props.alt, "data-image-delivery": delivery.kind, "data-image-id": id }));
+}
+// `useId` matches between the server render and hydration, and a browser-only render gets a
+// different one, so finding the element means this render is hydrating it.
+function hydratedDelivery(props, id) {
+    if (typeof document === "undefined")
+        return undefined;
+    const img = document.querySelector(`img[data-image-id="${CSS.escape(id)}"]`);
+    const kind = img?.getAttribute("data-image-delivery");
+    if (kind === "as-is")
+        return AS_IS;
+    if (kind === "route")
+        return ROUTE;
+    if (kind !== "signed")
+        return undefined;
+    const { srcSet: widthsSrcSet } = getImageProps({
+        ...props,
+        loader: ({ width }) => String(width),
+    }).props;
+    const widths = signedWidthsFromSrcSet(img?.getAttribute("srcset") ?? "", widthsSrcSet ?? "");
+    return widths && { kind: "signed", widths };
+}

package/dist/image.server.d.ts

@@ -0,0 +1,4 @@
+import type { JSX } from "react";
+import { type ImageProps } from "./delivery.js";
+export type { ImageProps } from "./delivery.js";
+export declare function Image(props: Readonly<ImageProps>): JSX.Element;

package/dist/image.server.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { imageSigner } from "@all1ndev/next-signed-image/signer";
+import { getImageProps } from "next/image";
+import { preload } from "react-dom";
+import { nextImageDelivery, ROUTE, serverDelivery } from "./delivery.js";
+// The `react-server` branch: renders once, on the server, so it needs none of the client
+// branch's hydration bookkeeping.
+export function Image(props) {
+    const delivery = serverDelivery(props, imageSigner) ?? ROUTE;
+    const { props: imgProps } = getImageProps({ ...props, ...nextImageDelivery(delivery) });
+    // getImageProps only computes attributes; next/image's own preload hint comes from its
+    // component, which this <img> replaces, so the same options are passed here.
+    if (props.preload === true) {
+        preload(imgProps.src, {
+            as: "image",
+            imageSrcSet: imgProps.srcSet,
+            imageSizes: imgProps.sizes,
+            crossOrigin: imgProps.crossOrigin,
+            referrerPolicy: imgProps.referrerPolicy,
+            fetchPriority: imgProps.fetchPriority,
+        });
+    }
+    return _jsx("img", { ...imgProps, alt: props.alt });
+}

package/dist/route.d.ts

@@ -0,0 +1,15 @@
+import { type ImageSigner, type ImageSizes } from "./delivery.js";
+export type { ImageSigner, ImageSizes } from "./delivery.js";
+/**
+ * Marks the app's signer. Stands in for `server-only`, which the SSR pass of a client
+ * component cannot import: it throws if the signer module is ever evaluated in a browser.
+ */
+export declare function defineImageSigner<Signer extends ImageSigner>(signer: Signer): Signer;
+/**
+ * The App Router GET handler behind /api/image, for images that first render in the browser:
+ * 400 for a width or quality next/image would not request, 403 for a source the signer
+ * refuses, else a 302 to the signed URL or to the file itself.
+ */
+export declare function createImageRoute(signer: ImageSigner, { sizes }?: {
+    sizes?: ImageSizes;
+}): (request: Request) => Response;

package/dist/route.js

@@ -0,0 +1,54 @@
+import { defaultImageSizes } from "./delivery.js";
+/**
+ * Marks the app's signer. Stands in for `server-only`, which the SSR pass of a client
+ * component cannot import: it throws if the signer module is ever evaluated in a browser.
+ */
+export function defineImageSigner(signer) {
+    if (typeof window !== "undefined") {
+        throw new Error("@all1ndev/next-signed-image: the image signer was bundled for the browser. Is next.config wrapped with withSignedImages?");
+    }
+    return signer;
+}
+/**
+ * The App Router GET handler behind /api/image, for images that first render in the browser:
+ * 400 for a width or quality next/image would not request, 403 for a source the signer
+ * refuses, else a 302 to the signed URL or to the file itself.
+ */
+export function createImageRoute(signer, { sizes = defaultImageSizes } = {}) {
+    const widths = new Set([...sizes.deviceSizes, ...sizes.imageSizes]);
+    const qualities = new Set(sizes.qualities);
+    // Signing exists so outsiders cannot make the resizer render arbitrary sizes or sources.
+    return function GET(request) {
+        const params = new URL(request.url).searchParams;
+        const src = params.get("src");
+        const width = Number(params.get("w"));
+        const quality = Number(params.get("q"));
+        if (!src || !widths.has(width) || !qualities.has(quality)) {
+            return new Response("Bad request", { status: 400 });
+        }
+        const kind = signer.delivery(src);
+        if (kind === "sign")
+            return redirect(signer.sign({ src, width, quality }));
+        // The target is request input: redirect only to its normalized http(s) form.
+        const asIs = kind === "as-is" ? parseHttpUrl(src) : null;
+        if (asIs)
+            return redirect(asIs.href);
+        return new Response("Forbidden", { status: 403 });
+    };
+}
+// 302, not 308: a permanent redirect is cached for good and would outlive a key rotation.
+function redirect(location) {
+    return new Response(null, {
+        status: 302,
+        headers: { Location: location, "Cache-Control": "public, max-age=86400" },
+    });
+}
+function parseHttpUrl(src) {
+    try {
+        const url = new URL(src);
+        return url.protocol === "https:" || url.protocol === "http:" ? url : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/signer.browser.d.ts

@@ -0,0 +1,2 @@
+import type { ImageSigner } from "./delivery.js";
+export declare const imageSigner: ImageSigner | undefined;

package/dist/signer.browser.js

@@ -0,0 +1,3 @@
+// The browser branch of `@all1ndev/next-signed-image/signer`: the browser holds no key, so a client
+// `Image` reads its server's decision back from the hydrated <img> instead.
+export const imageSigner = undefined;

package/dist/signer.default.d.ts

@@ -0,0 +1,2 @@
+import type { ImageSigner } from "./delivery.js";
+export declare const imageSigner: ImageSigner | undefined;

package/dist/signer.default.js

@@ -0,0 +1,6 @@
+// What `@all1ndev/next-signed-image/signer` resolves to on the server when the app's next.config
+// does not alias it to the app's signer module: evaluating it throws.
+function unconfigured() {
+    throw new Error('@all1ndev/next-signed-image: no image signer is configured. Wrap your next.config with withSignedImages(config, { signer: "./src/image-signer.ts" }) from "@all1ndev/next-signed-image/config", or alias "@all1ndev/next-signed-image/signer" to that module in your test runner.');
+}
+export const imageSigner = unconfigured();

package/dist/sizes.d.ts

@@ -0,0 +1,8 @@
+/** The widths and qualities next/image may request, and so the only ones the route signs. */
+export type ImageSizes = {
+    deviceSizes: number[];
+    imageSizes: number[];
+    qualities: number[];
+};
+export declare const DEFAULT_QUALITY = 75;
+export declare const defaultImageSizes: ImageSizes;

package/dist/sizes.js

@@ -0,0 +1,8 @@
+export const DEFAULT_QUALITY = 75;
+// Next's own defaults (`imageConfigDefault` in next/dist/shared/lib/image-config.js), pinned so
+// a Next upgrade that changes them cannot desync the route from the loader.
+export const defaultImageSizes = {
+    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
+    imageSizes: [32, 48, 64, 96, 128, 256, 384],
+    qualities: [DEFAULT_QUALITY],
+};

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@all1ndev/next-signed-image",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "A drop-in next/image replacement for image services that need server-side signed URLs (Thumbor, imgproxy, signed imgix/Cloudinary/S3), with no hydration mismatch.",
+  "keywords": [
+    "next",
+    "nextjs",
+    "next/image",
+    "image",
+    "signed-url",
+    "thumbor",
+    "imgproxy",
+    "react-server-components"
+  ],
+  "license": "MIT",
+  "author": "Andrei L (https://all1n.dev)",
+  "homepage": "https://github.com/all1ndev/next-signed-image/tree/main/packages/next-signed-image#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/all1ndev/next-signed-image.git",
+    "directory": "packages/next-signed-image"
+  },
+  "bugs": "https://github.com/all1ndev/next-signed-image/issues",
+  "type": "module",
+  "sideEffects": [
+    "./dist/signer.default.js"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/image.client.d.ts",
+      "react-server": "./dist/image.server.js",
+      "default": "./dist/image.client.js"
+    },
+    "./delivery": {
+      "types": "./dist/delivery.d.ts",
+      "default": "./dist/delivery.js"
+    },
+    "./route": {
+      "types": "./dist/route.d.ts",
+      "default": "./dist/route.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./signer": {
+      "types": "./dist/signer.default.d.ts",
+      "browser": "./dist/signer.browser.js",
+      "default": "./dist/signer.default.js"
+    },
+    "./signer/browser": {
+      "types": "./dist/signer.browser.d.ts",
+      "default": "./dist/signer.browser.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@types/react": ">=19",
+    "next": ">=16",
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "24.19.0",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "next": "16.4.2",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "typescript": "7.1.0-beta",
+    "vitest": "4.1.12"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }