Changeset 155c24e in Klonkt

Timestamp:

07/20/2026 10:52:58 PM (7 weeks ago)

Author:

Robin <roboburr@…>

Branches:

main

Children:

7922694

Parents:

e6c6e6f

git-author:

Robin <roboburr@…> (07/20/2026 10:52:57 PM)

git-committer:

Robin <roboburr@…> (07/20/2026 10:52:58 PM)

Message:

Feature: emit shaer:helpRequest on direct notes (FEP-633c 5.2.1)

The wire now claims exactly what the FEP specifies. The shaer
namespace (​https://ns.klonkt.com/shaer#) joins AP_CONTEXT, so the term
is valid JSON-LD; a C2S note carrying shaer:helpRequest true routes
through the direct path with the flag stored (additive column
ap_outbox.help_request) and the built note emits the term, strictly on
direct notes only. Non-observing servers ignore it; a guardian-side
client can render the alert card the spec allows.

Changed files:
src/services/ActivityPubService.js

• shaer namespace in AP_CONTEXT
• ingest reads shaer:helpRequest / helpRequest from the object
• deliverDirectNote stores the flag; buildReplyNote emits the term

src/config/database.js

• additive column ap_outbox.help_request

test/c2s-direct.test.js

• term emitted with flag, absent without, namespace declared

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

Files:

• src/config/database.js (modified) (1 diff)
• src/services/ActivityPubService.js (modified) (5 diffs)
• test/c2s-direct.test.js (modified) (1 diff)

src/config/database.js

@@ -443 +443 @@
   ensureColumn('ap_outbox', 'visibility', 'TEXT');  // 'direct' = private mention, never Public (shaer-tqc)
   ensureColumn('ap_outbox', 'to_actors', 'TEXT');   // JSON array of recipient actor URIs for direct notes
+  ensureColumn('ap_outbox', 'help_request', 'INTEGER'); // FEP-633c shaer:helpRequest (ward's call for help)
 }
 

src/services/ActivityPubService.js

@@ -46 +46 @@
     // Question stays valid JSON-LD (a strict processor would otherwise drop votersCount).
     votersCount: 'toot:votersCount',
+    // FEP-633c (Guardians): the shaer namespace. helpRequest marks a direct
+    // note as a ward's call for help (spec 5.2.1); ignorable by everyone else.
+    shaer: 'https://ns.klonkt.com/shaer#',
   },
 ];
@@ -259 +262 @@
         : (post.to_actor ? [post.to_actor] : [PUBLIC]),
       cc: post.visibility === 'direct' ? [] : [PUBLIC, `${meR}/followers`],
+      // FEP-633c 5.2.1: a ward's call for help. Only ever on direct notes.
+      'shaer:helpRequest': (post.visibility === 'direct' && post.help_request) ? true : undefined,
       tag: [
         ...mentionTags(post.content),
@@ -1855 +1860 @@
             } : null)
             .filter(Boolean);
-          const r = await deliverDirectNote(site, { recipients, text: plain, language: object.language || null, inReplyTo: typeof object.inReplyTo === 'string' ? object.inReplyTo : null, attachments: atts });
+          const help = object['shaer:helpRequest'] === true || object.helpRequest === true;
+          const r = await deliverDirectNote(site, { recipients, text: plain, language: object.language || null, inReplyTo: typeof object.inReplyTo === 'string' ? object.inReplyTo : null, attachments: atts, helpRequest: help });
           if (!r || !r.id) return { status: 502, error: 'direct_failed' };
           return { status: 201, id: r.id, url: `${base}/ap/notes/${r.id}` };
@@ -1971 +1977 @@
 // The same S2S leg a Mastodon DM takes, so a guardian on any instance
 // receives it as a private mention (the ward call-for-help path).
-export async function deliverDirectNote(site, { recipients, text, language, inReplyTo, attachments }) {
+export async function deliverDirectNote(site, { recipients, text, language, inReplyTo, attachments, helpRequest }) {
   const base = (process.env.PUBLIC_BASE_URL || '').replace(/\/+$/, '');
   const list = [...new Set((recipients || []).filter((u) => /^https?:\/\//i.test(String(u || ''))))].slice(0, 8);
@@ -1999 +2005 @@
     .map((a) => ({ url: a.url, mediaType: String(a.mediaType), name: String(a.name || '').slice(0, 120) }));
   const id = crypto.randomUUID();
-  db.prepare(`INSERT INTO ap_outbox (id, site_slug, post_id, post_slug, in_reply_to, to_actor, to_handle, content, language, attachments, visibility, to_actors, created_at)
-              VALUES (?,?,?,?,?,?,?,?,?,?,?,?,CURRENT_TIMESTAMP)`)
-    .run(id, site.slug, '', null, inReplyTo || null, resolved[0].uri, resolved[0].handle, content, lang, media.length ? JSON.stringify(media) : null, 'direct', JSON.stringify(resolved.map((r) => r.uri)));
+  db.prepare(`INSERT INTO ap_outbox (id, site_slug, post_id, post_slug, in_reply_to, to_actor, to_handle, content, language, attachments, visibility, to_actors, help_request, created_at)
+              VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,CURRENT_TIMESTAMP)`)
+    .run(id, site.slug, '', null, inReplyTo || null, resolved[0].uri, resolved[0].handle, content, lang, media.length ? JSON.stringify(media) : null, 'direct', JSON.stringify(resolved.map((r) => r.uri)), helpRequest ? 1 : 0);
   const row = iStmts().getO.get(id);
   const note = buildReplyNote(base, site, row);

test/c2s-direct.test.js

@@ -38 +38 @@
 });
 
+test('a help request emits shaer:helpRequest (FEP-633c 5.2.1)', () => {
+  db.prepare(`INSERT INTO ap_outbox (id, site_slug, post_id, post_slug, in_reply_to, to_actor, to_handle, content, visibility, to_actors, help_request, created_at)
+    VALUES ('d3','me','',NULL,NULL,'https://r.test/u/g','@g@r.test','<p>help</p>','direct','["https://r.test/u/g"]',1,CURRENT_TIMESTAMP)`).run();
+  const row = db.prepare('SELECT * FROM ap_outbox WHERE id = ?').get('d3');
+  const note = AP.buildReplyNote('https://test.example', site, row);
+  assert.equal(note['shaer:helpRequest'], true);
+  assert.deepEqual(note.cc, []);   // still strictly direct
+  // and the namespace is declared, so the term is valid JSON-LD
+  const ctx = AP.AP_CONTEXT.find((p) => p && typeof p === 'object');
+  assert.equal(ctx.shaer, 'https://ns.klonkt.com/shaer#');
+  // a plain direct note (no flag) does NOT carry the term
+  const plainRow = db.prepare('SELECT * FROM ap_outbox WHERE id = ?').get('d1');
+  assert.equal(AP.buildReplyNote('https://test.example', site, plainRow)['shaer:helpRequest'], undefined);
+});
+
 test('direct without any real recipient is refused (400 no_recipients)', async () => {
   const r = await AP.ingestOutboxActivity(site, user, {