A modern and easy to use dashboard. 80+ integrations. 20K+ icons built in. Authentication out of the box. No YAML, drag and drop configuration.
import { createHmac, hkdfSync, randomUUID } from "node:crypto";
import { setImmediate } from "node:timers/promises";
import { createId, formatBytes } from "@homarr/common";
import { env } from "@homarr/common/env";
import { decryptSecret, encryptSecret, readBoundedResponseAsync, verifyKeyedFingerprint } from "@homarr/common/server";
import { cancelBodyAsync, fetchGuardedAsync } from "@homarr/core/infrastructure/http";
import { createLogger } from "@homarr/core/infrastructure/logs";
import { ErrorWithMetadata } from "@homarr/core/infrastructure/logs/error";
import { createGetSetChannel } from "@homarr/redis";
const logger = createLogger({ module: "imageProxy" });
export const IMAGE_PROXY_REDIS_TTL_SECONDS = 86400;
export const IMAGE_PROXY_MAX_BYTES = 32 * 1024 * 1024;
export const IMAGE_PROXY_TIMEOUT_MS = 10_000;
const createHmacChannel = (hmac: `${string}.${string}`) => createGetSetChannel<string>(`image-proxy:hmac:${hmac}`);
const createUrlByIdChannel = (id: string) =>
createGetSetChannel<{
url: `${string}.${string}`;
headers: `${string}.${string}`;
}>(`image-proxy:url:${id}`);
export type ForwardImageResult =
| { image: ArrayBuffer; contentType: string | null }
| { redirectUrl: string }
| { error: "not-found" }
| { error: "upstream-error"; statusCode: number }
| { error: "fetch-error" };
export class ImageProxy {
private static hmacKey: Buffer<ArrayBuffer> | null = null;
/**
* Generate secure key for image-proxy from encryption key
*/
private static getHmacKey(): Buffer<ArrayBuffer> {
this.hmacKey ??= Buffer.from(hkdfSync("sha256", env.SECRET_ENCRYPTION_KEY, "", "image-proxy", 32));
return this.hmacKey;
}
public async createImageAsync(url: string, headers?: Record<string, string>): Promise<string> {
const existingId = await this.getExistingIdAsync(url, headers);
if (existingId) {
logger.debug("Image already exists in the proxy", {
id: existingId,
url: this.redactUrl(url),
headers: this.redactHeaders(headers ?? null),
});
return this.createImageUrl(existingId);
}
const id = createId();
await this.storeImageAsync(id, url, headers);
return this.createImageUrl(id);
}
public async createImagesAsync(urls: string[], headers?: Record<string, string>): Promise<string[]> {
// Album assets share credentials. Hash/encrypt that immutable value once,
// and bound each registration batch so it cannot monopolize rendering.
const headerValue = JSON.stringify(headers ?? null);
const headerHash = this.hashSecret(headerValue);
const encryptedHeaders = encryptSecret(headerValue);
const links: string[] = [];
for (let index = 0; index < urls.length; index += 128) {
const batch = await Promise.all(
urls.slice(index, index + 128).map(async (url) => {
const urlHash = this.hashSecret(url);
const hashChannel = createHmacChannel(`${urlHash}.${headerHash}`);
const existingId = await hashChannel.getAsync();
if (existingId) return this.createImageUrl(existingId);
const id = randomUUID();
await createUrlByIdChannel(id).setAsync(
{ url: encryptSecret(url), headers: encryptedHeaders },
{ ttlSeconds: IMAGE_PROXY_REDIS_TTL_SECONDS },
);
await hashChannel.setAsync(id, { ttlSeconds: IMAGE_PROXY_REDIS_TTL_SECONDS });
return this.createImageUrl(id);
}),
);
links.push(...batch);
if (index + 128 < urls.length) await setImmediate();
}
return links;
}
public async forwardImageAsync(id: string, requestSignal?: AbortSignal): Promise<ForwardImageResult> {
if (id.startsWith("persistent.")) return this.getPersistentImageRedirect(id);
const urlAndHeaders = await this.getImageUrlAndHeadersAsync(id);
if (!urlAndHeaders) {
return { error: "not-found" };
}
const proxyUrl = this.createImageUrl(id);
const controller = new AbortController();
const signal = requestSignal ? AbortSignal.any([controller.signal, requestSignal]) : controller.signal;
const deadline = setTimeout(
() => controller.abort(new DOMException("Image forwarding deadline exceeded", "TimeoutError")),
IMAGE_PROXY_TIMEOUT_MS,
);
try {
signal.throwIfAborted();
return await fetchGuardedAsync(
new URL(urlAndHeaders.url),
{
headers: urlAndHeaders.headers ?? undefined,
trustedOrigin: urlAndHeaders.trustedOrigin,
timeout: IMAGE_PROXY_TIMEOUT_MS,
signal,
},
async (response) => {
if (!response.ok) {
await cancelBodyAsync(response);
logger.error(
new ErrorWithMetadata("Failed to fetch image", {
id,
url: this.redactUrl(urlAndHeaders.url),
headers: this.redactHeaders(urlAndHeaders.headers),
proxyUrl,
statusCode: response.status,
}),
);
return { error: "upstream-error", statusCode: response.status };
}
const body = await readBoundedResponseAsync(response, IMAGE_PROXY_MAX_BYTES, "Image", signal);
const image = body?.buffer ?? new ArrayBuffer(0);
logger.debug("Forwarding image succeeded", {
id,
url: this.redactUrl(urlAndHeaders.url),
headers: this.redactHeaders(urlAndHeaders.headers),
proxyUrl,
size: formatBytes(image.byteLength),
});
return { image, contentType: response.headers.get("content-type") };
},
);
} catch (error) {
logger.error(
new ErrorWithMetadata(
"Failed to forward image",
{
id,
url: this.redactUrl(urlAndHeaders.url),
headers: this.redactHeaders(urlAndHeaders.headers),
proxyUrl,
},
{ cause: error },
),
);
return { error: "fetch-error" };
} finally {
clearTimeout(deadline);
controller.abort();
}
}
private createImageUrl(id: string): string {
return `/api/image-proxy/${id}`;
}
private getPersistentImageRedirect(id: string): ForwardImageResult {
const parts = /^persistent\.([a-f0-9]{64})\.([a-f0-9]+)\.([a-f0-9]{32})$/.exec(id);
if (!parts) return { error: "not-found" };
const [, signature = "", ciphertext = "", initializationVector = ""] = parts;
const encryptedUrl = `${ciphertext}.${initializationVector}` as const;
if (!verifyKeyedFingerprint(`image-proxy:persistent:${encryptedUrl}`, signature)) return { error: "not-found" };
try {
const url = URL.parse(decryptSecret(encryptedUrl));
if (!url || (url.protocol !== "http:" && url.protocol !== "https:")) return { error: "not-found" };
return { redirectUrl: url.href };
} catch {
return { error: "not-found" };
}
}
private async getImageUrlAndHeadersAsync(id: string) {
const urlHeaderChannel = createUrlByIdChannel(id);
const urlHeader = await urlHeaderChannel.getAsync();
if (!urlHeader) {
logger.warn("Image not found in the proxy", { id });
return null;
}
const url = decryptSecret(urlHeader.url);
return {
url,
headers: JSON.parse(decryptSecret(urlHeader.headers)) as Record<string, string> | null,
trustedOrigin: new URL(url).origin,
};
}
private async getExistingIdAsync(url: string, headers: Record<string, string> | undefined): Promise<string | null> {
const urlHash = this.hashSecret(url);
const headerHash = this.hashSecret(JSON.stringify(headers ?? null));
const channel = createHmacChannel(`${urlHash}.${headerHash}`);
return await channel.getAsync();
}
private async storeImageAsync(id: string, url: string, headers: Record<string, string> | undefined): Promise<void> {
const urlHash = this.hashSecret(url);
const headerHash = this.hashSecret(JSON.stringify(headers ?? null));
const hashChannel = createHmacChannel(`${urlHash}.${headerHash}`);
const urlHeaderChannel = createUrlByIdChannel(id);
await urlHeaderChannel.setAsync(
{
url: encryptSecret(url),
headers: encryptSecret(JSON.stringify(headers ?? null)),
},
{ ttlSeconds: IMAGE_PROXY_REDIS_TTL_SECONDS },
);
await hashChannel.setAsync(id, { ttlSeconds: IMAGE_PROXY_REDIS_TTL_SECONDS });
logger.debug("Stored image in the proxy", {
id,
url: this.redactUrl(url),
headers: this.redactHeaders(headers ?? null),
});
}
private hashSecret(value: string): string {
return createHmac("sha256", ImageProxy.getHmacKey()).update(value).digest("hex");
}
private redactUrl(url: string): string {
const urlObject = new URL(url);
const redactedSearch = [...urlObject.searchParams.keys()].map((key) => `${key}=REDACTED`).join("&");
return `${urlObject.origin}${urlObject.pathname}${redactedSearch ? `?${redactedSearch}` : ""}`;
}
private redactHeaders(headers: Record<string, string> | null): string | null {
if (!headers) return null;
return Object.keys(headers).join(", ");
}
}