Changeset fc40410 in Klonkt

Timestamp:

07/28/2026 07:43:47 AM (6 weeks ago)

Author:

Robin Genis <roboburr@…>

Branches:

main

Children:

b258a79

Parents:

6bc2e31b

Message:

Externe embeds: thumbnail-only, en gated aan de serverkant

Fase 2 van shaer-277. Een note zonder fediverse-quote maar met een externe link
levert nu een embed-kaart op, via dezelfde resolver (oEmbed of een bekende
provider). Twee besluiten zitten erin verankerd:

THUMBNAIL-ONLY. Nooit de iframe van de aanbieder. Een willekeurig
derde-partij-frame in een kindveilige app is een gat dat je niet meer dicht
krijgt, dus de kaart draagt een afbeelding en een titel en niets uitvoerbaars.

GATED AAN DE SERVERKANT. Externe embeds zijn een gated feature: de wereld van
een ward buiten de fediverse is aan de guardians. Cruciaal is WAAR die gate zit:
bij het serialiseren, niet in de client. Een embed die de client alleen maar
verbergt, is wel degelijk al op het toestel afgeleverd. Staat de gate dicht, dan
gaat shaer:embed simpelweg niet mee.

De regel zelf (externalEmbedsAllowed) is puur en apart getest: null = auto, wat
uit staat voor een ward en aan voor ieder ander; een expliciet guardian-besluit
wint beide kanten op.

Changed files:
src/config/database.js

• ap_timeline.embed_json en sites.external_embeds (NULL = auto)

src/services/guardianship/notes.js

• externalEmbedsAllowed(setting, isWard), puur en geexporteerd

src/services/guardianship/index.js

• doorgeexporteerd

src/services/ActivityPubService.js

• resolveExternalEmbed + firstExternalUrl + timelineEmbed
• inbound: geen quote maar wel een externe link -> embed resolven (out of band)

src/routes/activitypub.js

• inbox-read past de gate toe en serveert shaer:embed alleen als die open staat

New file:
test/external-embeds.test.js

• 5 tests: de auto-regel, het expliciete besluit, link-selectie (mentions en hashtags overslaan), en dat een kaart zonder url geen kaart is

remarks: 205 tests groen. Nog te doen: de clients laten shaer:embed renderen met
de bestaande QuoteCard, en een UI voor guardians om de gate te bedienen (hoort
bij shaer-3kp).

-robo
Co-Authored-By: Claude Opus 4.8 <noreply@…>

Files:

• src/config/database.js (modified) (2 diffs)
• src/routes/activitypub.js (modified) (2 diffs)
• src/services/ActivityPubService.js (modified) (4 diffs)
• src/services/guardianship/index.js (modified) (1 diff)
• src/services/guardianship/notes.js (modified) (2 diffs)
• test/external-embeds.test.js (added)

src/config/database.js

@@ -132 +132 @@
   ensureColumn('sites', 'show_search',     'INTEGER DEFAULT 1');
   ensureColumn('sites', 'show_archive_link', 'INTEGER DEFAULT 1');
-  ensureColumn('sites', 'og_theme', 'TEXT');               // OG share-card variant: NULL=auto (follow site theme) | 'light' | 'dark'
+  // Gated feature (FEP-633c): may external (non-fediverse) embeds be shown to
+  // this account? NULL = auto, which means OFF for a ward and ON for anyone
+  // else. The guardians flip it; the gate itself lives server-side, so a ward
+  // never even receives the thumbnail it is not allowed to see.
+  ensureColumn('sites', 'external_embeds', 'INTEGER');
+  ensureColumn('sites', 'og_theme', 'TEXT');             // OG share-card variant: NULL=auto (follow site theme) | 'light' | 'dark'
 
   // Per-post noindex + type
@@ -550 +555 @@
   ensureColumn('ap_timeline', 'link_json', 'TEXT');          // FEP-e232 object-link (quote/ref) tags from the inbound note, served back as `tag`
   ensureColumn('ap_timeline', 'quote_json', 'TEXT');         // FEP-044f resolved quoted-post snapshot (author + content), for the embedded quote card
+  ensureColumn('ap_timeline', 'embed_json', 'TEXT');         // resolved EXTERNAL embed (oEmbed/provider), thumbnail-only; gated per site (sites.external_embeds)
   ensureColumn('ap_timeline', 'author_emoji_json', 'TEXT');  // FEP-9098 custom emojis in the author's display name (shaer:author.emojis)
   ensureColumn('ap_timeline', 'reblog_emoji_json', 'TEXT');  // FEP-9098 custom emojis in the booster's display name (shaer:booster.emojis)

src/routes/activitypub.js

@@ -145 +145 @@
   if (!auth || auth.site.slug !== req.params.slug) return res.status(403).end();
   const base = baseUrl(req);
+  // Gated feature (FEP-633c): may this account see EXTERNAL embeds? A ward's
+  // world outside the fediverse is the guardians' call. The gate is applied
+  // here, at serialisation: a blocked embed is never sent, because an embed the
+  // client merely hides has still been delivered to the device.
+  const isWard = (() => { try { return Guardianship.listGuardians(auth.site.slug).length > 0; } catch { return false; } })();
+  const embedsAllowed = Guardianship.externalEmbedsAllowed(auth.site.external_embeds, isWard);
   const items = AP.getTimeline(auth.site.slug, 60).map((t) => ({
     id: `${t.id}#create`,
@@ -195 +201 @@
       'shaer:liked': !!t.liked,
       'shaer:boosted': !!t.boosted,
+      // An external (non-fediverse) embed, thumbnail-only and never an iframe.
+      // Omitted entirely when the gate is closed (see above).
+      'shaer:embed': embedsAllowed ? AP.timelineEmbed(t.embed_json) : undefined,
     },
   }));

src/services/ActivityPubService.js

@@ -22 +22 @@
 import HtmlSanitizerService from './HtmlSanitizerService.js';
 import AudioEmbedService from './AudioEmbedService.js';
+import EmbedResolver from './EmbedResolver.js';
 import Push from './PushService.js';
 import { getTenancy } from './SettingsService.js';
@@ -1575 +1576 @@
             if (!qj) return;
             for (const sl of slugs) { try { db.prepare('UPDATE ap_timeline SET quote_json = ? WHERE id = ? AND slug = ?').run(qj, o.id, sl); } catch { /* ignore */ } }
+          }).catch(() => { /* best-effort */ });
+        } else {
+          // No fediverse quote: try an EXTERNAL embed (oEmbed / known provider),
+          // thumbnail-only. Also out of band, and stored for everyone; the gate
+          // that decides who may SEE it is applied at serve time (§5.3-style
+          // gated feature, see the inbox read).
+          const slugs = subs.map((s) => s.slug);
+          resolveExternalEmbed(o.content).then((ej) => {
+            if (!ej) return;
+            for (const sl of slugs) { try { db.prepare('UPDATE ap_timeline SET embed_json = ? WHERE id = ? AND slug = ?').run(ej, o.id, sl); } catch { /* ignore */ } }
           }).catch(() => { /* best-effort */ });
         }
@@ -2837 +2848 @@
 }
 
+// The first external (non-fediverse) link in a note, resolved to the same card
+// shape as a quote: THUMBNAIL ONLY, never the provider's iframe. An arbitrary
+// third-party frame inside a kid-safe app is a hole you cannot close again, so
+// the embed carries an image and a title and nothing executable.
+// Returns the JSON to store, or null when there is nothing worth showing.
+export async function resolveExternalEmbed(html) {
+  const first = firstExternalUrl(html);
+  if (!first) return null;
+  const io = EmbedResolver.liveIO({
+    safeFetch,
+    detectProvider: (u) => AudioEmbedService.detectProvider(u),
+    fetchActor,
+    actorInfo,
+  });
+  const card = await EmbedResolver.resolveEmbed(first, io).catch(() => null);
+  // 'ap' is handled by the quote path; a bare 'link' is not worth a card.
+  if (!card || card.kind === 'ap' || card.kind === 'link') return null;
+  const thumb = (card.media || []).find((m) => m && m.url);
+  if (!thumb && !card.title) return null;
+  return JSON.stringify({
+    url: card.url,
+    kind: card.kind,                       // 'provider' | 'oembed'
+    provider: card.provider || null,
+    title: card.title || null,
+    author: card.author || null,
+    media: thumb ? [thumb] : [],           // thumbnail only, no html/iframe
+  });
+}
+
+/** The first http(s) link in sanitized note HTML that is not a mention/hashtag. */
+export function firstExternalUrl(html) {
+  if (!html || typeof html !== 'string') return null;
+  for (const m of html.matchAll(/<a\b[^>]*href=["']([^"']+)["'][^>]*>/gi)) {
+    const tag = m[0];
+    if (/\b(mention|hashtag|u-url)\b/i.test(tag) && /mention|hashtag/i.test(tag)) continue;
+    const href = m[1];
+    if (/^https?:\/\//i.test(href)) return href;
+  }
+  return null;
+}
+
+/** The stored external-embed card, for the C2S read. */
+export function timelineEmbed(embedJson) {
+  try { const e = embedJson ? JSON.parse(embedJson) : null; return (e && typeof e === 'object' && e.url) ? e : undefined; }
+  catch { return undefined; }
+}
+
 // FEP-044f embedded quote card: resolve the quoted post to a compact, sanitised
 // snapshot { url, author{name,handle,icon}, content, published, media } so the
@@ -3576 +3634 @@
   getInteractions, getInteractionById, setInteractionBoosted, setInteractionLiked, setMyReaction, getMyReactions, buildReplyNote, getOutboxNote, deliverReply, resolveRemoteNote,
   listOutbox, deliverOutboxDelete, deliverOutboxUpdate, deliverDirectNote,
-  webfingerResolve, followActor, resolveRemoteActor, unfollowActor, listFollowing, setAutoBoost, backfillFromOutbox, getTimeline, timelineAttachments, timelineEmojis, timelineObjectLinks, timelineQuote, sendInteraction, voteOnPoll, voteOnRemotePoll,
+  webfingerResolve, followActor, resolveRemoteActor, unfollowActor, listFollowing, setAutoBoost, backfillFromOutbox, getTimeline, timelineAttachments, timelineEmojis, timelineObjectLinks, timelineQuote, timelineEmbed, sendInteraction, voteOnPoll, voteOnRemotePoll,
   acceptGatedFollow, rejectGatedFollow, isWardGuardian, sendFollowDecision,
   parseOwnPoll, pollTally, ownPollView, deliverPollUpdate, maybeCrawlThread, sendReport, localMentionSlugs,

src/services/guardianship/index.js

@@ -16 +16 @@
  */
 export { SHAER_CONTEXT, GUARDIAN_RELATIONSHIP, GUARDIAN_RELATIONSHIP_COMPACT, isGuardianRelationship } from './context.js';
-export { helpRequestProps, isHelpRequest, waveProps, isWave, hasGuardiansProps, objectHasGuardians } from './notes.js';
+export { helpRequestProps, isHelpRequest, waveProps, isWave, hasGuardiansProps, objectHasGuardians, externalEmbedsAllowed } from './notes.js';
 export { wireDelivery, c2sVisibility, deliverDirectNote } from './delivery.js';
 export { wireHandshake, handleOutbox as handleGuardianshipOutbox, handleInbox as handleGuardianshipInbox, parseRelationship } from './handshake.js';

src/services/guardianship/notes.js

@@ -15 +15 @@
   try { return (slug && listGuardians(slug).length) ? { 'shaer:hasGuardians': true } : {}; }
   catch { return {}; }
+}
+
+/**
+ * May EXTERNAL (non-fediverse) embeds be shown to this account?
+ *
+ * A gated feature in the FEP-633c sense: a ward's world outside the fediverse
+ * is the guardians' call. `setting` is `sites.external_embeds`:
+ *   null/undefined → auto: off for a ward, on for anyone else
+ *   0 → off, 1 → on (the guardians decided)
+ *
+ * Pure, so the rule is testable on its own. The gate is applied SERVER-side:
+ * a blocked embed is never serialised into the feed, because an embed that the
+ * client merely hides has still been delivered.
+ */
+export function externalEmbedsAllowed(setting, isWard) {
+  if (setting === 0 || setting === 1) return setting === 1;
+  return !isWard;
 }
 
@@ -48 +65 @@
 }
 
-export default { helpRequestProps, isHelpRequest, waveProps, isWave, hasGuardiansProps, objectHasGuardians };
+export default { helpRequestProps, isHelpRequest, waveProps, isWave, hasGuardiansProps, objectHasGuardians, externalEmbedsAllowed };