Profile pictures from Gravatar or the identity provider, fetched and kept by the server

Both sources are off until switched on under Settings, Sign-in. The server asks only
gravatar.com (by a hash of the email) and the identity provider's own host, accepts only
small PNG/JPEG/WebP/GIF, keeps each picture for a day and serves it from /api/avatars/<id>,
so browsers never contact either. Shown in the user menu and on the Users page, with initials
as the fallback; the Privacy page says when it is on.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-18 23:47:50 +02:00
1 parent 9782bd3252
commit c05c847d17
26 files changed
+4361 -21

No files matched your search

+186
View File
@@ -0,0 +1,186 @@
/**
* Profile pictures, fetched and kept by this server so that people's browsers never contact an outside address.
*
* Where a picture can come from (Settings → Sign-in → Profile pictures, both off until an administrator turns them on):
* - the identity provider's own "picture" claim, tried first, and
* - Gravatar, by a SHA-256 hash of the person's email address (never the address itself).
*
* The server only ever asks the hosts it is allowed to: gravatar.com, and the identity provider's own host. A "picture" claim naming anywhere
* else is ignored, so a claim cannot be used to make the server fetch an arbitrary address. What comes back must be a small PNG, JPEG, WebP or
* GIF — never SVG, which can carry script and would be served from this app's own origin.
*/
import { createHash } from "node:crypto";
import { env } from "../env.js";
import type { ProfilePictureSettings } from "./settingsStore.js";
/** What the server will accept as a picture. */
const MAX_BYTES = 256 * 1024;
const TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
const FETCH_TIMEOUT_MS = 4000;
const MAX_REDIRECTS = 2;
const FOUND_TTL_MS = 24 * 3600_000;
/** Someone with no picture is asked about again after this, so adding one shows up the same day without asking every page view. */
const MISSING_TTL_MS = 3600_000;
/** A host that could not be reached is tried again soon. */
const FAILED_TTL_MS = 5 * 60_000;
const MAX_CACHED = 200;
export interface AvatarImage {
contentType: string;
body: Buffer;
}
export type AvatarFetcher = (url: string) => Promise<Response>;
const realFetcher: AvatarFetcher = (url) =>
fetch(url, { redirect: "manual", signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), headers: { accept: [...TYPES].join(", "), "user-agent": "HomelabManager" } });
let fetcher: AvatarFetcher = realFetcher;
/** Tests stand in for the network. */
export function setAvatarFetcherForTests(f: AvatarFetcher | null): void {
fetcher = f ?? realFetcher;
cache.clear();
}
/** A person's email as Gravatar wants it: trimmed, lower case, SHA-256. */
export function gravatarHash(email: string): string {
return createHash("sha256").update(email.trim().toLowerCase()).digest("hex");
}
export function gravatarUrl(email: string): string {
return `https://gravatar.com/avatar/${gravatarHash(email)}?s=128&d=404`;
}
function issuerHost(): string | null {
try {
return new URL(env.authentik.issuerUrl).host.toLowerCase();
} catch {
return null;
}
}
const isGravatarHost = (host: string) => host === "gravatar.com" || host.endsWith(".gravatar.com");
/** Whether the server may ask this address for a picture: Gravatar over HTTPS, or the identity provider's own host. */
export function isAllowedPictureUrl(raw: string, idpHost: string | null = issuerHost()): boolean {
let url: URL;
try {
url = new URL(raw);
} catch {
return false;
}
const host = url.host.toLowerCase();
if (url.username || url.password) return false;
if (isGravatarHost(url.hostname.toLowerCase())) return url.protocol === "https:";
return idpHost !== null && host === idpHost && (url.protocol === "https:" || url.protocol === "http:");
}
/** The "picture" claim, if it is an address at all; kept as given and judged again whenever it is used. */
export function pictureFromClaims(sources: Record<string, unknown>[]): string | undefined {
for (const source of sources) {
const value = source.picture;
if (typeof value !== "string") continue;
const trimmed = value.trim();
if (trimmed.length === 0 || trimmed.length > 500) continue;
try {
const url = new URL(trimmed);
if (url.protocol === "https:" || url.protocol === "http:") return trimmed;
} catch {
// not an address
}
}
return undefined;
}
/** The addresses this person's picture may be fetched from under the current settings, in the order they are tried. */
export function avatarSources(user: { email: string | null; pictureUrl: string | null }, settings: ProfilePictureSettings, idpHost: string | null = issuerHost()): string[] {
const out: string[] = [];
if (settings.identityProvider && user.pictureUrl && isAllowedPictureUrl(user.pictureUrl, idpHost)) {
// A claim that names Gravatar is Gravatar all the same: it needs that switched on too.
let host = "";
try {
host = new URL(user.pictureUrl).hostname.toLowerCase();
} catch {
// judged above
}
if (!isGravatarHost(host) || settings.gravatar) out.push(user.pictureUrl);
}
if (settings.gravatar && user.email && user.email.includes("@")) out.push(gravatarUrl(user.email));
return [...new Set(out)];
}
/** The address the browser asks this server for, or null when there is no picture to look for. `v` changes with the source so a new one is not hidden by the browser's copy. */
export function avatarUrlFor(user: { id: number; email: string | null; pictureUrl: string | null }, settings: ProfilePictureSettings): string | null {
const sources = avatarSources(user, settings);
if (sources.length === 0) return null;
return `/api/avatars/${user.id}?v=${createHash("sha256").update(sources.join("\n")).digest("hex").slice(0, 8)}`;
}
// ─── Fetching and keeping ──────────────────────────────────────────────────
interface Entry {
until: number;
image: AvatarImage | null;
}
const cache = new Map<string, Entry>();
function remember(url: string, image: AvatarImage | null, ttl: number): void {
cache.delete(url);
cache.set(url, { until: Date.now() + ttl, image });
while (cache.size > MAX_CACHED) cache.delete(cache.keys().next().value as string);
}
/** One picture from one address: followed through at most two redirects, only to addresses that are allowed too. */
async function download(start: string): Promise<{ image: AvatarImage | null; failed: boolean }> {
let url = start;
for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
let res: Response;
try {
res = await fetcher(url);
} catch {
return { image: null, failed: true };
}
if (res.status >= 300 && res.status < 400) {
const location = res.headers.get("location");
let next: string | null = null;
try {
next = location ? new URL(location, url).toString() : null;
} catch {
next = null;
}
if (!next || !isAllowedPictureUrl(next)) return { image: null, failed: false };
url = next;
continue;
}
if (res.status >= 500) return { image: null, failed: true };
if (!res.ok) return { image: null, failed: false };
const type = (res.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
if (!TYPES.has(type)) return { image: null, failed: false };
const declared = Number(res.headers.get("content-length"));
if (Number.isFinite(declared) && declared > MAX_BYTES) return { image: null, failed: false };
let body: Buffer;
try {
body = Buffer.from(await res.arrayBuffer());
} catch {
return { image: null, failed: true };
}
if (body.length === 0 || body.length > MAX_BYTES) return { image: null, failed: false };
return { image: { contentType: type, body }, failed: false };
}
return { image: null, failed: false };
}
/** The first of this person's sources that has a picture, from the keep or from the source itself. Null when none does. */
export async function getAvatar(user: { email: string | null; pictureUrl: string | null }, settings: ProfilePictureSettings): Promise<AvatarImage | null> {
for (const source of avatarSources(user, settings)) {
const kept = cache.get(source);
if (kept && kept.until > Date.now()) {
if (kept.image) return kept.image;
continue;
}
const { image, failed } = await download(source);
remember(source, image, image ? FOUND_TTL_MS : failed ? FAILED_TTL_MS : MISSING_TTL_MS);
if (image) return image;
}
return null;
}
+13
View File
@@ -135,6 +135,17 @@ export interface SignInSettings {
otherwise: "viewer" | "keep";
}
/**
* Where people's profile pictures may come from. Both are off until an administrator turns them on, because each means this server asks an
* outside address for a picture (Gravatar is told a hash of the person's email). The browser never does: pictures are fetched and kept by the server.
*/
export interface ProfilePictureSettings {
/** gravatar.com, by a hash of the person's email address. */
gravatar: boolean;
/** The picture the identity provider (Authentik) names for the person in its "picture" claim. */
identityProvider: boolean;
}
/** How the agents out on the servers are kept up to date. Off until an administrator turns it on. */
export interface AgentSettings {
/** An agent that is behind downloads the newer script from this app, checks it and replaces itself. */
@@ -215,6 +226,7 @@ export interface AppSettings {
healthChecks: HealthCheckSettings;
digest: DigestSettings;
signIn: SignInSettings;
profilePictures: ProfilePictureSettings;
inventory: InventorySettings;
selfBackup: SelfBackupSettings;
agents: AgentSettings;
@@ -258,6 +270,7 @@ const DEFAULTS: AppSettings = {
inventory: { currency: "", pricePerKwh: null },
agents: { autoUpdate: false },
selfBackup: { enabled: true, time: "03:30", keep: 14 },
profilePictures: { gravatar: false, identityProvider: false },
signIn: { roleFromGroups: false, groupsClaim: "groups", adminGroups: [], operatorGroups: [], otherwise: "viewer" },
healthChecks: { serverOfflineMinutes: 60, diskUsagePercent: 90, domainWarnDays: 30, diskForecastDays: 14, backupStaleHours: 48, restoreTestDays: 0 },
// Docker's default bridge (172.17.0.0/16) and the pool it hands custom networks from (172.18–31) live here, and every