Changeset 6c152a5 in Klonkt for src/services/guardianship

Timestamp:

07/28/2026 08:15:31 PM (6 weeks ago)

Author:

Robin Genis <roboburr@…>

Branches:

main

Children:

6eab7e9

Parents:

742ba7e

Message:

De Undo bij het loslaten van een ward reist nu echt mee

Loslaten was een lokale delete. De guardian vergat het kind, terwijl de server
van het kind hem gewoon in shaer:guardians bleef noemen. De vorige commit zette
dat als waarschuwing in beeld; Robin noemt het terecht een bug, want FEP-633c
3.2 zegt gewoon dat een Undo van de Relationship de guardian eruit haalt.

Nu gaat er een Undo naar het kind en naar de andere guardians, met dezelfde
adressering als de Offer waarmee het begon (3.1.1), zodat geen kopie achterblijft
die denkt dat de band er nog is. De ontvangende kant haalt de guardian eruit,
maar alleen als de guardian zelf tekent: de variant waarbij het kind opzegt met
een mede-ondertekenende guardian heeft een tweede handtekening nodig en is niet
gebouwd, dus die wordt geweigerd in plaats van half uitgevoerd.

De laatste guardian kan niet meer alleen weglopen. 3.3 geldt zolang er meer dan
een over is; de set leegmaken is emancipatie (3.4) en daar gaat geen enkele
partij alleen over. Dat wordt geweigerd aan beide kanten, en de knop biedt in
dat geval alleen nog een nee aan in plaats van een ja die toch een fout geeft.

Een kind op DEZELFDE instance kreeg de Undo niet: een inbox op deze machine is
van deze machine niet over HTTP bereikbaar, en dat hoort ook niet. De commit-kant
lost dat al zo op dat elke instance schrijft wat hij host; het loslaten doet dat
nu ook. In de browser gevonden nadat de guardian-kant leeg was en de kant van het
kind nog niet.

Een guardian-app kan hetzelfde over C2S: een Undo naar de eigen outbox loopt
langs precies dezelfde functie als de knop in de PWA, zodat die twee niet uit
elkaar kunnen groeien.

Changed files:
src/services/guardianship/handshake.js

• endGuardianship: bouwt en verstuurt de Undo, weigert emancipatie, en schrijft de kant van een lokaal gehost kind zelf
• applyInboundUndo + dropGuardianFromWard: de ontvangende kant
• handleOutbox accepteert Undo; handleInbox routeert hem

src/services/guardianship/index.js

• endGuardianship en parseUndoRelationship geexporteerd

src/services/ActivityPubService.js

• de guardianship-dispatch ziet Undo nu voordat de generieke Undo-tak hem opslokt met een 202
• push voor een vertrokken guardian en een vertrokken mede-guardian

src/routes/guardian.js

• /wards/remove loopt langs endGuardianship in plaats van een lokale delete
• release-check meldt niet langer dat de Undo blijft liggen

src/assets/js/guardian.js

• geen ja-knop meer als jij de laatste bent; een 409 wordt getoond in plaats van stil hertekend

src/services/i18n.js

• de waarschuwing klopt weer, plus push-teksten in nl, en, de

test/guardianship.test.js

• zes tests: de Undo werkt aan beide kanten, de laatste guardian wordt geweigerd, hij is idempotent, C2S loopt hetzelfde pad, een vreemde Undo verandert niets, en een kind op dezelfde instance wordt ook bijgewerkt terwijl er niets bezorgd is

remarks: end-to-end nagekeken in de browser: na het loslaten staat guard niet
meer in shaer:guardians van het actor-document van het kind, en een POST die de
knop omzeilt krijgt 409 would_emancipate.

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

Location:

src/services/guardianship

Files:

• handshake.js (modified) (5 diffs)
• index.js (modified) (1 diff)

src/services/guardianship/handshake.js

@@ -26 +26 @@
 const idOf = (v) => (typeof v === 'string' ? v : (v && typeof v === 'object' && typeof v.id === 'string' ? v.id : null));
 const arr = (v) => (Array.isArray(v) ? v : (v ? [v] : [])).filter((x) => typeof x === 'string');
+
+/**
+ * FEP-633c §3.2/§3.3 — ending a guardianship.
+ *
+ * "After commit, either side MAY end the relationship with `Undo` of the
+ * `Relationship`. An `Undo` from a guardian, or from the ward co-signed by an
+ * existing guardian, removes the guardian from `shaer:guardians`."
+ *
+ * §3.3 bounds it: this is how ONE guardian goes while others remain. Removing
+ * the last one empties `shaer:guardians` and that is emancipation (§3.4), which
+ * has its own flow and is explicitly not a single party's call. So an Undo that
+ * would leave a ward with nobody is refused here rather than quietly performed.
+ */
+export function parseUndoRelationship(activity) {
+  const type = Array.isArray(activity && activity.type) ? activity.type[0] : (activity && activity.type);
+  if (type !== 'Undo') return null;
+  return parseRelationship(activity && activity.object);
+}
 
 /** Parse a Relationship object into {ward, candidate} or null. */
@@ -87 +105 @@
 }
 
+/**
+ * End a guardianship from the local guardian's side and let it travel (§3.2).
+ *
+ * One path for both callers: the button in the Guardian PWA and an `Undo` a
+ * Guardian app POSTs to its own outbox. Addressed like the Offer that started
+ * it (§3.1.1): the ward, and every other guardian, so no copy is left behind
+ * believing the relation still stands.
+ */
+export async function endGuardianship(site, wardUri) {
+  const me = deps.selfId(site.slug);
+  if (!relations.getRelation(site.slug, 'guardian', wardUri)) return { status: 404, error: 'not_my_ward' };
+  const set = await existingGuardiansOf(wardUri);
+  const others = set.filter((g) => g !== me);
+  // Only a set we actually read counts as proof. A remote ward whose server is
+  // down reads as an empty set; refusing on that would trap the guardian, and
+  // the ward's server checks again on arrival anyway.
+  if (set.length && others.length === 0) return { status: 409, error: 'would_emancipate' };
+  const recipients = [wardUri, ...others];
+  const undo = {
+    id: `${me}/undo/${Date.now().toString(36)}${Math.floor(Math.random() * 1e4).toString(36)}`,
+    type: 'Undo', actor: me, to: recipients,
+    object: { type: 'Relationship', subject: wardUri, relationship: GUARDIAN_RELATIONSHIP_COMPACT, object: me },
+  };
+  const delivered = await fanout(site, recipients, undo);
+  relations.removeRelation(site.slug, 'guardian', wardUri);
+  // A ward we host ourselves never receives its own delivery: an inbox on this
+  // machine is not reachable over HTTP from this machine (and should not be).
+  // The commit path has the same shape and solves it the same way — each
+  // instance writes what it hosts (applyCommitLocally).
+  const wardSlug = deps.localSlug(wardUri);
+  if (wardSlug) dropGuardianFromWard(wardSlug, deps.selfId(site.slug));
+  notify(site.slug, { kind: 'guardianship_ended', ward: wardUri, delivered });
+  return { status: 202, delivered, guardiansLeft: others.length };
+}
+
+/**
+ * The ward's side of an ended guardianship: drop that guardian, unless doing so
+ * would empty the set. §3.3 only permits this while more than one remains;
+ * emptying it is emancipation (§3.4) and no single party decides that.
+ */
+function dropGuardianFromWard(wardSlug, guardianUri) {
+  const set = relations.listGuardians(wardSlug).map((r) => r.other_uri);
+  if (!set.includes(guardianUri)) return false;   // already gone: an Undo is idempotent
+  if (set.length <= 1) {
+    notify(wardSlug, { kind: 'guardianship_end_refused', guardian: guardianUri, reason: 'would_emancipate' });
+    return false;
+  }
+  relations.removeRelation(wardSlug, 'ward', guardianUri);
+  notify(wardSlug, { kind: 'guardian_left', guardian: guardianUri });
+  return true;
+}
+
+/** The receiving side of that Undo. Returns true when consumed. */
+function applyInboundUndo(site, activity) {
+  const rel = parseUndoRelationship(activity);
+  if (!rel) return false;
+  const me = deps.selfId(site.slug);
+  const actor = idOf(activity.actor);
+  const ward = rel.ward;
+  const guardian = rel.candidate;   // in an Undo the Relationship's object is the leaving guardian
+
+  if (ward === me) {
+    // I am the ward. Only the guardian itself may end its own relation here;
+    // the ward-co-signed variant of §3.2 needs a second signature and is not
+    // built, so it is refused rather than half-honoured.
+    if (actor !== guardian) return false;
+    dropGuardianFromWard(site.slug, guardian);
+    return true;
+  }
+
+  // I am one of the other guardians: nothing of mine changes, but being left
+  // as one of fewer is exactly the kind of thing a guardian should hear about.
+  if (relations.getRelation(site.slug, 'guardian', ward)) {
+    notify(site.slug, { kind: 'coguardian_left', ward, guardian });
+    return true;
+  }
+  return false;
+}
+
 // ── C2S: a LOCAL party acts (PWA, Berichten, or the Shaer app outbox) ──────
 
@@ -95 +192 @@
 export async function handleOutbox(site, activity) {
   const type = Array.isArray(activity.type) ? activity.type[0] : activity.type;
-  if (!['Offer', 'Accept', 'Reject'].includes(type)) return null;
+  if (!['Offer', 'Accept', 'Reject', 'Undo'].includes(type)) return null;
   const me = deps.selfId(site.slug);
+
+  // ── Undo: a guardian ends its own guardianship (§3.2). Same path as the
+  //    button in the Guardian PWA, so an app and the dashboard cannot drift.
+  if (type === 'Undo') {
+    const rel = parseUndoRelationship(activity);
+    if (!rel) return null;
+    if (rel.candidate !== me) return { status: 403, error: 'not_your_relation' };
+    return endGuardianship(site, rel.ward);
+  }
 
   // ── Offer: the local site is the guardian-candidate. ───────────────────
@@ -152 +258 @@
 export async function handleInbox(site, activity) {
   const type = Array.isArray(activity.type) ? activity.type[0] : activity.type;
-  if (!['Offer', 'Accept', 'Reject'].includes(type)) return false;
+  if (!['Offer', 'Accept', 'Reject', 'Undo'].includes(type)) return false;
+  if (type === 'Undo') return applyInboundUndo(site, activity);
   const me = deps.selfId(site.slug);
   const actor = idOf(activity.actor);
@@ -216 +323 @@
 }
 
-export default { wireHandshake, handleOutbox, handleInbox, parseRelationship };
+export default { wireHandshake, handleOutbox, handleInbox, parseRelationship, parseUndoRelationship, endGuardianship };

src/services/guardianship/index.js

@@ -18 +18 @@
 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';
+export { wireHandshake, handleOutbox as handleGuardianshipOutbox, handleInbox as handleGuardianshipInbox, parseRelationship, parseUndoRelationship, endGuardianship } from './handshake.js';
 export { offersCollection, followsCollection, wardsCollection } from './queues.js';
 export * as follows from './follows.js';