@uuaid/pillar 2.0.3 → 2.2.0

package/src/receipts.mjs

@@ -0,0 +1,145 @@
+/**
+ * Receipts — the recipient's own signed word that an envelope arrived.
+ *
+ * A carrier receipt (`seq`, `sha`) proves a CARRIER stored the envelope. It
+ * says nothing about the recipient. These are the two recipient-signed
+ * signals the Interaction Convention already defines, which the mobile app
+ * sends and honours, now spoken by this package too:
+ *
+ *   delivery ack   kind "ack", payload { thread, inReplyTo: <envelope id> }
+ *   read receipt   kind "ack", payload { v: 1, type: "pillar-read-receipt",
+ *                                        upTo: <envelope id>, thread }
+ *
+ * Both are ordinary sealed envelopes, so each is signed by the recipient's
+ * key and verified by open() before anything here sees it. What they prove
+ * and what they do not is spelled out in INTERACTION-CONVENTION.md: a receipt
+ * is evidence about a MAILBOX (the endpoint holding the key stored or opened
+ * the envelope), never about an understanding. Labels in this package say
+ * "acknowledged" and "read receipt", never "delivered to the agent".
+ *
+ * Sending either is opt-in (config.json `receipts`), and only ever to a
+ * contact: acking a stranger would confirm the address is live.
+ */
+export const READ_RECEIPT_TYPE = "pillar-read-receipt";
+export const MAX_READ_RECEIPTS_PER_RUN = 64;
+
+/** Thread root of an envelope: the payload's `thread`, else the envelope itself. */
+export function threadOf(envelope, payload) {
+  const t = payload && typeof payload === "object" ? payload.thread : undefined;
+  return typeof t === "string" && t.length > 0 ? t : envelope.id;
+}
+
+export function isReadReceipt(payload) {
+  return !!payload && typeof payload === "object" && !Array.isArray(payload) &&
+    payload.type === READ_RECEIPT_TYPE &&
+    typeof payload.upTo === "string" && payload.upTo.length > 0 &&
+    typeof payload.thread === "string" && payload.thread.length > 0;
+}
+
+/** A plain delivery ack for one received envelope (convention rule 2). */
+export function deliveryAck(envelope, payload) {
+  return { kind: "ack", payload: { thread: threadOf(envelope, payload), inReplyTo: envelope.id } };
+}
+
+export function readReceipt({ thread, upTo }) {
+  return { kind: "ack", payload: { v: 1, type: READ_RECEIPT_TYPE, upTo, thread } };
+}
+
+/**
+ * What a peeked envelope says about our send `envelopeId` to `recipient`:
+ * "delivered", "read", or null. A delivery ack answers it by `inReplyTo`
+ * only: the ack of a FOLLOW-UP carries the same `thread` and is not about
+ * this row. A read receipt covers it by `upTo` or `thread`, and counts only
+ * while read receipts are on (`read: false` ignores them, as applyReceipt does).
+ */
+export function receiptFor(view, envelopeId, recipient, { read = true } = {}) {
+  if (!view || view.kind !== "ack" || view.sender !== recipient) return null;
+  const p = view.payload;
+  if (isReadReceipt(p)) return read && (p.upTo === envelopeId || p.thread === envelopeId) ? "read" : null;
+  return p && typeof p === "object" && p.inReplyTo === envelopeId ? "delivered" : null;
+}
+
+/**
+ * The read receipts that cover a batch of inbound messages being marked
+ * read: one per (sender, conversation), citing the latest envelope in it.
+ * A group message carries no `thread`, so its receipt names that envelope as
+ * both thread and upTo; the sender applies it to everything earlier it sealed
+ * to us in that group. Receipts and our own notes are never receipted.
+ *
+ * `views`: [{ id, sender, kind, payload, groupId? }] in arrival order.
+ */
+export function planReadReceipts(views, { self, max = MAX_READ_RECEIPTS_PER_RUN } = {}) {
+  const latest = new Map(); // key -> { to, thread, upTo }
+  for (const v of views) {
+    if (!v || v.kind === "ack" || v.sender === self) continue;
+    if (v.groupId) {
+      latest.set(`g|${v.sender}|${v.groupId}`, { to: v.sender, thread: v.id, upTo: v.id });
+    } else {
+      const thread = threadOf(v, v.payload);
+      latest.set(`t|${v.sender}|${thread}`, { to: v.sender, thread, upTo: v.id });
+    }
+  }
+  const all = [...latest.values()];
+  return { receipts: all.slice(-max), dropped: Math.max(0, all.length - max) };
+}
+
+/**
+ * Apply an inbound ack to the outbox. Only ever to rows we sent TO the
+ * ack's verified sender: nobody else can acknowledge them.
+ *
+ * Returns { kind: "ack" | "read" | null, marked }.
+ */
+export function applyReceipt(mailbox, envelope, payload, { applyRead = true } = {}) {
+  if (envelope.kind !== "ack" || !payload || typeof payload !== "object") return { kind: null, marked: 0 };
+  const from = envelope.sender;
+  if (isReadReceipt(payload)) {
+    if (!applyRead) return { kind: "read", marked: 0, ignored: "read-receipts-off" };
+    const rows = mailbox.outboundTo(from);
+    const cited = rows.find((r) => r.envelope_id === payload.thread);
+    let candidates;
+    let cutoffRow;
+    if (cited?.group_id) {
+      // Group: everything earlier we sealed to this member in that group.
+      candidates = rows.filter((r) => r.group_id === cited.group_id);
+      cutoffRow = rows.find((r) => r.envelope_id === payload.upTo) ?? cited;
+    } else {
+      candidates = rows.filter((r) => r.thread === payload.thread || r.envelope_id === payload.thread);
+      cutoffRow = rows.find((r) => r.envelope_id === payload.upTo);
+    }
+    // An unknown anchor still covers the whole conversation: the receipt is
+    // authenticated from its counterparty, and the rows are only ever ours
+    // to THAT counterparty, so an over-mark is their own mail marked read.
+    const cutoff = cutoffRow?.created_at;
+    const ids = candidates.filter((r) => !cutoff || r.created_at <= cutoff).map((r) => r.envelope_id);
+    const marked = ids.length ? mailbox.markOutboundRead(ids, { at: envelope.createdAt }) : 0;
+    return { kind: "read", marked };
+  }
+  if (typeof payload.inReplyTo === "string" && payload.inReplyTo) {
+    const ok = mailbox.markOutboundAcked(payload.inReplyTo, { from, ackId: envelope.id, at: envelope.createdAt });
+    return { kind: "ack", marked: ok ? 1 : 0 };
+  }
+  return { kind: null, marked: 0 };
+}
+
+/** True when an inbound ack/reply answers something we sent to its sender. */
+export function answersOurSend(mailbox, envelope, payload) {
+  if (envelope.kind !== "ack" && envelope.kind !== "reply") return false;
+  const sentTo = (id) => {
+    if (typeof id !== "string" || !id) return false;
+    const row = mailbox.getOutbound(id);
+    return !!row && row.recipient === envelope.sender;
+  };
+  if (sentTo(payload?.inReplyTo)) return true;
+  return envelope.kind === "ack" && isReadReceipt(payload) && (sentTo(payload.thread) || sentTo(payload.upTo));
+}
+
+/** Human status line for one outbox row; wording follows the convention's limits. */
+export function describeOutboundStatus(row) {
+  const parts = [];
+  if (row.status === "delivered") parts.push(`accepted by carrier ${row.delivered_at ?? ""}`.trim());
+  else parts.push("not yet accepted by any carrier");
+  if (row.recipient_ack_at) parts.push(`acknowledged by the recipient's key ${row.recipient_ack_at}`);
+  if (row.recipient_read_at) parts.push(`read receipt ${row.recipient_read_at}`);
+  if (!row.recipient_ack_at && !row.recipient_read_at && row.kind !== "ack") parts.push("no recipient receipt yet");
+  return parts.join("; ");
+}