diff --git a/README.md b/README.md
index 97ca5cf..7b13e9f 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,12 @@ You need to generate a matrix id, using the algorithm as shown above.
2. mxc: `mxc://example.org/klipy_ZmZkNGFjMTQzZTYzMzVhYzY4OTUxYjc4N2QzYzE5MDIvZTgvM2EvNUxNMGpScEwuZ2lm`
3. will return a redirect to `https://static.klipy.com/ii/ffd4ac143e6335ac68951b787d3c1902/e8/3a/5LM0jRpL.gif`
+## Link previews
+
+`GET /_soliditas/preview_url?url=[url]` answers in the shape of the Matrix `/preview_url` endpoint. Missing `og:` tags are filled from `twitter:` tags, ``, `<meta name="description">` and oEmbed. Twitter/X links are read from the [FxTwitter API](https://github.com/FxEmbed/FxEmbed), Reddit and TikTok titles from their oEmbed endpoints, Tumblr posts without an image get the [fxtumblr](https://github.com/knuxify/fxtumblr) render, and Misskey-family notes show their images from the ActivityPub object unless marked sensitive, instead of the author's avatar.
+
+`og:image` is returned as `mxc://[servername]/og_[base64url of the image url]`. When a post has more than one image, `com.sable.images` lists up to ten of them as `{ url, width, height }`, and `og:image` stays the single image other clients show (the FxTwitter mosaic for tweets).
+
## License
This project is licensed under Apache 2.0, see LICENSE.
diff --git a/src/index.ts b/src/index.ts
index e4e1723..ae78f09 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -18,6 +18,7 @@
import { matrixEndpointNotImplemented, matrixInvalidParam } from './matrixError';
import { toMatrixID } from './mxcId';
+import { previewUrl } from './preview';
import { proxyMediaCall } from './proxy';
import { returnMatrixServerVers } from './serverversion';
import { MatrixWellKnownServer, SoliditasAddressConvertResponse } from './types';
@@ -37,6 +38,8 @@ export default {
} else if (url.pathname.startsWith('/_matrix/federation/v1/media/download/')) {
const mediaId = url.pathname.replace('/_matrix/federation/v1/media/download/', '');
return proxyMediaCall(mediaId);
+ } else if (url.pathname === '/_soliditas/preview_url') {
+ return previewUrl(url.searchParams.get('url'), serverName);
} else if (url.pathname === '/_soliditas/adressconvert'){
// helper function mainly for debug reasons as it should be embeded in the client for production use
const remoteType = url.searchParams.get('remoteType');
diff --git a/src/preview.ts b/src/preview.ts
new file mode 100644
index 0000000..8e3aa04
--- /dev/null
+++ b/src/preview.ts
@@ -0,0 +1,303 @@
+/*
+ Apache License 2.0
+
+ Copyright 2026 Rye
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/
+
+import { matrixInvalidParam, matrixRessourceNotFound } from './matrixError';
+import { toMatrixID } from './mxcId';
+
+const USER_AGENT = 'Soliditas (bot; +https://github.com/SableClient/soliditas) facebookexternalhit/1.1';
+
+const CORS_HEADERS = {
+ 'Content-Type': 'application/json',
+ 'Access-Control-Allow-Origin': '*',
+};
+
+const TWITTER_HOSTS = /^(?:www\.|mobile\.)?(?:twitter|x|fxtwitter|fixupx|vxtwitter|fixvx)\.com$/;
+const TWITTER_STATUS = /^\/(?:[^/]+|i\/web)\/status(?:es)?\/(\d+)/;
+
+const TUMBLR_BLOG_POST = /^([a-z\d-]+)\.tumblr\.com$/;
+const TUMBLR_DASHBOARD_POST = /^\/([a-z\d-]+)\/(\d+)/;
+
+const OEMBED_ENDPOINTS: [RegExp, string][] = [
+ [/(?:^|\.)reddit\.com$/, 'https://www.reddit.com/oembed'],
+ [/(?:^|\.)tiktok\.com$/, 'https://www.tiktok.com/oembed'],
+];
+
+const NAMED_ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: '\u00a0' };
+
+const MAX_IMAGES = 10;
+
+type Tags = Record<string, string>;
+
+type Image = { url: string; width?: number; height?: number };
+
+type Preview = { tags: Tags; images: Image[]; cover?: Image };
+
+type OEmbed = {
+ title?: string;
+ author_name?: string;
+ provider_name?: string;
+ thumbnail_url?: string;
+ thumbnail_width?: number;
+ thumbnail_height?: number;
+};
+
+type ActivityNote = {
+ sensitive?: boolean;
+ attachment?: { mediaType?: string; url?: string; width?: number; height?: number }[];
+};
+
+type FxMedia = { url?: string; thumbnail_url?: string; width?: number; height?: number };
+
+type FxTweet = {
+ text?: string;
+ author?: { name?: string; screen_name?: string; avatar_url?: string };
+ media?: { photos?: FxMedia[]; videos?: FxMedia[]; mosaic?: { formats?: { jpeg?: string } } };
+};
+
+export function parsePublicUrl(value: string, base?: string | URL): URL | null {
+ let url: URL;
+ try {
+ url = new URL(value, base);
+ } catch {
+ return null;
+ }
+ if (url.protocol !== 'https:' && url.protocol !== 'http:') return null;
+ const host = url.hostname.toLowerCase();
+ if (!host.includes('.') || host.includes(':') || host.startsWith('[')) return null;
+ if (/^[\d.]+$/.test(host)) return null;
+ if (host === 'localhost' || /\.(localhost|local|internal|home\.arpa)$/.test(host)) return null;
+ return url;
+}
+
+function decodeEntities(value: string): string {
+ return value.replace(/&(?:#x([\da-f]+)|#(\d+)|([a-z]+));/gi, (entity, hex, decimal, name) => {
+ const code = hex ? Number.parseInt(hex, 16) : decimal ? Number.parseInt(decimal, 10) : undefined;
+ if (code !== undefined) return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : entity;
+ return NAMED_ENTITIES[name.toLowerCase()] ?? entity;
+ });
+}
+
+function fetchPublic(url: URL, accept: string): Promise<Response | null> {
+ return fetch(url, { headers: { 'User-Agent': USER_AGENT, Accept: accept }, redirect: 'follow' })
+ .then((response) => (response.ok ? response : null))
+ .catch(() => null);
+}
+
+async function fetchJson<T>(url: URL): Promise<T | null> {
+ const response = await fetchPublic(url, 'application/json');
+ return response ? ((await response.json().catch(() => null)) as T | null) : null;
+}
+
+function setTag(tags: Tags, key: string, value: string | number | undefined): void {
+ if (value === undefined || value === '' || tags[key]) return;
+ tags[key] = String(value);
+}
+
+function toSize(value: string | number | undefined): number | undefined {
+ const size = typeof value === 'number' ? value : Number.parseInt(value ?? '', 10);
+ return Number.isFinite(size) && size > 0 ? size : undefined;
+}
+
+function toImage(value: string | undefined, base?: string | URL, width?: string | number, height?: string | number): Image | null {
+ const url = value ? parsePublicUrl(value, base) : null;
+ if (!url || url.pathname === '/') return null;
+ return { url: url.href, width: toSize(width), height: toSize(height) };
+}
+
+function imageKey(image: Image): string {
+ const url = new URL(image.url);
+ if (!url.hostname.endsWith('.media.tumblr.com')) return url.href;
+ return url.pathname.split('/').slice(1, 3).join('/');
+}
+
+function addImages(images: Image[], candidates: (Image | null)[]): void {
+ for (const image of candidates) {
+ if (image && images.length < MAX_IMAGES && !images.some((known) => imageKey(known) === imageKey(image))) images.push(image);
+ }
+}
+
+async function readPage(page: Response, base: string | URL): Promise<{ preview: Preview; oembed?: string; misskeyNote: boolean }> {
+ const tags: Tags = {};
+ const fallback: Tags = {};
+ const found: { url: string; width?: string; height?: string }[] = [];
+ let title = '';
+ let oembed: string | undefined;
+ let misskeyNote = false;
+
+ await new HTMLRewriter()
+ .on('meta', {
+ element(element) {
+ const key = element.getAttribute('property') ?? element.getAttribute('name');
+ const raw = element.getAttribute('content');
+ const content = raw && decodeEntities(raw).trim();
+ if (!key || !content) return;
+ if (key === 'misskey:note-id') misskeyNote = true;
+ if (key === 'og:image' || key === 'og:image:url') found.push({ url: content });
+ else if (key === 'og:image:width' || key === 'og:image:height') {
+ const last = found.at(-1);
+ const side = key === 'og:image:width' ? 'width' : 'height';
+ if (last && !last[side]) last[side] = content;
+ } else if (key.startsWith('og:image')) return;
+ else if (key.startsWith('og:')) setTag(tags, key, content);
+ else if (key.startsWith('twitter:') || key === 'description') setTag(fallback, key, content);
+ },
+ })
+ .on('link[rel="alternate"][type="application/json+oembed"]', {
+ element(element) {
+ const href = element.getAttribute('href');
+ oembed ??= href ? decodeEntities(href) : undefined;
+ },
+ })
+ .on('title', {
+ text(text) {
+ title += text.text;
+ },
+ })
+ .transform(page)
+ .arrayBuffer();
+
+ setTag(tags, 'og:title', fallback['twitter:title'] ?? decodeEntities(title).trim());
+ setTag(tags, 'og:description', fallback['twitter:description'] ?? fallback['description']);
+
+ const images: Image[] = [];
+ addImages(images, found.map((image) => toImage(image.url, base, image.width, image.height)));
+ if (!images.length) addImages(images, [toImage(fallback['twitter:image'] ?? fallback['twitter:image:src'], base)]);
+ return { preview: { tags, images }, oembed, misskeyNote };
+}
+
+async function noteImages(url: URL): Promise<Image[]> {
+ const response = await fetchPublic(url, 'application/activity+json');
+ const note = response ? ((await response.json().catch(() => null)) as ActivityNote | null) : null;
+ if (!note || note.sensitive) return [];
+ const images: Image[] = [];
+ addImages(
+ images,
+ (note.attachment ?? []).filter((file) => file.mediaType?.startsWith('image/')).map((file) => toImage(file.url, url, file.width, file.height)),
+ );
+ return images;
+}
+
+function mergeOEmbed(preview: Preview, oembed: OEmbed, authoritative: boolean): void {
+ const { tags } = preview;
+ if (authoritative && oembed.title) tags['og:description'] = oembed.title;
+ setTag(tags, 'og:title', oembed.title ?? oembed.author_name);
+ setTag(tags, 'og:site_name', oembed.provider_name);
+ if (!preview.images.length) addImages(preview.images, [toImage(oembed.thumbnail_url, undefined, oembed.thumbnail_width, oembed.thumbnail_height)]);
+}
+
+async function previewTweet(id: string): Promise<Preview | null> {
+ const body = await fetchJson<{ tweet?: FxTweet }>(new URL(`https://api.fxtwitter.com/status/${id}`));
+ const tweet = body?.tweet;
+ if (!tweet) return null;
+
+ const tags: Tags = { 'og:site_name': 'X' };
+ const { name, screen_name: handle, avatar_url: avatar } = tweet.author ?? {};
+ setTag(tags, 'og:title', name && handle ? `${name} (@${handle})` : (name ?? handle));
+ setTag(tags, 'og:description', tweet.text);
+
+ const images: Image[] = [];
+ const media = [...(tweet.media?.photos ?? []), ...(tweet.media?.videos ?? [])];
+ addImages(images, media.map((item) => toImage(item.thumbnail_url ?? item.url, undefined, item.width, item.height)));
+ if (!images.length) addImages(images, [toImage(avatar)]);
+
+ const mosaic = images.length > 1 ? toImage(tweet.media?.mosaic?.formats?.jpeg) : null;
+ return { tags, images, cover: mosaic ?? undefined };
+}
+
+async function previewPage(url: URL): Promise<Preview | null> {
+ const endpoint = OEMBED_ENDPOINTS.find(([host]) => host.test(url.hostname))?.[1];
+ const known = endpoint ? fetchJson<OEmbed>(new URL(`${endpoint}?format=json&url=${encodeURIComponent(url.href)}`)) : null;
+
+ const page = await fetchPublic(url, 'text/html');
+ const base = page?.url || url;
+ const html = page?.headers.get('Content-Type')?.includes('text/html') ? await readPage(page, base) : null;
+ const knownOEmbed = await known;
+ if (!html && !knownOEmbed) return null;
+
+ const preview = html?.preview ?? { tags: {}, images: [] };
+ const { tags } = preview;
+ if (knownOEmbed) mergeOEmbed(preview, knownOEmbed, true);
+ else if (html?.oembed && !(tags['og:title'] && tags['og:description'] && preview.images.length)) {
+ const discovered = parsePublicUrl(html.oembed, base);
+ const found = discovered ? await fetchJson<OEmbed>(discovered) : null;
+ if (found) mergeOEmbed(preview, found, false);
+ }
+ if (html?.misskeyNote) {
+ const attachments = await noteImages(url);
+ if (attachments.length) preview.images = attachments;
+ }
+ return preview;
+}
+
+function tumblrPost(url: URL): string | null {
+ const blog = TUMBLR_BLOG_POST.exec(url.hostname)?.[1];
+ if (blog && blog !== 'www') {
+ const id = /^\/post\/(\d+)/.exec(url.pathname)?.[1];
+ return id ? `${blog}/${id}` : null;
+ }
+ if (!/^(?:www\.)?tumblr\.com$/.test(url.hostname)) return null;
+ const [, dashboardBlog, id] = TUMBLR_DASHBOARD_POST.exec(url.pathname) ?? [];
+ return id ? `${dashboardBlog}/${id}` : null;
+}
+
+async function previewTumblr(url: URL, post: string): Promise<Preview | null> {
+ const [preview, fxtumblr] = await Promise.all([previewPage(url), previewPage(new URL(`https://tpmblr.com/${post}`))]);
+ if (!preview || preview.images.length || !fxtumblr?.images.length) return preview ?? fxtumblr;
+ preview.images = fxtumblr.images;
+ return preview;
+}
+
+function toMatrixPreview({ tags, images, cover }: Preview, serverName: string): Record<string, unknown> {
+ const toMxc = (image: Image) => `mxc://${serverName}/${toMatrixID(image.url, 'og_')}`;
+ const preview: Record<string, unknown> = { ...tags };
+
+ const main = cover ?? images[0];
+ if (main) {
+ preview['og:image'] = toMxc(main);
+ if (main.width) preview['og:image:width'] = main.width;
+ if (main.height) preview['og:image:height'] = main.height;
+ }
+ if (images.length > 1) {
+ preview['com.sable.images'] = images.map((image) => ({ url: toMxc(image), width: image.width, height: image.height }));
+ }
+ return preview;
+}
+
+export async function previewUrl(target: string | null, serverName: string): Promise<Response> {
+ const url = target ? parsePublicUrl(target) : null;
+ if (!url) {
+ return new Response(JSON.stringify(matrixInvalidParam('url must be a public http(s) url')), {
+ headers: CORS_HEADERS,
+ status: 400,
+ });
+ }
+
+ const tweet = TWITTER_HOSTS.test(url.hostname) ? TWITTER_STATUS.exec(url.pathname)?.[1] : undefined;
+ const tumblr = tumblrPost(url);
+ const preview = (tweet ? await previewTweet(tweet) : null) ?? (tumblr ? await previewTumblr(url, tumblr) : await previewPage(url));
+ if (!preview) {
+ return new Response(JSON.stringify(matrixRessourceNotFound('no html preview for this url')), {
+ headers: CORS_HEADERS,
+ status: 404,
+ });
+ }
+
+ return new Response(JSON.stringify(toMatrixPreview(preview, serverName)), {
+ headers: { ...CORS_HEADERS, 'Cache-Control': 'public, max-age=86400' },
+ });
+}
diff --git a/src/proxy.ts b/src/proxy.ts
index 4e4df9c..aa29c28 100644
--- a/src/proxy.ts
+++ b/src/proxy.ts
@@ -19,6 +19,7 @@
import { MatrixError } from './types';
import { matrixInvalidParam } from './matrixError';
import { fromMatrixID } from './mxcId';
+import { parsePublicUrl } from './preview';
/**
* helper function to decode matrix id, and either return the decoded id or a error response
@@ -113,6 +114,17 @@ function proxyKlipy(path: string): Response {
return buildMultipartRedirect(`https://static.klipy.com/ii/${path}`)
}
+function proxyOpenGraphImage(url: string): Response {
+ const image = parsePublicUrl(url);
+ if (!image) {
+ return new Response(JSON.stringify(matrixInvalidParam('the og image is not a public http(s) url')), {
+ status: 400,
+ statusText: 'the og image is not a public http(s) url',
+ });
+ }
+ return buildMultipartRedirect(image.href);
+}
+
export async function proxyMediaCall(rawId: string): Promise<Response> {
const decodedId = decodeMatrixId(rawId);
if (typeof decodedId !== 'string') {
@@ -121,12 +133,15 @@ export async function proxyMediaCall(rawId: string): Promise<Response> {
const isGiphy: boolean = rawId.startsWith('giphy_') || decodedId.startsWith('giphy_');
const isTenor: boolean = rawId.startsWith('tenor_') || decodedId.startsWith('tenor_');
const isKlipy: boolean = rawId.startsWith('klipy_') || decodedId.startsWith('klipy_');
+ const isOpenGraph: boolean = rawId.startsWith('og_');
if (isTenor) {
return proxyTenor(decodedId);
} else if (isGiphy) {
return proxyGiphy(decodedId);
} else if (isKlipy) {
return proxyKlipy(decodedId);
+ } else if (isOpenGraph) {
+ return proxyOpenGraphImage(decodedId);
}
return new Response(JSON.stringify(matrixInvalidParam("the identifier of the remote didn't match any supported remote identifier")), {
status: 400,
diff --git a/test/preview.spec.ts b/test/preview.spec.ts
new file mode 100644
index 0000000..000dad3
--- /dev/null
+++ b/test/preview.spec.ts
@@ -0,0 +1,363 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+
+import worker from '../src/index';
+import { toMatrixID } from '../src/mxcId';
+import { proxyMediaCall } from '../src/proxy';
+
+const env = {} as { SERVERNAME: any; HOSTNAME: any; PORT: any };
+
+function preview(target: string) {
+ return worker.fetch({ url: `https://gifs.example/_soliditas/preview_url?url=${encodeURIComponent(target)}` }, env, {});
+}
+
+function servePage(html: string, contentType = 'text/html; charset=utf-8') {
+ return vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(html, { headers: { 'Content-Type': contentType } }));
+}
+
+function serveRoutes(routes: Record<string, () => Response>) {
+ return vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+ const url = String(input instanceof Request ? input.url : input);
+ const route = Object.keys(routes).find((prefix) => url.startsWith(prefix));
+ return route ? routes[route]() : new Response(null, { status: 404 });
+ });
+}
+
+function html(body: string) {
+ return new Response(body, { headers: { 'Content-Type': 'text/html' } });
+}
+
+function json(body: unknown) {
+ return Response.json(body);
+}
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe('preview_url', () => {
+ it('answers with the open graph tags and an mxc for the image', async () => {
+ servePage(`<html><head>
+ <meta property="og:title" content="A post">
+ <meta property="og:description" content="Something happened">
+ <meta property="og:site_name" content="Example">
+ <meta property="og:image" content="/cover.png">
+ <meta property="og:image:width" content="640">
+ <meta property="og:image:height" content="nope">
+ </head></html>`);
+
+ const response = await preview('https://news.example/post');
+
+ expect(response.status).toBe(200);
+ expect(response.headers.get('Access-Control-Allow-Origin')).toBe('*');
+ expect(await response.json()).toEqual({
+ 'og:title': 'A post',
+ 'og:description': 'Something happened',
+ 'og:site_name': 'Example',
+ 'og:image': `mxc://gifs.example/${toMatrixID('https://news.example/cover.png', 'og_')}`,
+ 'og:image:width': 640,
+ });
+ });
+
+ it('falls back to the title and description tags', async () => {
+ servePage('<html><head><title> Plain & page