Changeset fc40410 in Klonkt for src/services/guardianship

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@…>

Location:

src/services/guardianship

Files:

• index.js (modified) (1 diff)
• notes.js (modified) (2 diffs)

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 };