Webmention-Avatare lokal cachen

Ein Astro-Helper lädt Webmention-Avatare beim Build herunter, dedupliziert und räumt sie auf. Die CSP bleibt strikt, Leser rufen den Avatar-Host nie auf.

Nachdem die Security-Header mit einer strikten Content Security Policy und img-src 'self' data: live waren, zeigte der nächste Scan ein neues Problem. Die Mention-Fotos auf meinen Post-Seiten waren weg. img-src auf 'self' data: https: zu öffnen, hätte nur das Symptom behoben. Stattdessen habe ich die Avatare zur Build-Zeit gecacht. Die CSP blieb strikt, und Leser schickten keine einzige Anfrage mehr an den Avatar-Host.

Das Problem

Meine Komponente Webmentions.astro hat die Facepile und die Antworten mit Avatar-URLs direkt aus der API von webmention.io gerendert:

<img
    src="https://avatars.webmention.io/files.mastodon.social/0ec46...jpg"
    alt=""
    loading="lazy"
/>

Das waren drei Probleme auf einmal:

  1. CSP. img-src 'self' data: blockt externe Bilder, und mit https: wäre die Direktive praktisch wertlos.
  2. Datenschutz für meine Leser. Bei jedem Aufruf einer Seite mit Mentions hat ihr Browser avatars.webmention.io angefragt. Der Host sah IP-Adresse, User-Agent, Referer und den Pfad des Posts. Nach Art. 5.1.c DSGVO (Datenminimierung) ist das eine unnötige Weitergabe personenbezogener Daten.
  3. Verfügbarkeit. War webmention.io down oder langsam, fehlten die Avatare oder hielten das Rendering auf.

Die Idee

Die Webmentions wurden sowieso zur Build-Zeit geholt. Jede Avatar-URL war also schon beim Rendern bekannt. Also die Bilder gleich mit herunterladen, lokal speichern und im HTML auf den lokalen Pfad umschreiben. Dafür braucht es vier Bausteine:

  • einen Cache-Ordner unter public/, der zwischen Builds erhalten bleibt;
  • eine Kopie nach dist/, weil Astro public/ vor dem Rendering nach dist/ kopiert und spätere Downloads sonst im aktuellen Build fehlen;
  • eine Deduplizierung, damit ein Autor, der denselben Post liked und repostet, nur einmal heruntergeladen wird;
  • ein Aufräumen am Build-Ende, das Avatare löscht, auf die nichts mehr verweist.

Der Helper

src/lib/avatar-cache.ts:

import { createHash } from 'node:crypto';
import { existsSync } from 'node:fs';
import { copyFile, mkdir, readdir, unlink, writeFile } from 'node:fs/promises';
import path from 'node:path';

const PUBLIC_DIR = path.resolve(
    process.cwd(),
    'public',
    'images',
    'webmention',
);
const DIST_DIR = path.resolve(process.cwd(), 'dist', 'images', 'webmention');
const URL_PATH = '/images/webmention';

const EXT_BY_MIME: Record<string, string> = {
    'image/jpeg': 'jpg',
    'image/png': 'png',
    'image/webp': 'webp',
    'image/gif': 'gif',
    'image/avif': 'avif',
    'image/svg+xml': 'svg',
};

const memo = new Map<string, Promise<string | null>>();
const usedFilenames = new Set<string>();

async function mirrorToDist(filename: string, srcPath: string) {
    try {
        await mkdir(DIST_DIR, { recursive: true });
        const dest = path.join(DIST_DIR, filename);
        if (!existsSync(dest)) await copyFile(srcPath, dest);
    } catch {
        // dist/ gibt's in `astro dev` nicht, ignorieren
    }
}

async function download(url: string): Promise<string | null> {
    const hash = createHash('sha1').update(url).digest('hex').slice(0, 16);
    await mkdir(PUBLIC_DIR, { recursive: true });

    try {
        const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
        if (!res.ok) return null;
        const mime = (res.headers.get('content-type') ?? '')
            .split(';')[0]
            .trim()
            .toLowerCase();
        const ext = EXT_BY_MIME[mime] ?? 'jpg';
        const filename = `${hash}.${ext}`;
        const filepath = path.join(PUBLIC_DIR, filename);
        if (!existsSync(filepath)) {
            const buf = Buffer.from(await res.arrayBuffer());
            await writeFile(filepath, buf);
        }
        usedFilenames.add(filename);
        await mirrorToDist(filename, filepath);
        return `${URL_PATH}/${filename}`;
    } catch {
        return null;
    }
}

export function cacheAvatar(url: string | undefined): Promise<string | null> {
    if (!url) return Promise.resolve(null);
    if (!/^https?:\/\//i.test(url)) return Promise.resolve(url);
    let pending = memo.get(url);
    if (!pending) {
        pending = download(url);
        memo.set(url, pending);
    }
    return pending;
}

async function sweepDir(dir: string): Promise<number> {
    if (!existsSync(dir)) return 0;
    const entries = await readdir(dir);
    let removed = 0;
    await Promise.all(
        entries.map(async (name) => {
            if (!usedFilenames.has(name)) {
                await unlink(path.join(dir, name));
                removed++;
            }
        }),
    );
    return removed;
}

export async function sweepCache(): Promise<{ removed: number }> {
    const publicRemoved = await sweepDir(PUBLIC_DIR);
    await sweepDir(DIST_DIR);
    return { removed: publicRemoved };
}

Vier Details, die leicht untergehen:

  • Der SHA1 der URL ist der Dateiname. Derselbe Avatar bekommt immer denselben Namen, egal in welchem Build er auftaucht.
  • Die Dateiendung kommt aus dem MIME-Type im Response-Header. webmention.io liefert manche Avatare unter URLs ohne Endung aus.
  • Die memo-Map verhindert doppelte Downloads in einem Build. Die Komponente ruft cacheAvatar über Promise.all auf, sonst würde ein Autor mit Like und Repost zweimal parallel geladen.
  • usedFilenames plus sweepCache ergeben einen Mark-and-Sweep-Cache. Jeder Treffer markiert eine Datei als benutzt, am Ende löscht der Sweep alles Unmarkierte, etwa den Avatar eines zurückgenommenen Likes.

In Webmentions.astro lief der Cache-Schritt direkt nach fetchMentions:

---
import { cacheAvatar } from '~/lib/avatar-cache';
// ...
const all = await fetchMentions(targetStr);

await Promise.all(
    all.map(async (m) => {
        if (m.author?.photo) {
            const local = await cacheAvatar(m.author.photo);
            if (local) m.author.photo = local;
            else delete m.author.photo;
        }
    }),
);
---

Scheiterte ein Download (Timeout, 404), wurde author.photo entfernt, und die Komponente zeigte stattdessen einen Avatar mit den Initialen des Autors.

Aufräumen als Astro-Integration

sweepCache darf erst laufen, wenn alle Seiten gerendert sind. Sonst löscht er Avatare, die eine später gerenderte Seite noch braucht. Der Hook astro:build:done ist genau dieser Zeitpunkt. src/integrations/avatar-cache-sweep.ts:

import type { AstroIntegration } from 'astro';
import { sweepCache } from '../lib/avatar-cache';

export default function avatarCacheSweep(): AstroIntegration {
    return {
        name: 'avatar-cache-sweep',
        hooks: {
            'astro:build:done': async ({ logger }) => {
                const { removed } = await sweepCache();
                if (removed > 0) {
                    logger.info(
                        `swept ${removed} orphaned webmention avatar${removed === 1 ? '' : 's'}`,
                    );
                }
            },
        },
    };
}

Registriert in astro.config.mjs:

import avatarCacheSweep from './src/integrations/avatar-cache-sweep';

export default defineConfig({
    integrations: [
        mdx(),
        sitemap({
            /* ... */
        }),
        avatarCacheSweep(),
    ],
});

Im astro dev-Modus läuft astro:build:done nicht, der Sweep greift also nur bei astro build. Ein Dev-Server kann so keine Avatare wegräumen, die der nächste Produktions-Build noch braucht.

Warum /images/webmention/

Mein erster Versuch war /webmention-avatars/ direkt unter dem Site-Root. Das ging, passte aber nicht zu der Cache-Regel, die ich in Caddy schon hatte:

header /images/* Cache-Control "public, max-age=604800"

Unter /images/webmention/ bekamen die Avatare ohne weitere Konfiguration eine Woche Browser-Cache.

Der Cache-Ordner gehört nicht ins Repository. Er füllt sich beim Build, wenn er leer ist, und bleibt sonst vom letzten Lauf liegen. In die .gitignore kommt deshalb:

public/images/webmention/

In einer CI ohne dauerhaften Cache werden die Avatare bei jedem Build neu geholt. Es sind ein paar kleine JPEGs, das ist unkritisch.

Das Ergebnis

Im gebauten HTML zeigte das Bild jetzt auf die eigene Seite:

<img src="/images/webmention/556ae159c81f2fc1.jpg" alt="" loading="lazy" />
  • Die CSP blieb strikt. img-src 'self' data: reichte.
  • Keine Anfragen an Dritte beim Aufruf. Leser luden die Avatare von meinem Server, der Mention-Host sah sie nie.
  • Die Verfügbarkeit war entkoppelt. Die Avatare hingen nur noch an einem erfolgreichen Build, nicht daran, ob webmention.io beim Lesen erreichbar war.
  • Der Cache räumte sich selbst auf. Zurückgezogene Likes und gelöschte Kommentare nahmen ihren Avatar beim nächsten Build mit. Auch das ist Datenminimierung.

Zum Mitnehmen

  • Externe Ressourcen, die zur Build-Zeit bekannt sind, gehören in einen lokalen Cache. Was für selbst gehostete Google Fonts gilt, gilt auch für Avatare, Icons und Badges.
  • CSP und Datenschutz führten zur selben Lösung. Wer die Avatare nicht mehr extern lädt, muss die CSP nicht aufweichen und gibt die IP-Adressen seiner Leser nicht weiter.
  • Ein Cache ohne Aufräumen wird zum Datenfriedhof. Mark-and-Sweep sind ein paar Zeilen Code.

Mehr dazu

Thema
  • IndieWeb Zuerst auf der eigenen Domain veröffentlichen und persönliche Websites über offene Standards wie Webmention und Microformats verbinden.
Baut auf
  • Security-Header in Caddy Eine strikte Content Security Policy, HSTS und no-referrer in einem Caddy-Siteblock, geprüft mit Webbkoll, securityheaders.com und dem Mozilla Observatory.
Nutzt
  • Caddy Webserver und Reverse Proxy, der TLS-Zertifikate selbst holt und erneuert, eingerichtet in einem kurzen Caddyfile.

In der Graph-Ansicht zeigen →