@kubun/plugin-p2p 0.11.0 → 0.12.1

package/lib/groups/peer-presence.js

@@ -0,0 +1,295 @@
+import { normalizeDID } from '@kokuin/token';
+import { HLC } from '@kubun/hlc';
+import { getP2PStore } from '@kubun/store-p2p';
+/** Coalescing window for the epoch lane. A catch-up walk applies its commits well inside it. */ const ANNOUNCE_COALESCE_MS = 50;
+/**
+ * Pull an announcement out of an untyped gather reply. The gather surface hands
+ * back `unknown`, so a version-skewed or malicious responder must contribute
+ * nothing rather than throw — and must not be able to write a row from a shape
+ * the schema would have refused.
+ */ function extractAnnouncement(value) {
+    if (value == null || typeof value !== 'object') {
+        return null;
+    }
+    const reply = value;
+    const { label, availability, capabilities, hlc } = reply;
+    if (typeof label !== 'string' || typeof hlc !== 'string' || hlc === '') {
+        return null;
+    }
+    if (availability !== 'always-on' && availability !== 'interactive' && availability !== 'mobile') {
+        return null;
+    }
+    if (!Array.isArray(capabilities)) {
+        return null;
+    }
+    const parsed = [];
+    for (const entry of capabilities){
+        if (entry == null || typeof entry !== 'object') {
+            return null;
+        }
+        const capability = entry;
+        if (typeof capability.protocol !== 'string' || typeof capability.version !== 'number') {
+            return null;
+        }
+        const transports = capability.transports;
+        if (transports !== null && !Array.isArray(transports)) {
+            return null;
+        }
+        parsed.push({
+            protocol: capability.protocol,
+            version: capability.version,
+            transports: transports === null ? null : transports.filter((hint)=>typeof hint === 'string')
+        });
+    }
+    return {
+        label,
+        availability,
+        capabilities: parsed,
+        hlc
+    };
+}
+export function createPeerPresence(params) {
+    const { logger } = params;
+    const selfDID = normalizeDID(params.localDID);
+    // groupID → the timer coalescing that group's epoch-lane announces.
+    const pendingAnnounces = new Map();
+    // Tasks whose timer has already fired. A pending timer can be cleared; these
+    // can only be waited for — see `dispose`.
+    const inFlight = new Set();
+    let disposed = false;
+    /** Run `task` now, keeping it visible to `dispose` until it settles. */ const track = (task)=>{
+        const running = task().finally(()=>{
+            inFlight.delete(running);
+        });
+        inFlight.add(running);
+    };
+    const getProfile = async ()=>{
+        const store = await getP2PStore(params.stores);
+        const row = await store.getLocalPeerProfile(selfDID);
+        if (row == null) {
+            return null;
+        }
+        return {
+            label: row.label,
+            // As in the query handler: the row was written from a validated profile.
+            availability: row.availability,
+            capabilities: row.capabilities
+        };
+    };
+    const announceProfile = async (groupID, profile)=>{
+        // Stamped once for both the frame and the local row, and never taken from the
+        // caller: the anchor decides which of two announcements from this device wins
+        // on every receiver, so it has to come from the device's one clock — and the
+        // local row has to carry the same value a co-member holds, or the two copies
+        // of one announcement disagree.
+        const announcedHLC = HLC.serialize(params.hlc.now());
+        // Seed this device's own row. The hub fans a publish to subscribers minus the
+        // sender, so nothing ever hands a device back its own announcement: without
+        // this write the projection is the one place that cannot see the device it
+        // lives on. It is also what a `peer/query` reply is read from.
+        const store = await getP2PStore(params.stores);
+        await store.upsertPeerAnnouncement({
+            groupID,
+            peerDID: selfDID,
+            label: profile.label,
+            availability: profile.availability,
+            capabilities: profile.capabilities,
+            hlc: announcedHLC,
+            epoch: params.getGroupEpoch(groupID) ?? 0
+        });
+        await params.publish(groupID, {
+            type: 'peer:announce',
+            label: profile.label,
+            availability: profile.availability,
+            capabilities: profile.capabilities,
+            hlc: announcedHLC,
+            announcerDID: selfDID
+        });
+    };
+    const announce = async (groupID)=>{
+        const profile = await getProfile();
+        if (profile == null) {
+            logger?.debug('nothing announced: this device has declared no peer profile', {
+                groupID
+            });
+            return false;
+        }
+        await announceProfile(groupID, profile);
+        return true;
+    };
+    /**
+   * How many co-members could answer this query at all — every projected device
+   * but this one, keeping only those whose advertised capabilities match what is
+   * being asked for.
+   *
+   * This is the set that would not DECLINE, which is what a quorum can count:
+   * a decline is a throw, and the gather drops an errored reply before counting
+   * it. Counting roster members instead would set a target no group with a
+   * silent or non-matching device could ever reach.
+   */ const answerableCount = async (groupID, protocols)=>{
+        const store = await getP2PStore(params.stores);
+        const rows = await store.listPeerAnnouncements(groupID);
+        return rows.filter((entry)=>normalizeDID(entry.peer_did) !== selfDID && (protocols == null || entry.capabilities.some((capability)=>protocols.includes(capability.protocol)))).length;
+    };
+    const gather = async (groupID, options = {})=>{
+        const protocols = options.protocols ?? null;
+        // Without a quorum every gather costs its whole window — 5s, on every
+        // foreground refresh — because nothing else can tell the client that the
+        // last answer has already arrived. Known-and-answerable is the largest
+        // target that can actually be met, so it closes the window the moment
+        // everybody replies and falls back to the timeout when somebody is asleep.
+        // A caller's own quorum always wins.
+        const quorum = options.quorum ?? await answerableCount(groupID, protocols);
+        const replies = await params.query(groupID, {
+            protocols
+        }, // Zero would be a quorum met by the first reply, which is not what "nothing
+        // is known to answer" means. Nothing known, nothing to wait for: the window.
+        quorum > 0 ? {
+            ...options,
+            quorum
+        } : options);
+        const gathered = [];
+        const seen = new Set();
+        for (const reply of replies){
+            // Attributed exactly as a pushed frame is: the sender the lane
+            // authenticated, never anything the reply body carried. The reply body
+            // holds no DID at all — it is the announce body.
+            const peerDID = normalizeDID(reply.senderDID);
+            if (peerDID === selfDID || seen.has(peerDID)) {
+                continue;
+            }
+            const announcement = extractAnnouncement(reply.value);
+            if (announcement == null) {
+                logger?.warn('peer/query reply ignored: not an announcement', {
+                    groupID,
+                    peerDID
+                });
+                continue;
+            }
+            seen.add(peerDID);
+            // A reply IS an announcement, so it folds through the same apply — same LWW
+            // by the announcer's stamp, same epoch stamping, same loopback guard.
+            await params.applyAnnouncement(groupID, {
+                type: 'peer:announce',
+                label: announcement.label,
+                availability: announcement.availability,
+                capabilities: announcement.capabilities,
+                hlc: announcement.hlc,
+                announcerDID: peerDID
+            });
+            gathered.push({
+                peerDID,
+                ...announcement
+            });
+        }
+        return gathered;
+    };
+    const refresh = async (groupID, options = {})=>{
+        // No profile, no traffic: a device that has not said what it is has not opted
+        // into the peer lane, and a trigger must not put a query on the lane on its
+        // behalf. An explicit `gather` still asks — there the host did.
+        if (!await announce(groupID)) {
+            return [];
+        }
+        return await gather(groupID, options);
+    };
+    // Off the current turn, and never awaited by its caller. Both triggers that use
+    // this fire from inside something that must not wait: an epoch advance holds
+    // the group mutex and its write transaction, and a hub lifecycle event is
+    // awaited by the adapter's state machine.
+    const later = (run)=>{
+        setTimeout(()=>{
+            if (disposed) {
+                return;
+            }
+            track(run);
+        }, 0);
+    };
+    return {
+        async setProfile (profile) {
+            const store = await getP2PStore(params.stores);
+            await store.setLocalPeerProfile({
+                peerDID: selfDID,
+                label: profile.label,
+                availability: profile.availability,
+                capabilities: profile.capabilities
+            });
+            // Before the announces, so nothing can arrive in response to one of them
+            // with no listener up yet.
+            params.onProfileSet?.();
+            // Device-wide, so every group hears it: the label and the capability set are
+            // properties of the device, and a group told nothing would keep offering a
+            // capability this device no longer answers.
+            for (const groupID of params.joinedGroupIDs()){
+                try {
+                    await announceProfile(groupID, profile);
+                } catch (error) {
+                    logger?.warn('profile announce failed for a group', {
+                        groupID,
+                        error
+                    });
+                }
+            }
+        },
+        getProfile,
+        announce,
+        gather,
+        refresh,
+        scheduleRefresh (groupID, reason) {
+            later(async ()=>{
+                try {
+                    logger?.debug('peer presence refresh', {
+                        groupID,
+                        reason
+                    });
+                    await refresh(groupID);
+                } catch (error) {
+                    logger?.warn('peer presence refresh failed', {
+                        groupID,
+                        reason,
+                        error
+                    });
+                }
+            });
+        },
+        scheduleAnnounce (groupID, reason) {
+            if (pendingAnnounces.has(groupID)) {
+                return;
+            }
+            const timer = setTimeout(()=>{
+                pendingAnnounces.delete(groupID);
+                if (disposed) {
+                    return;
+                }
+                track(async ()=>{
+                    try {
+                        logger?.debug('peer presence announce', {
+                            groupID,
+                            reason
+                        });
+                        await announce(groupID);
+                    } catch (error) {
+                        logger?.warn('peer presence announce failed', {
+                            groupID,
+                            reason,
+                            error
+                        });
+                    }
+                });
+            }, ANNOUNCE_COALESCE_MS);
+            pendingAnnounces.set(groupID, timer);
+        },
+        async dispose () {
+            disposed = true;
+            for (const timer of pendingAnnounces.values()){
+                clearTimeout(timer);
+            }
+            pendingAnnounces.clear();
+            // One pass is enough: nothing a tracked task does schedules another one,
+            // and `disposed` stops any trigger that fires from here on.
+            await Promise.allSettled([
+                ...inFlight
+            ]);
+        }
+    };
+}

package/lib/groups/peer-selection.d.ts

@@ -0,0 +1,37 @@
+import type { PeerAnnouncement } from '@kubun/store-p2p';
+/**
+ * "I answer directed merkle catch-up sessions" — matched on protocol AND version,
+ * exactly. A future direct transport is a new capability, not a wider match here.
+ */
+export declare const MERKLE_SYNC_PROTOCOL = "kubun/sync-merkle";
+export declare const MERKLE_SYNC_VERSION = 1;
+export type SelectSyncPeerOptions = {
+    /**
+     * This device's own DID. Required, because the projection holds this device's
+     * own row (every announce seeds it) and a session with yourself is a session
+     * with nobody.
+     */
+    selfDID: string;
+};
+/**
+ * Every co-member advertising merkle catch-up, best first.
+ *
+ * Pure and synchronous over rows the caller already read — the ranking is a
+ * policy, and the one thing that must not become another store query.
+ *
+ * "Live" here means "advertises the capability", with no freshness cutoff: this
+ * system holds no liveness fact to threshold. `announced_at` is when THIS device
+ * applied the announcement, a row is never deleted on silence, and a stale row
+ * says so rather than disappearing — so a cutoff would be a liveness policy with
+ * UI consequences invented at the ranking.
+ *
+ * The whole order rather than its head, because a row says only that a device
+ * once announced: the peer it names may be off, and nothing here can tell. Only
+ * an attempted session finds out, so the caller needs somewhere to go next.
+ */
+export declare function rankSyncPeers(rows: Array<PeerAnnouncement>, options: SelectSyncPeerOptions): Array<PeerAnnouncement>;
+/**
+ * The candidate an automatic catch-up tries first, or `undefined` when the
+ * projection offers none. The head of {@link rankSyncPeers}.
+ */
+export declare function selectSyncPeer(rows: Array<PeerAnnouncement>, options: SelectSyncPeerOptions): PeerAnnouncement | undefined;

package/lib/groups/peer-selection.js

@@ -0,0 +1,72 @@
+import { normalizeDID } from '@kokuin/token';
+/**
+ * "I answer directed merkle catch-up sessions" — matched on protocol AND version,
+ * exactly. A future direct transport is a new capability, not a wider match here.
+ */ export const MERKLE_SYNC_PROTOCOL = 'kubun/sync-merkle';
+export const MERKLE_SYNC_VERSION = 1;
+/**
+ * Availability tiers, best first. A device's own claim about itself, agreed by
+ * nobody: one that overstates it wastes a session, so there is no authority here
+ * to protect. An unrecognized class ranks after every known one rather than being
+ * dropped, so a device announcing a future tier stays selectable.
+ */ const AVAILABILITY_RANK = {
+    'always-on': 0,
+    interactive: 1,
+    mobile: 2
+};
+const UNKNOWN_AVAILABILITY_RANK = Object.keys(AVAILABILITY_RANK).length;
+function answersMerkleSync(row) {
+    return row.capabilities.some((capability)=>capability.protocol === MERKLE_SYNC_PROTOCOL && capability.version === MERKLE_SYNC_VERSION);
+}
+function availabilityRank(row) {
+    return AVAILABILITY_RANK[row.availability] ?? UNKNOWN_AVAILABILITY_RANK;
+}
+/**
+ * Compared relationally, never subtracted: `announced_at` is a count of seconds
+ * on SQLite and a timestamp on Postgres, and `b - a` is `NaN` for the latter —
+ * which sorts nothing and reports no error.
+ */ function compareRecency(left, right) {
+    if (left.announced_at === right.announced_at) {
+        return 0;
+    }
+    return left.announced_at < right.announced_at ? 1 : -1;
+}
+/**
+ * Every co-member advertising merkle catch-up, best first.
+ *
+ * Pure and synchronous over rows the caller already read — the ranking is a
+ * policy, and the one thing that must not become another store query.
+ *
+ * "Live" here means "advertises the capability", with no freshness cutoff: this
+ * system holds no liveness fact to threshold. `announced_at` is when THIS device
+ * applied the announcement, a row is never deleted on silence, and a stale row
+ * says so rather than disappearing — so a cutoff would be a liveness policy with
+ * UI consequences invented at the ranking.
+ *
+ * The whole order rather than its head, because a row says only that a device
+ * once announced: the peer it names may be off, and nothing here can tell. Only
+ * an attempted session finds out, so the caller needs somewhere to go next.
+ */ export function rankSyncPeers(rows, options) {
+    const selfDID = normalizeDID(options.selfDID);
+    const candidates = rows.filter((row)=>normalizeDID(row.peer_did) !== selfDID && answersMerkleSync(row));
+    candidates.sort((left, right)=>{
+        const byAvailability = availabilityRank(left) - availabilityRank(right);
+        if (byAvailability !== 0) {
+            return byAvailability;
+        }
+        const byRecency = compareRecency(left, right);
+        if (byRecency !== 0) {
+            return byRecency;
+        }
+        // Total order, so two rows a caller cannot tell apart never pick different
+        // peers on two devices reading the same projection.
+        return left.peer_did < right.peer_did ? -1 : 1;
+    });
+    return candidates;
+}
+/**
+ * The candidate an automatic catch-up tries first, or `undefined` when the
+ * projection offers none. The head of {@link rankSyncPeers}.
+ */ export function selectSyncPeer(rows, options) {
+    return rankSyncPeers(rows, options)[0];
+}

package/lib/groups/roster-projection.d.ts

@@ -0,0 +1,53 @@
+import type { GroupMember, P2PStoreAPI } from '@kubun/store-p2p';
+import type { GroupPermission, RosterState } from '@kumiai/mls';
+import type { GroupMemberData } from '../types.js';
+/**
+ * The role a member holds according to the handle's own roster.
+ *
+ * The roster is folded from the genesis anchor plus exactly the entries the
+ * authenticated MLS commit chain enacted, in epoch order — the same roster the
+ * commit policy judges an incoming commit against. Its order is therefore the
+ * epoch chain's, not a timestamp the signer chose for itself, so no party can
+ * place a role change earlier in the sequence than the commit that carried it.
+ *
+ * The roster is DID-keyed and can hold a role for a DID with no MLS membership,
+ * so lookups normalize; a member the roster says nothing about holds no
+ * permission beyond membership, which is `member`.
+ */
+export declare function roleFromRoster(roster: RosterState, memberDID: string): GroupPermission;
+export type MirrorRosterRolesParams = {
+    /**
+     * The store to write through. Inside a transaction this MUST be the
+     * transactional store — a bare store read/write there deadlocks
+     * single-connection SQLite against the transaction's own write lock.
+     */
+    store: P2PStoreAPI;
+    groupID: string;
+    /** The post-commit roster: `handle.roster` of the handle that accepted it. */
+    roster: RosterState;
+    /** The members whose `role` should be reconciled against that roster. */
+    memberDIDs: Array<string>;
+    /**
+     * The live membership rows to compare the roster against. Callers that have
+     * already read them pass them in so the comparison costs no extra query; when
+     * omitted the rows are read here.
+     *
+     * They must be read on the SAME store — inside a transaction, the
+     * transactional one — and must predate no write that changes a role.
+     */
+    members?: Array<GroupMember>;
+};
+/**
+ * Reconcile each member's role against the roster and report what changed.
+ *
+ * Only rows whose stored role actually differs from the roster's answer are
+ * written, and only those are returned, so a caller can announce a role change
+ * without announcing every member the commit merely left alone. The common
+ * commit changes nobody's role and therefore writes nothing.
+ *
+ * A DID with no live membership row is skipped: membership stays MLS-native and
+ * a role can never conjure a member. A tombstoned row is likewise left alone —
+ * an ex-member's role is frozen at the value it held when they were removed,
+ * which is what an announcement of their removal must report.
+ */
+export declare function mirrorRosterRoles(params: MirrorRosterRolesParams): Promise<Array<GroupMemberData>>;

package/lib/groups/roster-projection.js

@@ -0,0 +1,65 @@
+import { normalizeDID } from '@kokuin/token';
+import { toISO } from '../context/types.js';
+/**
+ * The role a member holds according to the handle's own roster.
+ *
+ * The roster is folded from the genesis anchor plus exactly the entries the
+ * authenticated MLS commit chain enacted, in epoch order — the same roster the
+ * commit policy judges an incoming commit against. Its order is therefore the
+ * epoch chain's, not a timestamp the signer chose for itself, so no party can
+ * place a role change earlier in the sequence than the commit that carried it.
+ *
+ * The roster is DID-keyed and can hold a role for a DID with no MLS membership,
+ * so lookups normalize; a member the roster says nothing about holds no
+ * permission beyond membership, which is `member`.
+ */ export function roleFromRoster(roster, memberDID) {
+    return roster.roles.get(normalizeDID(memberDID)) ?? 'member';
+}
+/**
+ * Reconcile each member's role against the roster and report what changed.
+ *
+ * Only rows whose stored role actually differs from the roster's answer are
+ * written, and only those are returned, so a caller can announce a role change
+ * without announcing every member the commit merely left alone. The common
+ * commit changes nobody's role and therefore writes nothing.
+ *
+ * A DID with no live membership row is skipped: membership stays MLS-native and
+ * a role can never conjure a member. A tombstoned row is likewise left alone —
+ * an ex-member's role is frozen at the value it held when they were removed,
+ * which is what an announcement of their removal must report.
+ */ export async function mirrorRosterRoles(params) {
+    const { store, groupID, roster, memberDIDs } = params;
+    const rows = params.members ?? await store.listGroupMembers(groupID);
+    const byDID = new Map(rows.map((row)=>[
+            normalizeDID(row.member_did),
+            row
+        ]));
+    const changed = [];
+    for (const memberDID of memberDIDs){
+        const row = byDID.get(normalizeDID(memberDID));
+        if (row == null) {
+            continue;
+        }
+        const role = roleFromRoster(roster, memberDID);
+        if (row.role === role) {
+            continue;
+        }
+        changed.push({
+            groupID,
+            memberDID: row.member_did,
+            role,
+            createdAt: toISO(row.created_at)
+        });
+    }
+    // Written together once every row is judged: the batch costs one statement per
+    // distinct role rather than one per member. The common commit moves nobody, and
+    // that case must not reach the store at all — not even to no-op on an empty
+    // list.
+    if (changed.length > 0) {
+        await store.setGroupMemberRoles(groupID, changed.map(({ memberDID, role })=>({
+                memberDID,
+                role
+            })));
+    }
+    return changed;
+}

package/lib/groups/store-received-grant.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from '@kubun/logger';
-import type { DelegationStoreAPI } from '@kubun/store-delegation';
+import { type DelegationStoreAPI } from '@kubun/store-delegation';
 import type { P2PStoreAPI } from '@kubun/store-p2p';
 import type { P2PEventEmitter } from './events.js';
 export type StoreReceivedGrantParams = {
@@ -39,8 +39,9 @@ export type StoreReceivedGrantParams = {
  *
  * Returns `true` when the held row was inserted or materially changed (LWW
  * upsert with a newer hlc and at least one differing content field). Returns
- * `false` when no row change occurred — verification failure, audience
- * mismatch, missing required claims, LWW lost against an existing row, or an
+ * `false` when no row change occurred — verification failure, a subject that
+ * is not the signer, audience mismatch, missing required claims, a lifetime
+ * above `MAX_CAP_TTL_SECONDS`, LWW lost against an existing row, or an
  * idempotent re-broadcast with identical content. Never throws on a forged or
  * malformed token — it is skipped like an unverifiable broadcast entry.
  *