6.7 KiB
Rich link bookmark cards (OpenGraph), cached offline (agy gap 10, roadmap 30)
Part of specs/plugins-parity/. No new crate. Reuses the tokenizer of notescraft-htmlmd (clean-paste, task 1), ureq (already approved, engine uses it), sha2 (approved).
Research (2026-10-21; agy claims checked)
- Notion bookmarks, Capacities weblinks (title, description, favicon, hero image), Craft link cards, Bear: from agy; Capacities is the only one linked (https://capacities.io/docs/objects/weblinks), not fetched here. Bear: not verified. Treat "who has it" as Notion, Capacities, Craft (unverified details).
- Obsidian: community plugins Link Embed / Auto Card Link fill the gap (not verified in this run: search returned nothing; names from memory, check before citing). Obsidian itself renders bare URLs as plain links.
- Standard: Open Graph protocol https://ogp.me/ (
og:title,og:description,og:image,og:site_name,og:url), with fallbacks<title>,<meta name=description>,<link rel=icon>. - Privacy risk is the reason for the strict policy below: fetching a URL leaks the user's IP and the fact that a note links there. This conflicts with the roadmap "Network policy reminder" (no title fetching for pasted links without its own spec section and a settings switch): THIS spec is that section.
Problem
A note full of bare links is unreadable ("what was that URL?"). Cards show title, site and summary at a glance and still work offline.
Goal
A line that contains ONLY a URL (a standalone paragraph, https://..., no other text) renders as a bookmark card in live preview when metadata is cached; the Markdown stays the bare URL (portable). Fetching happens ONLY when the user asks: context menu "Fetch link card" on a URL, palette "Link card: Fetch for the URL under the cursor", or the paste toast action "Make card" after a URL paste. Never automatic.
Non-goals (v1)
Automatic fetching on paste or on note open; background refresh; thumbnails/hero images (Q1); oEmbed/YouTube players; crawling robots.txt; link cards inside tables or lists; writing the title into the note (Feature ideas 2).
Design decisions
D1 Network policy (hard rules)
- Setting
web.link_cards(bool, defaultfalse). Off:linkcard.fetchreturnsnetwork_disabled; the UI shows the enable notice (same pattern as the Maps placeholder). - A fetch runs only from a command the user triggered. Not in
ai/assistant_gate.rsat all (neither READ nor WRITE list) so an AI agent cannot trigger network. - URL guard (
crates/engine/src/linkcard/url.rs, pure): schemehttp/httpsonly; no userinfo; length <= 2048; host notlocalhost, not an IP literal that is loopback/private/link-local/unspecified/multicast/CGNAT; max 3 redirects, each re-checked; timeout 8 s total; response body read up to 512 KiB (the<head>is all that is needed);Content-Typemust betext/htmlorapplication/xhtml+xml; one request in flight per URL; global limit 4 concurrent. Ceiling (documented): DNS names resolving to private IPs (rebinding) are not blocked in v1; user-initiated so accepted, upgrade path: a customureqresolver. Q2. - User agent
NotesCraft/<version> (link card); no cookies, no referrer.
D2 Cache
.notescraft/cache/web/<sha256-hex(normalised-url)>.json written with write_private: {"v":1,"url","final_url","title","description","site","favicon":null|"data"?, "fetched_ms"}; fields clipped (title 200, description 500, site 80 chars), control characters removed. Max 2 000 entries; oldest evicted on write. URL normalisation: lowercase scheme/host, drop fragment, keep query. linkcard.get NEVER touches the network.
D3 Engine (crates/engine/src/linkcard/{mod,url,fetch,og,cache,commands}.rs)
| id | params | result | network | writes |
|---|---|---|---|---|
linkcard.get |
{url} |
`{card | null}` | no |
linkcard.fetch |
{url, refresh?} |
{card} |
YES | cache |
linkcard.clear |
{url?} (none = all) |
{removed} |
no | cache |
og.rs uses notescraft_htmlmd::tokens::tokenize on the first 512 KiB, reads `<meta property |
name content>and |